Support prefixItems in array schemas
splitbrain opened this issue · comments
I am modelling an existing API which uses positional arguments in the request body. According to this stackoverflow answer the correct way to do that is to use prefixItems.
Unfortunately, this seems not to be picked up by openapi-explorer. The model tab just shows [].
Any chance this could be supported properly? Or maybe there's a workaround?
Do you have a link to the oas schema where this is documented.
Of course if it is spec compliant we would accept a PR to implement thine missing functionality. Thanks for finding this missing piece.
From what I understand, this comes from JSON-Schema. But digging further into this, it seems it is not fully supported after all. The swagger editor however does display at least some info:
https://json-schema.org/understanding-json-schema/reference/array#tupleValidation has some more info on the used syntax.
So it's clearly something in the json schema draft 2020-12 schema that could be added. Given that we'll keep this ticket open. I will share two concerns about using this however:
- This is non-trivial functionality that likely leads to a lot of confusion. In these cases when you already know about these properties, first class properties of the parent are a better design. Or changing the array to be an object with nested properties, one of those of those being an array.
- This can't work for most typed languages given that typed languages don't have a concept of positional schema for array elements.
While I can recommend all day long that this should never be done, that doesn't stop it from having been added to the spec. So if someone spends the time to implement this feature, as per Draft 2020-12, we will accept it, but will caution that this functionality should never exist in an API due to its lack of polymorphism across languages.
Note on the first point and the example, the example uses address, but not every address works that way, so realistically, the example is a really bad one and sets a bad precedent. If you are trying to create an api with properties for an address, see: