6 releases
0.1.1 | Nov 13, 2023 |
---|---|
0.1.0 | Feb 8, 2020 |
0.0.3 | Jan 26, 2020 |
0.0.2 | Jan 25, 2020 |
0.0.1 | Jan 25, 2020 |
#765 in Database interfaces
145KB
4.5K
SLoC
yaml-validator-cli
Command-line interface for validating YAML files using schemas written in yaml.
Quick Links:
Command-line help information
yaml-validator-cli 0.1.0
Command-line interface to the yaml-validator library.
Use it to validate YAML files against a context of any number of cross-referencing schema files.
The schema format is proprietary, and does not offer compatibility with any other known YAML tools
USAGE:
yaml-validator-cli [OPTIONS] --uri <uri> [--] [files]...
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-s, --schema <schemas>... Schemas to include in context to validate against. Schemas are added in order, but do
not validate references to other schemas upon loading.
-u, --uri <uri> URI of the schema to validate the files against.
ARGS:
<files>... Files to validate against the selected schemas.
Currently supported datatypes
The schema format supports a very limited number of types that map very closely to the YAML specification:
string
utf8-compliant stringinteger
i64 integerreal
f64 floating point valuehash
(also know asdictionary
orhashmap
) that mapsstring ➞ <type>
as defined initems
items: <type>
(optional) type of the values in the hash
array
array of items of type<type>
items: <type>
(optional) type of the values in the array.
object
struct with known fields (unlike a hash).items
array of fields and their types as below<name>: <type>
$ref: <uri>
reference to schema in same context identified by<uri>
Examples
All of the examples below can also be found in the examples/ directory.
Using references to avoid deeply nested and non-reusable structures
We can define a person
object and later refer to it by its uri in a different schema phonebook
:
# phonebook.yaml
---
uri: person
schema:
type: object
items:
name:
type: string
phone:
type: integer
---
uri: phonebook
schema:
type: object
items:
phonebook:
type: array
items:
$ref: person
Source: examples/nesting/schema.yaml
We can then use the above schema to validate a yaml document as defined here:
# mybook.yaml
---
phonebook:
- name: timmy
phone: 123456
- name: tammy
phone: 987654
Source: examples/nesting/mybook.yaml
... Using the yaml-validator-cli
as follows:
$ yaml-validator-cli --schema phonebook.yaml --uri phonebook -- mybook.yaml
all files validated successfully!
Referencing schemas across file boundaries
All schemas given using the --schema
commandline option are all loaded into the same context, so referencing a schema defined in a separate file is exactly the same as if they had been defined in the same file.
# person-schema.yaml
---
uri: person
schema:
type: object
items:
name:
type: string
phone:
type: integer
Source: examples/multiple-schemas/person-schema.yaml
# phonebook-schema.yaml
---
uri: phonebook
schema:
type: object
items:
phonebook:
type: array
items:
$ref: person
Source: examples/multiple-schemas/phonebook-schema.yaml
Validate the following yaml document against our schemas above:
# mybook.yaml
---
phonebook:
- name: timmy
phone: 123456
- name: tammy
phone: 987654
Source: examples/multiple-schemas/mybook.yaml
... Using the yaml-validator-cli
as follows:
$ yaml-validator-cli \
--schema phonebook-schema.yaml \
--schema person-schema.yaml \
--uri phonebook \
mybook.yaml
all files validated successfully!
Combining all the different types with nested references
We can define a schema in 3 levels as below, where a customer-list is defined as an array of customers, which in turn contain elements of their own, as well as references to a third schema 'car':
# schema.yaml
---
uri: car
schema:
type: object
items:
year:
type: integer
model:
type: string
extra features:
type: array
items:
type: string
price:
type: real
---
uri: customer
schema:
type: object
items:
name:
type: string
cars:
type: hash
items:
$ref: car
---
uri: customer-list
schema:
type: array
items:
$ref: customer
Source: examples/all-types/schema.yaml
Validate the following customer list document against the defined schema:
# customers.yaml
---
- name: Teodor Fælgen
cars:
work:
model: Ford T
extra features:
- gps
- heated seats
price: 200.00
racing:
model: Il Tempo Gigante
extra features:
- blood bank
- radar
price: 3000.00
- name: Lightning McQueen
cars:
himself:
model: Stock
extra features:
- massive eyes instead of windows
- arrogance
price: 0.00
Source: examples/all-types/customers.yaml
... Using the yaml-validator-cli
as follows:
$ yaml-validator-cli \
--schema schema.yaml \
--uri customer-list \
customers.yaml
all files validated successfully!
Locating errors in documents
Error messages always contain the full path within the document, as well as the document name in which the validation error occurred. This lets you pretty easily track down the exact source of the error.
With a phonebook schema as follows:
# schema.yaml
---
uri: person
schema:
type: object
items:
name:
type: string
age:
type: integer
---
uri: phonebook
schema:
type: array
items:
$ref: person
Source: Source: examples/locating-errors/schema.yaml
We can validate our very non-compliant document defined as:
# phonebook.yaml
- name: John
age: 52
- name: Karen
age: 12.5
- name: 200
age: Jimmy
Source: Source: examples/locating-errors/phonebook.yaml
Using yaml-validator-cli as follows:
$ yaml-validator-cli \
--schema schema.yaml \
--uri phonebook \
phonebook.yaml
phonebook.yaml:
#[1].age: wrong type, expected integer got real
#[2].age: wrong type, expected integer got string
#[2].name: wrong type, expected string got integer
The error message correctly tells us that there's an issue with the document phonebook.yaml
supplied. Karen's age is a real, not an integer, and Jimmy's age and name have been switched.
Note: The #
denotes the root of the document, phonebook.yaml
in this case.
Dependencies
~7MB
~128K SLoC