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

MIT license

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 string
  • integer i64 integer
  • real f64 floating point value
  • hash (also know as dictionary or hashmap) that maps string ➞ <type> as defined in items
    • 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