JSON Formatting Best Practices

JSON (JavaScript Object Notation) has become the lingua franca of data exchange on the web. Whether you're building APIs, configuring applications, or storing data, you'll encounter JSON daily. Proper formatting makes JSON readable, debuggable, and maintainable — skills every developer needs.

What Is JSON?

JSON is a lightweight, text-based data interchange format derived from JavaScript object literal syntax. Despite its JavaScript origins, JSON is language-independent and supported by virtually every programming language. It supports six data types: strings, numbers, booleans, null, arrays, and objects. Its simplicity is its greatest strength — JSON is easy for humans to read and write, and easy for machines to parse and generate.

Formatting vs. Minification

JSON can be represented in two forms: formatted (pretty-printed) and minified. Formatted JSON uses indentation and line breaks to show structure clearly. Minified JSON removes all unnecessary whitespace to reduce file size. Both represent identical data — the difference is purely visual.

Use formatted JSON during development, in configuration files, and anywhere humans need to read it. Use minified JSON for network transmission, API responses in production, and storage where size matters. A typical API response might be 30–40% smaller when minified, which adds up at scale.

Indentation: 2 Spaces vs. 4 Spaces vs. Tabs

The most common debate in JSON formatting is indentation width. Two-space indentation is the most popular choice in the JavaScript ecosystem — it's used by npm's package.json, ESLint configurations, and most Node.js projects. Four-space indentation is common in Python-adjacent projects and enterprise Java environments. Tabs are rarely used in JSON files.

In JavaScript, JSON.stringify(data, null, 2) produces 2-space indentation, while JSON.stringify(data, null, 4) produces 4-space. The second argument is a replacer function (or null), and the third is the indentation level. For minified output, omit the third argument entirely.

Common JSON Errors and How to Fix Them

JSON is strict about syntax. Unlike JavaScript objects, JSON has specific rules that trip up developers regularly:

• Trailing commas: {"a": 1, "b": 2,} is invalid. Remove the comma after the last item.
• Single quotes: {'name': 'value'} is invalid. JSON requires double quotes exclusively.
• Unquoted keys: {name: "value"} is invalid. All keys must be double-quoted strings.
• Comments: JSON does not support comments of any kind. Use JSONC or JSON5 if you need comments.
• Undefined: undefined is not a valid JSON value. Use null instead.
• NaN and Infinity: These are not valid JSON numbers. Use null or a string representation.

Validating JSON

Always validate JSON before using it. In JavaScript, wrap JSON.parse() in a try-catch block to handle malformed input gracefully. For schema validation — ensuring JSON has the correct structure and data types — use libraries like Zod, Ajv, or Joi. Schema validation catches issues that syntactic validation misses, like missing required fields or incorrect data types.

JSON in APIs

When designing JSON APIs, follow these conventions: use camelCase for property names (most common in JavaScript APIs), use consistent date formats (ISO 8601: 2025-01-15T10:30:00Z), include pagination metadata for list endpoints, and use consistent error response structures. Avoid deeply nested objects when possible — flat structures are easier to work with.

Set the Content-Type: application/json header for JSON responses. For large responses, consider supporting field selection (GraphQL-style) or implementing JSON streaming for datasets that don't fit comfortably in memory.

JSON vs. YAML vs. XML

Each format has its strengths. JSON is ideal for data interchange, API communication, and configuration where comments aren't needed. Its parsing is fast and unambiguous. YAML supports comments, multi-line strings, and anchors/aliases — making it better for human-edited configuration files like Docker Compose or Kubernetes manifests. However, YAML's significant whitespace and implicit typing can cause subtle bugs.

XML offers namespaces, schemas (XSD), attributes, and mixed content — features needed in document-centric applications, SOAP APIs, and enterprise integrations. It's verbose but powerful. For new projects, JSON is almost always the right default for data exchange, while YAML works well for configuration files that humans edit frequently.

Performance Considerations

JSON parsing is generally fast, but can become a bottleneck with very large payloads. In Node.js, JSON.parse() blocks the event loop for large strings. Consider streaming parsers like JSONStream for files over a few megabytes. On the client side, large JSON responses increase memory usage and parsing time — paginate your APIs and only send the data clients actually need.