[zaphodias]

it doesn't look worse than OpenAPI's yaml to me

it's fairly concise, the method and the request/response types are well separated and readable

the only thing I could argue with is mixing validation and type defs, as it looks like one of these things that quickly evolve over time and you end up duplicating both in the schema and the business logic