clarify and enforce the input JSON schema

We should clearly document the input JSON schema we accept, and enforce it rigorously, generating useful error messages when inputs violate spec. We should not silently fail on spec violations.

If we can enforce the spec deterministically using a JSON parsing tool that would be ideal. If not, we should have a fuzz tester that ensures we fail properly.