schema-discriminator-defined

Since 0.0.1 · fixed by --fix · In the rulesets: Recommended at warning, Strict at error, All at error

This rule checks that every schema with oneOf has a discriminator.

Rule details

Without a discriminator, a tool that reads a value against oneOf validates it against every alternative and keeps the one that matches, which is slow, which fails when two alternatives match, and which generated code in most languages cannot do at all. With discriminator, one property names the alternative, and a generated client deserializes into the right type.

The rule reports Schema with oneOf clause does not have a discriminator.

Examples

Good. petType names the alternative.

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
      oneOf:
        - $ref: "#/components/schemas/Cat"
        - $ref: "#/components/schemas/Dog"

Bad. Whether a pet is a cat or a dog is found by trial.

components:
  schemas:
    Pet:
      type: object
      oneOf:
        - $ref: "#/components/schemas/Cat"
        - $ref: "#/components/schemas/Dog"

Automatic fixes

--fix adds discriminator.propertyName when every alternative of the oneOf has one property in common with a distinct const value in each. Every other case stays for you to decide.

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.

commands:
  lint:
    rules:
      schema-discriminator-defined: off
Was this helpful?