Recommended use of discriminator, oneOf, inheritance

[pvdbosch]

We're regularly encountering errors when oneOf or discriminators are being used.

• OpenAPI document authors sometimes mistakenly assume that the oneOf subschema types are part of the JSON message; and that it can easily be retrieved as a data element by applications interacting with the API.
• oneOf with object-type subschemas and discriminator property should work
  • this generates inheritance with type info annotations to deserialization can be done to the correct generated child class
  • we may recommend always use "mapping", and against serializing the schema names (they're also not lowerCamelCase so invalid wrt [cod-design]
  • for "any-type" lists, like "embedded", this could become difficult though
• oneOf with object-type subschemas without a discriminator is not deserializable
  • it's missing type info annotations needed to determine child class, but to be tested if inherited classes actually get generated in this case
• oneOf with simple, non-object types, leads to code generation problems
  • recommend to either replace by single combined schema w/o oneOf, or use explicit separate properties
• oneOf with subschemas that only define "required" properties can be a good alternative, like used for BelgianRemittanceInformation
  • this generates a flat class structure. The allowed combinations of properties isn't visible in generated classes, but can still be validated if validating the exchanged messages against the schema in the OpenAPI document

[pvdbosch]

Confirmed that oneOf with simple types gives bad code generation results, for instance:

  BelgianRemittanceInformationOneOfTwoStrings:
      oneOf:
        - description: Unstructured Remittance Information as supported by Belgian banks
          type: string
          maxLength: 140
        - description: Structured Remittance Information in the Belgian OGM-VCS format. Often formatted for display as +++ 3 digits / 4 digits / 5 digits / +++.
          type: string
          pattern: "^\\d{12}$"
          example: "010806817183"

generates:

public interface BelgianRemittanceInformationOneOfTwoStrings {
}

without any subclasses of this empty interface. Tested using openapi-generator 7.5.0, same behavior when using referenced subschemas instead of inline ones.

[pvdbosch]

Tested oneOf with object-type subschemas without discriminator in Java. It doesn't seem to work as desired:

• inheritance is generated, but the base interface doesn't have any common properties
• subclasses are missing @JsonTypeInfo, to jackson can't determine subtype to use when deserializing

    BelgianRemittanceInformationOneOfTwoObjects:
      type: object
      properties:
        variant:
          type: string
          enum:
            - variantA
            - variantB
      oneOf:
        - $ref: "#/components/schemas/BelgianRemittanceInformationUnstructuredObject"
        - $ref: "#/components/schemas/BelgianRemittanceInformationStructuredObject"
    BelgianRemittanceInformationStructuredObject:
      type: object
      properties:
        structured:
          $ref: "#/components/schemas/BelgianRemittanceInformationStructured"
    BelgianRemittanceInformationUnstructuredObject:
      type: object
      properties:
        unstructured:
          $ref: "#/components/schemas/BelgianRemittanceInformationUnstructured"

warning: 'oneOf' is intended to include only the additional optional OAS extension discriminator object. For more details, see https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.9.2.1.3 and the OAS section on 'Composition and Inheritance'.

generated Java code:

• empty BelgianRemittanceInformationOneOfTwoObjects interface
• BelgianRemittanceInformationStructuredObject and BelgianRemittanceInformationUnstructuredObject subclasses with all properties, including the "variant" property