Document api types wrt validation

Part 3 in a series of changes towards data validation.
nit: gofmt doesn't handle comments well... Can you manually align string and `yaml:...` with the lines below for easier scanning?