Openapi-specification: Could array items contain an array of schemas?

[adjenks]

I'm having difficulty understanding why in a requestBody one cannot specify the elements of an array explicitly. One can only have a general schema that applies to all items.

As it states in the latest OpenApi Spec:

items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.

But in json schema it states:

The value of "items" MUST be either a valid JSON Schema or an array
of valid JSON Schemas.

My particular API REALLY needs to have request bodies that contain arrays with specifically ordered and typed elements, but with the current definition this is not allowed. I'm having a hard time understanding why the specification should disallow the definition of any particular JSON structure.

My schema definition currently breaks all the tools, so I've worked around it by defining my schemas as empty like so:

type: array
items: {}

and then I provide the details of how it should really be structured in the examples section.

So, as the title says, I'd like to know why it was chosen to not allow this. I'd also like to know if anyone would be open to the idea of getting rid of the "and not an array" requirement? I know this likely has a variety of implications, but let's talk about them 😀.

[handrews]

@adjenks see #1532 for one possible way forward on this and other JSON Schema compatibility issues.

[adjenks]

@handrews Thank you for pointing me to one of the possible future solutions. It does look interesting, with support for other types of schema definitions. It is good to keep things decoupled. In the meantime I'll just work around it.

[mariotoffia]

@handrews, @analogue Hi I've got the same problem. Actually ordering of my objects is not specific but the kind of objects are. Did you solve it? If so, can you please share that?

For example i need different named objects to contain different properties, e.g.:

[
 { "n" : "fanspeed", "maxSpeed" : 999, "stepping" : 10, "ot" : "Fan" },
 { "n" : "aqi", "good" : 44, "poor" : 124, "hazardous" : 150, "ot" : "PM" }
]

Where the ot = Fan and PM ar completely different schema objects.

Cheers,
Mario

[handrews]

@mariotoffia PR #1977 updates the forthcoming OpenAPI Specification 3.1 to use JSON Schema draft 2019-09, which includes the tuple form of items. So OAS 3.1 will solve this, but it's not available as part of OAS 3.0 or earlier.

[philsturgeon]

This was fixed in #1977 so we can close this.