Document api types wrt validation

Part 3 in a series of changes towards data validation.
Yeah, I noticed that it screws up when a comment comes between.  Ignoring for now.