Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Recommending camelCase for JSON members #1255

Closed
garrettmac opened this issue Feb 10, 2018 · 11 comments

Comments

@garrettmac
Copy link

commented Feb 10, 2018

As suggested by @dgeb I'm moving my PR #1247 into an issue for recommending camelCase for JSON members.

The gist of my argument couldn't have been said better than the point @dgeb mentions in #1247

We may have placed too much emphasis on correlating case between URLs and JSON members in forming our current recommendations.


I wanted to first mention it's JSON, which stands for Javascript Object Notation, therefor should be in camelCase.

In addition I also wanted to share the following:

Several well-established style guides recommend camelCase:


JSON.org:

  • Property names must be camel-cased, ascii strings.

Google JSON Style Guide (they follow the JSON.org spec):

  • Property names must be camel-cased, ascii strings.

Crockford state:

  • Most variables and functions should start with a lower case letter.
  • Names should be formed from the 26 upper and lower case letters (A .. Z, a .. z), the 10 digits (0 .. 9)

Schema.org

Properties start with a lower case letter and are also camelCase.

W3resource(same thing) state:

Property names must be camel-cased, ascii strings.

camelCase in the wild:


kebab-case does not play nicely with JSON. Some examples include:

  • JavaScript (you cannot do person.first-name)
  • EmberJs Framework
  • Schema.org / JSON-LD
    and
  • GraphQL / GraphQL Queries? (maybe? not actually sure on this one, admittedly haven't done much here)

I would enjoy feedback from the maintainers of the project and the community.

@dgeb

This comment has been minimized.

Copy link
Member

commented Feb 10, 2018

@garrettmac Thank you for opening this as an issue for discussion separate from your original PR.

I am generally in favor of changing this recommendation for JSON members as you've proposed. I have come to believe that ease of use with JavaScript and minimizing the likelihood of serialization/deserialization processing should take higher precedence than strict fidelity with URL naming recommendations.

However, this decision does have a bit of a ripple effect.

I have not heard a strong argument to change the recommendations for URL segments from kebab-case. And the current recommendation for resource collection URLs is:

It is recommended that the URL for a collection of resources be formed from the resource type.

We could change the recommendation for resource types to follow the general JSON member recommendation, which would involve changing this URL recommendation to involve a transformation. However, it's also possible to just leave this alone by keeping the recommendation for resource types as kebab-case.

And if we accept a transformation, then it's also possible to consider changing the recommendation for resource types to be singular instead of plural (which is not a purely mechanical transformation).

Anyway, I'm just pulling on these threads a bit because everything's connected and we want to have a coherent set of recommendations.

@jeremiahlee

This comment has been minimized.

Copy link

commented Feb 10, 2018

I oppose changing the recommendation to camelCase. Kebab-case is easier to serialize/deserialize than camelCase for languages and frameworks that do not use camelCase idiomatically.

If JSON API is meant to be a wire protocol, the data structures should be optimized for the transport of data. Using the response JSON as a direct interface to the data does not seem to be the intent of the specification. A JSON API response for a compound document, for example, is not a particularly convenient data structure to use directly. It's meant to be mapped to an application's data model before the application uses it.

@ubsan

This comment has been minimized.

Copy link

commented Feb 11, 2018

why not just use underscores? that's easily useable from javascript, works well with (de)serialization, and is easy to translate into URLs?

@marceloverdijk

This comment has been minimized.

Copy link

commented Feb 11, 2018

In non JSONAPI services I always used snake case over camel case.
I prefer it over camel case especially for readability. Honestly, I did not use kebab case before using JSONAPI and also wouln’t use kebab case for any non JSONAPI service.

However I have no objection against recommending for camel case.

Camel case in url’s I would not favor, in that case I prefer kebab case.

I think for JSONAPI recommending the kind of naming conventions is a good thing.
E.g. I also would like a recommendadtion for pagina info.

@jlaustill

This comment has been minimized.

Copy link

commented Feb 11, 2018

I have actually written a custom parser that first converts keys from kebab-case to camelCase and then serialized it. My only concern would be breaking backwards compatibility. I'm commenting mainly to follow this conversation...

@joukevandermaas

This comment has been minimized.

Copy link
Contributor

commented Feb 13, 2018

Seems to me like this ship has sailed. No library implementation wants to change its default because it would break their users. I know mine won't (Saule). The spec still allows camel case so what's the problem?

@anik786

This comment has been minimized.

Copy link

commented Feb 18, 2018

I would really like an official recommendation by json-api themselves, regarding if I should use camel case or snake case for JSON members. At least that way we have consistency.

@antonkomarev

This comment has been minimized.

Copy link

commented Mar 1, 2018

Thank you for starting this thread. Naming questions are always hard ones, and it would be better to have recommendations for all the parts of the specification.

We've discussed keys name convention in our company so far and one of the benefits of the kebab-case in property names over snake_case was consistency of document data format and consistency of the URI parts format.

Instead of snake_case:
http://localhost/some-endpoint?include=some_relation&fields=field_one

Or camelCase:
http://localhost/some-endpoint?include=someRelation&fields=fieldOne

kebab-case looks more consistent:
http://localhost/some-endpoint?include=some-relation&fields=field-one

Same for the document body.

But at the end, frontend team doesn't care about json properties naming because normalizer converts them to camelCase right after fetching the data. Additionally we've found that some libraries camelize types of the resources to match camelized property names. So frontend guys camelizing all the keys & types for easier search through the local data repository.

If choosing between snake_case and kebab-case, kebab is better to keep data consistent. But when starting to compare camelCase with kebab-case it starts to be much harder to decide what to choose.

I can see two benefit from camelCase in document body at this moment:

  • it's produces shortestVariantOfTheString and minimizes payload;
  • frontend teams camelizing all the properties while normalizing data, then this process will be faster.

If we'll have camelCase in URI query part I can see only one benefit:

  • lower string length what allows to have a bit more characters in query.

But if we'll have kebab-case in URI and camelCase in body - it will be pretty strange that ?include=some-relation&fields=field-one returns relationship someRelation and field fieldOne.

Keep in mind that backend libraries could returns data in the same format you've requested it in URI. So if you'll write ?include=test_me you will have relationship test_me, but if you'll write ?include=testMe, you'll have relationship testMe.

I'd vote for consistency. If make document properties camelCase, then same should be done for URI Query part and resource types too. It will be easier to perform comparisons and searches over the local storage.

@antonkomarev

This comment has been minimized.

Copy link

commented Mar 5, 2018

I understood one more thing. If we'll make relationships camelized then relationship links will be camelized too: /parent/{parent-id}/relationships/childResource. And to keep same naming convention it will require to camelize not only URI query part, but all the URIs.
http://localhost/someEndpoint?include=someRelation&fields=fieldOne

@antonkomarev

This comment has been minimized.

Copy link

commented Mar 5, 2018

@dgeb is there any recommendations from W3C or something similar what declare that URI should be lower-cased?

Personally I've used hyphens all the time in URIs, it works great for SEO. But now I understand that front-end application could have human-readable endpoints with kebab-case slugs, and back-end application which exposes machine readable API don't have this requirement. Or am I missing something important?

I've found only W3C: HTML and URLs:

There may be URLs, or parts of URLs, where case doesn't matter, but identifying these may not be easy. Users should always consider that URLs are case-sensitive.

Here is WHATWG URL Specification, but there is nothing about camel or kebab case there.

There are a lot of discussions on stack overflow related to this question, here is one of them: https://stackoverflow.com/questions/10302179/hyphen-underscore-or-camelcase-as-word-delimiter-in-uris

@ethanresnick

This comment has been minimized.

Copy link
Member

commented Oct 7, 2018

Closed by #1297.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
10 participants
You can’t perform that action at this time.