"discriminator" in polymorphism, OpenAPI 2.0 (Swagger 2.0)

Question

Referencing OpenAPI 2.0, Schema Object, or Swagger 2.0, Schema Object, and the definition of discriminator field as:

Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the required property list. When used, the value MUST be the name of this schema or any schema that inherits it.

My confusions/ questions:

It is ambiguous to me, what role exactly it plays in inheritance or polymorphism. Could some one please explain discriminator with a working example showing what it exactly does and what if we do not use it? Any errors, warnings or any tools that depends on it for some operations?
Is it the case that swagger-editor does not support discriminator, and this field is used in some other tools?

What I have tried so far:

I have tried to use swagger-editor and the example from the same documentation (also mentioned below), to play around with this property to see if I can see any of its special behaviors. I changed the property, removed it, and extend the Dog model to one level deeper and tried the same on the new sub-model, but I did not see any changes in the preview of swagger-editor.
I tried searching online, and specially stackoverflow questions, but did not find any relevant information.

The sample code I used to do experiments:

definitions:
  Pet:
    type: object
    discriminator: petType
    properties:
      name:
        type: string
      petType:
        type: string
    required:
    - name
    - petType
  Cat:
    description: A representation of a cat
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        huntingSkill:
          type: string
          description: The measured skill for hunting
          default: lazy
          enum:
          - clueless
          - lazy
          - adventurous
          - aggressive
      required:
      - huntingSkill
  Dog:
    description: A representation of a dog
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
      - packSize

score 14 · Accepted Answer · edited Apr 17 '18 at 13:16

14

According to this google group, discriminator is used on top of the allOf property and it is defined in the super type for polymorphism. If discriminator is not used, the allOf keyword describes that a model contains the properties of other models for composition.

Just like in your sample code, Pet is a super type with property of petType identified as the discriminator and Cat is a sub type of Pet. Following is a json example of a Cat object:

{
  "petType": "Cat",
  "name": "‎Kitty"
}

The use of discriminator intends to indicate the property used to identify the type of an object. Assumes that there are tools that can proper support definition objects with the use of discriminator, it is possible to determine the type by scanning the property. For example, identify the object is a Cat according to petType.

However, the discriminator field is not well defined in the current version's specification or the samples (see issue #403). As far as I know, there is no tools provided by Swagger properly support it at the time being.

discriminator may be used if the model has a property used to determine the type. In this case, it is naturally fit and it can be used as an indicator for other developers understand the polymorphism relationship. If third party tools like ReDoc which support discriminator (see petType in this gif and example) is considered, you may find this useful.

edited Apr 17 '18 at 13:16

erip

16,374
11
66
121

answered Sep 27 '16 at 16:52

Wilson

11,339
2
29
33

3

When no tools support `discriminator`, that means there is no point in using it then. – Musa Haidari Sep 27 '16 at 18:49
2

It can be used if your schema has a property used to identify the type. In such a case, `discriminator` is naturally fit and can help other developers understand the polymorphism relationship. If you use a third party tool like [ReDoc](https://github.com/Rebilly/ReDoc) that support `discriminator`, it may be useful. – Wilson Sep 28 '16 at 01:35
5

@wilson @musa. ReDoc author here. What I can add is that `discriminator` is really hard to work with from the point of tool-author. Frankly speaking, I can't recall other tools than ReDoc that take any use of discriminator :( Here is link to gif of how discriminator is used in ReDoc: https://github.com/Rebilly/ReDoc/raw/master/docs/images/discriminator-demo.gif. @Wilson you're welcome to attach it to your answer – RomanHotsiy Jan 31 '17 at 11:09
@RomanHotsiy Thank your for your notes and the link to the gif :) – Wilson Jan 31 '17 at 12:05
FYI: Im the author of http://nswag.org a swagger toolchain for .net. The lib supports discriminator in the spec and c#/typescript generators... – Rico Suter Aug 06 '17 at 07:46

score 9 · Answer 2 · edited Jan 10 '22 at 13:56

The discriminator functionality has been much improved in OpenApi 3. You now provide a discriminator object which contains the name of the discriminator property, as well as a mapping of values of that property to schema names.

(I realize you did ask about OpenApi 2, but this is so much improved in 3 that hopefully you can make use of it).

See: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminatorObject for the v3.0.0 spec

"discriminator" in polymorphism, OpenAPI 2.0 (Swagger 2.0)

2 Answers2

Linked