Generate YAML Schema for Docker Compose Files

Docker Compose Configuration to YAML Schema

Docker Compose files define multi-container applications. Converting a sample compose configuration to YAML Schema enables validation that catches errors before docker compose up.

Example Docker Compose JSON

{
  "version": "3.8",
  "services": {
    "web": {
      "image": "nginx:alpine",
      "ports": ["80:80", "443:443"],
      "volumes": ["./nginx.conf:/etc/nginx/nginx.conf:ro"],
      "dependsOn": ["api"],
      "restart": "unless-stopped",
      "healthcheck": {
        "test": ["CMD", "curl", "-f", "http://localhost"],
        "interval": "30s",
        "timeout": "10s",
        "retries": 3
      }
    },
    "api": {
      "build": {
        "context": ".",
        "dockerfile": "Dockerfile"
      },
      "environment": {
        "NODE_ENV": "production",
        "DATABASE_URL": "postgres://db:5432/app"
      },
      "dependsOn": ["db"]
    },
    "db": {
      "image": "postgres:16",
      "volumes": ["pgdata:/var/lib/postgresql/data"],
      "environment": {
        "POSTGRES_DB": "app",
        "POSTGRES_USER": "admin"
      }
    }
  },
  "volumes": {
    "pgdata": {}
  }
}

Generated YAML Schema

type: object
properties:
  version:
    type: string
    pattern: "^\\d+\\.\\d+$"
  services:
    type: object
    patternProperties:
      "^[a-z][a-z0-9_-]*$":
        type: object
        properties:
          image:
            type: string
          build:
            oneOf:
              - type: string
              - type: object
                properties:
                  context:
                    type: string
                  dockerfile:
                    type: string
                required:
                  - context
          ports:
            type: array
            items:
              type: string
              pattern: "^\\d+:\\d+(/tcp|/udp)?$"
          volumes:
            type: array
            items:
              type: string
          environment:
            oneOf:
              - type: object
                patternProperties:
                  "^[A-Z][A-Z0-9_]*$":
                    type: string
              - type: array
                items:
                  type: string
                  pattern: "^[A-Z][A-Z0-9_]*=.*$"
          dependsOn:
            type: array
            items:
              type: string
          restart:
            type: string
            enum:
              - "no"
              - always
              - on-failure
              - unless-stopped
          healthcheck:
            type: object
            properties:
              test:
                oneOf:
                  - type: string
                  - type: array
                    items:
                      type: string
              interval:
                type: string
                pattern: "^\\d+[smh]$"
              timeout:
                type: string
                pattern: "^\\d+[smh]$"
              retries:
                type: integer
                minimum: 0
        oneOf:
          - required: [image]
          - required: [build]
  volumes:
    type: object
    patternProperties:
      "^[a-z][a-z0-9_-]*$":
        type: [object, "null"]
  networks:
    type: object
    patternProperties:
      "^[a-z][a-z0-9_-]*$":
        type: [object, "null"]
required:
  - services

Key Validation Patterns

Service must have image or build:

oneOf:
  - required: [image]
  - required: [build]

Port mapping format:

pattern: "^\\d+:\\d+(/tcp|/udp)?$"

Environment variable naming:

patternProperties:
  "^[A-Z][A-Z0-9_]*$":
    type: string

Extending for Custom Conventions

Teams can add organization-specific rules:

# Require health checks for all production services
healthcheck:
  type: object
  required:
    - test
    - interval

IDE Integration

With a YAML schema, VS Code's YAML extension provides autocompletion, inline validation, and hover documentation for your compose files. Add the schema reference at the top of your compose file or configure it in .vscode/settings.json.