Knowledge Base: JSON Formatting Best Practices

Start Here: What Good JSON Looks Like

Good JSON is not just pretty-printed. It is valid according to the JSON specification, easy to scan in code review, and safe to exchange across languages and tools. The highest-value habits are simple: emit strict JSON, format it consistently, keep object keys unique, and validate important payloads against a schema.

If you want the short version, use this checklist:

• Use double quotes for every key and string value.
• Use consistent indentation, usually 2 spaces for web and API JSON.
• Do not ship comments, trailing commas, undefined, NaN, or Infinity.
• Keep object member names unique and do not rely on key order for meaning.
• Use explicit conventions for nulls, empty arrays, timestamps, and large numeric identifiers.
• Pin your JSON Schema draft when validation matters.

Use Strict JSON, Not JSON-Like Syntax

Many editors and libraries accept relaxed formats such as JSONC or JSON5, but a formatter should output strict JSON when the file or response is meant to be consumed as JSON. That means:

• Strings and keys use double quotes only.
• Comments are not allowed.
• Trailing commas are not allowed.
• Object member names should be unique for predictable interoperability.
• JSON numbers are finite only. NaN and Infinity are not valid JSON values.

{
  // invalid comment
  'userId': 42,
  "roles": ["admin",],
  "score": NaN,
  "userId": 99
}

{
  "userId": 42,
  "roles": [
    "admin"
  ],
  "score": null
}

A parser may accept extensions, but generators and published examples should stay strict. That is the safest way to avoid cross-language surprises.

Pick a Formatting Convention and Keep It Stable

Whitespace is insignificant to JSON parsers, but it matters a lot to human readers. Consistent formatting makes reviews faster and diffs smaller.

Recommended Defaults

• Prefer 2-space indentation for general web development and API payload examples.
• Put each property on its own line once an object stops being trivially short.
• Keep very short arrays inline only when they remain easy to scan.
• If a file is reviewed in Git, use a stable key order for readability, but never treat that order as part of the data contract.

{
  "accountId": "acct_1042",
  "createdAt": "2026-03-11T14:30:00Z",
  "displayName": "Northwind Labs",
  "features": [
    "exports",
    "history",
    "sso"
  ],
  "isActive": true,
  "plan": "pro"
}

Pretty-print for source control, logs meant for people, and documentation. Minify when payload size matters in transit or storage. The content stays the same; only the whitespace changes.

Design Values for Interoperability, Not Just Appearance

A formatter can make JSON look clean, but teams still need consistent rules for names, missing values, dates, and numbers. Those choices determine whether the JSON is easy to consume in real systems.

Key Names

Pick one naming style per API or dataset, usually camelCase or snake_case, and apply it everywhere. Avoid hyphens in keys unless you have a strong compatibility reason, because they are awkward in many programming languages.

Null, Omitted, and Empty Values

• Use null when a field exists conceptually but has no value.
• Omit a key when the field is optional and absent.
• Use [] or {} for an empty collection, not null, if the client can still iterate or read it as a collection.

Dates and Times

JSON has no built-in date type. Use full timestamp strings with a timezone, such as 2026-03-11T14:30:00Z. That keeps values portable and easier to validate. Avoid locale-specific formats like 03/11/2026, which are ambiguous across regions.

Numbers, IDs, and Money

Large integers are a common source of bugs because many parsers map JSON numbers to IEEE 754 doubles. Treat identifiers as strings if they may exceed safe integer precision. For money, prefer a documented convention such as integer minor units (1099 cents) or a decimal string, instead of leaving rounding behavior implicit.

{
  "invoiceId": "9007199254740993",
  "issuedAt": "2026-03-11T14:30:00Z",
  "customerName": "Avery Chen",
  "discountCode": null,
  "lineItems": [],
  "totalCents": 2599
}

Validate Important JSON With a Pinned Schema

If JSON matters to an API, config file, import pipeline, or knowledge base export, formatting alone is not enough. Add schema validation. The current general-use JSON Schema draft is 2020-12, and it is worth pinning explicitly so your examples and validators agree on the same rules.

• Declare $schema so validators do not guess the draft.
• Mark required properties and reject unexpected fields where the contract should stay tight.
• Treat format as helpful, but do not rely on it alone for critical business rules.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "invoiceId": { "type": "string" },
    "issuedAt": { "type": "string", "format": "date-time" },
    "totalCents": { "type": "integer", "minimum": 0 },
    "lineItems": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["invoiceId", "issuedAt", "totalCents", "lineItems"],
  "additionalProperties": false
}

Common Problems a JSON Formatter Will Not Fix for You

Pretty-printing can expose problems, but it cannot decide the meaning of broken or ambiguous data. Watch for these issues during review:

• Duplicate keys: some parsers keep the last value, others behave differently. Do not rely on duplicates being resolved the way you expect.
• Encoding issues: JSON exchanged across systems should be UTF-8. Unexpected byte-order marks or bad character encoding can break imports.
• Top-level primitives: valid JSON can be a single string or number, but objects and arrays are usually a better choice for APIs and data files because they are easier to extend.
• JSONC/JSON5 leakage: editor-friendly config syntax often breaks when copied into a strict JSON parser, linter, or API request.

Best-Practice Workflow

1. Write or generate strict JSON only.
2. Apply one formatting convention automatically across the project.
3. Review naming, timestamps, null handling, and numeric precision rules.
4. Validate with a pinned JSON Schema before storing, importing, or publishing the data.
5. Pretty-print for humans, minify for transport where size matters.

Conclusion

JSON formatting best practices are really about reducing ambiguity. Clean indentation helps humans, but the bigger wins come from strict syntax, unique keys, safe number handling, explicit timestamp conventions, and schema-backed validation. If your formatter and your contract rules agree, your JSON will stay readable, valid, and far more portable across tools and languages.