I see a lot of questions revolving around accessing JSON keys that use hyphens (kebab-case), but now I find myself wondering should I just stick to camelCase or snake_case in my keys. I know hyphens also can create complicated mappings when ported between languages. I've seen some JSON deserialize libraries convert those keys to a camelCase style.


var something = {
  "some-value": 'thing'


var something = {
  "someValue": 'thing',
  "some_other_value": 'thing_two'
  • 4
    REST has nothing to say about payload formats.
    – Eric Stein
    May 28 '16 at 17:24
  • 1
    Good to know, I am still curious if there are any best practices around JSON formatting. May 28 '16 at 17:27
  • 2
    Why do you use kebab-case in JSON? People usually use camelCase for JSON because it's always good practice to follow the naming conventions of the programming environment and it's standard practice to use camelCase for variables in JavaScript. Though I'm going by the assumption that you're using JSON to communicate with JavaScript.
    – Alternatex
    May 28 '16 at 17:41
  • 5
    It is not really a bad practice, since JSON is language independent and therefore shouldn't be constrained by the syntax of any particular language. That said, it makes sense to use only alphanumerical characters, since this can map directly to identifiers in all mainstream languages, so this will just lead to the least amount of mapping trouble.
    – JacquesB
    May 29 '16 at 19:07
  • 2
    @Alternatex: +1 for "kebab-case" :-)
    – gnasher729
    Nov 3 '16 at 20:40

You can use anything as JSON keys, as long as it is valid UTF-8, doesn't contain zero code points, and it would be useful if you could represent the key as a string in the programming language of your choice. I might recommend not to use different Unicode representations of the same string (for example "Ä" written as one or two code points).

Reading some comments: It seems some people try to create classes with instance variables that match the keys in JSON dictionaries. Which of course doesn't work if your key is "some-value" unless you write COBOL. I think this is misguided. I have model classes which are designed the way I want them. JSON is just used to fill the model classes. I'll take whatever the server guys decided to use for the keys and put it into my model objects.

  • 2
    urg, you beg the question of how your consuming program accesses the json keys. Commonly this is done by parsing the json as an object. Using hypens or other characters which prevent this just makes life hard for your consumers
    – Ewan
    May 30 '16 at 22:44
  • 1
    And this is valid: {"❓":"✅"} May 17 '19 at 21:26
  • 2
    How do hyphens prevent anything? I get a dictionary, and a can use "some-key" as a key, I can even use "❓" as a key.
    – gnasher729
    May 17 '19 at 23:16
  • Ewan, any JSON parser must be able to handle any string as a key. And how is handling an underscore hard? The parser uses the same code it would use for string data.
    – gnasher729
    Oct 25 '21 at 9:21
  • The ON in JSON stands for object notation, so the idea that you somehow shouldn't try to access your JSON as if it's an object makes little sense. No one is stopping you from adding an extra mapping layer if you so choose, but you could be adding that mapping layer even if you were accessing your JSON as an object.
    – Flater
    Oct 25 '21 at 10:01

There are plenty of JSON serialization systems that are more than capable of handling mapping between field names that aren't suitable for use in the language they integrate with. In most cases, they aren't hard to use, and require only a little bit of extra effort. In an ideal world, you wouldn't have to, but if your API already uses dashes, changing it would be cure worse than the disease. Also note that using dashes is the most common style in certain languages, most notably those based on LISP, so probably there's a silent minority of your API's consumers who are happy to see dashes rather than another format.

  • I will up vote this ASAP I found insight in it, Thank You. May 29 '16 at 17:21

After spending some time in the industry and working a few systems. I don't think there is a best practice or proper casing for JSON keys. The most important aspect of any formatting (casing/code-style/etc) is consistency and team adoption.

If the code base is fragmented and inconsistent, meet as a team and agree on a consistent style then police the formating collectively.


if you use hyphens, they can get treated as "minus" unless you bracket them - unaesthetic and extra typing...

    var t = json.phrase_stems.text-1;      //error
    var t = json.phrase_stems["text-1"];  //ok 

But if you need to build the string, you need brackets irrespective

    var myTextNo = 1;
    var t = json.phrase_stems["text" + myTextNo];

I prefer to avoid hyphens.


You can't use it (or at least not easily) in swift Decodable for JSON decoding, because the hypen is not acceptable charater. You can't do for example:

struct AccessToken: Decodable{
    let access_token: String
    let expires-in: Int

because the "expires-in" isn't valid as a variable name. There're solutions for that of course but it makes our job to unneccesary difficult.

  • That’s what CodingKeys is for. Basically everything is acceptable in CodingKeys. And I want to use field names in my Swift classes that follow Swift coding standards and the application’s terminology, not what the database developers want, so CodingKeys will be used anyway.
    – gnasher729
    Oct 25 '21 at 2:31
  • Please read my comment again: "There're solutions for that of course but it makes our job to unnecessary difficult." It is exactly means what you've just answered: You have to add CodingKeys instead of keep it as simple (and nice) as possible with Decodable. But if you are an API developer than maybe better to use filed names which are compatible with much languages as possible so this is why not advised to use hypen in field name. And before you answer again: please read the original question. Oct 25 '21 at 9:39

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.