JSON Formatting Best Practices for APIs and Configs
JSON has quietly become the lingua franca of modern software. It moves data between web services, defines the configuration of build tools, structures the manifests of package managers, and serializes most of the state we ship across networks. The format is simple enough that it is tempting to assume there is nothing to learn. In practice, the small formatting decisions you make — key style, indentation, number handling, ordering — are the difference between a JSON contract that ages well and one that becomes painful in six months.
This guide collects the practices that survive contact with real systems: production APIs, config files in version control, and machine-to-machine data exchange.
Key Naming: Pick One Style and Hold It
The first and most contentious decision is key naming. The two real choices are camelCase and snake_case. There is no technical advantage either way — JSON parsers do not care. The advantage comes from consistency.
Most large APIs follow one convention exclusively. Google, Twitter, and most cloud providers use camelCase; Stripe, Slack, and a number of Python-heavy services use snake_case. The wrong move is mixing them in the same payload ({"userId": 1, "user_email": "..."}). Mixed casing forces every consumer to remember which exception applies to which field.
If your backend is Python or Ruby, snake_case aligns naturally with the language and removes a translation step. If you serve JavaScript-heavy frontends, camelCase matches the language and avoids an unmapping layer. Either is defensible; pick once, document it, and enforce it with a linter.
Indentation, Whitespace, and File Size
JSON has two reasonable shapes: pretty (indented, one key per line) and minified (no whitespace at all). They are interchangeable for parsers and meaningfully different for humans and bandwidth.
Pretty (good for files in git):
{
"name": "WordCaseFix",
"version": "1.0.0",
"features": ["case", "regex", "json"]
}
Minified (good for API responses):
{"name":"WordCaseFix","version":"1.0.0","features":["case","regex","json"]}
For configuration files committed to version control, use pretty JSON with two-space indentation. The size cost is irrelevant and the diff readability is huge. For API responses over the wire, minify by default; gzip will compress away most of the difference, but the bytes still travel through every proxy and log. Use a formatter to switch between the two, and a minifier-style mindset for production payloads.
Numbers, Strings, and the Quiet Gotchas
JSON has one number type. Internally, most parsers represent it as a 64-bit IEEE 754 float, which can exactly represent integers only up to 2^53 (9,007,199,254,740,992). If your API returns 64-bit integer IDs from a database, send them as strings, not numbers — otherwise JavaScript clients will silently corrupt the last few digits.
| Value type | JSON representation | Watch out for |
|---|---|---|
| Big integer ID | String: "123456789012345678" | JS Number.MAX_SAFE_INTEGER ≈ 9.0×10^15 |
| Money | String or integer cents | Never floats — 0.1+0.2 !== 0.3 |
| Date/time | ISO 8601 string | Avoid epoch-seconds ambiguity |
| Null vs missing | Pick one explicitly | Document which means "unknown" |
| Boolean | true / false | Never "true"/"false" as strings |
Dates should always be ISO 8601 with explicit timezone (2025-06-18T14:30:00Z or 2025-06-18T14:30:00+02:00). Naked dates without timezone information are a frequent source of off-by-one bugs across continents.
Schema, Ordering, and Compatibility
JSON itself has no schema, but real APIs need one. Use JSON Schema or OpenAPI to document the shape of every endpoint, and publish that schema alongside the API. Consumers will use it for code generation, validation, and documentation.
Key order in objects is officially insignificant — by the JSON spec, {"a":1,"b":2} equals {"b":2,"a":1}. In practice, deterministic key ordering makes diffs reviewable and makes deterministic hashing possible. Most formatters offer "sort keys" alphabetically; consider it for configuration files. For API responses, prefer a stable order chosen by your library to keep network traces consistent.
For long-term compatibility, follow two simple rules: never remove or rename a field — add new ones; treat unknown fields as ignorable on the consumer side. If you serve config that may evolve, you may also want to convert between YAML and JSON or CSV and JSON at the edges, so users of each format don't fork your source of truth.
package.json they do not. Use a documented schema and meaningful key names instead of trying to comment inside data.
Validation and Tooling
One of JSON's strengths is that the syntax is strict enough to be machine-verified before any application logic runs. A surprising number of production bugs come from JSON that "almost" validates — a trailing comma, an unescaped tab inside a string, a literal newline where a \n escape was intended. Adding a JSON validator to your build pipeline catches these in seconds instead of in production logs.
For source-controlled configuration, format-on-save is the simplest tooling improvement you can make. Every modern editor offers a JSON formatter as a built-in or extension, and the keyboard-shortcut habit removes whole categories of merge conflict. Where pretty-printing matters across machines, commit a .editorconfig file alongside the JSON to lock the indentation choice. For API responses, write at least one contract test per endpoint that loads a real sample of the response and validates it against a JSON Schema; this protects you from silent shape regressions when a backend team renames a field.
Frequently Asked Questions
Can JSON have trailing commas?
Not in standard JSON. {"a":1,} is invalid and most parsers will reject it. JSON5 and some lenient parsers accept trailing commas, but if your file might be read by anything else, leave them off. Use a JSON validator if you suspect a stray comma is breaking your payload.
How should I represent enums in JSON?
As strings, not integers. "status": "active" is self-documenting; "status": 1 requires the consumer to know what 1 means. The few bytes saved by integers are never worth the readability cost in logs and dashboards.
Is YAML better than JSON for configuration?
For files humans edit by hand, YAML's comments and reduced punctuation are real advantages. For files programs generate or consume frequently, JSON's stricter syntax catches more errors. Many projects choose YAML for source-controlled config and JSON for machine output, converting between them with a YAML-to-JSON converter as needed.