Document api types wrt validation

Part 3 in a series of changes towards data validation.
Actually, nm.  That's probably not sustainable, as gofmt will likely just re-scamble it.  *sigh*