Check a YAML config against a schema

Your team keeps a JSON Schema for its service configs, and the configs themselves are YAML, because people write them by hand and YAML is kinder to hands. The schema is the contract; the question before a deploy is whether today’s edit still honours it. A schema validates JSON, so the check has two steps: read the YAML the way a program will read it, then hold that reading to the schema. The first step matters more than it looks, because YAML’s reading is sometimes not what its writer meant.

1 · Read the YAML as JSON

Convert shows exactly what a YAML parser makes of the file, as JSON you can then check. Paste the config as it is in the repository.

name: checkout
replicas: 2
port: 8080
tls: no
regions:
  - eu-west-1
healthcheck:
  path: /healthz
  interval: 30s

{
  "name": "checkout",
  "replicas": 2,
  "port": 8080,
  "tls": "no",
  "regions": [
    "eu-west-1"
  ],
  "healthcheck": {
    "path": "/healthz",
    "interval": "30s"
  }
}

Most of it came across as the writer intended: the name is a string, the replica count and the port are numbers, and the one region is a list of one. Two values did not, and both look innocent in the YAML.

tls: no became the string "no". Under YAML 1.2, which Convert reads by, only true and false are booleans, so no is a word. Older 1.1 readers, still common, would have read it as false — which means the same file can mean two things depending on the library. And 30s is text, since YAML has no durations: a program expecting seconds as a number gets a string with a letter in it.

2 · Hold it to the schema

The JSON Convert produced is the document to check, unchanged. Take it across with the button over the result, switch the editor to Schema, and put the team’s schema in the right pane.

{
  "name": "checkout",
  "replicas": 2,
  "port": 8080,
  "tls": "no",
  "regions": [
    "eu-west-1"
  ],
  "healthcheck": {
    "path": "/healthz",
    "interval": "30s"
  }
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["name", "replicas", "port"],
  "properties": {
    "name": { "type": "string" },
    "replicas": { "type": "integer", "minimum": 1 },
    "port": { "type": "integer" },
    "tls": { "type": "boolean" },
    "regions": { "type": "array", "items": { "type": "string" } },
    "healthcheck": {
      "type": "object",
      "required": ["path"],
      "properties": {
        "path": { "type": "string" },
        "interval": { "type": "number" }
      }
    }
  }
}

Invalid · 2 errors

$.tls  type  Expected a boolean, found a string.
$.healthcheck.interval  type  Expected a number, found a string.

Both surprises from the first step are caught, and nothing else is. The schema asks for a boolean at tls and a number at the health check’s interval, and each error names the path, the rule and what was found instead. The required fields are all present and the replica count meets its minimum. Unlike a generated schema, this one does not forbid keys it does not list, so a new setting would pass.

The fixes belong in the YAML, not the JSON: tls: false, and interval: 30 with the unit moved into the key’s name or the documentation. Edit the source on Convert and carry the result across again, or edit the JSON in the editor to try a fix before you make it for real — the verdict on the band follows every keystroke.

Why not validate the YAML directly

A schema describes values — strings, numbers, booleans, lists — and says nothing about how they are spelled. YAML has several spellings for most values and different versions disagree about some of them, so a check run against the YAML text would have to guess which reading you meant. Converting first makes that reading visible. When the verdict fails, the JSON on the left shows you the value the check actually saw, which is usually the whole explanation.

Anchors and aliases, if your configs use them, are expanded in the JSON: a block defined once and reused three times appears three times, and the schema checks every copy. Comments are dropped, since JSON has none.

Keeping the check close at hand

The editor remembers both panes for the tab, so with the schema loaded once on the right you can keep pasting converted configs over the left and read each verdict in turn. Name the right pane after the schema’s file, so that with several schemas in play the one loaded is plain at a glance.

If your schema declares a draft newer than draft-07, the band says it is reading it as draft-07, and keywords from the newer draft that the validator does not know are reported as not fully checked rather than silently passed.

Where to go from here

• YAML: what comes back quoted, and why a long number keeps its digits.
• Between Convert and the editor: carrying a document across in either direction.
• Check a document against a JSON Schema, and writing a schema from a sample when you have none yet.

Open the editor in Schema mode with your team’s schema, or start on YAML to JSON.