JSON Best Practices: Design, Naming, and Data Types

Why This List Exists

JSON looks simple, so teams often ship inconsistent shapes: camelCase mixed with snake_case, dates in three formats, IDs sometimes strings and sometimes numbers, arrays that suddenly become objects. Each inconsistency costs debugging time forever.

The practices below are boring on purpose. Boring keeps production stable.

Naming: Pick One and Stick

camelCase is the modern default for public JSON APIs, matches JavaScript idioms, and is the choice in Google’s JSON style guide. snake_case is fine for internal or Python-heavy stacks. Never mix within one payload.

Data Types: Be Explicit

JSON has six types: string, number, boolean, null, object, array. Use them precisely.

• Numbers for quantities. Strings for identifiers—even numeric IDs.
• Booleans for booleans. Do not send "true" (string) or 1 (number).
• null when the value is absent by design; missing key when it is not applicable.
• Arrays for ordered lists of the same shape.
• Objects for records with named fields.

IDs Are Strings

Long numeric IDs overflow JavaScript’s 53-bit integer range. IDs with leading zeros lose the zeros when parsed as numbers. Order IDs, phone numbers, and postal codes all belong as strings.

{
  "orderId": "1000000000000000123",
  "postalCode": "01234"
}

Dates and Times: Use ISO 8601

ISO 8601 (YYYY-MM-DD or the full timestamp with timezone) is the only unambiguous format across locales.

{
  "createdAt": "2026-07-25T14:30:00Z",
  "birthdate": "1990-04-12"
}

Nulls, Empties, and Missing Keys

There are three ways to say "nothing", and they mean different things.

Consistent Shapes

APIs should not change shape based on the number of items.

• Always return arrays for list endpoints, even if there is one item.
• Do not switch a key between object and array.
• Prefer flat structures over deeply nested ones when both work.
• Repeat keys instead of merging distinct records.

// Good
{ "items": [{ "id": "1" }] }

// Bad — shape changes when only one item
{ "items": { "id": "1" } }

Versioning

Every JSON contract eventually changes. Plan for it.

• Version the API path (/v1/orders) or use a header for API versioning.
• Include a $schema URL for standalone JSON files when useful.
• Add new fields as optional; never repurpose existing fields.
• Remove fields only after a deprecation window.

Validation With JSON Schema

A schema turns "trust the client" into "verify at the door". Reject bad payloads with field-level errors instead of failing deeper in the code.

{
  "type": "object",
  "required": ["orderId", "email"],
  "properties": {
    "orderId": { "type": "string" },
    "email":   { "type": "string", "format": "email" }
  },
  "additionalProperties": false
}

Errors: Standardized and Actionable

Adopt a shape and use it everywhere.

{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Email is not valid",
    "field": "email"
  }
}

Real-World Examples

How these habits show up.

Common Mistakes

Every one of these is a real ticket teams have shipped.

• Numeric IDs that overflow JavaScript.
• Mixed date formats across endpoints.
• Reusing a field for a new meaning after a release.
• Returning null for lists instead of [].
• Silently dropping unknown fields instead of failing loudly.

Best Practices Cheat Sheet

A tight summary for your team wiki.

• Pick one naming style.
• IDs as strings, always.
• ISO 8601 for dates and times.
• Consistent shapes, even for single items.
• Version your API and evolve additively.
• Validate with JSON Schema at trust boundaries.
• Return field-level errors.

Why Use Convert CSV Online?

When JSON comes from a spreadsheet, Convert CSV Online is free, browser-based, and requires no account for everyday conversions. It preserves string IDs, produces predictable shapes, and lets you preview in the Online CSV Editor. Client-side workflows run on Windows, macOS, and Linux browsers.

Conclusion

JSON is easy to write and easy to write badly. Adopt the boring rules above and future engineers—including you—will move faster.