JSON Formatting Tips Every Developer Should Know

JavaScript Object Notation (JSON) has become the lingua franca of data exchange on the web. Whether you're building APIs, configuring tools, or storing data, you'll encounter JSON daily. Here are the essential tips and common pitfalls every developer should know.

JSON Syntax Basics

JSON is strict about syntax. Unlike JavaScript objects, JSON has rigid rules:

Common Syntax Errors

1. Trailing Commas

The most common JSON error. That innocent comma after the last item will break everything:

{
  "name": "John",
  "age": 30,  ← trailing comma breaks parsing
}

{
  "name": "John",
  "age": 30
}

2. Single Quotes

Coming from JavaScript or Python? Double quotes only:

{
  'name': 'John'  ← single quotes not allowed
}

3. Unquoted Keys

Valid in JavaScript, invalid in JSON:

{
  name: "John"  ← key must be quoted
}

Data Type Reference

JSON supports six data types:

{
  "string": "Hello, World!",
  "number": 42,
  "float": 3.14159,
  "boolean": true,
  "null": null,
  "array": [1, 2, 3],
  "object": { "nested": "value" }
}

Formatting for Readability

Pretty Print vs. Minified

Minified JSON saves bandwidth but is impossible to read. Always pretty-print when debugging:

{"users":[{"id":1,"name":"John"},{"id":2,"name":"Jane"}]}

{
  "users": [
    {
      "id": 1,
      "name": "John"
    },
    {
      "id": 2,
      "name": "Jane"
    }
  ]
}

JavaScript Formatting Commands

Format JSON in your code or browser console:

// Pretty print with 2-space indentation
JSON.stringify(obj, null, 2);

// Minify JSON
JSON.stringify(obj);

// Parse and format a JSON string
JSON.stringify(JSON.parse(jsonString), null, 2);

Debugging API Responses

When APIs return unexpected data, follow this debugging workflow:

1. Validate the JSON: Is it even valid JSON? Paste it into a validator to check for syntax errors.
2. Pretty print: Format it to see the structure clearly.
3. Check data types: Is that "123" a string or should it be 123 (number)?
4. Look for nulls: Missing data often appears as null instead of an error.
5. Check array lengths: Empty arrays [] might indicate a query returned no results.

Special Characters and Escaping

These characters must be escaped in JSON strings:

{
  "quote": "She said \"Hello\"",
  "backslash": "C:\\Users\\John",
  "newline": "Line 1\nLine 2",
  "tab": "Col1\tCol2",
  "unicode": "Emoji: \u2764"
}

JSON5 and JSONC: When Standard JSON Isn't Enough

Standard JSON is strict for good reason—it's unambiguous. But for configuration files, that strictness can be annoying. Alternatives exist:

JSONC (JSON with Comments)

Used by VS Code, TypeScript, and other tools. Allows // and /* */ comments:

{
  // This is a comment
  "debug": true,
  
  /* Multi-line comments
     are also supported */
  "port": 3000
}

JSON5

A superset of JSON that allows trailing commas, single quotes, unquoted keys, and more. Great for human-edited configs.

Performance Tips

• Avoid deeply nested structures: Each level of nesting adds parsing overhead and complexity.
• Use consistent key ordering: Some parsers can optimize when keys are in predictable order.
• Consider alternatives for large data: For very large datasets, consider NDJSON (newline-delimited JSON) for streaming, or binary formats like MessagePack.
• Minify for production: Remove whitespace from JSON in API responses to reduce bandwidth.

Security Considerations

• Never use eval(): Always use JSON.parse() to parse JSON. eval() can execute malicious code.
• Validate input: Don't trust JSON from external sources. Validate the structure and values before using them.
• Watch for prototype pollution: Be careful when merging JSON objects into existing objects in JavaScript.

Quick Reference

JSON's simplicity is its greatest strength. Master these fundamentals, and you'll debug faster, write cleaner configs, and communicate more effectively with APIs. When in doubt, validate—a good JSON formatter will catch mistakes before they become runtime errors.