JSON is the de facto data format of the modern web. It is also one of the most abused — trailing commas, single quotes, mixed casing, inconsistent nesting. Bad JSON is debuggable; inconsistent JSON across an API is a maintenance nightmare. This guide covers the practices we use to keep JSON clean across thousands of API responses.
1. Always pretty-print during development
Minified JSON is great for production (smaller wire size), but during development you want indentation. Pretty-printed JSON with 2-space indent is the universal standard — 4 spaces wastes horizontal space, tabs render inconsistently across terminals.
{
"id": "usr_8f3a",
"email": "ada@example.com",
"createdAt": "2026-06-15T10:30:00Z",
"roles": ["admin", "editor"]
}Use a JSON Formatter that highlights syntax errors at the exact character offset — you will catch typos in seconds instead of staring at "Unexpected token" stack traces.
2. Validate before you ship
Common JSON syntax mistakes that break parsers:
- Trailing commas — {"a": 1,} is invalid in strict JSON (allowed in JS but breaks JSON.parse).
- Single quotes — JSON requires double quotes for both keys and string values.
- Comments — JSON has no comments. Use a separate JSON-with-Comments format (JSONC) if you must.
- Unquoted keys — {name: "ada"} is JS, not JSON.
- NaN, Infinity, undefined — not valid in JSON. Use null or omit the key.
3. Consistent key naming
Pick one casing convention and stick to it across your entire API. The three common choices:
- camelCase — JavaScript convention, most common in web APIs (Stripe, GitHub).
- snake_case — Python/Ruby convention, common in backend-heavy APIs (GitHub v3 mixed).
- kebab-case — rare in JSON, common in URLs and CSS.
Never mix casing in the same API. A response with userId, user_id, and user-id in different endpoints is a documentation disaster.
4. ISO 8601 for all dates
Dates are the single biggest source of parsing bugs. Always use ISO 8601 with a timezone (UTC preferred):
"createdAt": "2026-06-15T10:30:00Z"
"updatedAt": "2026-06-15T10:30:00+02:00"Avoid Unix timestamps in JSON unless you have a specific performance reason — they are unreadable in logs and easy to confuse with milliseconds-vs-seconds.
5. Flatten when you can, nest when you must
Deeply nested JSON is hard to query, hard to convert to CSV, and hard to read. Prefer flat structures with prefixed keys:
// Avoid
{
"user": {
"address": {
"city": "Lisbon",
"country": "PT"
}
}
}
// Prefer (for tabular use cases)
{
"user_city": "Lisbon",
"user_country": "PT"
}Nest when the child object has independent identity (e.g. an order with line items) — flat here would force artificial keys like order_line_1_name.
6. Minify for production
Whitespace is bytes. For large payloads served over the wire, minify:
{"id":"usr_8f3a","email":"ada@example.com","roles":["admin","editor"]}Minification typically saves 15–30% on JSON payload size. Combined with gzip, the savings compound. Just make sure your dev tooling pretty-prints on read — minified JSON in a debugger is brutal.
7. Convert to CSV for non-developers
When you need to share API output with stakeholders, JSON is the wrong format. Convert to CSV — every spreadsheet tool on earth opens CSV natively. A JSON to CSV converter flattens arrays of objects into rows; each top-level key becomes a column.
Use case: export your user list endpoint as CSV for the marketing team. They open it in Excel, filter and pivot, and never touch your database.
8. Schema is a contract, not a suggestion
If you control both sides of an API, define the schema with JSON Schema. Even a loose schema catches:
- Missing required fields
- Wrong types (string vs number for IDs)
- Out-of-range values (negative IDs, future dates)
- Inconsistent enum values across environments
A 30-line JSON Schema file saves days of debugging "why does staging return user_id as a number but prod returns a string?"
9. Versioning
Add a version field at the top level so consumers can branch on schema:
{
"version": "2026-06-01",
"data": { ... }
}Date-based versions beat numeric versions — they communicate when the schema changed and let consumers migrate on a schedule.
Putting it together
Clean JSON is a habit, not a feature. Pretty-print in dev, minify in prod, validate before shipping, use ISO 8601 dates, pick one casing convention, and convert to CSV when sharing with non-developers. Run your payloads through a JSON Formatter and JSON to CSV Converter as part of your normal workflow — the discipline pays off the first time you debug a production issue at 2am.