Skip to main content

JSON Explanation

This document explains what JSON is, how it's written, what characters you can use, and how to escape special characters.

What is JSON?​

  • JSON stands for JavaScript Object Notation. It's a plain-text format for storing and exchanging structured data (like settings, lists, or small databases).
  • JSON is human-readable and used by many tools and websites to share information.

Basic building blocks​

  • Object: A collection of key/value pairs surrounded by curly braces { }.
    • Example: { "name": "Alice", "age": 30 }
  • Array: An ordered list of values surrounded by square brackets [ ].
    • Example: [{ "id": 1 }, { "id": 2 }]
  • Key (also called property name): Always a string wrapped in double quotes ".
  • Value: Can be one of:
    • a string (in double quotes), e.g. "hello"
    • a number, e.g. 42 or 3.14
    • a boolean: true or false
    • null to represent "no value"
    • an object { ... }
    • an array [ ... ]

Formatting rules (must-haves)​

  • Keys must be in double quotes. Single quotes are not allowed for keys.
  • Strings must use double quotes ("like this").
  • Use a colon : between each key and its value: "key": value.
  • Separate items in objects and arrays with commas ,.
  • Do not put a comma after the last item in an object or array (no trailing commas).
  • JSON is case-sensitive (true is valid, True is not).
  • You cannot put comments in JSON (some tools accept them, but standard JSON does not).

Example (valid JSON):

{
  "title": "Example",
  "enabled": true,
  "count": 5,
  "tags": ["docs", "example"],
  "owner": { "name": "Alice", "email": "[email protected]" }
}

Characters and encodings​

  • JSON text is normally encoded in UTF-8, which supports most characters and languages.
  • Inside strings you can use letters, numbers, punctuation, and many Unicode characters directly.
  • Some characters must be escaped inside strings (see next section).

Escaping special characters in strings​

If you need to include certain special characters inside a string, you must escape them by using a backslash \ followed by a code or character:

  • \" — a double quote inside a string
  • \\ — a backslash
  • \n — newline (line break)
  • \t — tab
  • \r — carriage return
  • \b — backspace
  • \f — form feed
  • \uXXXX — a Unicode character by hexadecimal code, e.g. \u00E9 for é

Example with escapes:

{
  "message": "He said, \"Hello\" on line 1.\nThen he left.",
  "path": "C:\\Users\\Name"
}

Common mistakes and how to avoid them​

  • Missing double quotes around keys: { name: "Alice" } is invalid — use "name".
  • Using single quotes: { 'name': 'Alice' } is invalid.
  • Trailing commas: { "a": 1, } is invalid.
  • Unescaped special characters in strings (e.g., an unescaped double quote inside a string).
  • Double quotes being converted “smart quotes” (note the difference between ” and ") by word processors

Quick reference cheat-sheet​

  • Object: { "key": value }
  • Array: [ value1, value2 ]
  • String: "text"
  • Number: 123 or 3.14
  • Boolean: true / false
  • Null: null