JSON Best Practices

Writing good JSON is more than just valid syntax. Well-designed JSON is consistent, readable, efficient, and secure. This guide covers the most important best practices for writing, designing, and working with JSON in real-world applications.

1. Naming Conventions

Choose one naming convention and stick to it throughout your entire API or application. Mixing conventions creates confusion and bugs.

{"firstName": "Alice", "lastName": "Smith", "isActive": true}

{"first_name": "Alice", "last_name": "Smith", "is_active": true}

• Never mix camelCase and snake_case in the same API
• Use descriptive, meaningful key names — avoid abbreviations like usr or fn
• Use plural names for arrays: "users" not "user"
• Use boolean prefixes: isActive, hasPermission, canEdit

2. Use the Right Data Types

• Use numbers for numeric values — don't store "age": "28" as a string
• Use booleans for true/false — not "active": "yes" or "active": 1
• Use null for absent values — not empty strings "" or 0
• Use arrays for ordered lists — not numbered keys like "item1", "item2"
• Use ISO 8601 strings for dates: "2025-01-01T00:00:00Z"

3. Structure Design

• Keep nesting shallow — deeply nested JSON is hard to read and query. Aim for 3 levels maximum.
• Be consistent — if a field is sometimes an array and sometimes a single value, always use an array
• Don't use arrays as objects — if items have meaningful keys, use an object, not an array of key-value pairs
• Include metadata — for API responses, include pagination, timestamps, and request IDs

4. Performance Tips

• Minify for production — remove whitespace before sending JSON over the network
• Omit null fields — don't include keys with null values unless the consumer needs to know they're absent
• Paginate large arrays — never return thousands of items in a single response
• Use compression — enable gzip/brotli compression on your server for JSON responses
• Cache responses — use HTTP caching headers for JSON that doesn't change frequently

5. Security Considerations

• Never include sensitive data — don't put passwords, secrets, or PII in JSON responses unless absolutely necessary
• Validate all input — always validate and sanitize JSON received from clients before processing
• Limit response size — set maximum payload sizes to prevent denial-of-service attacks
• Use HTTPS — always transmit JSON over encrypted connections
• Avoid JSON injection — sanitize user input before embedding it in JSON strings

6. Common Mistakes to Avoid

• Using trailing commas (valid in JavaScript but not in JSON)
• Using single quotes instead of double quotes
• Storing numbers as strings: "count": "42"
• Using inconsistent key names across similar objects
• Returning different structures for success and error responses
• Not validating JSON before sending it to an API