JSON Formatting Best Practices: Write, Validate, and Debug JSON
Learn JSON syntax rules, common formatting mistakes, validation strategies, and how to work with nested structures in APIs.
Why JSON Formatting Matters
JSON (JavaScript Object Notation) is the de facto standard for data exchange on the web. Whether you are building a REST API, configuring a build tool, or storing application settings, well-formatted JSON is easier to debug, maintain, and collaborate on. Poorly formatted JSON wastes developer time with preventable syntax errors.
JSON Syntax Rules You Must Know
- Keys must be double-quoted. Single quotes and unquoted keys are invalid.
{"name": "value"}is correct;{name: "value"}is not. - Strings use double quotes. Single-quoted strings are not valid JSON.
- Trailing commas are forbidden.
{"a": 1, "b": 2,}will fail to parse. - Comments are not supported. Unlike JavaScript, JSON has no comment syntax. Use a description field if you need to annotate your data.
- Data types: JSON supports strings, numbers, booleans (
true/false),null, objects, and arrays. No dates, no undefined, no functions.
Common Formatting Mistakes
Mistake 1: Copying from a Console Log
Browser console.log() output is not valid JSON. It may show undefined values, single quotes, or trailing commas that a JSON parser will reject. Always use JSON.stringify() to produce valid JSON from a JavaScript object.
Mistake 2: Escaping Gone Wrong
Strings containing quotes, backslashes, or control characters need proper escaping. A stray backslash can break the entire document. Use a JSON validator to catch these issues early.
Mistake 3: Number Precision
JSON numbers are IEEE 754 double-precision floating point. Very large integers (beyond 2^53) lose precision. For financial or high-precision data, store numbers as strings and parse them with a big-number library.
Why Pretty-Printing Matters
Minified JSON (no whitespace) saves bandwidth but is unreadable for humans. Pretty-printing adds indentation and line breaks, turning a wall of text into a scannable structure. During development and debugging, always pretty-print your JSON. In production, minify it for transfer and pretty-print on the client side if needed.
A consistent 2-space indent is the most common convention. Some teams prefer 4 spaces or tabs; what matters is consistency within a project.
Validation Strategies
Validation catches errors before they reach production. Three approaches work well together:
- Syntax validation checks whether the JSON is well-formed. Most editors do this automatically.
- Schema validation (using JSON Schema) checks whether the data conforms to expected types, required fields, and value constraints.
- Contract testing verifies that API responses match the expected shape, often integrated into CI pipelines.
Working with Nested Structures
Deeply nested JSON is hard to read and slow to parse. Flatten structures where possible. If an API returns objects nested five levels deep, consider transforming the data into a flatter shape on the client. Keep nesting to three levels or fewer when you control the schema.
JSON vs Other Formats
JSON has largely replaced XML for APIs because it is less verbose and maps directly to native data structures in most languages. YAML is a superset of JSON that supports comments and is popular for configuration files. TOML is another configuration format with a simpler grammar. Choose JSON for APIs and data exchange; use YAML or TOML for configuration.