JSON Best Practices: Formatting, Validation, and Common Pitfalls

What Is JSON?

JSON (JavaScript Object Notation) is a lightweight, text-based data format specified in RFC 8259. It represents data as key-value pairs, arrays, strings, numbers, booleans, and null. Despite originating from JavaScript syntax, JSON is language-independent and is now the default data format for REST APIs, configuration files, and message queues worldwide.

JSON Syntax Fundamentals

A valid JSON document is one of: object, array, string, number, boolean, or null.

{
  "name": "Alice",
  "age": 30,
  "active": true,
  "address": {
    "city": "Berlin",
    "zip": "10115"
  },
  "tags": ["developer", "designer"],
  "notes": null
}

Common syntax rules that trip people up:

Keys must be double-quoted strings — single quotes are invalid: {'key': 'value'} is not JSON
Trailing commas are not allowed — [1, 2, 3,] is invalid JSON (though JavaScript allows it)
Comments are not supported — there is no // comment or /* */ in JSON
Numbers cannot have leading zeros: 07 is invalid
Strings must escape special characters: ", \, , , \uXXXX

Common JSON Parsing Errors and How to Fix Them

Unexpected token

// Invalid — single quotes and trailing comma
{'name': 'Alice', 'age': 30,}

// Valid
{"name": "Alice", "age": 30}

Precision loss with large numbers

JSON numbers map to IEEE 754 double-precision floats in JavaScript. Integers larger than Number.MAX_SAFE_INTEGER (2^53 - 1 = 9,007,199,254,740,991) lose precision:

JSON.parse('{"id": 9007199254740993}')
// → {id: 9007199254740992}  ← precision loss!

For large integers (like database IDs, snowflake IDs), transmit them as strings in JSON and parse them with a BigInt-aware library.

Circular references

const obj = {};
obj.self = obj;
JSON.stringify(obj); // TypeError: Converting circular structure to JSON

Use a replacer function or a library like flatted to handle circular structures.

JSON Schema Validation

JSON Schema (defined at json-schema.org) is a vocabulary for describing the structure of JSON documents. Use it to validate API inputs and catch malformed data early.

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

Validation libraries: ajv (Node.js), jsonschema (Python), networknt/json-schema-validator (Java).

Security Considerations

JSON injection

If user input is embedded directly into a JSON string without proper escaping, an attacker can inject additional JSON fields or corrupt the structure. Always use a proper serialization function (JSON.stringify()) rather than building JSON by string concatenation.

// WRONG — vulnerable to injection if username contains quotes or backslashes
const json = '{"user": "' + username + '"}';

// CORRECT
const json = JSON.stringify({ user: username });

Prototype pollution

Parsing JSON that contains __proto__ or constructor keys can pollute JavaScript object prototypes in some libraries:

// Dangerous with vulnerable parsers
JSON.parse('{"__proto__": {"isAdmin": true}}')

Use libraries that are prototype-pollution safe, or sanitize keys after parsing in security-sensitive contexts.

Large payload DoS

Deeply nested or very large JSON payloads can cause stack overflows or excessive memory use during parsing. Set maximum payload sizes in your HTTP framework (express.json({ limit: "1mb" })) and consider depth limits for untrusted inputs.

API Design Best Practices

Use camelCase or snake_case consistently — pick one convention and stick to it across your entire API
Use ISO 8601 for dates — "2025-06-12T10:30:00Z" is unambiguous; Unix timestamps are also acceptable
Wrap responses in a consistent envelope — {"data": {...}, "error": null} makes client handling predictable
Version your API — adding fields is backward compatible; removing or renaming fields is not
Return meaningful null vs. missing key — {"value": null} means "value exists but is null"; omitting the key means "value not applicable"

Formatting and Minification

Use pretty-printed JSON during development for readability, minified JSON in production for smaller payloads:

// Pretty (development)
JSON.stringify(obj, null, 2);

// Minified (production)
JSON.stringify(obj);

Use the Copynix JSON Formatter to instantly format and validate JSON in your browser. It highlights syntax errors, supports pretty-print and minify modes, and handles large payloads without sending any data to a server.

JSON Alternatives Worth Knowing

JSON5 — superset of JSON that allows comments, trailing commas, and single quotes. Good for config files.
JSONC — JSON with comments, used by VS Code (tsconfig.json).
MessagePack — binary JSON equivalent, ~30% smaller, faster to parse.
Protocol Buffers (protobuf) — Google's binary format with strict schema. Much more compact and faster for high-throughput internal APIs.

Summary

JSON is simple by design, but its edge cases (large numbers, circular references, security pitfalls) create real bugs in production systems. Validate API inputs with JSON Schema, serialize with JSON.stringify() (never string concatenation), set payload limits, and use ISO 8601 for dates. These practices catch the majority of JSON-related bugs before they reach users.