JSON

Schema & Validation

• Always validate against JSON Schema before processing untrusted input—don't assume structure
• Define schemas for API responses—catches contract violations early
• Use

  additionalProperties: false

  to reject unknown fields in strict contexts

Naming & Consistency

• Pick one convention and stick to it—

  camelCase

  for JS ecosystems,

  snake_case

  for Python/Ruby
• Avoid mixed conventions in same payload—

  userId

  alongside

  user_name

  confuses consumers
• Use plural for collections:

  "users": []

  not

  "user": []

Null Handling

• Distinguish "field is null" from "field is absent"—they mean different things
• Omit optional fields entirely rather than sending

  null

  —reduces payload, clearer intent
• Document which fields are nullable in schema—don't surprise consumers

Dates & Times

• Always use ISO 8601:

  "2024-01-15T14:30:00Z"

  —no ambiguous formats like

  "01/15/24"

• Include timezone or use UTC with

  Z

  suffix—local times without zone are useless
• Timestamps as strings, not epoch integers—human-readable, no precision loss

Numbers & IDs

• Large IDs as strings:

  "id": "9007199254740993"

  —JavaScript loses precision above 2^53
• Money as string or integer cents—never float:

  "price": "19.99"

  or

  "price_cents": 1999

• Avoid floats for anything requiring exactness—currency, coordinates with precision

Structure Best Practices

• Keep nesting shallow—3 levels max; flatten or split into related endpoints
• Consistent envelope for APIs:

  {"data": ..., "meta": ..., "errors": ...}

• Paginate large arrays—never return unbounded lists; include

  next

  /

  prev

  links or cursor

API Response Patterns

• Errors as structured objects:

  {"code": "INVALID_EMAIL", "message": "...", "field": "email"}

• Include request ID in responses for debugging:

  "request_id": "abc-123"

• Return created/updated resource in response—saves client a follow-up GET

Serialization

• toJSON()

  method silently overrides output—Date becomes string, custom classes may surprise
• Map, Set, BigInt don't serialize—need custom replacer function
• Circular references throw—detect cycles before stringify or use libraries like

  flatted

• Strip sensitive data before serializing—don't rely on client to ignore extra fields

Parsing Safety

• __proto__

  key can pollute prototypes—sanitize input or use

  Object.create(null)

• Parse in try/catch—malformed JSON from external sources is common
• Reviver function for type reconstruction: dates, BigInt, custom types

Unicode

• Emoji need surrogate pairs in escapes: 😀 =

  \uD83D\uDE00

  —single

  \u1F600

  invalid
• Control chars U+0000–U+001F must be escaped—pasted text may contain invisible ones
• BOM at file start breaks parsing—strip

  \uFEFF

  from file input