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
| Mode | Schema | What 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.json | the 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.
| Code | Meaning |
|---|---|
0 | the file matches the schema |
1 | there are schema errors, the file can't be read or it isn't YAML |
2 | invalid 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
| Message | Cause |
|---|---|
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 script | the job has no script (or the key is misspelled) |
stage 'x' is not declared in stages | the 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 schemas | a 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: binscriptas the mapping{'echo a': 'b'}. Quote such lines:- 'echo a: b'. - In compose, one error drags along a second one. An invalid value inside
healthcheckgives both'healthcheck' was unexpectedat 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
stagelands intest. Ifstageslists your own stages withouttest, you getstage 'test' is not declared in stages— setstageexplicitly. - Structure is checked, not meaning. These pass:
needspointing to a nonexistent job,extendspointing to a nonexistent template,depends_onpointing to a nonexistent service,includeof a missing file (included files aren't read). - The file must be passed explicitly. Without arguments or with a third argument you get
usageand code2, 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