JSON Formatting Best Practices

Why Formatting Matters

"It's just data, who cares how it looks?"

You will. At 3 AM. When you're debugging a 500-line config file and can't find that one misplaced comma. Formatting is a gift to your future self.

Well-formatted JSON is:

• Easier to read — Find what you need quickly
• Easier to debug — Spot errors at a glance
• Easier to diff — Version control shows meaningful changes
• Easier to maintain — Other developers will thank you

Indentation: The Great Debate

Two camps: 2 spaces vs 4 spaces. (Tabs people exist too, bless their hearts.)

Industry consensus: 2 spaces. Most major projects (npm, VS Code configs, Google's style guide) use 2 spaces. It's compact but readable.

{
  "user": {
    "name": "Alice",
    "email": "alice@example.com",
    "settings": {
      "theme": "dark",
      "notifications": true
    }
  }
}

Compare with 4 spaces:

{
    "user": {
        "name": "Alice",
        "email": "alice@example.com",
        "settings": {
            "theme": "dark",
            "notifications": true
        }
    }
}

Both work. Pick one for your project and stick with it. Consistency beats personal preference.

Key Naming Conventions

There are several conventions for naming JSON keys. Here's the breakdown:

camelCase (Recommended for JavaScript)

{
  "firstName": "John",
  "lastName": "Doe",
  "emailAddress": "john@example.com",
  "phoneNumber": "+1-555-0100"
}

This is the standard in JavaScript ecosystems. It maps directly to JS object properties.

snake_case (Common in Python/Ruby APIs)

{
  "first_name": "John",
  "last_name": "Doe",
  "email_address": "john@example.com",
  "phone_number": "+1-555-0100"
}

Python APIs often use this. It's also valid and widely used.

kebab-case (Avoid for JSON keys)

{
  "first-name": "John"
}

Don't use this. In JavaScript, you'd need bracket notation: obj["first-name"]. Annoying.

Key Ordering

JSON objects are technically unordered. But for humans, order matters.

Option 1: Alphabetical

{
  "age": 28,
  "email": "john@example.com",
  "id": 1,
  "name": "John",
  "role": "admin"
}

Pros: Easy to find keys, consistent diffs. Cons: Related keys might be far apart.

Option 2: Logical Grouping

{
  "id": 1,
  "name": "John",
  "email": "john@example.com",
  "age": 28,
  "role": "admin"
}

Pros: ID first (primary identifier), then personal info, then metadata. Cons: Requires agreement on what's "logical."

My recommendation: For config files, use logical grouping. For data interchange, alphabetical is safer.

Minified vs Pretty-Printed

Know when to use which:

Pretty-Printed (Development)

For humans: config files, debugging, documentation examples.

{
  "name": "my-app",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.18.2"
  }
}

Minified (Production)

For machines: API responses, data storage, network transfer.

{"name":"my-app","version":"1.0.0","dependencies":{"express":"^4.18.2"}}

Minified JSON is ~30% smaller. For APIs serving millions of requests, that adds up to real bandwidth savings.

JavaScript Conversion

const data = { name: "Alice", age: 25 };

// Pretty print
const pretty = JSON.stringify(data, null, 2);

// Minify
const mini = JSON.stringify(data);

// Pretty print existing JSON string
const formatted = JSON.stringify(JSON.parse(jsonString), null, 2);

Formatting Arrays

Short Arrays: Single Line

{
  "tags": ["javascript", "tutorial", "beginner"],
  "scores": [98, 87, 92]
}

Long Arrays: Multi-Line

{
  "users": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" },
    { "id": 3, "name": "Charlie" }
  ]
}

Array of Objects: One Per Line

{
  "permissions": [
    {
      "resource": "users",
      "actions": ["read", "write"]
    },
    {
      "resource": "posts",
      "actions": ["read"]
    }
  ]
}

Rule of thumb: If an array fits on one line without scrolling, keep it there. Otherwise, expand it.

Null and Empty Values

Be consistent with how you handle missing data:

Option 1: Omit Missing Keys

{
  "name": "Alice",
  "email": "alice@example.com"
}

The middleName key isn't present. Code must check if it exists.

Option 2: Include as Null

{
  "name": "Alice",
  "middleName": null,
  "email": "alice@example.com"
}

Explicit about what's missing. Easier for consumers to know what fields exist.

Date Formatting

JSON has no date type. Use ISO 8601 format:

{
  "createdAt": "2024-11-24T10:30:00Z",
  "updatedAt": "2024-11-24T15:45:30.123Z",
  "birthDate": "1995-06-15"
}

Always include timezone for timestamps (the Z means UTC). Date-only fields (like birthDate) don't need time components.

Number Formatting

{
  "integer": 42,
  "float": 3.14159,
  "scientific": 1.23e10,
  "negative": -42,
  "zero": 0
}

Don't do this:

{
  "price": "19.99",
  "count": "42",
  "available": "true"
}

Numbers and booleans should be their actual types, not strings. Stringly-typed data is a code smell.

Special Characters and Escaping

Some characters must be escaped in JSON strings:

{
  "quote": "She said \"Hello!\"",
  "path": "C:\\Users\\Documents",
  "multiline": "Line 1\nLine 2",
  "tab": "Column1\tColumn2"
}

Formatting Tools

Online Tools

• JSON-parser.net — Our tool! Format, validate, and beautify JSON
• VS Code built-in — Right-click → Format Document
• Prettier — Supports JSON with configurable options

Command Line

# Python (built-in)
python -m json.tool input.json > formatted.json

# Node.js
cat input.json | npx json -o json-4

# jq (powerful JSON processor)
jq '.' input.json > formatted.json

Programmatic Formatting

// JavaScript
const formatted = JSON.stringify(data, null, 2);

// With sorting keys
const sortedFormatted = JSON.stringify(data, Object.keys(data).sort(), 2);

Formatting Checklist

Before committing JSON files, check:

• ✅ Consistent indentation (2 spaces recommended)
• ✅ Consistent key naming (camelCase or snake_case)
• ✅ No trailing commas
• ✅ Numbers are numbers, not strings
• ✅ Booleans are booleans, not strings
• ✅ Dates use ISO 8601 format
• ✅ No invalid characters or encoding issues
• ✅ Valid JSON (run through a validator)

FAQ

Should I use single or double quotes?

Double quotes only. JSON doesn't support single quotes. Ever.

Can I add comments to JSON?

No. Standard JSON doesn't support comments. Use JSONC (JSON with Comments) if your tooling supports it, or switch to YAML for config files.

What about trailing commas?

Not allowed in JSON. Your parser will reject them. Use a linter or formatter to catch these.

Related Guides

• What is JSON? — The fundamentals
• Common JSON Errors — Debug formatting issues
• JSON to YAML — Alternative format