← Full reference

yamlschema

Offline validation of .gitlab-ci.yml and docker-compose.yml against the official JSON schemas — an IzzyLab sandbox tool

yamlschema is a small tool built into the IzzyLab sandbox (it's not a standard Linux package). It reads a YAML file and validates it against the official JSON schema: GitLab CI (gitlab-ci) or the Compose Specification (compose). This way the config is judged almost as the real tool would judge it — a typo in a key or a job without script is an error, not "valid YAML". It works without internet: the schemas live in /opt/schemas.

In real projects the same role is played by GitLab's built-in CI Lint and docker compose config.

Syntax

yamlschema gitlab-ci FILE
yamlschema compose   FILE

Exactly two arguments. There are no other options. To check data from a pipeline, pass /dev/stdin as the file.

Modes

ModeSchemaWhat else it checks
gitlab-ci/opt/schemas/gitlab-ci.json (GitLab 17.8)every job has script, run, trigger or extends; its stage is declared in stages (if there are no stages, build, test, deploy, .pre, .post are allowed; the default stage is test)
compose/opt/schemas/compose-spec.jsonthe schema only: unknown keys, types, allowed values

In gitlab-ci, reserved keys (default, include, stages, variables, workflow, image, services, cache, before_script, after_script, spec) and hidden jobs starting with a dot (.template) are not treated as jobs.

Output and exit codes

On success it prints nothing. Errors go to stderr, one per line, at most five:

bad-ci.yml: build: Additional properties are not allowed ('scrpt' was unexpected)
bad-ci.yml: deploy/when: 'sometimes' is not one of ['on_success', 'on_failure', 'always', 'never', 'manual', 'delayed']
bad-ci.yml: build: job has no script
bad-ci.yml: build: stage 'biuld' is not declared in stages

Format: file: path/to/field: message. The path (root) means an error at the top level. The message is truncated to 200 characters.

CodeMeaning
0the file matches the schema
1there are schema errors, the file can't be read or it isn't YAML
2invalid invocation: wrong mode or number of arguments (prints usage)

Examples

cat > .gitlab-ci.yml <<'EOF'
stages: [build, test]
build:
  stage: build
  image: alpine:3.20
  script:
    - echo build
test:
  script: echo test
EOF
yamlschema gitlab-ci .gitlab-ci.yml && echo OK

cat > docker-compose.yml <<'EOF'
services:
  web:
    image: nginx:1.27
    ports: ["8080:80"]
    depends_on: [db]
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: example
EOF
yamlschema compose docker-compose.yml && echo OK

# check YAML produced by another command
yq '.' docker-compose.yml | yamlschema compose /dev/stdin

# in a script — just the exit code
if yamlschema gitlab-ci .gitlab-ci.yml 2>/dev/null; then echo valid; else echo invalid; fi

Common errors and what they mean

MessageCause
Additional properties are not allowed ('scrpt' was unexpected)a typo or unknown key in a GitLab job
Unevaluated properties are not allowed ('port' was unexpected)the same for compose (the correct key is ports)
job has no scriptthe job has no script (or the key is misspelled)
stage 'x' is not declared in stagesthe stage isn't listed in stages
'sometimes' is not one of [...]an invalid value — the allowed ones are listed in brackets
10 is not of type 'string'the wrong type: e.g. interval: 10 instead of "10s"
[{'echo a': 'b'}] is not valid under any of the given schemasa line with : in script became a mapping — it needs quotes
(root): None is not of type 'object'the file is empty

Pitfalls

  • At most five errors are shown. After fixing them, run it again: more may appear.
  • A colon followed by a space in a command. YAML reads - echo a: b in script as the mapping {'echo a': 'b'}. Quote such lines: - 'echo a: b'.
  • In compose, one error drags along a second one. An invalid value inside healthcheck gives both 'healthcheck' was unexpected at the service level and the real cause deeper down (services/w/healthcheck/interval: 10 is not of type 'string'). Look for the line with the longest path.
  • A job without stage lands in test. If stages lists your own stages without test, you get stage 'test' is not declared in stages — set stage explicitly.
  • Structure is checked, not meaning. These pass: needs pointing to a nonexistent job, extends pointing to a nonexistent template, depends_on pointing to a nonexistent service, include of a missing file (included files aren't read).
  • The file must be passed explicitly. Without arguments or with a third argument you get usage and code 2, not a check of the current directory.
  • The tool exists only in the sandbox. Outside IzzyLab the equivalents are CI Lint in the GitLab UI and docker compose config -q.

See also

gitlab-ci · docker-compose · yq · kubeconform · actionlint