Configuration-as-Code with JSON: Best Practices

In modern software development, managing application and infrastructure settings can quickly become complex. Hardcoding values within your application logic or relying on manual configurations is fragile, error-prone, and difficult to scale. This is where Configuration-as-Code (CaC) comes in.

CaC is the practice of managing system configurations (like server settings, database connections, feature flags, application parameters) in structured, machine-readable files. These files are treated just like application code – they are versioned, reviewed, and deployed through automated pipelines.

Among the various formats available for CaC (YAML, HCL, XML, etc.), JSON (JavaScript Object Notation) is a popular and widely supported choice. Its simplicity, ubiquitous parsing libraries across languages, and native compatibility with JavaScript environments make it a strong contender.

Why JSON for Configuration-as-Code?

JSON offers several advantages that make it suitable for CaC:

• Simplicity: JSON's data structures (objects, arrays, primitives) are easy to understand.
• Ubiquitous Support: Parsers are available in virtually every programming language and environment.
• Readability: For simple configurations, JSON is quite human-readable.
• Interoperability: It's a standard data interchange format, making it easy to share configurations between different systems or services.
• Schema Definition: JSON Schema provides a powerful way to define the structure and types of your configuration, enabling validation.

Key Benefits of CaC with JSON

• Consistency & Repeatability: Ensures configurations are the same across different environments (development, staging, production).
• Versioning & Audit Trails: Storing configuration in version control (like Git) provides a history of changes, who made them, and when.
• Collaboration: Allows multiple team members to work on configurations simultaneously using standard code development workflows.
• Automation: Configurations can be automatically applied as part of CI/CD pipelines.
• Reduced Errors: Machine-readable formats and validation reduce the likelihood of manual typos and misconfigurations.

Common Use Cases

JSON-based CaC is used in many scenarios:

• Application Settings: Database credentials (or references), API keys (or references), feature flags, logging levels, external service endpoints.
• Build & Deployment Configurations: Defining build steps, deployment targets, environment variables for pipelines.
• Infrastructure Definitions: While YAML is more common, some tools like CloudFormation or Terraform use JSON for defining cloud infrastructure.
• API Definitions: OpenAPI/Swagger specifications are often written in JSON (or YAML).

Best Practices for JSON CaC

1. Structure and Organization

How you structure your JSON files is crucial for maintainability. Avoid massive, monolithic files.

• Logical Grouping: Group related settings together in nested objects.
• Modularity: Consider splitting configurations into multiple files based on domain (e.g., `database.json`, `api.json`, `featureFlags.json`).
• Consistency: Maintain a consistent nesting depth and structure across your project.

{
  "app": {
    "name": "MyAwesomeApp",
    "version": "1.0.0",
    "logLevel": "info"
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "dbName": "app_db"
    // IMPORTANT: No credentials here!
  },
  "api": {
    "baseUrl": "https://api.example.com/v1",
    "timeoutMs": 5000
  }
}

2. Naming Conventions

Use clear and consistent naming for your keys.

• Camel Case or Snake Case: Choose one style (e.g., "logLevel" or "log_level") and stick to it project-wide. Camel case is common for JSON due to its JavaScript origins.
• Descriptive Names: Key names should clearly indicate the purpose of the value.

3. Schema Validation

Ensure your configuration files adhere to a predefined structure and data types using JSON Schema.

• Define Schemas: Create .json or .jsonld files defining the expected structure, required fields, data types, and constraints for your configuration.
• Automate Validation: Integrate schema validation into your CI/CD pipeline or a pre-commit hook. Tools are available in most languages (e.g., ajv in Node.js).
• Benefits: Prevents deployment errors caused by malformed or incomplete configurations early in the process.

4. Versioning and Source Control

Treat your JSON configuration files like source code.

• Use Git (or similar): Store your configuration files in a version control system.
• Commit Changes: Every change to the configuration should be a commit with a meaningful message.
• Pull Requests/Code Reviews: Review configuration changes just like you review code changes.
• Tag Releases: Tag specific versions of your configuration that correspond to software releases.

5. Environment-Specific Configurations

Applications often require different settings for development, staging, production, etc. Avoid duplicating entire files.

• Layered Configuration: Use a system that loads a base configuration and then overlays environment-specific values from separate files or sources. Common approaches include:
  • Separate files per environment (e.g., config.json, config.development.json, config.production.json).
  • Using environment variables to override JSON values.
  • Configuration management tools that handle environment-specific values.
• Minimize Differences: Only include values that *must* differ between environments in environment-specific files.

{
  "api": {
    "baseUrl": "https://dev-api.example.com/v1"
  },
  "logLevel": "debug"
}

{
  "api": {
    "baseUrl": "https://api.example.com/v1" // Override
  },
  "logLevel": "info" // Override
}

6. Handling Sensitive Data (Secrets)

Never store secrets (passwords, API keys, encryption keys) directly in your JSON configuration files, especially if they are in source control!

• Externalize Secrets: Use secure methods like:
  • Environment Variables (common for cloud deployments and CI/CD).
  • Secret Management Systems (e.g., HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, Kubernetes Secrets).
  • Config files encrypted at rest and decrypted at runtime in a secure environment.
• Your JSON config should reference where to find the secret (e.g., { database: { username: "DB_USER", passwordRef: "ENV:DB_PASSWORD" } }) rather than containing the secret value itself.

7. Comments (or Lack Thereof)

A significant limitation of standard JSON is the lack of support for comments. This can make configurations less self-documenting.

• Workarounds:
  • Use JSON5 or HJSON (non-standard, require specific parsers).
  • Maintain separate documentation (e.g., README files).
  • Use conventions where keys explain themselves or add `_comment` keys (ugly and not standard).
  • Prefer YAML if comments are essential and JSON's strictness isn't a hard requirement.

8. Balance Simplicity and Repetition (DRY)

JSON doesn't have features like anchors or includes found in YAML. While repeating small values is often acceptable for clarity, significant repetition might indicate a need for:

• Refactoring the configuration structure.
• Using a templating engine or configuration management tool that processes JSON.
• Considering a different configuration format if the complexity warrants it.

Considerations and Potential Downsides

• Lack of Comments: As mentioned, this is a major drawback for documentation within the file itself.
• Verbosity for Complex Structures: Can become quite nested and lengthy compared to formats like YAML, especially with deeply nested arrays and objects.
• No Anchors/Includes: No native way to reference or reuse values within the same file, leading to repetition.
• Strict Syntax: While good for parsing, a single misplaced comma or brace can break the entire file.

Conclusion

Using JSON for Configuration-as-Code is a robust approach that leverages JSON's wide support and simplicity. By following best practices around structuring, validation, versioning, and secure handling of sensitive data, you can build a reliable and maintainable configuration system for your applications and infrastructure. While it has limitations like the lack of comments, its advantages often make it an excellent default choice, especially within JavaScript-heavy ecosystems or when strict data interchange standards are required.