Need help with your JSON?

Try our JSON Formatter tool to automatically identify and fix syntax errors in your JSON. JSON Formatter tool

Reserved Words as Keys in JSON: Why They Cause Problems

While JSON itself is relatively forgiving about what names you can use for keys, the programming languages and environments that process JSON often have limitations. Using reserved words as keys in JSON can lead to unexpected errors and complications when this data is parsed and used in different programming languages. This article explains what reserved words are, why they cause problems, and how to avoid these issues in your JSON data.

What Are Reserved Words?

Reserved words (also called keywords) are identifiers that have special meaning in a programming language. They cannot be used as variable names, function names, or in other contexts where identifiers are expected, because they are part of the language's syntax.

For example, words like if, else, for, function,return, class, and this are reserved in many programming languages.

JSON and Reserved Words

According to the JSON specification (RFC 8259), there are no restrictions on what strings can be used as object keys. Technically, this means that in pure JSON, you can use any string as a key, including reserved words from programming languages:

Valid JSON with potentially problematic keys:

{
  "class": "admin",
  "if": true,
  "function": "calculateTotal",
  "return": 42,
  "this": "refers to the current object"
}

This JSON is perfectly valid according to the specification, but it may cause problems when used in specific programming environments.

Why Reserved Words Cause Problems

The complications arise not in the JSON format itself but when the JSON data is:

Parsed into native objects: When JSON is converted to objects in programming languages
Accessed using dot notation: Languages that use dot notation to access object properties can have conflicts
Used in generated code: Auto-generated code might fail to compile if it includes reserved words
Processed by certain frameworks: Some frameworks and libraries apply additional restrictions

1. Problems with Dot Notation

One of the most common issues occurs when using dot notation to access properties:

JavaScript example:

// Parse valid JSON with reserved words as keys
const data = JSON.parse('{"class": "admin", "if": true, "function": "calculateTotal"}');

// This will cause a syntax error!
console.log(data.class);     // Error: unexpected token: class
console.log(data.if);        // Error: unexpected token: if
console.log(data.function);  // Error: unexpected token: function

2. Framework and Library Restrictions

Many frameworks and libraries that work with JSON impose additional restrictions:

GraphQL: Field names cannot start with double underscores (__) as these are reserved for internal use
MongoDB: Field names cannot contain dollar signs ($) or dots (.)
Database ORMs: Many ORMs have restrictions on field names that map to database columns
Template engines: Various template engines may have reserved words for their own syntax

3. Language-Specific Issues

JavaScript:

Cannot use dot notation with reserved words like class, for, if
Must use bracket notation: data["class"] instead of data.class

Python:

Reserved words like class, if, else as keys require dictionary access (data["class"])
When creating objects with these keys, attribute access (data.class) won't work

Java:

When deserializing JSON to Java objects, reserved words can't be used as field names
Requires special annotations or naming strategies to handle such fields

TypeScript:

When defining interfaces for JSON objects, reserved words require special syntax
Must use string literals in interface definitions: { "class": string }

Best Practices to Avoid Problems

Avoid using reserved words as keys: The simplest solution is to not use reserved words from major programming languages
Use alternative naming conventions: Instead of "class", use "className" or "classType"
Follow camelCase or snake_case consistently: This helps avoid many reserved words
Use prefixes: Add descriptive prefixes like "user_class" instead of just "class"
Know your target languages: Be aware of reserved words in the languages that will process your JSON

Common Reserved Words to Avoid

Here's a list of common reserved words across multiple programming languages that are best avoided as JSON keys:

abstract
await
break
case
catch
class
const
continue

debugger
default
delete
do
else
enum
export
extends

false
finally
for
function
if
implements
import
in

Working with Reserved Words When Necessary

Sometimes you might need to work with JSON that already contains reserved words as keys. Here are techniques to handle this:

1. Use Bracket Notation

// JavaScript example
const data = JSON.parse('{"class": "admin", "if": true}');

// Use bracket notation instead of dot notation
console.log(data["class"]); // Works: "admin"
console.log(data["if"]);    // Works: true

2. Property Mapping

// Map problematic property names to safe names
function safeObject(jsonObject) {
  const mappings = {
    "class": "className",
    "if": "condition",
    "function": "functionName"
  };
  
  const result = {};
  for (const key in jsonObject) {
    const safeKey = mappings[key] || key;
    result[safeKey] = jsonObject[key];
  }
  
  return result;
}

// Usage
const safeData = safeObject(data);
console.log(safeData.className);  // "admin"
console.log(safeData.condition);  // true

Important Note:

While JSON itself allows any string as a key, it's best to design your JSON with the destination language and framework in mind. This preventative approach saves troubleshooting time and makes your JSON more universally usable across different programming environments.

Need help with your JSON?

Try our JSON Formatter tool to automatically identify and fix syntax errors in your JSON. JSON Formatter tool