JSON Syntax: Rules, Examples, and Best Practices

JSON (JavaScript Object Notation) powers modern web APIs, configuration files, and data storage. But if your syntax is wrong—even by a single character—your JSON won't parse. This guide covers every rule you need to write valid JSON, with practical examples for each data type.

What is JSON?

JSON is a text-based, human-readable format for exchanging structured data. It's language-agnostic, lightweight, and used everywhere from REST APIs to config files. Understanding its syntax rules prevents parsing errors and makes debugging faster.

Not sure what JSON is? Read our introduction to JSON first.

The Six JSON Data Types

JSON supports exactly six primitive data types. Every value in JSON must be one of these:

1. String

Sequences of characters enclosed in double quotes (not single quotes). Strings can contain letters, numbers, symbols, and escaped characters.

"hello world"
"user@example.com"
"Product #42"
"Line 1\nLine 2"
"Price: $19.99"
"Unicode: \u00e9"

'hello world'        // Single quotes - NOT allowed
"unterminated string
"Tab	here"          // Unescaped control characters - NOT allowed
"Quote\"inside"      // Needs backslash escape

Escape sequences: Use backslash for special characters: \" for quotes, \\ for backslash, \n for newline, \t for tab, \u0000 for Unicode.

2. Number

Integers or decimals, positive or negative. No quotes needed.

42
3.14159
-100
0
1.5e10
-0.0001

"42"              // Quoted - this is a string, not a number
042               // Leading zeros not allowed
1.2.3             // Multiple decimal points
NaN               // Not valid (even though JavaScript accepts it)
Infinity          // Not valid in JSON

3. Boolean

Only two values: true or false (lowercase, no quotes).

true
false
{ "is_active": true, "completed": false }

True              // Capitalized - wrong
"true"            // Quoted string, not a boolean
1                 // Not equivalent to true in JSON
yes               // Not valid

4. Null

Represents absence of a value. Use null (lowercase, no quotes).

null
{ "user": null, "email": "test@example.com" }

NULL              // Wrong capitalization
"null"            // This is a string
undefined         // JavaScript only, not valid in JSON
None              // Python syntax, not valid here

5. Object

An unordered collection of key-value pairs, enclosed in curly braces. Keys must always be double-quoted strings. Values can be any JSON data type.

{ "name": "Alice", "age": 30 }

{
  "id": 1,
  "email": "alice@example.com",
  "active": true,
  "metadata": null
}

{ "nested": { "key": "value" } }

{ name: "Alice" }              // Unquoted key - keys MUST be quoted
{ 'name': 'Alice' }           // Single quotes - must use double quotes
{ "name": "Alice", }          // Trailing comma after last property
{ "name": "Alice" "age": 30 } // Missing colon between key and value

6. Array

An ordered list of values, enclosed in square brackets. Values can be of any type, including mixed types and nested arrays.

[1, 2, 3, 4]

["apple", "banana", "orange"]

[
  { "id": 1, "name": "Alice" },
  { "id": 2, "name": "Bob" }
]

[1, "mixed", true, null, { "key": "value" }]

[]  // Empty array

[1, 2, 3,]              // Trailing comma - not allowed
[1 2 3]                 // Missing commas
['a', 'b']              // Single quotes in arrays
(1, 2, 3)               // Parentheses instead of brackets

Critical JSON Syntax Rules

Rule 1: Keys Must Be Double-Quoted Strings

This is one of the most common mistakes. In objects, every key must be a string enclosed in double quotes. No exceptions.

// Correct
{ "firstName": "John", "age": 30 }

// Wrong - unquoted key
{ firstName: "John", age: 30 }

// Wrong - numeric key (must be string)
{ 1: "first", 2: "second" }

Rule 2: All Strings Use Double Quotes

JSON does not support single quotes. This includes both object keys and string values.

// Correct
{ "language": "JSON is strict" }

// Wrong - single quotes
{ 'language': 'JSON is strict' }

Rule 3: No Trailing Commas

The last item in an object or array must not have a trailing comma.

// Correct
{ "a": 1, "b": 2 }
[1, 2, 3]

// Wrong - trailing commas
{ "a": 1, "b": 2, }
[1, 2, 3,]

Rule 4: Whitespace Is Insignificant

Spaces, tabs, and newlines between tokens don't affect meaning (but must be inside strings). These are all equivalent:

{"name":"Alice","age":30}

{
  "name": "Alice",
  "age": 30
}

{  "name"  :  "Alice"  ,  "age"  :  30  }

Rule 5: Nesting Has No Depth Limit

Objects and arrays can be nested arbitrarily deep. Each level is a complete, valid JSON structure.

{
  "user": {
    "profile": {
      "address": {
        "country": "USA",
        "city": "New York"
      }
    }
  },
  "posts": [
    {
      "id": 1,
      "comments": [
        { "author": "Alice", "text": "Great!" },
        { "author": "Bob", "text": "Thanks!" }
      ]
    }
  ]
}

Rule 6: Unicode Support

JSON fully supports Unicode characters. You can include them directly (if your file is UTF-8 encoded) or escape them using \uXXXX notation.

// Unicode directly (UTF-8 file)
{ "greeting": "Bonjour 🌍 こんにちは" }

// Unicode escaped
{ "greeting": "Bonjour \ud83d\ude0a" }

// Mixed
{ "symbol": "€", "escaped": "\u0041BC" }

Complete Valid vs Invalid Examples

{
  "user_id": 12345,
  "name": "Sarah Johnson",
  "email": "sarah@example.com",
  "is_premium": true,
  "last_login": null,
  "tags": ["developer", "designer"],
  "preferences": {
    "theme": "dark",
    "notifications": true
  }
}

{
  user_id: 12345,              // ❌ Key not quoted
  "name": 'Sarah Johnson',     // ❌ Single quotes
  "email": "sarah@example.com",
  "is_premium": True,          // ❌ Capitalized boolean
  "last_login": undefined,     // ❌ undefined not valid
  "tags": ["developer", "designer",],  // ❌ Trailing comma
  "preferences": {
    "theme": "dark",
    "notifications": true,     // ❌ Trailing comma after last item
  }
}

Debugging Syntax Errors

Common places where syntax breaks:

• Unquoted keys: { name: "Alice" } should be { "name": "Alice" }
• Single quotes: { 'key': 'value' } should be { "key": "value" }
• Trailing commas: Always remove the comma after the last element
• Missing colons: { "key" "value" } should be { "key": "value" }
• Bare values: { key: undefined } should be { "key": null }

Need to validate your JSON? Use SnapUtils JSON Formatter to check syntax instantly and get error details.

Best Practices for JSON

• Use consistent indentation: Either 2 or 4 spaces for readability
• Keep key names lowercase_with_underscores: Follows common API conventions
• Avoid deeply nested structures: Aim for 3-4 levels max for maintainability
• Use meaningful key names: "user_email" is clearer than "ue"
• Validate before storing: Always parse/validate JSON before using it in production
• Add comments externally: JSON doesn't support comments; use JSONC or documentation

For more on formatting practices, see how to format JSON and common JSON errors.