ys - yaml-schema

yaml-schema is a tool to validate YAML files against a YAML schema.

The YAML Schema specification is based on JSON Schema (https://json-schema.org/), but expressed as YAML.

yaml-schema is both a Rust library and an executable.

Documentation

See detailed documentation at https://yaml-schema.net/.

When writing schemas or instances in YAML, remember that mapping keys are parsed by YAML first. Unquoted keys such as 1 become a number; keys that start with @, #, or other special characters may be invalid or require quoting. Use explicit quotes (e.g. "@id", "1") when the property name must be that exact string. See also issue #62.

JSON Schema vs YAML: JSON object keys are always strings. YAML allows other scalar mapping keys (e.g. integers, booleans). The propertyNames keyword validates each mapping key against a subschema. Only scalar types are permitted (string, integer, number, boolean, null); array and object types (and array/object keywords such as items or properties) are rejected at load time. Composition keywords (oneOf, anyOf, allOf) are supported when every branch uses scalar types. When no type is provided, the subschema is treated as type: string and validates the canonical string form of the key (JSON Schema compatible). String keywords such as pattern and enum work without an explicit type. When a non-string scalar type is specified (e.g. integer), the YAML key node is validated directly. See the Types documentation for details.

Example Usage

Given a schema.yaml file containing:

type: object
properties:
  foo:
    type: string
  bar:
    type: number

And a valid.yaml file containing:

foo: "I'm a string"
bar: 42

Then when you issue the command

ys -f schema.yaml valid.yaml

Then the command should succeed with exit code 0

On the other hand, when given an invalid.yaml file containing:

foo: 42
bar: "I'm a string"

Then the command

ys -f schema.yaml invalid.yaml

Should fail with exit code 1

JSON Output

Pass --json to emit structured errors instead of plain text. Use it with the same options as usual.

Successful validation (exit code 0): stdout is empty.

ys --json -f schema.yaml valid.yaml

(no output on stdout)

Validation failures (exit code 1): stdout is a single JSON array of objects, one per error. Each object has:

Field	Meaning
`index`	Byte offset into the source, or `null` if unknown
`line`	1-based line number, or `null` if unknown
`col`	0-based column index from the parser, or `null` if unknown
`path`	Dot-separated path from the document root (e.g. `foo`, `items.0`)
`error`	Human-readable message

Using the same schema.yaml / invalid.yaml scenario as above, with foo and bar violating their types:

ys --json -f schema.yaml invalid.yaml

stdout (pretty-printed; the tool emits compact JSON on one line):

[
  {
    "col": 5,
    "error": "Expected a string, but got: 42 (int)",
    "index": 5,
    "line": 1,
    "path": "foo"
  },
  {
    "col": 5,
    "error": "Expected a number, but got: \"I'm a string\" (string)",
    "index": 13,
    "line": 2,
    "path": "bar"
  }
]

Other failures (exit code 1): schema load errors, missing arguments, YAML parse errors, and similar issues print a single JSON object on stderr: {"error":"<message>"}.

If the schema file cannot be read:

ys --json -f /path/to/missing-schema.yaml valid.yaml

stderr:

{"error":"Failed to read YAML schema file /path/to/missing-schema.yaml: No such file or directory (os error 2)"}

The exact error text depends on the failure (OS messages, parse errors, etc.).

Validation errors are written to stdout; non-validation errors use stderr, so callers can distinguish validation results from tooling or I/O failures.

Features

yaml-schema uses Cucumber to specify and test features:

See the features folder for all examples.

Installation

Currently, yaml-schema requires Git, Rust and Cargo to build and install: https://doc.rust-lang.org/cargo/

To install the stable release from crates.io:

cargo install yaml-schema

That should build and install the executable at $HOME/.cargo/bin/ys (which should be in your PATH)

Alternatively, one can install from latest source:

cargo install --git https://github.com/yaml-schema/yaml-schema

Usage

Running ys without any options or arguments should display the help:

A tool for validating YAML against a schema

Usage: ys [OPTIONS] [FILE] [COMMAND]

Commands:
  version  Display the ys version
  help     Print this message or the help of the given subcommand(s)

Arguments:
  [FILE]  The YAML file to validate

Options:
  -f, --schema <SCHEMAS>  Schema file(s) to load. The first is the root schema; additional
                          schemas are pre-loaded for $ref resolution. May be specified multiple
                          times (-f a.yaml -f b.yaml). Omit when the instance YAML has a
                          top-level string `$schema` (URL or path)
      --fail-fast         Specify this flag to exit (1) as soon as any error is encountered
      --json              Emit errors as JSON: validation failures as a JSON array on stdout;
                          other failures as {"error":"..."} on stderr
  -h, --help              Print help
  -V, --version           Print version

Self-Validation

yaml-schema is self-validating. That is, running

cargo run -- -f yaml-schema.yaml yaml-schema.yaml

should always succeed.

yaml-schema 0.9.3