Complete Guide to JSON Formatting and Validation
What is JSON?
JSON (JavaScript Object Notation) is a lightweight, human-readable data interchange format originally derived from JavaScript object syntax. Despite its JavaScript origins, JSON is language-independent and is now the default format for REST APIs, configuration files, NoSQL databases like MongoDB, and inter-service communication across virtually every programming stack. A valid JSON document is either an object (key-value pairs in curly braces), an array (ordered list in square brackets), or a primitive value (string, number, boolean, or null).
Why does formatting matter?
When JSON is sent over a network or generated by a program, it is typically minified — all whitespace stripped — to minimize payload size and improve transmission speed. While minified JSON is machine-efficient, it is impractical for human inspection. A single-line blob of hundreds of nested properties is unreadable and nearly impossible to debug. Formatting restores indentation and newlines so the data hierarchy becomes immediately visible. This matters in code reviews, debugging sessions, and when writing configuration files that your team will maintain over time.
Common JSON errors and how to fix them
Trailing commas are the most common mistake: `{"key": "value",}` is invalid JSON even though it works in JavaScript. Remove the comma after the last item in any object or array. Single quotes are another frequent error — all strings and property names must use double quotes. Unescaped control characters inside strings (literal newlines, tabs, or backslashes) must be written as escape sequences: \n, \t, \\. Comments are not supported in standard JSON despite being common in JavaScript — if you need comments in config files, consider JSON5 or JSONC format.
JSON vs XML: choosing the right format
JSON is more compact, easier to read, and natively supported in every modern programming language, making it the default choice for web APIs and configuration files. XML offers more power when you need document-centric features: namespaces, mixed content (text alongside child elements), XSLT transformation, or formal schema validation via XML Schema Definition. For most modern API development, JSON is the right choice. XML still dominates in enterprise integration, document formats (DOCX, XLSX, SVG), and legacy systems built on SOAP or RSS.
JSON data types
JSON supports exactly six data types: string (always double-quoted Unicode text), number (integers or decimals, no quotes), boolean (the literals true or false), null (the literal null), object (key-value pairs in curly braces), and array (ordered list in square brackets). Notice what JSON does NOT support: dates (use ISO 8601 strings instead), undefined, functions, regular expressions, or BigInt. When you need to represent a date in JSON, always use a standardized string like "2026-05-16T00:00:00Z" so any language can parse it correctly.
Validating JSON in your code
In JavaScript and TypeScript, wrap JSON.parse() in a try-catch block to validate. In Python use json.loads() with a json.JSONDecodeError handler. For validating the structure of JSON (not just syntax), use JSON Schema — a standard that lets you declare which fields are required, what types they must be, and what constraints apply. Libraries like Ajv (JavaScript), jsonschema (Python), and go-jsonschema (Go) implement JSON Schema. In TypeScript, Zod provides runtime validation with automatic TypeScript type inference, which is ideal for validating API responses at the boundary of your application.
Best practices for JSON in production
Always validate JSON at your application boundary — when receiving input from users or external APIs — not just in your internal code. Use consistent casing for keys; camelCase is conventional in JavaScript APIs, snake_case in Python. Prefer explicit null over omitting fields so your consumers can distinguish 'not provided' from 'set to null'. For performance-sensitive APIs, measure the trade-off between JSON and binary formats like Protocol Buffers or MessagePack — binary formats are faster to parse and smaller, but lose human readability. Document your JSON structures with JSON Schema so consumers have a machine-readable specification.