JSON Property Naming¶

Context¶

This guideline applies to all APIs using JSON as message serialization format.

Description¶

JSON property names MUST be formatted according to camelCase, with following rules

• Names MUST start with a lower case letter
• Names consisting of multiple words MUST be concatenated seamlessly and the first character of every concatenated word is capitalized
• Abbreviations and acronyms MUST be treated as words where only the first character is capitalized in case of concatenation (e.g. abbreviation Id for Identifier, acronym Xml instead of XML)
• Names MUST only consist of ASCII characters [a-z], [A-Z], and [0-9]

Additionally, the following rules SHOULD be observed for creating good names

• Words in names SHOULD use American English
• Names SHOULD be kept short and concise
• Names consisting of multiple words SHOULD be "readable" as if they were continuous text
• Abbreviation of everyday language words SHOULD NOT be used, besides in cases where abbreviated forms are the commonly used form
• The context of a name SHOULD be taken into account to decide if a prefix is necessary for a name. E.g., the properties of a resource course are automatically understood to be course properties. So a property name of a course should not be named courseName but just name when appearing inside a course schema.

Examples¶

Example JSON document with properties named according to above rules

{
  "name": "Max Mustermann",
  "firstName": "Max",
  "dateOfBirth": "2000-01-01",
  "iotDevices": [ {} ],
  "sharedIotDevices": [ ... ]
}

The following shows examples NOT following the camelCase rules.

{
  "Name": "Max Doe",
  "first_name": "Max",
  "date-of-birth": "2000-01-01",
  "iotdevices": [ ... ],
  "sharedIOTDevices": [ ... ],
}

The next examples show how to use context in naming properties.

{
  "type": "person",
  "attributes": {
      "name": "Max Doe",
      "fathersName": "Jon Doe"
  }
}

{
  "page": {
      "size": 42
  }
}