This is OK for simple structures, but in a deeply nested structures and larger APIs you'd probably also need some equivalent of json-schema $refs and ability to

This is OK for simple structures, but in a deeply nested structures and larger APIs you'd probably also need some equivalent of json-schema $refs and ability to reuse blocks in your api schema.