JSON Formatting Best Practices for Clean, Readable Code

JSON has become the universal data format for web APIs, configuration files, and data storage. Writing clean, well-formatted JSON makes debugging easier and keeps your projects maintainable.

Use Consistent Indentation

Always use 2 or 4 spaces for indentation, and stick with one choice throughout your project. Never use tabs in JSON files — many parsers handle them inconsistently.

{
  "user": {
    "name": "Jane Smith",
    "email": "[email protected]",
    "roles": ["admin", "editor"]
  }
}

Choose Clear Property Names

Use camelCase or snake_case Consistently

Pick one naming convention and apply it everywhere:

// camelCase (common in JavaScript ecosystems)
{ "firstName": "Jane", "lastName": "Smith" }

// snake_case (common in Python/Ruby ecosystems)
{ "first_name": "Jane", "last_name": "Smith" }

Be Descriptive but Concise

• Good: "createdAt", "orderTotal", "isActive"
• Avoid: "ca", "ot", "flag1"

Structure Data Logically

Group Related Fields

{
  "billing": {
    "address": "123 Main St",
    "city": "London",
    "postcode": "SW1A 1AA"
  },
  "shipping": {
    "address": "456 Oak Ave",
    "city": "Manchester",
    "postcode": "M1 1AA"
  }
}

Use Arrays for Lists of Similar Items

{
  "products": [
    { "id": 1, "name": "Widget", "price": 9.99 },
    { "id": 2, "name": "Gadget", "price": 24.99 }
  ]
}

Handle Data Types Correctly

JSON supports strings, numbers, booleans, null, arrays, and objects. Use the right type for each value:

• Numbers — Do not quote numeric values: "price": 19.99 not "price": "19.99"
• Booleans — Use true/false without quotes: "active": true not "active": "true"
• Null — Use null for absent values: "middleName": null
• Dates — Use ISO 8601 strings: "created": "2026-03-25T10:30:00Z"

Avoid Common Mistakes

No Trailing Commas

Unlike JavaScript, JSON does not allow trailing commas:

// Invalid JSON
{ "a": 1, "b": 2, }

// Valid JSON
{ "a": 1, "b": 2 }

No Comments

JSON does not support comments. If you need comments, consider using JSONC (JSON with Comments) for configuration files, or add a "_comment" field:

{
  "_comment": "Timeout is in milliseconds",
  "timeout": 5000
}

Always Use Double Quotes

JSON requires double quotes for strings and property names. Single quotes are invalid:

// Invalid
{ 'name': 'Jane' }

// Valid
{ "name": "Jane" }

Keep Payloads Lean

• Remove fields that are always null or empty
• Use pagination for large collections instead of returning everything
• Consider separate endpoints for detailed vs. summary views

Minification vs. Pretty-Printing

During development, use pretty-printed JSON for readability. In production, minify your JSON to reduce bandwidth. A 100KB prettified JSON response might shrink to 60KB when minified — a meaningful saving at scale.

Format Your JSON Instantly

Working with messy or minified JSON? Our JSON Minifier tool lets you quickly format, validate, and minify JSON right in your browser. Paste in tangled JSON and get clean, properly indented output instantly.

Clean JSON is not just about aesthetics — it reduces bugs, speeds up debugging, and makes your APIs a pleasure to work with. Start applying these practices today and your future self will thank you.