Using JSON for Configuration Files: Best Practices and Examples

JSON is one of the most popular formats for application configuration files. Its universal parser support, simple syntax, and easy readability make it ideal for settings, feature flags, environment configs, and tooling. This guide explores JSON configuration file best practices, schema validation, secrets management, environment-specific overrides, and how to avoid common pitfalls. Use our JSON Validator to check config files and JSON Formatter to keep them readable.

Why JSON for Configuration?

Aspect	JSON Advantage	Alternative
Parser availability	Every language has a built-in JSON parser	YAML requires third-party libraries in many languages
Error messages	JSON parsers give specific line/column errors	YAML error messages can be cryptic with indentation issues
Schema validation	JSON Schema is mature and widely supported	TOML and .env files lack formal schema
Comments	Not supported natively (use // workaround with strip)	YAML supports # comments natively
Tooling ecoystem	Vast: formatters, validators, minifiers, diff tools	YAML has good tooling but less variety

JSON Configuration File Best Practices

{
  // Use .jsonc or strip comments before parsing
  "app": {
    "port": 3000,
    "host": "0.0.0.0"
  },
  "database": {
    "url": "postgres://localhost:5432/myapp",
    "pool": {
      "min": 2,
      "max": 10
    }
  },
  "features": {
    "darkMode": true,
    "beta": false,
    "experimentalApi": false
  },
  "logging": {
    "level": "info",
    "format": "json"
  }
}

Environment-Specific Overrides

Pattern for managing development, staging, and production configs:

// config/default.json (base config)
{
  "app": { "port": 3000 },
  "logging": { "level": "info" }
}

// config/production.json (overrides)
{
  "app": { "port": 8080 },
  "logging": { "level": "warn" }
}

// config/development.json (overrides)
{
  "logging": { "level": "debug" }
}

// Merge logic
const defaultConfig = require('./config/default.json');
const envConfig = require('./config/' + process.env.NODE_ENV + '.json');
const config = deepMerge(defaultConfig, envConfig);

Secrets Management

Never store secrets in configuration files committed to version control:

// BAD: secrets in config file
{
  "database": {
    "password": "super-secret-123"  // Committed to git!
  }
}

// GOOD: use environment variables
{
  "database": {
    "host": "localhost",
    "port": 5432,
    "password": "{{DB_PASSWORD}}"  // Resolved at runtime
  }
}

// Resolution in code
function resolveConfig(config) {
  const json = JSON.stringify(config);
  const resolved = json.replace(/{{(w+)}}/g, (_, key) => {
    return process.env[key] || '';
  });
  return JSON.parse(resolved);
}

Validating Configuration with JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "app": {
      "type": "object",
      "properties": {
        "port": { "type": "integer", "minimum": 1024, "maximum": 65535 },
        "host": { "type": "string", "format": "ipv4" }
      },
      "required": ["port", "host"]
    },
    "database": {
      "type": "object",
      "properties": {
        "url": { "type": "string", "format": "uri" }
      },
      "required": ["url"]
    }
  },
  "required": ["app", "database"]
}

Use our JSON Schema Validator to validate config files against schemas. Generate schemas from existing configs with JSON to Schema.

Tool-Specific Config Files

Tool	File	Purpose
npm	package.json	Project metadata, scripts, dependencies
VS Code	settings.json	Editor configuration, extensions
TypeScript	tsconfig.json	Compiler options, include/exclude paths
ESLint	.eslintrc.json	Linting rules and environments
Prettier	.prettierrc	Code formatting configuration
Docker	docker-compose.json	Service definitions and volumes
Kubernetes	*.json	Pod, service, and deployment manifests

JSON with Comments (.jsonc)

While JSON does not officially support comments, VS Code popularized .jsonc (JSON with Comments) which allows // and /* */ comments. Use our JSONC to JSON Converter to strip comments before parsing with standard JSON parsers.

Next Steps

Validate your configuration files with JSON Validator. Format config files with JSON Formatter. Generate JSON Schema for your configs with JSON to Schema.