Valid Key Names in JSON

JSON (JavaScript Object Notation) is a widely used data interchange format due to its simplicity and ease of use. JSON represents the structured data and is a popular choice for configuration files, API payloads, and data exchange between systems.

In JSON, key-value pairs are used to represent objects. While JSON is flexible, it does any defined rules and conventions for key names that are adhered to for compatibility and maintainability.

This article explores the best practices and guidelines for choosing valid key names in JSON.

1. Syntax

In JSON, data is written in the form of key-value pairs. A key name serves as a unique identifier for a value within the object. The keys are written in double quotes and values are written according to their data types.

Note that the keys are case-sensitive so "id" and "ID" are treated as two different key names. For this reason alone, it is very important to have a consistent naming strategy for the keys.

In the following example, ‘id‘, ‘name‘, and ‘role‘ are the keys so they are enclosed with double quotes.

{
	"id" : 10,
	"name" : "Lokesh",
	"role" : ["admin", "author"]
}

The JSON syntax does not impose any restrictions on the strings used as key names, does not require that name strings be unique, and does not assign any significance to the ordering of name/value pairs.

Reference: ECMA-404

2. Valid Characters in JSON Key Names

According to JSON.org, a string is a sequence of zero or more Unicode characters, wrapped in double quotes, using backslash escapes. Any valid string can be used as a JSON key.

{"key" : "value"}

{"keyName" : "value"}

{"key-name" : "value"}

{"key_name" : "value"}

All code points may be placed within the quotation marks except for the following code points that must be escaped:

• quotation mark (U+0022)
• reverse solidus or backslash (U+005C)
• control characters or non-printable characters (U+0000 to U+001F) such as tab, line feed, shift, etc.

For example, if a key name contains any double quote in it, then it must be escaped as follows:

{"Some \"random\" string" : "value"}

3. Best Practices

When choosing key names for objects within the JSON data, consider the following best practices:

• Use clear, consistent, and meaningful names that make the JSON data self-documenting.
• Choose between the camel-case (‘firstName‘) or snake-case (‘first-name‘) notations, and use it consistently.
• Avoid redundancy in key names. If a key name at a higher level already implies information, there’s no need to repeat it in the nested object. For example, if we have "person" as a key name, we don’t need "person_firstName" inside the object.
• Do not use the reserved keywords that are generally used in programming languages. They can lead to unexpected behavior.
• While some JSON parsers can handle unquoted key names, it is still recommended to always use quoted strings for maximum compatibility.
• Consider using JSON Schema to define the structure and validation rules for the JSON data ensuring that the JSON documents adhere to a defined structure.

4. Summary

At a high level, defining the key names in JSON documents seems an easy task. But if we are not careful, it can go wrong anytime. While JSON schema allows us to use all valid strings as key names, still we should define our own guidelines and follow them consistently.

Happy Learning !!