Need to clarify the interaction between minOccurs, maxOccurs and schema in the input description.
pvretano opened this issue · comments
There needs to be some clarifying text and perhaps examples added to the specification to explain the interaction between minOccurs
, maxOccurs
and schema
.
Specifically,
- The schema is used to express the definition of a single instance of an input.
- The
minOccurs
andmaxOccurs
members indicate the cardinality of that input. - If the cardinality is 1 then an input value in an execute request can be assigned directly to the input
"x": 10
- 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
- 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]
- 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 ...
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
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?
@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.
SWG meeting from 2024-08-05: We think this can be closed. See #434.