That said, I do wish there were a better format for it than YAML/JSON, and I think some of their design decisions were strange.
Note that a lot of OAS's strengths and weaknesses were inherited from its parent project, JSON Schema, which is also widely supported.
> I wanted it to be a terse specification, such that just glancing over the definition file gives you a sense of what the API consists of.
OAS specs in YAML (as opposed to JSON) are pretty terse and easy to scan, especially if the spec is kept fairly DRY by defining/refusing object schemas.
> I wanted a solution that handled websockets/server push as a first-class citizen, and not as a secondary add-on
OAS fails this one.[1]
> I wanted to provide library-level validation of request / response shape.
This is something all the major formats (JSON Schema/OAS, RAML, Blueprint, etc.) do. It's probably the first thing people want to do with an API spec. OAS has great support for validation in most languages, although implementation of the spec can be spottier with less-popular stacks like PHP.
> I wanted to extend it beyond typescript, notably into python (and hopefully beyond)
One of my projects uses Spot[1] to define its API. Spot has CLI tools that translate it into a plain OAS file (.yaml format), and then there are more CLI tools that generate code (models, validators, controllers, and even servers) from that spec file.
If you don't mind a polyglot toolchain -- and I think most of us have one at this point -- then the Spot => OAS => Python process works fine and is easy to set up. You don't even need to start with Spot, of course.
> I like the idea of generic structs and oneofs (which I'm going to implement in some future version). I think if we had an easy way to define generics in cross-language APIs, we'd probably use it a fair amount.
I agree that this is super important. OAS supports it, although it can be hard to read a lot of branches inheritance trees in that particular format.
You can split your definitions into separate files to make it easier (in both Spot and in plain OAS itself).
> I like the idea of having an extensible language, e.g. be able to provide a JSONLogic type. Imagine a field `priceCalculation: JsonLogic<string, number>`. That'd be pretty cool!
This makes sense, but at the end of the day, "JsonLogic<string, number>" is just a text format. With OAS, you can define a regex to validate inputs and outputs, which has been "good enough" in my experience, but definitely falls short of what you want.
What about GraphQL? That seems to have some of the features you're interested in, although the GraphQL paradigm is so different from HTTP (and has some tradeoffs) that I'd understand not even considering it.
