Add support for discriminator capability in response payloads

[darrelmiller]

This would allow representation of heterogenous collections. Details to follow,

[baywet]

@darrelmiller this is one of the last issues on the 1.0.10 roadmap, could you please provide the technical details so we can implement this as part of the conversion process?

[RabebOthmani]

Examples can be found here https://github.com/microsoft/kiota/pull/1014/files
@darrelmiller if you could please add more details on this tickets and some of the constraints we need to be paying attention to during the implementation. Thanks

[darrelmiller]

The following example demonstrates how to define a discriminator property in a JSON Schema without needing to use the discriminator keyword. The property is defined as an enum with just a single allowed value. This is effectively the same as a const keyword that is supported in later versions of JSON Schema and OpenAPI 3.1.

The discriminator keyword is an OpenAPI invention and is not a standard JSON Schema keyword. Therefore it is better to define the discriminator behavior with native JSON Schema keywords.

The challenge for kiota is that it will need to identify that the type of object that needs to be instantiated is based on a property that has an enum constraint with a single value. We can solve with a Microsoft Graph core because we know what the discriminator is called, but to solve this generically, will require a little more creativity.

openapi: 3.0.3
info:
  title: Collection filtered by query parameter
  version: 1.0.0
servers:
  - url: https://example.org/
paths:
  /sessions:
    get: 
      parameters:
        - name: location
          in: query
          required: false
          schema:
            type: string
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                type: array
                item:
                  $ref: "#/components/schemas/session"
components:
  schemas:
    entity:
      type: object
      properties:
        id: 
          type: string
    session:
      allof:
        - $ref: "#/components/schemas/entity"
      type: object
      properties: 
        '@OData.Type': 
          type: string
          enum:
           - session
        displayName: 
          type: string
        location:
          type: string
    workshop:
      allof:
        - $ref: "#/components/schemas/session"
      type: object
      properties: 
        '@OData.Type': 
          type: string
          enum:
           - workshop
        requiredEquipment: 
          type: string
    presentation:
      allof:
        - $ref: "#/components/schemas/session"
      type: object
      properties: 
        '@OData.Type': 
          type: string
          enum:
           - presentation
        recorded: 
          type: boolean

Additionally, we should check for the DerivedTypeConstraint annotation to determine if we should present the response schema as a oneOf. e.g.

      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                type: array
                item:
                  oneOf:
                    - $ref: "#/components/schemas/session"
                    - $ref: "#/components/schemas/workshop"
                    - $ref: "#/components/schemas/presentation"

[baywet]

so if I understand things property because the properties OData.Type are of type enum and because the enum values match a component name, they are discriminators? Also because there is inheritance between the components.

Shouldn't we wait for openapi.net to implement 3.1 so we can use the const keywork instead?

Also, as you mentioned, this description doesn't describe how to parse the discriminator from the API, would some x-ms extension on the document with some kind of templating be helpful?

e.g x-ms-discriminator-template: #microsoft.graph.{const}

[darrelmiller]

, they are discriminators?

They implicitly work as discriminators

Shouldn't we wait for openapi.net to implement 3.1 so we can use the const keywork instead?

We want Kiota to still work for OpenAPI 3.0. Most people have not migrated to 3.1 yet. Graph could use 3.1 once we support it.

this description doesn't describe how to parse the discriminator from the API,

I think we can infer the discriminator from the OpenAPI description. If we needed to be explicit, we can use the OpenAPI discriminator keyword.

[baywet]

Can you expand on why the example you provided doesn't include the discriminator keyword since it's part of 3.0?

[irvinesunday]

What's the difference between this approach and using the x-ms-discriminator-value extension we already use in the generated OpenAPI doc.?
e.g.:

[baywet]

with this extension, how do you know which field is the discriminator? (i.e. Odata.type)

[irvinesunday]

with this extension, how do you know which field is the discriminator? (i.e. Odata.type)

Actually that's what I'm scratching my head around too.
@darrelmiller ?