Generate JSON Schema for Configuration Files

Generating Schemas for Config Files

Configuration files are one of the best use cases for JSON Schema because the schema can power IDE autocompletion, validation, and documentation all at once.

Why Config Files Need Schemas

• Autocompletion: VS Code, JetBrains IDEs, and other editors use JSON Schema to suggest valid keys and values as you type.
• Validation: Catch typos and invalid values before the application starts.
• Documentation: The schema itself serves as a machine-readable specification of all configuration options.

Example: Custom App Config

Given a sample config:

{
  "port": 3000,
  "host": "localhost",
  "database": {
    "url": "postgres://localhost:5432/mydb",
    "pool": { "min": 2, "max": 10 }
  },
  "features": {
    "darkMode": true,
    "betaAccess": false
  },
  "allowedOrigins": ["https://example.com"]
}

Refined Schema

After generation and refinement:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "App Configuration",
  "description": "Configuration schema for MyApp",
  "type": "object",
  "properties": {
    "port": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535,
      "default": 3000
    },
    "host": { "type": "string", "default": "localhost" },
    "database": {
      "type": "object",
      "properties": {
        "url": { "type": "string", "format": "uri" },
        "pool": {
          "type": "object",
          "properties": {
            "min": { "type": "integer", "minimum": 0 },
            "max": { "type": "integer", "minimum": 1 }
          }
        }
      },
      "required": ["url"]
    },
    "features": {
      "type": "object",
      "additionalProperties": { "type": "boolean" }
    },
    "allowedOrigins": {
      "type": "array",
      "items": { "type": "string", "format": "uri" }
    }
  },
  "required": ["port", "database"]
}

Key Refinements

• default values tell consumers what the application uses when a field is omitted.
• features uses additionalProperties: { "type": "boolean" } because feature flags are a dynamic key-value map — you do not want to enumerate every flag in the schema.
• port has min/max constraints matching the valid TCP port range.
• title and description at the root make the schema self-documenting.

Linking to IDEs

Add a $schema property to your config file to activate IDE support:

{
  "$schema": "./config.schema.json",
  "port": 8080
}

VS Code and other editors will automatically load the referenced schema and provide completions and validation.