12 Best Practices

Follow these conventions to write clean, maintainable JSON that works well across teams and tools.

Naming Conventions

StyleExampleRecommendation
snake_case"first_name"Recommended for most JSON (Python-friendly)
camelCase"firstName"Common in JavaScript ecosystems
kebab-case"first-name"Avoid — hyphens conflict with arithmetic
PascalCase"FirstName"Avoid — reserved for classes in some languages

Rule of thumb: Choose one style and use it consistently across your entire project.

Structure Guidelines

Keep it flat when possible. Prefer:

// Good — flat
{
    "street": "123 Main St",
    "city": "Boston",
    "zip": "02101"
}

// Over-engineered — avoid unnecessary nesting
{
    "address": {
        "street": "123 Main St",
        "city": "Boston",
        "zip": "02101"
    }
}

Data Tips

TipGoodBad
Use booleans"active": true"active": "yes"
Use numbers for numbers"count": 5"count": "5"
Use null for missing"middle": null"middle": "null" or omit
Arrays for lists"tags": ["a","b"]"tags": "a,b"
Use ISO dates"2026-07-03""07/03/2026"

File Organization

  • One JSON file per concern — split data across files (e.g., users.json, products.json)
  • Use .json extension — never .txt or custom extensions
  • Pretty-print for editing — use 2-space or 4-space indentation
  • Minify for production — remove whitespace when serving over the network
  • Validate before committing — run a JSON validator in your CI pipeline

Common Pitfalls to Avoid

PitfallWhy it's badSolution
Comments in JSONNot part of the spec — breaks parsersUse a separate schema or docs file
Trailing commasInvalid in JSONRemove comma after last item
Overly deep nestingHard to read and accessFlatten or use references
Inconsistent key namingConfusing for developersAdopt a naming convention and stick to it
Storing binary dataJSON is text-onlyUse Base64 encoding or store separately

Quick Reference

{
    // ✔ Do this
    "name": "Alice",
    "age": 30,
    "active": true,
    "tags": ["json", "guide"],
    "address": null,

    // ✘ Not this
    "name": 'Alice',      // single quotes
    "age": "30",          // number as string
    "active": "true",     // boolean as string
    "tags": "json,guide", // array as string
    "address": "null"     // null as string
}

Remember: Valid JSON is strict JSON. A single error makes the entire file unusable. Always validate your JSON files before using them.

← Back