YES - YAML Easy Schema

Author: Thomas Sawyer
License: BSD-2-Clause
Copyright: © 2011 Thomas Sawyer, Rubyworks

SALES PITCH

It doesn’t get any easier than this!

YES is a schema system for YAML that is intuitive and extremely powerful.

YES Schemas are also YAML documents, so they eat there own dog food.

HOW IT WORKS

The design of YeS is as simple as it is powerful. A YeS schema is composed of YPath selectors mapped to document constraints. YPath is a syntax for selecting nodes from a YAML document.

When validating a YAML document against a YeS schema a “lint” program simply collects all matching nodes with their applicable constraints into a collection of unit-validations. Then this collection is filtered of all passing validations. All that is left are the failures. If the filtered list is empty the document is completely valid. If not empty, the lint program can provide a detailed editorial list of the failures.

Constraints are given as a mappings of validation type to validation parameters.

Lets take an example:

people/*/name:
  regexp: '[^/n]'

This simple schema selects all nodes under a ‘people` sequence of mappings with a name key, the value of which cannot contain newlines. In other words:

--
people:
  - name: Charlie Adams
  - name: Julie Ann Rose

Would satisfy the schema. But,

--
people:
  - name: |
      Charlie
      Adams

Would not.

TODO: Better Examples!!!

Sometimes multiple constraints of the same type need to be applied to a set of nodes. This can be done by expressing the same YPath with different constraints, for example:

people/*/name:
  regexp: '[^/t]'
people/*/name:
  regexp: '[^/n]'

But to make the intent more succinct a sequence of constraints can be give along with the logical-and tag , ‘!!and`.

people/*/name: !!and
  - regexp: '[^/t]'
  - regexp: '[^/n]'

If the ‘!!and` tag is not given, then the default operator is used, logical-or, which can also be explicitly stated as `!!or`:

people/*/name: !!or
  - regexp: '[^/t]'
  - regexp: '[^/n]'

In this way logical relationships of constraints can be created.

people/*/name: !!or
  - !!and
    - regexp: '[^/t]'
    - regexp: '[^/n]'
  - !!and
    - regexp: '[^/t]'
    - regexp: '[^/n]'

COMMAND LINE

To use on the command line lint tool. Say we have a ‘schema.yes` file:

---
name:
  type: str
  regexp: '[^\n]'
  required: true
age:
  type: int
birth:
  type: date

Try it on ‘sample.yaml`.

---
name: Thomas T. Thomas
age: 42
birth: 1976-07-04

Using the executable.

$ yes-lint schema.yes sample.yaml

In code that is:

require 'yes'

lint = YES::Lint.new(File.new('schema.yes'))

lint.validate(File.new('sample.yaml'))

CONTRIBUTE

Come on folks! Let’s get YAML up to snuff. A good Schema could really help YAML go the distance and penetrate some of those “Enterprisey” worlds.

Please read, write and comment on issues.
Please critique the code.
Please fork and submit patches in topic branches.

And please contribute to Rubyworks Ruby Development Fund so us poor Ruby OSS developers can eat :)

COPYRIGHT

(BSD-2 license)