YAML Schema Validation

A YAML parser checks grammar only. The check confirms that colons, dashes, and indentation follow the rules. It cannot tell whether a port number is missing or whether an age holds the word banana. A schema describes what the data must look like, and a validator checks the file against that description.

The Checklist Idea

Picture a school admission form with a checklist at the top: name required, age between 5 and 18, class from a fixed list. A clerk compares each form against the checklist. A schema acts as the checklist, and a validator acts as the clerk.

  +------------+
  | data.yaml  |---+
  +------------+   |     +-----------+     +-----------------+
                   +---> | Validator | --> | Pass  or  Errors|
  +------------+   |     +-----------+     +-----------------+
  | schema     |---+
  +------------+

JSON Schema for YAML

JSON Schema is the most popular schema language, and it works with YAML data because both formats describe the same structures. Schemas themselves can be written in YAML for easier reading.

type: object
required:
  - name
  - age
properties:
  name:
    type: string
  age:
    type: integer
    minimum: 5
    maximum: 18
  class:
    type: string
    enum: [nursery, primary, secondary]

Understanding the Keywords

Keyword	Meaning
type	Expected kind of value: string, integer, number, boolean, array, object
required	Keys that must exist
properties	Rules for each named key
enum	Allowed values from a fixed list
minimum, maximum	Number limits
pattern	A regular expression the text must match
items	Rules for entries inside a list

A Matching Data File

name: Meena
age: 12
class: primary

This file passes every rule. Change the age to twelve and the validator reports that the value is not an integer. Remove the name and the validator reports a missing required key.

Validating with Python

import yaml
from jsonschema import validate, ValidationError

schema = yaml.safe_load(open("schema.yaml"))
data = yaml.safe_load(open("data.yaml"))

try:
    validate(instance=data, schema=schema)
    print("Valid")
except ValidationError as err:
    print("Problem:", err.message)

Install the helper library with pip install jsonschema. The script loads both files, runs the check, and prints a readable message.

Validating Lists

type: array
items:
  type: object
  required: [id]
  properties:
    id:
      type: integer

The schema demands a list where every entry is a mapping with an integer id. The validator walks through each entry and reports the position of any failure.

Editor Support

Editors can attach a schema to a file and underline errors as you type. A special comment at the top of the file links the schema:

# yaml-language-server: $schema=./schema.json

The VS Code YAML extension reads this comment, offers auto-complete for known keys, and shows hover help. Many public schemas exist for common files, such as GitHub Actions workflows and Docker Compose.

Command-Line Tools

Tool	Purpose
check-jsonschema	Validates YAML files against a JSON Schema
ajv-cli	Fast validator for JavaScript projects
kubeconform	Checks Kubernetes manifests
yamale	Python tool with its own simple schema language

Benefits in Teams

• Errors surface before deployment instead of after a failure.
• New teammates learn the expected structure from the schema itself.
• Automated pipelines reject bad files before they reach a server.
• Documentation and validation stay in one place.

Reading Validation Messages

A failed validation names the location of the problem and the rule that broke. A message such as "12 is not of type string" tells you which value has the wrong type. A message such as "name is a required property" tells you which key is missing. Fix the data or relax the schema, depending on which one is wrong.

Building a Schema Step by Step

Begin with a sample file that works. Describe each key with its type, mark the essential keys as required, and run the validator against the sample. Add limits and allowed values after the basic version passes. Growing a schema in small steps keeps errors easy to trace.

Start with a small schema covering the required keys and types. Add stricter rules as the project grows and mistakes reveal which checks matter most.