JSON Formatting Best Practices for Developers

2-Space Indentation (Recommended for most projects)

{
  "user": {
    "id": 123,
    "profile": {
      "name": "John Doe",
      "email": "john@example.com",
      "preferences": {
        "theme": "dark",
        "notifications": true
      }
    },
    "roles": ["admin", "user"]
  }
}

✅ Best for web development, saves horizontal space, works well in most editors

4-Space Indentation

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

ℹ️ Good for complex nested structures, more readable but uses more horizontal space

Tab Indentation (Not Recommended)

{
	"user": {
		"id": 123,
		"name": "John"
	}
}

❌ Inconsistent rendering across different editors and platforms

camelCase (Recommended for JavaScript projects)

{
  "firstName": "John",
  "lastName": "Doe",
  "emailAddress": "john@example.com",
  "userPreferences": {
    "defaultTheme": "dark",
    "enableNotifications": true
  },
  "accountCreatedAt": "2024-01-01T00:00:00Z"
}

✅ Native JavaScript convention, no transformation needed in JS applications

snake_case (Common in Python/API projects)

{
  "first_name": "John",
  "last_name": "Doe",
  "email_address": "john@example.com",
  "user_preferences": {
    "default_theme": "dark",
    "enable_notifications": true
  },
  "account_created_at": "2024-01-01T00:00:00Z"
}

ℹ️ Common in REST APIs, Python applications, and database-centric systems

kebab-case (Avoid for JSON)

{
  "first-name": "John",
  "last-name": "Doe",
  "email-address": "john@example.com"
}

❌ Requires quotes when accessing properties in JavaScript: obj["first-name"]

Small Arrays - Single Line

{
  "colors": ["red", "green", "blue"],
  "numbers": [1, 2, 3, 4, 5],
  "roles": ["admin", "user"]
}

✅ Good for simple arrays with few, short items

Large Arrays - Multi-line

{
  "users": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com"
    },
    {
      "id": 2,
      "name": "Jane Smith", 
      "email": "jane@example.com"
    }
  ],
  "permissions": [
    "read",
    "write",
    "delete",
    "admin"
  ]
}

ℹ️ Better for complex objects or long lists

Nested Objects Structure

{
  "app": {
    "name": "MyApp",
    "version": "1.2.3",
    "config": {
      "database": {
        "host": "localhost",
        "port": 5432,
        "credentials": {
          "username": "admin",
          "passwordHash": "..."
        }
      },
      "cache": {
        "enabled": true,
        "ttl": 3600
      }
    }
  }
}

💡 Each nesting level gets consistent indentation

Establishing Team Standards

• Document JSON formatting rules in your style guide
• Choose consistent indentation (2 or 4 spaces)
• Standardize key naming convention (camelCase or snake_case)
• Define when to use single-line vs multi-line arrays
• Set maximum line length guidelines
• Establish sorting rules for object keys

Automation Tools

Git Hooks and CI/CD

# Pre-commit hook to format JSON files
#!/bin/bash
for file in $(git diff --cached --name-only | grep -E '\.(json)$'); do
  if [ -f "$file" ]; then
    prettier --write "$file"
    git add "$file"
  fi
done

Security Best Practices

• Never include sensitive data in formatted JSON committed to version control
• Use environment variables for secrets in configuration files
• Be cautious with JSON formatting in logs (may expose sensitive data)
• Validate JSON structure before formatting to prevent injection attacks

Performance Considerations

• Formatted JSON is 20-40% larger than minified JSON
• Use compression (gzip) to reduce network transfer costs
• Consider streaming parsers for very large JSON files
• Cache formatted versions to avoid repeated processing