Comparing Configuration Files with JSON Diff

Configuration files are among the most frequently compared JSON documents. Whether you are comparing config.dev.json vs. config.prod.json, or reviewing a pull request that modifies application settings, JSON diff provides a clear view of what changed and what stayed the same.

Environment comparison example:

// config.dev.json
{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "app_dev",
    "ssl": false,
    "pool": { "min": 1, "max": 5 }
  },
  "logging": {
    "level": "debug",
    "prettyPrint": true
  },
  "cache": {
    "enabled": false
  }
}

// config.prod.json
{
  "database": {
    "host": "db.production.internal",
    "port": 5432,
    "name": "app_prod",
    "ssl": true,
    "pool": { "min": 10, "max": 100 }
  },
  "logging": {
    "level": "warn",
    "prettyPrint": false
  },
  "cache": {
    "enabled": true,
    "ttl": 3600
  }
}

The diff clearly shows:

• Database host, name, SSL, and pool sizes differ (expected between environments)
• Logging level and formatting differ (expected)
• Cache is enabled in production with an additional ttl field

What to look for in config diffs:

1. Secrets in plaintext: If API keys or passwords appear in the diff, they should be moved to environment variables or a secrets manager.
2. Unexpected similarities: If dev and prod configs share the same database host, something is likely misconfigured.
3. Missing fields: A field present in dev but absent in prod might cause the application to use a fallback or crash.
4. Type mismatches: A port number stored as a string in one environment and a number in another will cause issues in strictly typed applications.

Best practices:

• Maintain a base configuration with environment-specific overrides rather than maintaining completely separate files.
• Use JSON diff in your CI/CD pipeline to validate that configuration changes are intentional.
• Review config diffs during pull request reviews with the same rigor as code changes.
• Keep a diff history to track how configurations evolve over time.