13

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?

Community
  • 1
  • 1
Sebastian K
  • 6,235
  • 1
  • 43
  • 67
  • 1
    It explains the motivation: to use characters that are safe in a URL. – Barmar Feb 04 '16 at 03: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 Feb 04 '16 at 03:34
  • i would not describe array syntax or template expressions as "very cumbersome". – dandavis Feb 04 '16 at 04: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 Jun 02 '16 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 Jun 02 '16 at 14:25
  • @slebetman Read the About page of the spec. Yehuda Katz, one of the primary editors of the spec, is the founder of Ember and has been very influential in the JS community. In fact, JSON-API came out of Ember Data. – Animal Rights Jul 22 '16 at 01:02
  • @skaterdav85: Then why does the spec look like it's written by a PHP programmer? The recommendation is simply silly. You'd want to do `obj.first-name` but that results in a syntax error in js. In PHP it is of course natural to do: `$obj["first-name"]`. Yes, you can do that in js as well but why? That reeks of PHPism – slebetman Jul 22 '16 at 01:18
  • @slebetman JSON:API is a robust specification that isn't meant to be consumed in its raw form. You'd want a serialization/deserialization layer that handles case conversion and turning resource objects into models with relationships. If you wanted a simple JSON API to be consumed in its raw form, JSON:API isn't it. The problem w/ consuming an API in raw form is that API changes can have massive impacts on your application code, requiring changes in several places. If you have a serializer layer like in Ember Data, then you can isolate API specifics to a small portion of your application code. – Animal Rights Jul 23 '16 at 07:10

2 Answers2

7

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"
}
ToTenMilan
  • 582
  • 1
  • 9
  • 19
2

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).

Charly Palencia
  • 192
  • 1
  • 8
  • 2
    But this is a very weak argument in this context. It's JSON data to be transmitted over the network, not some whitepaper. – slebetman Jul 22 '16 at 01:20