Document api types wrt validation

Part 3 in a series of changes towards data validation.
I would prefer that comments be in this file, so they show up in godoc. Maybe we could write a script to instead generate the RAML from here? ;)