yaml-validator-cli

Command-line interface for validating YAML files using schemas written in yaml.

Quick Links:

• Supported Datatypes
• Examples

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.

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!

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!

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!

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.