prettyjson

JSON Best Practices and Tips

📅 December 19, 2024 ⏱️ 8 min read

Working with JSON effectively requires understanding not just the syntax, but also best practices that ensure maintainability, performance, and security. This guide covers essential tips and practices for working with JSON in production applications.

Structure and Organization

Use Consistent Naming Conventions

Choose a naming convention and stick to it throughout your application:

  • camelCase: Common in JavaScript (e.g., firstName)
  • snake_case: Common in Python and Ruby (e.g., first_name)
  • kebab-case: Less common but used in some APIs (e.g., first-name)

Best Practice: Use camelCase for JavaScript applications, snake_case for Python/Ruby APIs, and be consistent across your entire API.

Keep Structures Flat When Possible

While JSON supports nested structures, flatter structures are often easier to work with: 

// Prefer this
{
  "userId": 123,
  "userName": "john_doe",
  "userEmail": "john@example.com"
}

// Over deeply nested
{
  "user": {
    "profile": {
      "personal": {
        "name": "john_doe"
      }
    }
  }
}

Data Types and Values

Use Appropriate Data Types

  • Use numbers for numeric values, not strings
  • Use booleans (true/false) instead of strings ("true"/"false")
  • Use null for missing values, not empty strings or 0
  • Use arrays for lists, not comma-separated strings

Date and Time Handling

JSON doesn't have a native date type. Use ISO 8601 format: 

{
  "createdAt": "2024-12-19T10:30:00Z",
  "updatedAt": "2024-12-19T15:45:00Z"
}

Always use UTC (indicated by the 'Z' suffix) to avoid timezone issues.

Validation and Schema

Use JSON Schema

JSON Schema provides validation, documentation, and type safety: 

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    }
  },
  "required": ["name"]
}

Validate Early

  • Validate JSON at API boundaries
  • Use schema validation before processing
  • Provide clear error messages for invalid data

Performance Optimization

Minify for Production

Remove unnecessary whitespace in production to reduce payload size: 

// Development (readable)
{
  "name": "John",
  "age": 30
}

// Production (minified)
{"name":"John","age":30}

Stream Large Files

For large JSON files, use streaming parsers instead of loading everything into memory:

  • Use streaming JSON parsers for files > 10MB
  • Process data incrementally
  • Avoid loading entire documents when possible

Consider Compression

Enable gzip or brotli compression for JSON responses in APIs to reduce bandwidth usage.

Security Best Practices

Sanitize Input

  • Never trust JSON input from external sources
  • Validate and sanitize all data
  • Be aware of JSON injection attacks

Handle Parsing Errors Safely

try {
  const data = JSON.parse(jsonString);
} catch (error) {
  // Handle error appropriately
  // Log the error, return a safe default, etc.
  console.error('Invalid JSON:', error);
  throw new Error('Failed to parse JSON');
}

Be Careful with eval()

Never use eval() to parse JSON. Always use JSON.parse() which is safe and secure.

API Design

Consistent Response Structure

Use a consistent structure for API responses: 

// Success response
{
  "status": "success",
  "data": {
    "user": { ... }
  }
}

// Error response
{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input"
  }
}

Use HTTP Status Codes

Don't rely solely on JSON status fields. Use appropriate HTTP status codes (200, 400, 404, 500, etc.) in conjunction with JSON responses.

Version Your APIs

Include version information in your API responses or headers to support backward compatibility.

Error Handling

Provide Meaningful Error Messages

{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "The email address format is invalid",
    "field": "email",
    "value": "invalid-email"
  }
}

Include Error Context

Provide enough context for debugging without exposing sensitive information:

  • Error codes for programmatic handling
  • Human-readable messages
  • Field-level validation errors
  • Request IDs for tracking

Common Pitfalls to Avoid

Trailing Commas

JSON doesn't allow trailing commas. This is invalid: 

{
  "name": "John",
  "age": 30,  // ❌ Trailing comma - invalid JSON
}

Comments

JSON doesn't support comments. If you need comments, use JSON5 or JSONC, or document your JSON separately.

Undefined Values

JavaScript's undefined is not valid JSON. Use null instead: 

// ❌ Invalid
{"value": undefined}

// ✅ Valid
{"value": null}

Circular References

JSON cannot represent circular references. You'll need to break the cycle or use a custom serialization method.

Formatting and Readability

Use Proper Indentation

For configuration files and development, use consistent indentation (typically 2 or 4 spaces): 

{
  "name": "John",
  "address": {
    "street": "123 Main St",
    "city": "New York"
  }
}

Sort Keys Consistently

While JSON doesn't require sorted keys, sorting them alphabetically can make diffs easier to read in version control.

Testing and Debugging

Use JSON Validators

  • Validate JSON before committing
  • Use online validators during development
  • Integrate validation into your CI/CD pipeline

Pretty Print for Debugging

Use formatted JSON for logging and debugging to make it human-readable: 

console.log(JSON.stringify(data, null, 2));

Documentation

Document Your JSON Structures

  • Use JSON Schema for formal documentation
  • Include examples in API documentation
  • Document field meanings and constraints
  • Provide sample requests and responses

Tools and Resources

Essential Tools

  • JSON Formatters: Format and validate JSON
  • JSON Schema Validators: Validate against schemas
  • JSON Path: Query and extract data from JSON
  • JSON Diff Tools: Compare JSON structures

Conclusion

Following these best practices will help you write better JSON, build more robust APIs, and avoid common pitfalls. Remember:

  • Be consistent in your naming and structure
  • Validate and sanitize all JSON data
  • Use appropriate data types
  • Optimize for performance when needed
  • Document your JSON structures
  • Handle errors gracefully

JSON's simplicity is its strength, but using it effectively requires understanding these best practices. By following these guidelines, you'll create more maintainable, secure, and performant applications.

← Back to Blogs