JSON Formatting Best Practices for Developers

JSON (JavaScript Object Notation) is everywhere — APIs, config files, databases, logs. And yet, malformed or poorly formatted JSON is one of the most common sources of developer frustration. This guide covers best practices, common mistakes, and how to keep your JSON clean.

Why Formatting Matters

Production JSON should be minified to save bandwidth. Development JSON should be beautifully formatted for readability. The difference looks like this:

Minified (production)

{"user":{"id":42,"name":"Sudo_Rogue","roles":["admin","builder"],"active":true}}

Beautified (development/debugging)

{
  "user": {
    "id": 42,
    "name": "Sudo_Rogue",
    "roles": ["admin", "builder"],
    "active": true
  }
}

The beautified version takes more bytes, but when you're debugging a 500-line API response at 2am, you'll be grateful for the indentation.

The 6 Most Common JSON Mistakes

1. Single Quotes Instead of Double Quotes

// ❌ Invalid JSON
{'name': 'Sudo_Rogue'}

// ✅ Valid JSON
{"name": "Sudo_Rogue"}

JSON mandates double quotes. Single quotes are valid in JavaScript but not in JSON. This trips up developers constantly when copying from JS object literals.

2. Trailing Commas

// ❌ Invalid JSON — trailing comma after last item
{
  "tools": ["password", "uuid", "base64",]
}

// ✅ Valid JSON
{
  "tools": ["password", "uuid", "base64"]
}

JavaScript allows trailing commas since ES5. JSON does not. Always remove the comma after the last element in arrays and objects.

3. Comments in JSON

// ❌ Invalid — JSON has no comment syntax
{
  // This is the user config
  "name": "Sudo_Rogue"
}

// ✅ Use JSONC (JSON with Comments) in config files
// that explicitly support it, like tsconfig.json

Pure JSON has no comment syntax. If you need comments in config files, use JSONC, TOML, or YAML instead. Many editors and tools (like VS Code's tsconfig.json parser) support JSONC as an extension.

4. Undefined Values

// ❌ Invalid — undefined is a JavaScript concept, not JSON
{"value": undefined}

// ✅ Use null for absent values
{"value": null}

5. Functions or Non-Primitive Types

// ❌ Invalid
{"callback": function() {}, "date": new Date()}

// ✅ Valid — serialize dates as ISO strings
{"createdAt": "2026-03-11T12:00:00.000Z"}

6. Incorrect Number Formats

// ❌ Invalid
{"value": .5}     // No leading zero
{"value": 1.}     // No trailing dot
{"value": 0xFF}   // No hex literals

// ✅ Valid
{"value": 0.5}
{"value": 255}

Key/Value Naming Conventions

JSON keys can be any string, but consistency matters. Choose a convention and stick to it across your entire API:

• camelCase — most common in JavaScript APIs (e.g. firstName)
• snake_case — common in Python/Ruby APIs (e.g. first_name)
• PascalCase — common in C#/.NET (e.g. FirstName)
• kebab-case — avoid in JSON keys (hyphens require quotes in JS: obj["first-name"])

Validating and Formatting JSON

Before deploying any JSON configuration or API response, validate it. Use our free online tool to beautify, minify, and validate any JSON instantly — without sending your data to a server:

Quick Reference: Valid JSON Data Types

{
  "string":  "Hello, world!",
  "number":  42,
  "float":   3.14159,
  "boolean": true,
  "null":    null,
  "array":   [1, "two", false, null],
  "object":  {"nested": "value"}
}

JSON supports exactly 7 value types: string, number, boolean, null, array, object — and that's it. No dates, no functions, no undefined, no symbols.

Summary

• Use double quotes for all keys and string values
• No trailing commas after the last item
• No comments in pure JSON
• Use null instead of undefined
• Serialize dates as ISO 8601 strings
• Always validate JSON before deploying
• Minify for production, beautify for debugging