https://github.com/yaml-schema/yaml-schema
Validate YAML documents using a YAML schema
https://github.com/yaml-schema/yaml-schema
rust yaml yaml-validator
Last synced: 2 months ago
JSON representation
Validate YAML documents using a YAML schema
- Host: GitHub
- URL: https://github.com/yaml-schema/yaml-schema
- Owner: yaml-schema
- License: mit
- Created: 2024-05-30T02:26:38.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2026-03-21T15:38:30.000Z (3 months ago)
- Last Synced: 2026-03-21T16:13:18.304Z (3 months ago)
- Topics: rust, yaml, yaml-validator
- Language: Rust
- Homepage:
- Size: 903 KB
- Stars: 24
- Watchers: 2
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
ys - yaml-schema
====
[](https://github.com/aisrael/yaml-schema/actions/workflows/ci-tests.yaml)
**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/](https://json-schema.org/)), but
expressed as YAML.
**yaml-schema** is both a Rust library _and_ an executable.
## 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](#example-usage), with `foo` and `bar` violating their types:
```sh
ys --json -f schema.yaml invalid.yaml
```
stdout (pretty-printed; the tool emits compact JSON on one line):
```json
[
{
"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":""}`.
If the schema file cannot be read:
```sh
ys --json -f /path/to/missing-schema.yaml valid.yaml
```
stderr:
```json
{"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](https://cucumber-rs.github.io/cucumber/main/) to specify and test features:
- [CLI usage](features/cli.feature)
- [Basic features](features/basics.feature)
- [String validation](features/validation/strings.feature)
- [Numeric types](features/validation/numbers.feature)
- [Const](features/validation/const.feature)
- [Enums](features/validation/enums.feature)
- [Object types](features/validation/objects.feature)
- [Arrays](features/validation/arrays.feature)
- [Composition](features/composition.feature)
- [Unevaluated properties/items](features/validation/unevaluated.feature)
See the [features](features/) folder for all examples.
## Installation
Currently, **yaml-schema** requires Git, Rust and Cargo to build and
install: [https://doc.rust-lang.org/cargo/](https://doc.rust-lang.org/cargo/)
To install the stable release from [crates.io](https://crates.io/crates/yaml-schema):
```
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 The schema to validate against
--fail-fast Specify this flag to exit (1) as soon as any error is encountered
-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.