JSON Style Guide — Naming Conventions, Formatting & Documentation Best Practices

Why a JSON Style Guide Matters

JSON has no opinion on key names, ordering, or formatting. Without team conventions, you end up with:

Inconsistent JSON — real-world examplejson

1{
2  "user_name": "Alice",
3  "userEmail": "[email protected]",
4  "Phone": "+1-555-0100",
5  "isActive": true,
6  "is_admin": false,
7  "created": "2026-04-02",
8  "updated_at": 1711929600,
9  "DOB": null
10}

Three different naming conventions. Two different date formats. Inconsistent null handling. This guide fixes all of it.

1. Naming Conventions

Convention	Example	Used By
camelCase	"userName", "createdAt"	JavaScript, TypeScript, Google JSON Style Guide
snake_case	"user_name", "created_at"	Python, Ruby, PostgreSQL, Stripe API
kebab-case	"user-name", "created-at"	CSS, HTML attributes (rare in JSON)
PascalCase	"UserName", "CreatedAt"	C#, .NET APIs

Important

Pick one convention and enforce it across your entire API. The most common choices are camelCase (JS ecosystems) and snake_case (Python/Ruby ecosystems). Mixing conventions within a single response is the worst outcome.

Key Naming Rules

✓Use descriptive names: "emailAddress" not "ea"
✓Use plural for arrays: "users" not "user"
✓Use is/has prefix for booleans: "isActive", "hasPermission"
✓Use At suffix for timestamps: "createdAt", "updatedAt"
✗Don't use abbreviations: "cnt" → "count"
✗Don't use type prefixes: "strName" → "name"

2. Formatting & Indentation

Context	Recommendation
Config files (package.json, tsconfig.json)	2-space indentation — matches ecosystem convention
API responses (production)	Minified — no whitespace (smaller payload, faster transfer)
API responses (development / debug)	2-space indented for readability
Documentation examples	2 or 4-space — match your team standard
Logs and debugging	Pretty-printed with JSON.stringify(data, null, 2)

Formatting in JavaScriptjavascript

1// Pretty-print for debugging
2const pretty = JSON.stringify(data, null, 2);
3
4// Minified for production
5const minified = JSON.stringify(data);
6
7// Custom formatting with a replacer
8const filtered = JSON.stringify(data, ['id', 'name', 'email'], 2);

3. Key Ordering

JSON objects are unordered by specification, but consistent ordering improves readability and diffing:

Recommended Key Ordering

Well-ordered JSON responsejson

1{
2  "id": "usr_8742",
3  "type": "user",
4  "name": "Alice Chen",
5  "email": "[email protected]",
6  "role": "admin",
7  "isActive": true,
8  "organizationId": "org_001",
9  "permissions": ["read", "write", "delete"],
10  "createdAt": "2026-01-15T10:30:00Z",
11  "updatedAt": "2026-04-02T14:00:00Z"
12}

Tip

Use a JSON Sorter to enforce key ordering automatically. In CI/CD, you can lint for key order using eslint-plugin-jsonc.

4. Date & Time Formats

Format	Example	When to Use
ISO 8601 with timezone	"2026-04-02T14:30:00Z"	Timestamps in APIs (recommended default)
ISO 8601 date only	"2026-04-02"	Dates without time (birthdays, deadlines)
ISO 8601 with offset	"2026-04-02T14:30:00+05:30"	When local timezone matters
Unix timestamp (seconds)	1711929600	Machine-to-machine, avoid in user-facing APIs
Unix timestamp (ms)	1711929600000	JavaScript Date.now() compatible

Important

Always use ISO 8601 strings for APIs. Unix timestamps are ambiguous (seconds vs milliseconds), unreadable in debugging, and create timezone confusion. Name timestamp fields with the At suffix: "createdAt", "expiresAt".

5. Null, Empty, and Missing Values

Scenario	Convention	Example
Field has no value	Use null — field is present but empty	"middleName": null
Field is inapplicable	Omit the key entirely	(key not present in response)
Empty collection	Use empty array, not null	"tags": []
Empty text	Use empty string or null (document which)	"bio": "" or "bio": null
Unknown boolean	Use null, not false	"isVerified": null

Consistent null handlingjson

1{
2  "id": "usr_8742",
3  "name": "Alice Chen",
4  "middleName": null,
5  "bio": "",
6  "tags": [],
7  "avatarUrl": null,
8  "isVerified": true,
9  "deletedAt": null
10}

6. Enumerations and Constants

Use string enums, not magic numbersjson

1{
2  "status": "active",
3  "role": "admin",
4  "priority": "high",
5  "currency": "USD"
6}
7
8// NOT this:
9{
10  "status": 1,
11  "role": 0,
12  "priority": 3,
13  "currency": 840
14}

Tip

String enums are self-documenting. "status": "active" is immediately clear. "status": 1 requires a lookup table. Define valid values in your JSON Schema or API docs.

7. Versioning JSON APIs

Include version contextjson

1{
2  "apiVersion": "2",
3  "data": {
4    "id": "usr_8742",
5    "name": "Alice Chen"
6  },
7  "meta": {
8    "requestId": "req_abc123",
9    "timestamp": "2026-04-02T14:30:00Z"
10  }
11}

Common versioning strategies: URL path (/v2/users), header (Accept: application/vnd.api+json;version=2), or response envelope ("apiVersion": "2").

8. The Definitive Checklist

✓One naming convention across all endpoints (camelCase or snake_case)
✓ISO 8601 for all dates and timestamps
✓Consistent null vs omit strategy, documented
✓String enums instead of magic numbers
✓Plural names for arrays, is/has prefix for booleans
✓Logical key ordering: identity → primary → data → relations → metadata
✓2-space indentation for config files, minified for production APIs
✓JSON Schema definition for every API endpoint
✓Linting in CI/CD (eslint-plugin-jsonc or custom rules)

Try It — Clean Up Inconsistent JSON

Try It Yourself

This JSON mixes conventions — try rewriting it with consistent camelCase

Try These Tools

JSON Sorter

Sort keys alphabetically or by custom priority

Open tool

JSON Pretty Print & Viewer

Format JSON with consistent indentation

Open tool

JSON Minifier

Minify JSON for production deployment

Open tool

JSON Validator

Validate JSON syntax before deployment

Open tool

Continue Learning

Structuring API Responses

Apply style guide rules to production API responses

JSON Config Files

Style conventions for package.json, tsconfig, and more

JSON Schema Validation

Enforce your style guide with JSON Schema

JSON vs XML vs YAML

How JSON style compares to XML and YAML conventions

Frequently Asked Questions

Should JSON keys use camelCase or snake_case?

It depends on your ecosystem. JavaScript/TypeScript APIs typically use camelCase (userName). Python/Ruby APIs typically use snake_case (user_name). The most important rule: pick one convention and use it consistently across your entire API. Google's JSON style guide recommends camelCase.

Should I use 2-space or 4-space indentation in JSON?

Both are valid. 2-space is more common in JavaScript ecosystems (package.json, tsconfig.json). 4-space is common in Python and Java ecosystems. Pick one and enforce it with a formatter. For APIs, indentation does not matter — production JSON should be minified.

How should I represent dates in JSON?

Use ISO 8601 format: "2026-04-02T14:30:00Z" for timestamps with timezone, or "2026-04-02" for date-only values. Always include the timezone offset or use UTC (Z suffix). Never use Unix timestamps in user-facing APIs — they are unreadable.

Should I include null values or omit missing keys?

For APIs: include the key with null if clients expect it (explicit schema). Omit it if the field is truly optional and clients handle missing keys. Be consistent — don't sometimes include null and sometimes omit the key for the same field. Document your convention.

How should I order keys in JSON objects?

Common strategies: (1) alphabetical — easiest to scan; (2) logical grouping — id first, then name, then metadata; (3) importance — most-used fields first. Alphabetical is easiest to enforce with tooling. Use a JSON sorter tool to maintain consistency.

Is it okay to add comments to JSON?

Standard JSON (RFC 8259) does not support comments. For config files, use JSONC (JSON with Comments, supported by VS Code and TypeScript) or JSON5. For documentation, use a companion schema file or README rather than trying to comment in JSON.