Schema as Glue — JSON Schema Across Formats

One schema, three formats

YAML, TOML, and JSON all parse into the same data model. So JSON Schema validates all three with no changes. You write the schema once; you point validators at any of the three formats; the rules apply uniformly.

Validators that work across formats

check-jsonschema — Python tool, pip install check-jsonschema, validates JSON, YAML, TOML against a JSON Schema.
ajv-cli with YAML loader — fastest validator for JSON; YAML support via --data-stream + js-yaml.
spectral — for OpenAPI specifically; runs JSON Schema rules on YAML or JSON specs.
Editor schema integration — VS Code's YAML / JSON / TOML extensions all read schemas from Schema Store and provide autocomplete + inline validation, regardless of format.

Schema-first as a discipline

Pick the format your team prefers, but write the schema in JSON Schema. The schema becomes the single source of truth. Convert as needed. Your schema is also documentation, autocomplete, type generator, mock data generator — depending on how far you want to go.

Principle: validate at boundaries, trust internally. The boundary is where untyped data enters your system — config load, API request, file upload. Validate there with JSON Schema; downstream code can assume the shape is correct.

Code

One schema, validates all four·bash

# Install
pip install check-jsonschema

# Validate JSON
check-jsonschema --schemafile config.schema.json config.json

# Same schema, validate YAML
check-jsonschema --schemafile config.schema.json config.yaml

# Same schema, validate TOML
check-jsonschema --schemafile config.schema.json config.toml

# Validate against a schema by URL (Schema Store)
check-jsonschema --schemafile https://json.schemastore.org/github-action.json action.yaml

Schema example — same rules apply to all·json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "port":     { "type": "integer", "minimum": 1024, "maximum": 65535 },
    "host":     { "type": "string" },
    "log_level": { "enum": ["debug", "info", "warn", "error"] },
    "database": {
      "type": "object",
      "properties": {
        "url":       { "type": "string", "format": "uri" },
        "pool_size": { "type": "integer", "minimum": 1, "maximum": 100 }
      },
      "required": ["url"]
    }
  },
  "required": ["host", "port", "database"]
}

VS Code — schemas auto-applied by filename·json

// .vscode/settings.json
{
  "json.schemas": [
    { "fileMatch": ["my-config.json"], "url": "./config.schema.json" }
  ],
  "yaml.schemas": {
    "./config.schema.json": ["my-config.yaml", "my-config.yml"]
  }
  // TOML uses Even Better TOML extension; configure via its own settings.
}

Exercise

Write a JSON Schema that describes a config you maintain. Validate the same schema against your YAML version, your TOML version (if you have one), and a deliberately broken JSON version. Add the validation step to your CI. The schema becomes a contract everyone — humans, formats, validators — agrees on.

Schema as Glue — JSON Schema Across Formats

One schema, three formats

Validators that work across formats

Schema-first as a discipline

Code

External links

Exercise

Progress

Comments 0