JavaScript Object Notation (JSON) has become the de facto standard for data interchange on the modern web. Despite its name, JSON is language-independent. While it was derived from JavaScript, it is now supported by virtually every programming language in existence, from Python and Go to Rust and C#.
According to the 2024 State of API Report, over 94% of public APIs use JSON as their primary format, vastly outpacing XML (at just under 4%). The reason for this dominance is simplicity. JSON is lightweight, easy for humans to read, and easy for machines to parse.
In this guide, we aren't just skimming the surface. We are going into the byte-level details of syntax, exploring the quirks of parsing large numbers, and defining strict validation schemas that can save your production environment from crashing.
JSON is built on two structures: a collection of name/value pairs (often called an object) and an ordered list of values (an array). However, strict JSON syntax is less forgiving than standard JavaScript objects.
A valid JSON value must be one of the following six types:
{}.[].true or false.null.Crucial Rule: JSON keys must be strings enclosed in double quotes. In JavaScript, you might write{ key: "value" }, but in JSON, this is a syntax error. It must be{ "key": "value" }.
Let's look at a complex but valid JSON object representing a user profile:
{
"id": 1024,
"username": "coder_jane",
"isActive": true,
"roles": ["admin", "editor"],
"preferences": {
"theme": "dark",
"notifications": null
},
"balance": 450.50
}Conversely, here are common attempts that result in Invalid JSON:
{
'id': 1024, // ERROR: Single quotes are not allowed
"name": "Jane", // ERROR: Trailing comma (if this is the last item)
"bio": undefined, // ERROR: 'undefined' is not a valid JSON type
"date": new Date() // ERROR: Functions/Objects are not standard JSON
}While JSON is the current king, XML was the previous standard, and YAML is often used for configuration. Understanding when to use which is critical for system architecture.
| Feature | JSON | XML | YAML |
|---|---|---|---|
| Readability | High | Medium (Verbose) | Very High |
| Parsing Speed | Fastest | Slow | Medium |
| Comments | No | Yes | Yes |
| Data Types | Basic (String, Number, Bool) | Text-based (Requires Schema) | Complex (Dates, Binary) |
| Usage | APIs, Web Storage | Enterprise, Documents | Config files (Docker, K8s) |
Verdict: Use JSON for data transmission (APIs). Use YAML for configuration files where humans need to write it manually. Avoid XML unless integrating with legacy enterprise systems (SOAP).
Every major language has a standard library for handling JSON. Here is how to do it safely in the two most popular languages.
The global JSON object provides two methods:
// Object to JSON String
const data = { id: 1, name: "Alice" };
const jsonString = JSON.stringify(data);
// Result: '{"id":1,"name":"Alice"}'
// JSON String to Object
try {
const parsed = JSON.parse(jsonString);
console.log(parsed.name); // "Alice"
} catch (error) {
console.error("Invalid JSON string:", error.message);
}Python's json module maps JSON types to Python dictionaries and lists.
import json
data = {"id": 1, "name": "Alice"}
# Dictionary to JSON String
json_string = json.dumps(data)
# Result: '{"id": 1, "name": "Alice"}'
# JSON String to Dictionary
try:
parsed = json.loads(json_string)
print(parsed["name"]) # "Alice"
except json.JSONDecodeError as e:
print(f"Failed to decode: {e}")Even experienced developers run into JSON issues. Here are the top 3 errors that break production applications.
JSON does not allow a comma after the last element in an array or object. While strict modes in modern linters catch this, legacy parsers will crash.
Incorrect: { "a": 1, "b": 2, }
Correct: { "a": 1, "b": 2 }
JSON does not support comments. This was an intentional design decision by Douglas Crockford to prevent people from using comments to include parsing directives, which would break interoperability. If you need configuration with comments, use JSONC (JSON with Comments) or YAML, but remember standard JSON parsers will fail on comments.
JSON numbers are double-precision floating-point format (IEEE 754). This means integers larger than 2^53 - 1 (approximately 9 quadrillion) lose precision.
If your API returns a 64-bit database ID like 9223372036854775807, a standard JavaScript parser will round it, corrupting the ID. Solution: Always return large 64-bit integers as Strings in your JSON (e.g., "id": "9223372036854775807").
When designing JSON responses for your REST or GraphQL API, following these conventions ensures long-term maintainability.
camelCase is the standard Performance Note: In benchmark tests parsing a 1MB payload, native JSON.parse in Node.js is typically 2x to 5x faster than XML parsers and up to 10x faster than YAML parsers. This is why YAML is excellent for configuration (written once, read rarely) but poor for high-throughput APIs.
How do you ensure the JSON you receive matches the structure you expect? Checking if (data.user && data.user.id) manually is error-prone and tedious. Enter JSON Schema.
JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. It's the "type safety" for your JSON. You define a schema (itself a JSON object), and a validator library checks your data against it.
Here is an example schema for a User object:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"userId": { "type": "integer", "minimum": 1 },
"username": { "type": "string", "pattern": "^[a-z0-9_]+$" },
"email": { "type": "string", "format": "email" },
"roles": {
"type": "array",
"items": { "type": "string", "enum": ["admin", "editor", "viewer"] }
}
},
"required": ["userId", "username", "email"]
}Using libraries like Ajv (for JavaScript) or jsonschema (for Python), you can automatically reject requests that don't match this contract. This is crucial for security, ensuring malicious users can't inject unexpected data types or massive payloads that crash your backend.
JSON is generally safe, but how you handle it matters. Here are three critical security mandates:
eval()In the early days of the web (circa 2005), developers often used eval() to parse JSON responses. This is a massive security hole. It allows arbitrary code execution if the JSON source is compromised. Always use JSON.parse().
When merging JSON data into existing objects, be wary of the __proto__ key. Attackers can use this to modify the prototype of the base Object, potentially altering logic across your entire application. Modern libraries usually strip this key, but if you write your own deep-merge function, you must explicitly block __proto__, constructor, and prototype keys.
While modern browsers have largely mitigated this with SameSite cookies and stricter parsing, it remains best practice to protect your JSON endpoints. One common technique is to prefix your JSON response with a non-executable string, often called a "security prefix". Google, for example, often prefixes JSON responses with )]}',\n.
The client script must strip these characters before parsing. This prevents an external site from loading your JSON endpoint via a <script> tag and reading the data.
Standard JSON is rigid. Extensions have emerged to fill specific niches.