The Complete JSON Formatting Guide: Syntax, Best Practices, and Common Issues
What is JSON?
JSON (JavaScript Object Notation) is a lightweight data interchange format, standardized by Douglas Crockford in the early 2000s. It is based on JavaScript object literal syntax but, as a text format independent of programming languages, almost all modern languages provide native support.
JSON design goal is a balance between "human-readable" and "machine-parseable." It uses simple key-value pairs and array structures to represent data, without XML tag redundancy or YAML indentation sensitivity. Today, RESTful APIs, configuration files, NoSQL databases (such as MongoDB), and other scenarios almost all use JSON as the data carrier.
The Six Data Types of JSON
The JSON standard defines six data types: String (must be wrapped in double quotes), Number (supports integers and floating-point numbers, does not support NaN/Infinity), Boolean (true or false), null (note the lowercase), Object (unordered key-value pair collection), and Array (ordered value collection).
It is particularly important to note that JSON does not support the following JavaScript types: undefined, Function, Symbol, BigInt, and Date objects. These values are ignored or converted to null during JSON.stringify. If you need to pass dates in JSON, they are usually represented as ISO 8601 format strings.
The Purpose of JSON Formatting
JSON data in production environments is usually compressed (no indentation, no line breaks) to reduce transmission size. For example, a JSON returned by an API might be a single line of text, almost impossible to read manually. Formatting (also called beautifying/Prettify) re-adds indentation and line breaks to make the data structure clear at a glance.
Common indentation options for formatting are 2 spaces (most common) or 4 spaces (more spacious). Tab indentation, while valid in JSON, is less universal than spaces and can display inconsistently across different editors. This tool defaults to 2-space indentation, which is also the default setting for mainstream tools like Prettier and ESLint.
JSON Validation and Common Error Troubleshooting
One of the core features of a JSON formatting tool is validation. Common errors include: trailing commas (an extra comma after the last property), single-quote strings (JSON only allows double quotes), unquoted key names, comments (standard JSON does not support comments), and extra commas or brackets. A good formatting tool can precisely locate error positions.
Another common "pseudo-JSON" issue is the BOM header. Some Windows editors save files with a UTF-8 BOM (\uFEFF), which causes JSON.parse to throw "Unexpected token." The solution is to re-save the file in UTF-8 encoding without BOM. This tool automatically handles BOM headers.
JSON Security Considerations
JSON itself does not contain executable code, but parsing JSON with eval() is extremely dangerous (and has been deprecated) because attackers can inject malicious JavaScript. Modern browsers provide the safe JSON.parse(), which only parses pure data and does not execute any code. Never use eval() to process JSON from untrusted sources.
Another security risk is JSON Hijacking. If an API returns JSON data starting with a square bracket, attackers can read it cross-origin via a <script> tag. Defense methods include adding an infinite loop prefix (such as while(1);) before the JSON response, or using CORS headers to restrict origins. Modern browsers have largely eliminated this risk.
JSON in Real-World Development
RESTful APIs: Almost all modern Web APIs use JSON as the request and response format. Compared to XML, JSON is more lightweight, parses faster, and consumes less mobile data. Although GraphQL uses its own query language, its responses are also in JSON format.
Configuration files: package.json, tsconfig.json, .eslintrc.json, and other front-end toolchain configurations widely use JSON. Although JSON does not support comments (JSONC is an extended format), its strict syntax reduces configuration ambiguity. The NoSQL database MongoDB directly stores documents in BSON format (similar to JSON), and its query syntax is also JSON-style.