The Complete Guide to JSON: Syntax, Parsing, and Best Practices

What is JSON?

JSON (JavaScript Object Notation) is a lightweight data interchange format that has become the de facto standard for data exchange on the web. Despite its name suggesting a JavaScript origin, JSON is language-independent and supported by virtually every modern programming language.

JSON was derived from JavaScript object literal syntax, but it has evolved into a standalone format specified by RFC 8259 and ECMA-404. Its simplicity and readability have made it the preferred choice over XML for most web APIs and configuration files.

JSON Syntax Rules

Understanding JSON syntax is fundamental to working with it effectively. Here are the core rules:

Data Types

JSON supports six data types:

1. Strings — Must be enclosed in double quotes: "hello world"
2. Numbers — Integer or floating point: 42, 3.14, -17, 1.0e10
3. Booleans — true or false (lowercase only)
4. Null — null (lowercase only)
5. Arrays — Ordered lists enclosed in square brackets: [1, 2, 3]
6. Objects — Key-value pairs enclosed in curly braces: {"key": "value"}

Important Syntax Constraints

• Keys must be strings (double-quoted)
• No trailing commas allowed
• No comments allowed (this is a common source of frustration)
• No single quotes — only double quotes for strings
• No undefined value — use null instead
• Numbers cannot have leading zeros (except 0 itself)

{
  "name": "John Doe",
  "age": 30,
  "isActive": true,
  "address": {
    "street": "123 Main St",
    "city": "Springfield",
    "state": "IL"
  },
  "hobbies": ["reading", "coding", "hiking"],
  "spouse": null
}

Parsing JSON in JavaScript

JavaScript provides two built-in methods for working with JSON:

JSON.parse()

Converts a JSON string into a JavaScript object:

const jsonString = '{"name": "Alice", "age": 25}';
const obj = JSON.parse(jsonString);
console.log(obj.name); // "Alice"

Error handling is critical when parsing JSON. Always wrap JSON.parse() in a try-catch block:

function safeJsonParse(str) {
  try {
    return { data: JSON.parse(str), error: null };
  } catch (e) {
    return { data: null, error: e.message };
  }
}

JSON.stringify()

Converts a JavaScript object into a JSON string:

const obj = { name: "Bob", scores: [95, 87, 92] };

// Compact output
JSON.stringify(obj);
// '{"name":"Bob","scores":[95,87,92]}'

// Pretty-printed with 2-space indent
JSON.stringify(obj, null, 2);

The second argument to JSON.stringify() is a replacer function that lets you filter or transform values:

const user = {
  name: "Alice",
  password: "secret123",
  email: "alice@example.com"
};

// Remove sensitive fields
const safe = JSON.stringify(user, (key, value) => {
  if (key === "password") return undefined;
  return value;
});
// '{"name":"Alice","email":"alice@example.com"}'

Working with JSON in Python

Python's json module provides similar functionality:

import json

# Parse JSON string
data = json.loads('{"name": "Alice", "age": 25}')
print(data["name"])  # Alice

# Convert to JSON string
obj = {"name": "Bob", "scores": [95, 87, 92]}
json_str = json.dumps(obj, indent=2)

# Read from file
with open("data.json", "r") as f:
    data = json.load(f)

# Write to file
with open("output.json", "w") as f:
    json.dump(data, f, indent=2)

JSON Schema Validation

For production applications, you should validate JSON data against a schema. JSON Schema is a vocabulary that allows you to annotate and validate JSON documents.

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

Common JSON Pitfalls

1. Circular References

JSON.stringify() throws an error on circular references:

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

2. Date Handling

JSON has no native date type. Dates are typically serialized as ISO 8601 strings:

const event = { name: "Meeting", date: new Date() };
const json = JSON.stringify(event);
// date becomes: "2024-01-15T10:30:00.000Z"

// When parsing, dates remain strings — you must convert manually
const parsed = JSON.parse(json);
parsed.date = new Date(parsed.date);

3. Large Numbers

JavaScript's Number type can lose precision with very large integers. Numbers beyond Number.MAX_SAFE_INTEGER (2^53 - 1) will be rounded:

JSON.parse('{"id": 9007199254740993}');
// { id: 9007199254740992 } — precision lost!

For large numbers, use strings or BigInt with a custom reviver.

4. Encoding Issues

JSON must be encoded in UTF-8 (or UTF-16/UTF-32 with BOM). Special characters in strings must be escaped:

• \" — double quote
• \\ — backslash
• \n — newline
• \t — tab
• \uXXXX — unicode character

Performance Tips

1. Stream large files — Don't load entire large JSON files into memory. Use streaming parsers like JSONStream in Node.js or ijson in Python.

2. Use JSON.parse() for config — It's faster than eval() and safer. Never use eval() to parse JSON.

3. Minimize payload size — Use short key names in high-volume APIs. Consider compression (gzip/brotli) for large responses.

4. Consider alternatives for binary data — JSON is text-based. For binary data, consider MessagePack, Protocol Buffers, or CBOR.

JSON vs Other Formats

Feature	JSON	XML	YAML	TOML
Readability	Good	Moderate	Excellent	Excellent
Verbosity	Low	High	Low	Low
Comments	No	Yes	Yes	Yes
Data types	6	Text only	Many	Many
Schema support	Yes	Yes (XSD)	No standard	No
Browser native	Yes	Partial	No	No

Conclusion

JSON's simplicity is its greatest strength. It's easy to read, easy to parse, and universally supported. By understanding its syntax rules, common pitfalls, and best practices, you can work with JSON confidently in any programming language.

Use our JSON Formatter tool to quickly format and validate your JSON data right in your browser.