I really like the idea of declarative and machine-readable validation and API descriptions, but JSON schema is often pretty frustrating to work with in practice. Building a compliant implementation is quite difficult.

The $ref resolution, as defined in the spec, is hideously complicated, to the point where many implementations just don't even bother supporting external $refs. It feels like it really should be a totally separate concern from validation, especially since how you store and compose schemas may end up being somewhat specific to a given use case.