OpenAPI - $ref inside x-patternProperties is not recognised by schema generators

[mick-jones-vertiv]

When using the Redfish openapi.yaml to generate a SDK (or documentation) both openap-generator-cli and swagger-codegen-cli are unable to parse a $ref schema reference inside 'x-patternProperties'. Pattern properties is a JSON schema construct that is not supported in the superset openapi schema and the "x-patternProperties" is a workaround that the generators do not fully support or recognize. Refer: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#specification-extensions

As a result, the output of a generator looks like this snippet:

The reference is there, but it is not resolved and the target component schema is not included in the output. This breaks any generated code as the output schema is no longer compliant. The specification does not say that $ref is not supported, but the two most common generators have the same problem.

Here's what the snippet looks like in the published Redfish OpenAPI spec (Resource.yaml):

[mraineri]

Unfortunately OpenAPI doesn't support the "patternProperties" concept that JSON Schema has. There were some discussions about it a while ago, but I don't think anyone on the OpenAPI front is moving forward with that support.

Will need to spend some time thinking how to work around this in a manner that works well with OpenAPI tooling...

[mick-jones-vertiv]

Since Feb 2021 OAS v3.1 is out and it has full support for JSON Schema 2020-12 Draft. Refer to: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject.

I don't think we should work around it as such. Maybe publish the workaround I described and spend resources on upgrading to OAS 3.1 which removes the problem. Although the JSON Schema would also have to be upgraded to 2020-12.

Tooling for OAS 3.1 is starting to ramp up, but as of today the two biggest stacks (OpenAPI and Swagger) don't have support for it, only commercial tools. In other words there's time.

[mraineri]

Thanks for the info; I'll see if we really need to update our JSON Schema files to support 2020-12; if there's enough backwards compatibility, we might be able to keep them at the existing draft in the 8010 bundle and move our OpenAPI support to 3.1 (and swap out the usage of x-patternProperties.