How to Format, Validate, and Debug JSON Data (Developer Guide)

JavaScript Object Notation (JSON) is the universal data format of the modern web. From RESTful API payloads and microservice messages to local configuration files (package.json, tsconfig.json), JSON powers data exchange across almost every programming language.

However, because JSON enforces strict syntax rules defined by ECMA-404, a single misplaced comma or unescaped quote can break an entire application deployment or API response.

This developer guide covers how JSON syntax works, common parsing errors, how to validate JSON programmatically and online, and best practices for debugging large API responses.

What makes JSON valid? (The ECMA-404 Standard)

JSON is a lightweight, text-based data-interchange format derived from JavaScript object literal syntax. However, JSON is stricter than JavaScript.

The 6 Primitive Data Types in JSON

Valid JSON supports only six fundamental data types:

1. String: Enclosed strictly in double quotes ("text").
2. Number: Integer or floating-point numbers without quotes (10, -4.5, 1.2e3).
3. Boolean: Literal true or false in lowercase.
4. Array: Ordered list of values enclosed in square brackets ([1, 2, 3]).
5. Object: Unordered collection of key-value pairs enclosed in curly braces ({"key": "value"}).
6. Null: Literal null representing empty/absent data.

Strict Syntax Rules You Must Follow

• Double Quotes Only: Property names and strings must use double quotes. 'name' or `name` are invalid.
• No Trailing Commas: Never place a comma after the final key in an object or element in an array.
• No Unescaped Control Characters: Characters like newlines (\n), tabs (\t), or literal quotes (\") inside strings must be properly escaped with backslashes.
• No Comments: Standard JSON does not permit single-line (//) or block (/* */) comments.

5 Most Common JSON Syntax Errors (and How to Fix Them)

1. The Trailing Comma Error

Invalid:

{
  "user": "alex",
  "role": "admin",
}

Valid Fix:

{
  "user": "alex",
  "role": "admin"
}

2. Single Quotes Instead of Double Quotes

Invalid:

{
  'status': 'success',
  'code': 200
}

Valid Fix:

{
  "status": "success",
  "code": 200
}

3. Unquoted Object Keys

In JavaScript, { name: "Alex" } is valid, but in JSON it is an invalid syntax error.

Invalid:

{
  id: 101,
  active: true
}

Valid Fix:

{
  "id": 101,
  "active": true
}

4. Unescaped Quotes inside String Values

If a string value contains double quotes, you must escape them with a backslash \".

Invalid:

{
  "message": "Click "Submit" to complete the request."
}

Valid Fix:

{
  "message": "Click \"Submit\" to complete the request."
}

5. Including Comments in Standard JSON

If your API parser uses strict JSON.parse(), any comment will trigger SyntaxError: Unexpected token /.

Invalid:

{
  // User identifier
  "id": 1001
}

Valid Fix: Remove comments or convert your file to JSONC / YAML if supported by your build setup.

Step-by-Step: Formatting and Validating JSON Online

When dealing with minified API responses (thousands of characters on a single line), manual inspection is impossible.

Step 1: Paste Raw JSON into ToolzStack JSON Formatter

Copy your minified or messy payload and paste it into the ToolzStack JSON Formatter.

Step 2: Auto-Indentation & Pretty Printing

The formatter automatically parses your data tree and renders clean 2-space or 4-space indentation. Tree navigation allows you to collapse large nested objects and arrays.

Step 3: Instant Error Highlighting

If the syntax is invalid, the validator highlights the exact line number, character index, and nature of the parsing error (e.g. Unexpected token ' in JSON at position 42).

Step 4: Copy or Convert

Once valid, you can copy the pretty-printed JSON, export minified JSON for production APIs, or convert it to YAML / XML / CSV.

Programmatic JSON Validation Techniques

JavaScript / TypeScript Node.js

function safeParseJson<T>(jsonString: string): { success: boolean; data?: T; error?: string } {
  try {
    const parsed = JSON.parse(jsonString);
    return { success: true, data: parsed };
  } catch (err) {
    return { success: false, error: (err as Error).message };
  }
}

Python

import json

def validate_json_string(data_str: str):
    try:
        data = json.loads(data_str)
        print("JSON is valid!")
        return True
    except json.JSONDecodeError as e:
        print(f"JSON invalid: {e.msg} at line {e.lineno} col {e.colno}")
        return False

Best Practices for Designing Clean JSON APIs

1. Use camelCase or snake_case Consistently: Standardize property naming across your entire API contract (createdAt or created_at).
2. Always Return Arrays or Objects: Avoid returning raw primitives like numbers or strings from root API endpoints.
3. Handle Empty States Explicitly: Use null or empty arrays [] rather than omitting fields, which keeps client TypeScript interfaces predictable.
4. Minify in Production: Serve minified JSON over HTTP with gzip or Brotli compression to minimize payload size.
5. Format in Staging & Debug Logs: Keep human-readable indentation enabled during local development and logging.

Try the free ToolzStack JSON Formatter & Validator to clean up, validate, and structure your JSON data instantly in your browser.