JSON Formatting Best Practices for APIs and Data Exchange

Messy JSON will break your parser, waste your afternoon, and cause weird integration bugs that are surprisingly hard to track down. If you work with APIs, config files, or data exports, getting your JSON formatting right saves you from all of that.

This guide covers the formatting standards worth following, the mistakes that actually break things, and some practical ways to keep your JSON clean.

Why JSON formatting matters

JSON is everywhere. Web APIs, config files, data pipelines. But sloppy formatting leads to real problems:

• Parsing failures: One stray comma and your app dies quietly
• Painful debugging: Good luck reading a 500-line minified blob
• Merge conflicts: Mixed indentation turns every PR into a mess
• Parser quirks: What Python accepts, Java might reject

JSON formatting standards

1. Use 2-space indentation

Two spaces is the convention most teams settle on. Compact enough, readable enough:

{
  "user": {
    "id": 12345,
    "name": "John Doe",
    "email": "john@example.com"
  }
}

You can use our JSON Formatter to fix indentation automatically.

2. Pick a key naming convention and stick with it

Pick one naming style and use it everywhere in your JSON:

• camelCase (common in JavaScript): firstName, userId, createdAt
• snake_case (common in Python/Ruby): first_name, user_id, created_at
• kebab-case (avoid for JSON keys since JavaScript can't access them with dot notation)

Rule of thumb: camelCase if your frontend is JavaScript, snake_case if your backend is Python or Ruby.

3. No trailing commas

JavaScript lets you get away with trailing commas. JSON does not. This will break your parser:

// ❌ INVALID JSON
{
  "name": "John",
  "age": 30,  // Trailing comma breaks parser
}

// ✅ VALID JSON
{
  "name": "John",
  "age": 30
}

Common JSON formatting mistakes

Mistake 1: Using single quotes

// ❌ INVALID - Single quotes not allowed in JSON
{
  'name': 'John'
}

// ✅ VALID - Always use double quotes
{
  "name": "John"
}

Mistake 2: Adding comments

JSON has no comment syntax. If you need inline documentation, use a separate schema file or add a _comment field as a workaround:

// ❌ INVALID
{
  "name": "John",  // User's full name
  "age": 30
}

// ✅ If comments needed, use JSONC or JSON5 (not standard JSON)
{
  "_comment": "User profile data",
  "name": "John",
  "age": 30
}

Mistake 3: Mixing data types

If the same field appears in multiple objects, keep the type consistent. Don't use a number in one place and a string in another:

// ❌ BAD - Inconsistent types
{
  "users": [
    {"id": 123, "active": true},
    {"id": "456", "active": "yes"}  // Type mismatch
  ]
}

// ✅ GOOD - Consistent types
{
  "users": [
    {"id": 123, "active": true},
    {"id": 456, "active": true}
  ]
}

API response formatting

Use a consistent error structure

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "field": "email"
  }
}

Wrap collections in objects

// ❌ Hard to extend with metadata
[
  {"id": 1, "name": "Item 1"},
  {"id": 2, "name": "Item 2"}
]

// ✅ Easy to add pagination, counts, etc.
{
  "data": [
    {"id": 1, "name": "Item 1"},
    {"id": 2, "name": "Item 2"}
  ],
  "total": 150,
  "page": 1
}

When to minify vs. pretty-print

During development: Always pretty-print. You need to read the thing.

In production: Minify your responses. It cuts bandwidth by 10-20%, sometimes more. Our JSON Minifier strips all the whitespace for you.

// Development (67 bytes)
{
  "name": "John",
  "age": 30
}

// Production (26 bytes - 61% smaller)
{"name":"John","age":30}

Validation and testing

Validate your JSON before you ship it:

1. Run it through our JSON Validator to catch syntax errors
2. Test with multiple parsers (JavaScript, Python, Java) since they don't all behave the same
3. Add jsonlint to your CI/CD pipeline so bad JSON never gets merged
4. Use JSON Schema to enforce structure and types at the boundary

Quick reference checklist

• ✅ 2-space indentation
• ✅ Double quotes for all keys and string values
• ✅ No trailing commas
• ✅ One naming convention (camelCase or snake_case), used everywhere
• ✅ Same data types for the same fields across objects
• ✅ Lint before deploying
• ✅ Minify in production, pretty-print in development
• ✅ Use null for missing values, not undefined or empty strings

Wrapping up

Clean JSON formatting prevents bugs, makes debugging faster, and keeps your APIs working across different languages and platforms. Most of the rules are simple. The hard part is being consistent about them, especially on a team. A linter in your CI pipeline goes a long way.

Want to clean up or check your JSON right now? Try our free JSON Formatter and JSON Validator.