OpenAPI and JSON Schema Divergence: Part 1

I have an idea. Why don't we give up on a strictly declarative format/solution? What if, associated with each possible API call, was a pseudocode or generalcode representation of the code executed to validate the request?

Is reading code snippets that difficult? For a short validation program, a machine could certainly infer if a type would be accepted (just run the validation).

I know that a declarative format seems like the right choice, given validation in mainstream programming languages is expressed declaratively via the type system, but these standards, to me, often seem to only translate awkwardly an implicit validation program into a very verbose declaration.

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.

It's certainly possible to talk about API specifications without mentioning either of those.