Support for array "items" to be array (valid JSON Schema, but not OpenAPI)?

Hi,

Will there be support forthcoming for items to be an array, as discussed in https://github.com/OAI/OpenAPI-Specification/pull/609?

My use case is, I want to send data in a request and/or response, where my data consists of a header section plus a body and where the latter could be somewhat large in size-- often 1k times larger, sometimes 1 million times larger, than the header size. ​For performance purposes, the header must come first, which allows the body to then be processed with fixed space regardless of the body size (a hypothetical example would be a header that contained some arbitrary string you need to count occurrences of, plus a body to search for that string in-- as long as you know what you are searching for before you receive the body, you can process the body in chunks and not have to remember what you already processed. In that simple example, obviously you could send the search string in some http header, but the header in my use case is more complex than just a string to search for, and it will be encoded as JSON, so not really viable to send as an http header).

Therefore, I’d like the specification to also reflect the fact that the header must come before the body.

Using JSON ​Schema, this is easy. I can specify that the data must be an array of two items, where the first item conforms to the header schema, and the second conforms to the payload schema. So my data may look like:

[
	{ "type": "header", ... },
	{ "type": "body", ... }
]

and my spec would be something like:

{
	"$schema": "https://json-schema.org/draft/2019-09/schema",
	"type": "array",
	"items": [
		{
			"type": "object",
			"properties": {
				"type": {
					"enum":  ["header"]
				}
			}
		},
		{
			"type": "object",
			"properties": {
				"type": {
					"enum":  ["body"]
				}
			}
		}
	]
}

However, openAPI does not allow items to be an array. So the best I can do, which isn’t very helpful, is to use a merged schema (e.g. oneOf or anyOf) to allow any array element to be a header or body-- which means that any validation using this specification will be useless for the purposes of ensuring that the header comes before the body.

Is there a better solution to this problem (whether currently available or planned to be available)?

Thank you

[MikeRalphson]

I have a validator in progress which will be released shortly (subscribe to releases on https://github.com/Mermade/oas-kit). Codegen will be lagging a bit behind that. Two major code-gen projects will need swagger-parser to support OAS 3.1 before they can implement. Stoplight announced 3.1 support today.

[MikeRalphson]

OAS 3.1 supports all of JSON Schema Draft 2020-12. In this draft, the array form of items was split out to the prefixItems keyword. This should do what you want.