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:
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?discriminator
, and this field is used in some other tools?What I have tried so far:
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.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
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.