JSON

--- name: JSON description: Work with JSON data structures, APIs, and serialization effectively. metadata: {"clawdbot":{"emoji":"📦","os":["linux","darwin","win32"]}} ---

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