Document api types wrt validation

Part 3 in a series of changes towards data validation.
I'll update that schema as part of this patchset.  Would you prefer to just leave comments out of this file and point people at the RAML/HTML?