Naming Conventions
Choose one convention and stick with it:
// Good: camelCase (JavaScript convention, most common)
{
"firstName": "Alice",
"lastName": "Smith",
"createdAt": "2026-07-22T10:00:00Z"
}
// Good: snake_case (Python convention, also common)
{
"first_name": "Alice",
"last_name": "Smith",
"created_at": "2026-07-22T10:00:00Z"
}
// Bad: Avoid mixing conventions
{
"firstName": "Alice",
"last_name": "Smith", // Inconsistent!
"createdAt": "2026-07-22T10:00:00Z"
}Recommendation: Use camelCase for JavaScript/TypeScript APIs, snake_case for Python/Ruby APIs. Document your choice.
Data Type Best Practices
Numbers
// Good: Use numbers for numeric values
{ "price": 19.99, "quantity": 42 }
// Bad: Don't use strings for numbers
{ "price": "19.99", "quantity": "42" }
// Good: Use strings for large integers (precision)
{ "id": "9007199254740993" }
// Good: Use null for missing numbers
{ "discount": null }Dates and Times
// Good: ISO 8601 format (recommended)
{ "createdAt": "2026-07-22T10:30:00Z" }
{ "date": "2026-07-22" }
{ "time": "10:30:00" }
// Bad: Avoid ambiguous formats
{ "date": "07/22/2026" } // MM/DD/YYYY or DD/MM/YYYY?
{ "timestamp": 1690000000 } // Unix timestamp - less readableBooleans
// Good: Use actual booleans
{ "isActive": true, "isDeleted": false }
// Bad: Don't use strings or numbers
{ "isActive": "true" }
{ "isActive": 1 }Null vs Missing
// Good: Use null for "explicitly empty"
{ "middleName": null }
// Good: Omit field for "not applicable" or "default"
{ "firstName": "Alice", "lastName": "Smith" }
// middleName omitted - not applicable
// Bad: Don't use empty strings for missing values
{ "middleName": "" } // Is this intentionally empty or missing?Security Best Practices
Never Trust User Input
// Bad: Dangerous - direct parsing
const data = JSON.parse(userInput);
// Good: Validate schema first
const Ajv = require('ajv');
const ajv = new Ajv();
const validate = ajv.compile(schema);
let data;
try {
data = JSON.parse(userInput);
} catch (e) {
throw new Error('Invalid JSON input');
}
if (!validate(data)) {
throw new Error('Invalid data');
}Prevent Prototype Pollution
// Bad: Vulnerable
const data = JSON.parse(userInput);
// If userInput contains {"__proto__": {"admin": true}}
// Good: Safe parsing with recursive sanitization
function safeParse(json) {
const data = JSON.parse(json, (key, value) => {
if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
return undefined;
}
return value;
});
return data;
}Size Limits
const MAX_JSON_SIZE = 1024 * 1024; // 1MB
function safeParseWithLimit(json) {
if (json.length > MAX_JSON_SIZE) {
throw new Error('JSON too large');
}
return JSON.parse(json);
}Performance Tips
Minimize Payload Size
// Bad: Verbose
{
"userIdentifier": "12345",
"userFullName": "Alice Smith",
"userEmailAddress": "alice@example.com"
}
// Good: Concise (with documentation)
{
"id": "12345",
"name": "Alice Smith",
"email": "alice@example.com"
}Use Pagination for Large Collections
// Good: Paginated response
{
"data": [...],
"pagination": {
"page": 1,
"perPage": 20,
"total": 150,
"totalPages": 8
}
}Compress Large Payloads
// Browsers automatically handle Accept-Encoding headers.
// Server-side compression is what matters:
// Express: app.use(compression())
// Nginx: gzip on;Common Pitfalls
Trailing Commas
// Bad: Invalid JSON
{ "name": "Alice", "age": 30, }
// Good: Valid JSON
{ "name": "Alice", "age": 30 }Comments
// Bad: Invalid JSON (use JSONC or JSON5 for comments)
{
// This is a comment
"name": "Alice"
}Single Quotes
// Bad: Invalid JSON
{ 'name': 'Alice' }
// Good: Valid JSON
{ "name": "Alice" }Key Quoting
// Bad: Invalid JSON
{ name: "Alice" }
// Good: Valid JSON
{ "name": "Alice" }API Design Patterns
Consistent Envelope
// Good: Success response
{
"success": true,
"data": { ... },
"meta": { "requestId": "abc123" }
}
// Good: Error response
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input",
"details": [...]
}
}Sparse Fieldsets
// Request: GET /users/123?fields=name,email
{
"id": "123",
"name": "Alice",
"email": "alice@example.com"
}Filtering and Sorting
// Request: GET /users?filter[role]=admin&sort=-createdAt
{
"data": [...],
"filters": { "role": "admin" },
"sort": { "field": "createdAt", "order": "desc" }
}Related Resources
- Python JSON Guide — Python-specific serialization patterns
- JavaScript JSON Guide — JSON.stringify and JSON.parse deep dive
- JSON Schema Validation — Validate your JSON structures
- JSON Security — Protect against common vulnerabilities
- JSON Schema Validator — Test your schemas online