JSON Formatting: Structure, Syntax & Best Practices

JSON Syntax at a Glance

{
  "string": "Hello, world!",
  "number": 42,
  "float": 3.14159,
  "boolean": true,
  "null_value": null,
  "array": [1, 2, 3, "four", true],
  "object": {
    "nested_key": "nested_value",
    "another": 100
  },
  "array_of_objects": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ]
}

/* JSON Rules:
   - Keys MUST be double-quoted strings (not single quotes)
   - Strings MUST use double quotes
   - No trailing commas (after last item in array or object)
   - No comments (JSON doesn't support // or /* */)
   - No undefined — use null instead
*/

JSON Data Types

Formatting for Readability vs Minification

Pretty-printed JSON (with indentation) is for humans and debugging. Minified JSON (no whitespace) is for network transmission. Both are valid JSON.

// Pretty-printed (2-space indent — standard):
{
  "user": {
    "id": 123,
    "name": "Alice",
    "roles": ["admin", "editor"]
  }
}

// Minified (network transport):
{"user":{"id":123,"name":"Alice","roles":["admin","editor"]}}

// JavaScript: convert between them
const obj = JSON.parse(jsonString);    // string → object
const pretty = JSON.stringify(obj, null, 2);   // object → pretty JSON
const minified = JSON.stringify(obj);          // object → minified JSON

JSON for REST API Responses

Consistent JSON structure in API responses makes clients easier to write and errors easier to diagnose. These patterns are widely adopted.

{
  "data": {
    "id": "usr_01ABC",
    "email": "alice@example.com",
    "created_at": "2026-04-10T14:30:00Z"
  },
  "meta": {
    "request_id": "req_xyz123",
    "version": "1.0"
  }
}

// Error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "fields": {
      "email": ["This field is required"]
    }
  }
}

// Paginated list
{
  "data": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 142,
    "total_pages": 8
  }
}

JSON Schema: Validate Your JSON

JSON Schema defines the expected structure of a JSON document. Tools like Ajv (JavaScript) validate data against the schema at runtime.

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

Common JSON Mistakes

• Single quotes instead of double quotes — {'key': 'value'} is invalid JSON. Keys and strings require double quotes.
• Trailing commas — [1, 2, 3,] and {"a": 1,} are invalid. Remove the comma after the last item.
• Comments in JSON — JSON has no comment syntax. If you need comments in config files, use JSONC (JSON with Comments, supported by VS Code and TypeScript) or YAML instead.
• Using NaN or Infinity — these are JavaScript values, not valid JSON. Use null or a sentinel number instead.
• Inconsistent date formats — use ISO 8601 (2026-04-10T14:30:00Z) for all dates. Avoid Unix timestamps (1712757000) unless you control both ends — they're hard to debug.
• Deeply nested structures — more than 4 levels of nesting is a sign the data model needs restructuring. Flat structures are easier to query, cache, and reason about.

Frequently Asked Questions

Is JSON5 the same as JSON?

No — JSON5 is a superset that adds comments, trailing commas, single quotes, and unquoted keys. It's useful for config files (webpack.config.js, for example), but it's not valid JSON and can't be parsed by standard JSON parsers.

Should I use JSON or YAML for config files?

Both are popular. JSON has strict syntax (easy to validate, widely supported). YAML is more readable for humans (supports comments, no quotes needed for strings, supports multiline) but whitespace-sensitive. For code-adjacent config, JSON or JSONC. For human-edited config, YAML.

What's the maximum size JSON can handle?

JSON itself has no size limit. Practical limits come from the parser — V8 (Node.js/Chrome) can parse JSON up to ~1GB. For large datasets, consider streaming JSON parsers (jsonstream, oboe.js) that don't load the entire document into memory.

How do I handle dates in JSON?

JSON has no date type. Best practice: serialize as ISO 8601 strings (2026-04-10T14:30:00Z). On parse, convert back to Date objects in your application code. Avoid Unix timestamps in new APIs — they're harder to debug than ISO strings.