We’re looking into YAML document validation at work for some internal APIs. The two contenders were Rx and Kwalify.

Suppose we want to validate this YAML document that represents a (portion of a) Venue object here at Songkick (I made up the capacity figure):

name:     Astoria
street:   157 Charing Cross Road
city:     London, UK
zip:      WC2H 0EN
lat:      51.500152
lng:      -0.126236
capacity: 12345

Kwalify

The schema in Kwalify:

type: map
mapping:
  name:
    type: str
  street:
    type: str
  city:
    type: str
  zip:
    type: str
  lat:
    type: float
  lng:
    type: float
  capacity:
    type: int

Pros

• easy to learn.
• useful validation errors
• excellent documentation
• can have complex validations such as regexes and arbitrary ruby code

Cons

• Ruby and Java only
• arrays and maps can only have the same type elements or values

Rx

The document schema in Rx:

type: //rec
optional:
  name:     //str
  street:   //str
  city:     //str
  zip:      //str
  lat:      //num
  lng:      //num
  capacity: //int

Pros

• same schemas can be used in JavaScript, Ruby, Perl, PHP and Python.
• can validate YAML and JSON
• can have arrays, maps with different type elements
• resulting schemas are much more concise
• easy to extend type system

Cons

• documentation lacks examples, so a little harder to grasp
• validation errors don’t contain any useful information
• missing some important Ruby types, such as date and time.

We’ve gone with Rx, because it’s minor shortcomings are easy to fix. I hope to find the time to extend at least the Ruby implementation to add some more types and add a few examples and useful exceptions.