JSON Practices Guide for Professional Development
Master JSON development with industry-standard naming conventions, structure design patterns, performance optimization techniques, and security practices used by top US tech companies.
1. Naming Conventions
camelCase for Keys
{ "firstName": "John", "lastName": "Doe", "dateOfBirth": "1990-01-15", "isActive": true } Recommended for JavaScript/TypeScript APIs. Most modern frameworks (React, Node.js, Angular) expect camelCase by default.
snake_case for APIs
{ "first_name": "John", "last_name": "Doe", "date_of_birth": "1990-01-15", "is_active": true } Preferred by Python/Django and many Ruby on Rails APIs. More readable in some contexts.
Consistency Rules
- Choose one convention and stick with it across your entire API
- Never mix camelCase and snake_case in the same response
- Boolean prefixes: Use "is", "has", "can" (e.g.,
isActive,hasPermission) - Date fields: Use ISO 8601 format (
2026-04-15or2026-04-15T10:30:00Z) - IDs: Use
idfor primary keys,userIdfor foreign keys
2. Structure Design Patterns
Nested vs Flat Structures
Use nested when data belongs together logically:
{ "user": { "id": 123, "name": "John", "address": { "city": "San Francisco", "zip": "94102" } } } Flat for Multiple Items
Use flat when referencing same entity multiple times:
{ "orders": [ {"id": 1, "userId": 123}, {"id": 2, "userId": 456} ], "users": { "123": {"name": "John"}, "456": {"name": "Jane"} } } Array Practices
Always Use Arrays for Lists
✓ ["item1", "item2"]
Paginate Large Arrays
3. Performance Optimization
Field Selection
Use sparse fieldsets to reduce payload size:
GET /api/users?fields=id,name,email
This pattern is used by Stripe, Shopify, and GitHub API.
Compression
Compress JSON for large responses using gzip/brotli:
Accept-Encoding: gzip Content-Type: application/json
Can reduce payload by 70-90% for repetitive data.
Benchmark: Parse Speed (2026)
| Library | Speed (GB/s) | For |
|---|---|---|
| simdjson | 3.0+ | High-throughput APIs |
| JSON for Modern C++ | 1.5 | Ease of use |
| Native JSON.parse | 0.5-1.0 | Browser/Node.js |
4. Security Practices
Never Do These
Always use JSON.parse() to prevent code injection attacks.
Always validate and sanitize JSON input before processing.
Filter out passwords, tokens, and PII from responses.
Schema Validation
Always validate incoming JSON against a schema:
// Use AJV, Joi, or Zod const schema = { type: "object", required: ["id", "email"], properties: { id: { type: "integer" }, email: { type: "string", format: "email" } } }; Rate Limiting
Protect against DoS via large payloads:
// Set max payload size MAX_JSON_SIZE: 1MB MAX_DEPTH: 64 levels MAX_KEYS: 10000
5. RESTful API Design Patterns
Standard Response Envelope
{ "success": true, "data": { ... }, "meta": { "page": 1, "perPage": 20, "total": 150 }, "timestamp": "2026-04-15T10:30:00Z" } Used by Stripe, Twilio, and most modern REST APIs.
Include Related Data
Use include parameter for related resources:
GET /api/orders?include=customer,items
Pattern from JSON:API specification.
Sparse Fieldsets
Request only needed fields:
GET /api/users?fields[id,name,email]
Reduces bandwidth significantly.
6. Error Handling (RFC 9457)
Problem Details Standard
HTTP/1.1 400 Bad Request Content-Type: application/problem+json { "type": "https://api.example.com/errors/validation", "title": "Validation Error", "status": 400, "detail": "Request body contains invalid JSON", "instance": "/api/users", "errors": [ {"field": "email", "message": "Invalid format"}, {"field": "age", "message": "Must be positive"} ] } HTTP Status Codes
200- Success201- Created400- Bad Request401- Unauthorized403- Forbidden404- Not Found
Error Code Patterns
- VALIDATION_ERROR - Invalid input
- RESOURCE_NOT_FOUND - Missing entity
- RATE_LIMITED - Too many requests
- INTERNAL_ERROR - Server fault