suggested supplement to docs on polymorphism

[jehrlich]

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]

[frankkilcommins]

@jehrlich thanks for raising the issue.

We can look to add more recommendations in this area. Using const would likely be more appropriate to enforce a strict type value. The value itself must then match the payload value and as specified in the discriminator mapping rather than the schema name/URI.