JSON Formatting Best Practices for Developers

JSON (JavaScript Object Notation) has become the de facto standard for data interchange in modern web development. Whether you're building REST APIs, configuring applications, or storing data, proper JSON formatting is crucial for maintainability and debugging.

Why JSON Formatting Matters

Properly formatted JSON makes your data structures easier to read, debug, and maintain. While minified JSON is ideal for production environments to reduce bandwidth, formatted JSON is essential during development.

Development vs Production

  • Development: Use prettified JSON with indentation for readability
  • Production: Use minified JSON to reduce file size and improve performance
  • Version Control: Always commit formatted JSON for better diff tracking

Essential Formatting Rules

1. Consistent Indentation

Use consistent indentation (2 or 4 spaces) throughout your JSON files. Most teams prefer 2 spaces for JSON:

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

2. Use Double Quotes

JSON spec requires double quotes for strings. Single quotes are not valid:

// ✅ Correct
{"name": "Alice"}

// ❌ Incorrect
{'name': 'Alice'}

3. No Trailing Commas

Unlike JavaScript, JSON does not allow trailing commas:

// ✅ Correct
{
  "items": ["apple", "banana", "cherry"]
}

// ❌ Incorrect
{
  "items": ["apple", "banana", "cherry",]
}

4. Organize Keys Logically

Group related properties and order them logically:

{
  "id": 1,
  "type": "user",
  "attributes": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com"
  },
  "metadata": {
    "created": "2025-01-01",
    "updated": "2025-01-10"
  }
}

Common Pitfalls to Avoid

1. Comments in JSON

Standard JSON doesn't support comments. If you need comments, consider:

  • Using a separate documentation file
  • Converting to JSON5 or JSONC for config files
  • Adding a _comment property (though not recommended)

2. Undefined and NaN

JSON doesn't support JavaScript's undefined or NaN. Use null instead:

{
  "value": null,
  "count": 0
}

3. Date Formatting

JSON has no native date type. Use ISO 8601 format:

{
  "timestamp": "2025-01-10T14:30:00Z",
  "date": "2025-01-10"
}

Tools for JSON Formatting

Several tools can help maintain proper JSON formatting:

  1. Online Formatters: toolcli JSON Formatter, JSONLint
  2. IDE Extensions: Prettier, ESLint with JSON plugins
  3. CLI Tools: jq for command-line JSON processing
  4. Git Hooks: Pre-commit hooks to validate JSON format

API Response Formatting

When designing APIs, consider these formatting practices:

Consistent Structure

{
  "status": "success",
  "data": {
    "users": [...]
  },
  "meta": {
    "page": 1,
    "total": 100
  }
}

Error Responses

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": {
      "field": "email",
      "value": "invalid-email"
    }
  }
}

Configuration Files

For configuration files, consider:

  1. Environment-specific configs: Use clear naming like config.dev.json, config.prod.json
  2. Validation: Implement JSON schema validation
  3. Documentation: Provide schema files and examples
  4. Secrets: Never commit sensitive data; use environment variables

Performance Considerations

When to Minify

Minify JSON for:

  • API responses in production
  • Static assets served to clients
  • Data stored in constrained environments

When to Format

Keep formatted JSON for:

  • Development and debugging
  • Version control commits
  • Documentation and examples
  • Configuration files

Conclusion

Proper JSON formatting is a fundamental skill for modern developers. By following these best practices, you'll write more maintainable code, debug issues faster, and collaborate more effectively with your team.

Remember to use tools like toolcli JSON Formatter to automatically format your JSON and catch syntax errors early in the development process.

Additional Resources