Need to clarify the interaction between minOccurs, maxOccurs and schema in the input description.

[Panagiotis (Peter) A. Vretanos]

There needs to be some clarifying text and perhaps examples added to the specification to explain the interaction between minOccurs, maxOccurs and schema.

Specifically,

1. The schema is used to express the definition of a single instance of an input.
2. The minOccurs and maxOccurs members indicate the cardinality of that input.
3. If the cardinality is 1 then an input value in an execute request can be assigned directly to the input

"x": 10

4. If the cardinality of an input is 1..N and only 1 input value is specified, that input value can be directly assigned to the input in an execute request.

"x": 10

5. If the cardinality of an input is 1..N and M input values are specified, those inputs values are assgined using an array in an execute request.

"x": [10, 7, 15, 34, 5]

6. If the cardinality of the input is N..M (e.g. 2..5) then input values are assigned using an array in an execute request:

"x": [1,2]

I've only used simple integer values as examples here but any value type (string, object, array, binary, etc.) would be handled the same way. Also, I have only shown values being assinged by value but values assigned by reference would work the same ...

[Francis Charette-Migneault]

The expected (or mandated?) resolution between JSON schema-specific and OGC-specific keywords should be also detailed.

For example, schema could include minItems/maxItems for an array type.
In this case, it is not clear which attribute between minOccurs/minItems and maxOccurs/maxItems should prevail, or if inconsistencies should be refused by the server altogether.

When oneOf is employed in schema, this can become trickier because minOccurs/maxOccurs does not necessarily map to all elements of that oneOf that could have or not minItems/maxItems depending on their type, since minOccurs/maxOccurs have some meaning for single-values and multi-value simultanouesly, while minItems/maxItems are only for array.

There is also the issue of the maxOccurs: "unbounded" which is equivalent to omiting maxItems altogether. This one is usually tricky to understand by newcomers because maxOccurs must be provided to define a multi-value form, and maxItems can be provided similarly with the same value except for that special case.

In a similar fashion, a qualifiedInputValue can define format, which can contradict or extend contentMediaType and contentEnconding that could be used in schema.

I have done some mapping/description/examples of these use cases for our implementation. You can find more details/inspiration here: https://pavics-weaver.readthedocs.io/en/latest/package.html#inputs-outputs-openapi-schema

[Steve McDaniel]

I also want to understand better the relationship between minOccur and the "required" property in JSON Schema. Should we treat them independently or consult both to determine optional vs. required?
Doesn't minOccur of 0 mean the input is not required?

[Jerome St-Louis]

@gardengeek99 The minOccurs of 0 means that an input as a whole is not required.

The required in the JSONSchema can be used to specify that a property "inside" an individual input (which itself is a JSON object) is required or not.

[Benjamin Pross]

SWG meeting from 2024-08-05: We think this can be closed. See #434.