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.