JSON Formatting Best Practices

JSON Formatting Best Practices

JSON is the lingua franca of web APIs, configuration files, and data interchange. While the format is simple, poorly formatted JSON causes real problems — hard-to-read configs, brittle parsing, and debugging headaches. These best practices will keep your JSON clean and maintainable.

Use Consistent Indentation

Always use 2 spaces for indentation in JSON files. Tabs and 4-space indentation work but 2 spaces is the dominant convention in the JavaScript and web development ecosystem.

{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.18.0"
  }
}

Minified JSON (no whitespace) is appropriate for network transfer but never for files humans read.

Key Naming Conventions

Use camelCase for JSON keys in JavaScript/TypeScript APIs. Use snake_case if your backend is Python or Ruby. The critical rule is consistency within a project.

{
  "userId": 42,
  "firstName": "Ada",
  "createdAt": "2026-01-15T09:00:00Z"
}

Avoid abbreviations that sacrifice clarity. "usr" saves four characters but costs readability.

Handle Dates Properly

Always use ISO 8601 format for dates. Include timezone information — UTC with the Z suffix is preferred.

{
  "createdAt": "2026-01-15T09:30:00Z",
  "expiresAt": "2026-02-15T09:30:00Z"
}

Never use Unix timestamps in JSON meant for human consumption. They are unreadable without conversion.

Null vs Absent Keys

Be intentional about null versus omitting a key. A null value means "this field exists but has no value." An absent key can mean "this field is not applicable" or "use the default."

{
  "middleName": null,
  "nickname": "ace"
}

Document your convention and apply it consistently across your API.

Arrays and Empty Values

Use empty arrays [] and empty objects {} instead of null when the field normally holds a collection. This prevents null-check bugs in consuming code.

{
  "tags": [],
  "metadata": {}
}

Validate Before Shipping

Always validate JSON against a schema in your CI pipeline. Use JSON Schema for API payloads and configuration files.

{
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" }
  }
}

Conclusion

Good JSON formatting is about readability, consistency, and preventing bugs. Pick conventions, document them, validate automatically, and your JSON will be a source of clarity rather than confusion.