JSON Best Practices
JSON Best Practices separates what RFC 8259 actually requires from industry convention and OpenFormatter's own recommendations — so you know which rules you can bend and which you can't.
Try It Now
Put this into practice with OpenFormatter's free tools — no signup, 100% client-side.
Specification: RFC 8259 recommends treating integers outside the range [-(2^53)+1, (2^53)-1] as unsafe for interoperability — not a hard MUST, but an explicit SHOULD. Many JSON parsers (including JavaScript's) silently lose precision on integers larger than this without erroring, which is a real, recurring source of production bugs when APIs return large IDs as raw numbers instead of strings.
Important: A number like 0123 is valid in some programming languages but is never valid JSON — RFC 8259's grammar excludes leading zeros entirely (except the single digit 0 itself). This trips up developers hand-writing JSON who carry the habit over from a language that allows it.
Definition
Being syntactically valid JSON (see JSON Syntax) is the minimum bar — it says nothing about whether a document is well-designed. This page is proactive: how to structure JSON well from the start, rather than reactive troubleshooting once something's already broken. For that, see the site's JSON error and invalid-JSON troubleshooting guides instead.
Not every recommendation below carries the same weight. Some of it is mandated by RFC 8259 itself; most of it is convention the industry has converged on without the specification saying anything about it; a small amount is OpenFormatter's own recommendation for working with these tools specifically. Treating a convention as if it were a requirement — or vice versa — misrepresents what the specification actually says, which is exactly what the three sections below exist to prevent.
Examples
A reasonably flat structure versus the same data over-nested for no real benefit.
// Reasonable
{ "orderId": 482, "customerName": "Ada Lovelace", "total": 129.99 }
// Needlessly deep for the same three facts
{ "order": { "details": { "identification": { "id": { "value": 482 } } } } }Representing a date unambiguously — ISO 8601 avoids the format-guessing problem entirely.
{ "createdAt": "2026-01-15T09:30:00Z" }This page distinguishes between requirements defined by specifications, practices commonly adopted by the software industry, and recommendations from the OpenFormatter editorial team.
Specification Requirements
- gavelJSON exchanged between systems MUST be encoded as UTF-8 (RFC 8259 §8.1); a generator MUST NOT add a byte-order mark.
- gavelA JSON number can never have a leading zero before the decimal point, except the single digit 0 itself — 01 and 007 are not valid JSON.
- gavelA JSON number never has a leading + — only an optional leading - is permitted.
- gavelA decimal point must be followed by at least one digit — a bare trailing . is not valid JSON.
Industry Practices
- publicPick one property-naming convention (commonly camelCase or snake_case) and use it consistently across an entire API — mixing conventions within one payload is a common source of integration bugs, even though nothing in the specification requires either.
- publicKeep nesting shallow where practical. Deeply nested payloads are harder for both humans and client code to work with, even though the grammar itself has no depth limit.
- publicVersion APIs explicitly — a version field, a URL segment, a media type parameter — rather than expecting clients to infer compatibility from a response's shape.
- publicPrefer descriptive, unambiguous property names over abbreviations — customerId over cid.
OpenFormatter Recommendations
- tips_and_updatesValidate a payload before formatting or transforming it. Catching a syntax error before reformatting saves a confusing debugging session later.
- tips_and_updatesKeep debugging examples minimal — a 3-line reproduction of a problem is more useful than pasting an entire production payload.
- tips_and_updatesUse pretty-printed JSON during development and minify only for actual transport or storage: optimize for the reader while you're working, for bytes once you're done.
Common Mistakes
Representing dates as ambiguous, inconsistently-formatted strings
A string like "01/02/2026" can't be reliably parsed as January 2nd or February 1st without an agreed convention — and JSON has no native date type to fall back on for a hint.
Fix: Use ISO 8601 (e.g. "2026-01-02T00:00:00Z") consistently. It's unambiguous, sortable as a string, and has broad parser support across languages.