JSON Complete Guide: Syntax, Validation, and Best Practices
Everything you need to know about JSON — syntax, data types, validation, formatting best practices, and the most common errors developers encounter.
Advertisement
JSON (JavaScript Object Notation) has become the universal language of web APIs and configuration files. Lightweight, human-readable, and natively supported in every major programming language, JSON has largely replaced XML as the data interchange format of choice. This guide covers everything from basic syntax to production best practices.
What Is JSON?
JSON is a text-based data interchange format derived from JavaScript object literal notation. Despite its name, JSON is completely language-independent — parsers exist for Python, Ruby, Java, Go, PHP, C#, Swift, and virtually every other language. Its spec is defined in RFC 8259 and ECMA-404.
JSON Syntax Rules
- Data is in name/value pairs: "key": value
- Keys MUST be strings enclosed in double quotes (not single quotes)
- Values can be: string, number, object, array, true, false, or null
- Objects are wrapped in curly braces { }
- Arrays are wrapped in square brackets [ ]
- Pairs are separated by commas — no trailing comma after the last item
- JSON has no support for comments
- Strings must use double quotes; backslash-escape special characters
JSON Data Types
| Type | Example | Notes |
|---|---|---|
| String | "Hello World" | Must use double quotes; escape \n, \t, \" |
| Number | 42 or 3.14 or -7 | No integer/float distinction; no leading zeros; no NaN/Infinity |
| Boolean | true or false | Lowercase only — not True/False |
| Null | null | Lowercase only — not Null/NULL |
| Object | {"k": "v"} | Unordered key-value pairs; keys must be unique |
| Array | [1, 2, 3] | Ordered list; values can be mixed types |
Validating JSON
A single syntax error — a missing comma, an unquoted key, a trailing comma — renders the entire JSON document invalid. Most JSON parsers fail loudly with an error message, but the message often only tells you the line where parsing failed, not where the actual syntax error is. A JSON formatter/validator shows you the exact error location and explains what's wrong.
Validate and format your JSON
Paste your JSON and get instant validation with precise error locations.
JSON vs XML
| Property | JSON | XML |
|---|---|---|
| Verbosity | Compact | Verbose (opening/closing tags) |
| Human readability | High | Moderate |
| Data types | 6 native types | Everything is a string (needs schema) |
| Comments | Not supported | Supported |
| Namespaces | Not supported | Supported |
| Browser support | Native (JSON.parse) | XPath/XSLT required |
| Best for | APIs, web, config | Enterprise EDI, SOAP, document markup |
Common JSON Errors and How to Fix Them
- Trailing comma — remove the comma after the last key-value pair or array element
- Single-quoted strings — change all ' to " around both keys and string values
- Unquoted keys — add double quotes around all object keys
- Undefined or NaN values — JSON doesn't support these; use null instead
- Comments — JSON has no comment syntax; remove all // and /* */ comments
- Missing comma between items — add comma between every pair/element
- Mismatched brackets — use a formatter to identify unbalanced { } and [ ]
JSON Best Practices
- Use camelCase for key names in APIs (consistent with JavaScript conventions)
- Use descriptive key names — avoid single-letter keys except in tight loops
- Null vs missing key: use null to represent 'no value'; omit the key for 'not applicable'
- Date/time as ISO 8601 strings ("2025-06-01T12:00:00Z") — not Unix timestamps for human-facing APIs
- Paginate large arrays — never return unlimited arrays in API responses
- Minify for production API responses; pretty-print for debugging and config files
Frequently Asked Questions
Can JSON have comments?
No. The JSON spec explicitly prohibits comments. If you need comments in configuration files, consider JSON5 (a superset that supports comments) or YAML. Some parsers accept // comments as an extension but this is non-standard and not portable.
What is the difference between JSON and JSON5?
JSON5 is a community-driven extension to JSON that allows: single-quoted strings, trailing commas, comments (// and /* */), hexadecimal numbers, and unquoted keys. JSON5 is useful for configuration files but should not be used for APIs — standard JSON only.
What is NDJSON (newline-delimited JSON)?
NDJSON is a format where each line is a valid JSON object, separated by newline characters. It is used for streaming APIs and log files where you need to append records without wrapping them in a JSON array. Each line can be parsed independently.
How do I handle special characters in JSON strings?
Use backslash escape sequences: \" for double quote, \\ for backslash, \n for newline, \t for tab, \r for carriage return, \/ for forward slash (optional), \uXXXX for Unicode characters.