JSON Formatting Best Practices

Proper JSON Structure

Valid JSON is built from two fundamental structures: objects (unordered sets of key-value pairs enclosed in curly braces) and arrays (ordered lists of values enclosed in square brackets). Every key must be a double-quoted string, and values can be strings, numbers, booleans, null, objects, or arrays. No other data types are permitted.

A well-structured JSON document uses consistent indentation, meaningful key names, and a predictable hierarchy. Here is an example that follows all of these conventions:

{
  "user": {
    "id": 1024,
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "roles": ["admin", "editor"],
    "preferences": {
      "theme": "dark",
      "language": "en",
      "notifications": true
    }
  }
}

Notice the 2-space indentation, descriptive key names in camelCase, and logical grouping of related fields under nested objects. These choices are not just aesthetic -- they make the data easier to navigate when documents grow to hundreds or thousands of lines.

Common JSON Mistakes

Even experienced developers trip over JSON syntax rules that differ from JavaScript or other languages. The most frequent errors include:

• Trailing commas -- a comma after the last item in an object or array is valid in JavaScript but causes a parse error in strict JSON.
• Single quotes -- JSON requires double quotes for all strings and keys. Single quotes will fail validation.
• Comments -- the JSON specification does not allow comments of any kind. Use a separate documentation file or switch to a format like JSONC or JSON5 if you need inline annotations.
• Unquoted keys -- every key must be wrapped in double quotes, unlike JavaScript object literals.
• Numeric precision -- JSON numbers are IEEE 754 doubles, so integers larger than 2^53 lose precision. Use strings for very large IDs.

Here is an example of invalid JSON that contains several of these mistakes:

// This will NOT parse
{
  name: 'Ada Lovelace',   // unquoted key, single quotes
  "age": 36,
  "tags": ["math", "computing",],  // trailing comma
}

The corrected version removes the comment, double-quotes all keys and strings, and eliminates the trailing commas:

{
  "name": "Ada Lovelace",
  "age": 36,
  "tags": ["math", "computing"]
}

When to Minify vs. Pretty-Print

Minifying JSON strips all whitespace, newlines, and indentation to produce the smallest possible payload. Pretty-printing does the opposite, adding structure so humans can read it comfortably. Each form has its place, and using the wrong one in the wrong context wastes either bandwidth or developer time.

Use minified JSON when:

• Sending API responses in production -- smaller payloads mean faster transfers and lower bandwidth costs.
• Storing data in databases or caches where readability is irrelevant.
• Embedding JSON in URLs, query parameters, or HTML attributes.

Use pretty-printed JSON when:

• Debugging API responses locally or in development environments.
• Writing configuration files that other developers will read and edit.
• Committing JSON to version control -- formatted files produce cleaner diffs.
• Documenting data structures in wikis, READMEs, or guides.

Many teams adopt a simple rule: pretty-print in development and version control, minify in production and transit. This gives you the best of both worlds with no manual effort if you integrate formatting into your build pipeline.

JSON in APIs vs. Configuration Files

API JSON and configuration JSON serve different audiences and should be formatted accordingly. API payloads are consumed by machines -- parsers do not care about indentation, and every extra byte costs real money at scale. Configuration files, on the other hand, are read and edited by humans who need to understand the structure at a glance.

For APIs, follow these conventions:

• Use consistent key naming. Most REST APIs use camelCase (firstName) or snake_case (first_name) -- pick one and enforce it project-wide.
• Set the Content-Type header to application/json so clients parse the response correctly.
• Return minified JSON in production. Let clients pretty-print if they need to.
• Wrap collections in a top-level object ({"data": [...]}) rather than returning a bare array, which makes it easier to add metadata like pagination later.

For configuration files (such as package.json, tsconfig.json, or CI pipeline configs):

• Always pretty-print with 2-space indentation.
• Sort keys alphabetically where order does not matter, so version-control diffs stay minimal.
• Add a $schema reference at the top when one is available -- editors like VS Code will provide autocomplete and inline validation automatically.

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "strict": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

Validating with JSON Schema

JSON Schema is a powerful standard for describing the expected shape of a JSON document. You write a schema that declares required fields, data types, allowed values, and constraints, then validate incoming data against it at runtime or in your CI pipeline. This catches structural problems before they cause runtime errors deep in your application logic.

Here is a minimal JSON Schema that validates a user object:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 0
    }
  },
  "additionalProperties": false
}

Popular validation libraries include ajv for JavaScript, jsonschema for Python, and everit-org/json-schema for Java. Integrating schema validation into your test suite or API middleware ensures that every JSON payload conforms to the contract you have defined, eliminating an entire category of bugs.

Linting and Automating JSON Quality

Linting goes beyond syntax validation. A JSON linter checks for style issues like inconsistent indentation, unsorted keys, or duplicate keys that are technically valid but almost always a mistake. Automating these checks in your workflow prevents formatting debates in code reviews and catches errors before they reach production.

Practical steps you can take today:

• Editor integration -- install a JSON language extension in VS Code, IntelliJ, or your editor of choice. Most will validate syntax in real time and offer auto-formatting on save.
• Pre-commit hooks -- use tools like prettier or jsonlint in a Git pre-commit hook so malformed JSON never makes it into the repository.
• CI checks -- add a validation step to your CI pipeline that runs json_verify, python -m json.tool, or a similar command against all JSON files in the project.
• Schema validation in tests -- write unit tests that validate sample payloads against your JSON Schema definitions, catching drift between your code and your documentation.

Consistent linting and formatting reduce cognitive load for everyone on the team. When every JSON file follows the same conventions, developers spend less time parsing structure and more time understanding data.