> Yes, this is as bad as it looks: “success” isn’t even part of the schema. It’s in the examples, but not the actual schema definition. Having gone through a p

> Yes, this is as bad as it looks: “success” isn’t even part of the schema. It’s in the examples, but not the actual schema definition. Having gone through a pretty heavy overhaul of an "OpenAPI" (full code in Elixir at https://github.com/etalab/transport-site/pull/3351 https://github.com/etalab/transport-site/pull/3351), I stumbled on that exact type of problem! At the scale of nginx, having automatic verification that the examples (and the output of the API in general) match the specification would be great. At our scale, here is what really helped me go through the rework (and ensure we do not regress too easily): - setting additionalProperties to "false" to detect key field "rot" - using "required: [x,y,z]" on everything, and by default specify "all the property keys", with an opt-out (so that each time a developer adds a field later, it is considered mandatory, unless otherwise specified) - use tooling during the tests: "assert_schema" (with OpenAPISpex) to ensure our API endpoints responses pass the spec (additionalProperties: false helps ensure we get an exception in case of key field rot, again!) - even more useful: crawl our production most important endpoints and tweak the spec until everything is green (an example of useful use of Task.async_stream in Elixir, by the way) https://github.com/etalab/transport-site/pull/3351/files#diff-e73c888e72cf3a5df29a7b628cb5ad208324e989ad8cc2cc5f7d12dce89a9707 https://github.com/etalab/transport-site/pull/3351/files#dif... It can be super frustrating for users to live with the uncertainty of the response of an API for sure, and I was happy to discover the Elixir tooling (OpenAPISpex in particular) worked so nicely once I understood what I had to do.