Document api types wrt validation

Part 3 in a series of changes towards data validation.
Merge pull request #312 from thockin/valid4

Document api types wrt validation