According to recommendation on JSON API specification site, we should use all lower case member names in JSON separated by hyphens:

The allowed and recommended characters for an URL safe naming of members are defined in the format spec. To also standardize member names, the following (more restrictive) rules are recommended:

Member names SHOULD start and end with the characters "a-z" (U+0061 to U+007A) Member names SHOULD contain only the characters "a-z" (U+0061 to U+007A), "0-9" (U+0030 to U+0039), and the hyphen minus (U+002D HYPHEN-MINUS, "-") as separator between multiple words.

So basically, we should be using JSON like this:

{
    "first-name": "Jason",
    "last-name": "Tough"
}

Would not it make it cumbersome to access those properties in JavaScript? Or any other programming language for that matter, especially if we want to generate classes from JSON Schema?

What is the motivation behind this recommendation?

According to recommendation on JSON API specification site, we should use all lower case member names in JSON separated by hyphens:

The allowed and recommended characters for an URL safe naming of members are defined in the format spec. To also standardize member names, the following (more restrictive) rules are recommended:

Member names SHOULD start and end with the characters "a-z" (U+0061 to U+007A) Member names SHOULD contain only the characters "a-z" (U+0061 to U+007A), "0-9" (U+0030 to U+0039), and the hyphen minus (U+002D HYPHEN-MINUS, "-") as separator between multiple words.

So basically, we should be using JSON like this:

{
    "first-name": "Jason",
    "last-name": "Tough"
}

Would not it make it cumbersome to access those properties in JavaScript? Or any other programming language for that matter, especially if we want to generate classes from JSON Schema?

What is the motivation behind this recommendation?

• javascript
• json
• rest
• jsonschema

• 1 It explains the motivation: to use characters that are safe in a URL. – Barmar Commented Feb 4, 2016 at 3:16
• 2 Yeah. That spec is stupid because underscore (_) is a url safe character. I guess 1. they thought using - saves them from typing shift and 2. they're not javascript programmers so have never used the foo.bar syntax much. Any JSON specification that does not make javascript usage a priority is bound to fail – slebetman Commented Feb 4, 2016 at 3:34
• i would not describe array syntax or template expressions as "very cumbersome". – dandavis Commented Feb 4, 2016 at 4:04
• It is worth mentioning that other recommendations such as CamelCase (mostly Java) is also widely used so firstName and last-name and anObjectWithAttributteFooBar are seen... The thing is, since legacy system do not have common rules, they are usually used until they start glitching, and people create a new standard to solve major issues... – Bonatti Commented Jun 2, 2016 at 14:24
• What alternative would you propose? I like lower-case everything because it means one less step when dealing with user-input. I like - because _ is difficult to read sometimes and, as lazy as this sound, _ requires pressing shift where - does not. – IMTheNachoMan Commented Jun 2, 2016 at 14:25

2 Answers 2

Looks like JSONAPI naming from the quote in question is no longer valid. Currently the `JSONAPI recommends:

Naming

The specification places certain hard restrictions on how members (i.e., keys) in a JSON:API document may named. To further standardize member names, which is especially important when mixing profiles authored by different parties, the following rules are also recommended:

Member names SHOULD be camel-cased (i.e., wordWordWord)
Member names SHOULD start and end with a character “a-z” (U+0061 to U+007A)
Member names SHOULD contain only ASCII alphanumeric characters (i.e., “a-z”, “A-Z”, and “0-9”)

so above example should be:

{
    "firstName": "Jason",
    "lastName": "Tough"
}

I have had the same question about that, i found this explanation about why i shouldn't use a underscore with namingDirectives. it's not the same but it looks pretty similar:

The UNDERSCORE character ("_") may be used in filenames and directory names where an application (unavoidably) generates this character, but in general, use of HYPHEN to mark juncture is preferable; the UNDERSCORE character may be visually confused with SPACE or an underline-effect in some predictable publication contexts. An UNDERSCORE must never be used in a filename or directory name that is used in a document URI — that is, a primary URI reference published as a document cover page URI (i.e. as required for identification of a Work Product as a whole or for identification of a separately-titled prose Part in a Multi-Part Work Product).