Hi guys
I’ve been thinking about the balance between following the JSON specification and allowing individual teams enough flexibility to build APIs that fit their use cases.
For a small project, manually checking API responses isn’t too difficult.
But when an API becomes larger, it seems useful to have automated checks for things like:
- Valid JSON document structure
- Required members
- Consistent resource types
- Relationship conventions
- Pagination rules
- Error response formats
- Naming conventions
- Deprecated fields or endpoints
- Documentation completeness
The challenge is deciding which rules should actually be enforced.
If every possible convention becomes a hard validation rule, development can become unnecessarily restrictive. But if everything is left to developers, inconsistencies can gradually accumulate.
I’m wondering how other JSON implementers approach this.
Do you use JSON Schema, OpenAPI tooling, custom validators, CI checks, or another API governance tool?
For example, would a workflow like this be useful?
API change → JSON validation → contract tests → CI → deployment
I’d be particularly interested in how teams distinguish between:
“This violates the JSON specification”
and
“This doesn’t violate the specification, but it violates our organization’s API conventions.”
Where do you think that boundary should be?