Need help with your JSON?

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

JSON Quoting Styles and Formatting Preferences

JSON (JavaScript Object Notation) is a lightweight data-interchange format that is easy for humans to read and write and easy for machines to parse and generate. While its structure is simple, adhering to its strict syntax rules, particularly regarding quoting, and maintaining consistent formatting are crucial for valid and readable JSON.

The Strict Rule: Double Quotes Only

One of the most common sources of JSON errors is the incorrect use of quotes. Standard JSON specifies that both object keys (property names) and string values *must* be enclosed in double quotes (`"`).

Correct (Standard JSON) Quoting:

{
  "name": "Alice",
  "age": 30,
  "isStudent": false,
  "courses": ["Math", "Science"]
}

Keys ("name", "age", "isStudent", "courses") and string values ("Alice", "Math", "Science") are enclosed in double quotes.

Why Single Quotes Are Invalid in Standard JSON

Unlike many programming languages (including JavaScript itself), standard JSON does not allow single quotes (`'`) for keys or string values. Using single quotes will cause a JSON parser to fail.

Incorrect (Invalid Standard JSON) Quoting:

{
  'name': 'Bob', // Invalid: single quotes used for key and value
  "city": "London"
}

The single quotes around 'name' and 'Bob' make this invalid JSON according to the specification.

JSON5: A More Permissive Alternative

Sometimes, when dealing with configuration files or data that is primarily hand-edited, developers might encounter JSON5. JSON5 is a superset of JSON that aims to be easier for humans to write and maintain. It allows:

Comments (single-line and multi-line)
Trailing commas in objects and arrays
Unquoted object keys (if they are valid identifiers)
Single quotes for strings

Valid JSON5 Example:

{
  // Configuration settings
  name: 'Charlie', // Unquoted key, single quoted value
  age: 25,
  items: [
    "apple",
    'banana', // Single quoted string in array
    // Comment inside array
  ], // Trailing comma
}

This is valid JSON5 but invalid standard JSON. Always check if the parser you are using supports JSON5 or only standard JSON.

Formatting Preferences: Readability and Consistency

Beyond the strict syntax, how JSON is formatted significantly impacts its readability. Common formatting preferences include:

1. Indentation

Using indentation (spaces or tabs) to show the hierarchical structure of the data. Common practices are 2 or 4 spaces per level, or a single tab.

// 2 Spaces
{
  "user": {
    "id": 1,
    "name": "Dave"
  }
}

// 4 Spaces
{
    "user": {
        "id": 1,
        "name": "Dave"
    }
}

// Tabs
{
	"user": {
		"id": 1,
		"name": "Dave"
	}
}

2. Whitespace Around Colons and Commas

Adding spaces after colons (`:`) and commas (`,`) is standard practice for better readability.

// Good whitespace
{
  "key1": "value1",
  "key2": 123
}

// Poor whitespace (valid but hard to read)
{"key1":"value1","key2":123}

3. Order of Keys (Less Common)

While JSON object key order is not guaranteed by the specification (parsers may or may not preserve it), some teams prefer to alphabetize keys in their source JSON files for consistency when reading and comparing different versions.

Why Consistent Formatting Matters

Readability: Well-formatted JSON is much easier for humans to read and understand, reducing the chance of manual errors.
Maintainability: Consistent style makes it easier for multiple people to work on the same JSON files.
Version Control: Standardized formatting minimizes unnecessary changes in version control systems (like Git), making diffs clearer and focusing on actual data changes, not just formatting shifts.

Tools for Formatting JSON

Fortunately, you don't have to manually format JSON. Many tools and editors offer automatic formatting:

Code Editors: VS Code, Sublime Text, Atom, and most modern editors have built-in or plugin-based JSON formatters.
Online JSON Formatters: Many web-based tools allow you to paste JSON and get a formatted output. Look for offline-capable options if you work with sensitive data.
Command-Line Tools: Tools like `jq` (for processing JSON) or even Python's `json.tool` can be used to validate and format JSON from the command line.
Prettier/ESLint: Code formatters and linters used in software development projects often include JSON formatting capabilities.

Pro Tip:

When collaborating, agree on a standard JSON formatting style (e.g., 2 spaces for indentation) and use automated tools to apply it consistently across your project. This avoids disputes and messy version control histories.

Conclusion

While JSON's syntax is minimal, understanding and applying its strict rules, especially the requirement for double quotes, is fundamental. Beyond syntax, consistent formatting through indentation and whitespace significantly enhances readability and ease of maintenance.

Leverage available tools to automate formatting and validation. Whether you stick to standard JSON or use a more permissive format like JSON5 where appropriate, prioritizing valid syntax and consistent style will make working with JSON much smoother.

Need help with your JSON?

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