YES - YAML Easy Schema
© 2011 Thomas Sawyer, Rubyworks
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
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]'
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'))
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 © 2011 Rubyworks, Thomas Sawyer