Data Formats
API Development
Best Practices
JSON Best Practices: Formatting, Validation & Performance
Published: May 29, 2026
•
10 min read
•
Intermediate Level
JSON (JavaScript Object Notation) has become the universal language for data exchange in web applications. Following best practices ensures your JSON is readable, maintainable, and performant across all stages of development.
1. Consistent Formatting Standards
Indentation and Spacing
Consistent indentation improves readability. Most teams use 2 or 4 spaces (never tabs).
✅ Recommended (2 spaces)
{
"user": {
"id": 123,
"name": "John Doe",
"email": "[email protected]"
}
}
✅ Alternative (4 spaces)
{
"user": {
"id": 123,
"name": "John Doe",
"email": "[email protected]"
}
}
Key Naming Conventions
- camelCase: Most common in JavaScript ecosystems
- snake_case: Common in Python and Ruby ecosystems
- kebab-case: Less common, but used in some APIs
Important: Choose one convention and stick to it throughout your application.
2. Validation and Error Handling
JSON Schema Validation
JSON Schema provides a powerful way to validate JSON structure and data types.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email",
"pattern": "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$"
},
"status": {
"type": "string",
"enum": ["active", "inactive", "pending"]
}
},
"required": ["id", "email"],
"additionalProperties": false
}
Common Validation Libraries
- JavaScript: ajv, joi, yup
- Python: jsonschema, pydantic
- Java: Jackson, Gson with validation
- Go: go-playground/validator
3. Performance Optimization
Minification for Production
Always minify JSON in production to reduce payload size and improve load times.
Before vs After Minification
Formatted (156 bytes)
{
"users": [
{
"id": 1,
"name": "Alice"
},
{
"id": 2,
"name": "Bob"
}
]
}
Minified (52 bytes)
{"users":[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]}
66% size reduction! Use our JSON Formatter to minify your JSON.
Compression Techniques
- Gzip/Brotli: Enable compression on your web server
- Selective Fields: Only include necessary data
- Pagination: Split large datasets into pages
- Field Selection: Allow clients to request specific fields
4. API Design Patterns
RESTful JSON API Structure
Follow consistent patterns for API responses:
// Successful response
{
"status": "success",
"data": {
"user": {
"id": 123,
"name": "John Doe",
"email": "[email protected]"
}
},
"meta": {
"timestamp": "2026-05-29T10:30:00Z",
"version": "1.0"
}
}
// Error response
{
"status": "error",
"error": {
"code": "VALIDATION_ERROR",
"message": "Email format is invalid",
"details": {
"field": "email",
"rule": "format"
}
},
"meta": {
"timestamp": "2026-05-29T10:30:00Z"
}
}
Pagination Pattern
{
"status": "success",
"data": {
"items": [
{ "id": 1, "name": "Item 1" },
{ "id": 2, "name": "Item 2" }
]
},
"pagination": {
"total": 100,
"count": 2,
"per_page": 2,
"current_page": 1,
"total_pages": 50,
"links": {
"next": "/api/items?page=2",
"prev": null
}
}
}
5. Security Considerations
Input Validation
Always validate and sanitize JSON inputs to prevent security vulnerabilities:
- JSON Injection: Validate against JSON Schema
- Size Limits: Implement maximum payload size
- Content-Type: Require proper Content-Type headers
- Rate Limiting: Prevent abuse with request limits
Common Security Pitfalls
⚠️ Security Warnings
- ✗ eval() with JSON: Never use eval() to parse JSON - use JSON.parse() instead
- ✗ Circular References: Avoid circular references that can cause infinite loops
- ✗ Large Nested Objects: Deep nesting can cause stack overflow errors
- ✗ Prototype Pollution: Be cautious with merging untrusted JSON objects
6. Tooling and Automation
Development Tools
- Our JSON Formatter: Online JSON tool for formatting and validation
- IDE Extensions: Prettier, ESLint for JSON
- CLI Tools: jq for command-line JSON processing
- Browser Extensions: JSON Formatter, JSON Viewer
Automated Testing
Include JSON validation in your CI/CD pipeline:
# Example: Node.js test with JSON Schema
const Ajv = require('ajv');
const userSchema = require('./schemas/user.json');
const ajv = new Ajv();
const validate = ajv.compile(userSchema);
test('user JSON matches schema', () => {
const userData = {
id: 123,
name: "John Doe",
email: "[email protected]"
};
const valid = validate(userData);
expect(valid).toBe(true);
});
7. Real-World Examples
Configuration Files
// package.json example
{
"name": "my-project",
"version": "1.0.0",
"description": "A sample project",
"main": "index.js",
"scripts": {
"start": "node index.js",
"test": "jest",
"build": "webpack"
},
"dependencies": {
"express": "^4.18.0",
"mongoose": "^7.0.0"
},
"devDependencies": {
"jest": "^29.0.0",
"webpack": "^5.0.0"
}
}
API Response Example
// GitHub API response example
{
"login": "octocat",
"id": 1,
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/followers",
"following_url": "https://api.github.com/users/octocat/following{/other_user}",
"type": "User",
"site_admin": false,
"name": "monalisa octocat",
"company": "GitHub",
"blog": "https://github.com/blog",
"location": "San Francisco",
"email": "[email protected]",
"hireable": false,
"bio": "There once was...",
"public_repos": 2,
"public_gists": 1,
"followers": 20,
"following": 0,
"created_at": "2008-01-14T04:33:35Z",
"updated_at": "2008-01-14T04:33:35Z"
}
Conclusion
Following JSON best practices leads to more maintainable, performant, and secure applications. Remember to:
- ✓ Maintain consistent formatting and naming conventions
- ✓ Implement robust validation with JSON Schema
- ✓ Optimize performance through minification and compression
- ✓ Follow security best practices to prevent vulnerabilities
- ✓ Use appropriate tooling for development and testing
For hands-on practice with JSON formatting and validation, try our JSON Formatter Tool.