swagger.io icon indicating copy to clipboard operation
swagger.io copied to clipboard

suggested supplement to docs on polymorphism

Open jehrlich opened this issue 10 months ago • 0 comments

Documentation at https://swagger.io/docs/specification/v3_0/data-models/inheritance-and-polymorphism/ includes this text:

Mapping Type Names

It is implied, that the property to which discriminator refers, contains the name of the target schema. In the example above, the objectType property should contain either simpleObject, or complexObject string. If the property values do not match the schema names, you can map the values to the names. To do this, use the discriminator/mapping keyword:

It seems to me that the docs should point out that this can and should be enforced using enum: like this:

            simpleObject:
              type: object       
              required:
                - objectType       
              properties:
                objectType:
                  type: string
                  enum: [simpleObject]
            complexObject:
              type: object       
              required:
                - objectType       
              properties:
                objectType:
                  type: string
                  enum: [complexObject]

jehrlich avatar Feb 25 '25 14:02 jehrlich