Document api types wrt validation

Part 3 in a series of changes towards data validation.
I'll have to figure out how to express formatting in RAML...