Open API 3.1 Conditional Schemas

[manstis]

Will there be support to define conditional schemas?

The OpenAPI 3.1 Specification suggests

"For more information about the properties, see JSON Schema Core and JSON Schema Validation."

https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-10.2.2

Both referenced documents cover dependencies and/or dependentSchemas.

The older Open API 3.0.x Specification implicitly states conditional schemas are unsupported.

"Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported".

No such comment is made for 3.1 so it could be assumed they are supported.

It is useful for consumers of Open API when used, for example, to generate User input forms programmatically.

[Azquelt]

At the moment, I think we have to support everything from the OpenAPI 3.1 spec, which would include both dependentSchemas and dependentRequired, but how much support we provide is may vary.

I think at a minimum we would want to allow:

• loading these properties from a static openapi.yaml
• including these properties in our model, so that they can be set using an OASModelReader or OASFilter

However, we could also add new annotations or add to existing ones.

@manstis Did you have any examples of what you'd want to be able to do in your code to add these properties to the final OpenAPI document?

[manstis]

Hi @Azquelt I forget the exact details other than some notes I captured at the time:

OpenAPI for Backstage Templates

• The generated OpenAPI definition is used to define the parameters for Backstage’s Templates. The parameter (map) entries > are used to generate the input form presented to Users to capture the parameters to execute the workflow (and > dataInputSchema generation, see below).
• Backstage uses react-jsonschema-form that supports a concept > called dependencies to dynamically alter > the form definition. This is not supported in OpenAPI and hence this feature is missing from the SWF PoC. dependencies is only support in OpenAPI 3.1
• SmallRye 3.1 does not support Conditional Schemas.
• See https://github.com/eclipse/microprofile-open-api/issues/567

The issue was that a library is being used to generate forms from JSON schemas. If the JSON schemas defined dependencies (on other schemas) they failed to be recognised and the generated forms incomplete.

I've moved onto other projects now; but can try to answer any questions you have ongoing.

[Azquelt]

Ok, so checking through what was written above, my understanding is:

• Backstage can create dynamic forms based on the dependencies property (which was in an earlier JSON Schema draft)
• This function isn't usable in MP OpenAPI 3.1 because there's no way to add this dependencies property

In #584 , we've made several changes which I think address this:

• the dependentRequired property can be set using either annotations or the model API (i.e. with OASModelReader, static openapi.yaml file or OASFilter)
  • this is the mechanism for requiring fields based on the presence of other fields which is available in the 2020-12 JSON Schema draft
  • this would not help with the Backstage issue described in this issue, but is likely to help with future versions or other frameworks
  • other properties for conditionally applying schemas in JSON Schema 2020-12 are also available via both annotations and the model API (if/then/else, dependentSchemas)
• the dependencies property can be set as a custom property using the model API
  • this would allow the generation of the schema required for Backstage
  • Example:

    schema.set("dependencies",
    Map.of("credit_card", List.of("billing_address"),
           "billing_address", List.of("credit_card"))
    );

Based on the above, I think the features being added in 4.0 are sufficient to close this issue, but do feel free to reopen if I've missed anything.