OpenAPI 3.0 treatment of enums

[opoudjis]

Enums with annotation are currently being output to JSONSchema as:

        oneOf:
        - const: "LEAInfo"
          title: LEAInfo
          ...

This is valid JSON Schema, but not valid OpenAPI 3.0.x JSON Schema: const is not recognised in its subset of JSON Schema. Until we can adopt OpenAPI 3.1.0, which complies with full JSON Schema, we need to change this to:

        oneOf:
        - enum: ["LEAInfo"]
          title: LEAInfo
          ...

Impact:

Error :: spec rule :: Propertyconstis not expected here.: 9589

This accounts for 9589 of the 11398 errors reported by Redocly.

[opoudjis]

Very pleasant surprise:

 <!-- JSON Schema for OpenAPI doesn't (currently) support 'const' as synonym for singleton 'enum' array -->
                <xsl:choose>
                        <xsl:when test="$strictJSON eq 'true'">
                                <xsl:value-of select="concat($indent, '- enum: [ ', $q, specgen:Code, $q, ' ]&#x0a;')"/>
                        </xsl:when>
                        <xsl:otherwise>
                                <xsl:value-of select="concat($indent, '- const: ', $q, specgen:Code, $q, '&#x0a;')"/>
                        </xsl:otherwise>
                </xsl:choose>

Which means that the initial implementation had foreseen this issue, and we need to turn strictJSON (i.e., misleadingly, strict compatibility with OpenAPI 3.0 rather than with JSON Schema) on; we will enable it when we move across to OpenAPI 3.1.

[opoudjis]

I see now that dmToJsonSchemaCreate.xsl and dmToJsonSchemaCreateStrict.xsl differ in turning strictJSON off or on.

This is otiose. If there is going to be an upgrade to OpenAPI 3.1, it will be labelled as such, and until then, we will only generate one version of the schemas.

So I will be using only dmToJsonSchemaCreate.xsl and dmToJsonSchemaUpdate.xsl, and go back to the other versions with OpenAPI 3.1. And again, JSON Schema versioning according to OpenAPI version will be handled more obviously.