Skip to content

Validate that oneOf and anyOf compositions define a discriminator - #811

Open
Inf1mum wants to merge 2 commits into
OpenAPITools:masterfrom
Inf1mum:fix/806-discriminator-rule
Open

Inf1mum wants to merge 2 commits into
OpenAPITools:masterfrom
Inf1mum:fix/806-discriminator-rule

Conversation

@Inf1mum

@Inf1mum Inf1mum commented Nov 10, 2026 •

Copy link
Copy Markdown

What

Adds a new style rule for the concern raised in #806: a schema that composes alternative models with oneOf or anyOf should define a discriminator, so that API consumers can tell the possible object types apart (see the Swagger documentation on inheritance and polymorphism referenced in the issue).

Rule semantics

  • Every schema of components/schemas that declares a non-empty oneOf or anyOf and has no discriminator is reported:
    *ERROR* in Model 'MyComposition', field 'discriminator' -> A schema with a oneOf or anyOf composition should define a discriminator
  • The discriminator is considered defined when the composing schema carries a discriminator object, as documented by the Swagger reference (the discriminator lives on the schema that carries oneOf/anyOf).
  • allOf is out of scope: it describes a merged model rather than a set of alternatives, and the referenced documentation limits the use of the discriminator to oneOf and anyOf.
  • The check is limited to the named schemas of components/schemas, like the existing model rules; covering inline compositions (e.g. in responses) could be a follow-up.

Config

New option validateModelDiscriminator (boolean, default true), following the repo convention of enabling all rules by default:

  • documented in the README options table
  • wired through the gradle plugin task and the maven plugin mojo
  • usable in the CLI options file (parsed by name, like the other options)

Tests

  • testModelDiscriminatorValidation (parameterized): oneOf without a discriminator is reported when the rule is on and stays silent when the flag is off
  • testModelDiscriminatorValidationSuccessWhenDiscriminatorIsDefined: a oneOf schema with a discriminator produces no error
  • testModelDiscriminatorValidationReportsAnyOfComposition: anyOf compositions are covered too
  • testModelDiscriminatorValidationIgnoresAllOfComposition: allOf is not reported
  • ValidatorParametersTest covers the new default; ErrorAggregatorTest covers the new error; the CLI default.json fixture was updated accordingly

./gradlew spotlessApply test passes on all modules (lib, cli, gradle-plugin, maven-plugin).

Fixes #806


Summary by cubic

Adds a model validation rule that flags named schemas in components/schemas with a non-empty oneOf or anyOf composition that don't define a discriminator, so consumers can tell the possible object types apart.

New Features

  • New validateModelDiscriminator option (defaults to true) exposed through the CLI, Gradle, and Maven plugins.
  • Only named schemas in components/schemas are checked; inline and empty compositions are not reported.
  • allOf is ignored since it describes a merged model rather than a set of alternatives.

Written for commit d030edd. Summary will update on new commits.

View guided diff

Adds the validateModelDiscriminator option (default: true): a schema
with a oneOf or anyOf composition should define a discriminator so that
API consumers can tell the possible object types apart. allOf is out of
scope as it describes a merged model rather than a set of alternatives.

Fixes OpenAPITools#806

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

3 issues found across 16 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lib/src/test/java/org/openapitools/openapistylevalidator/OpenApiSpecStyleValidatorTest.java">

<violation number="1" location="lib/src/test/java/org/openapitools/openapistylevalidator/OpenApiSpecStyleValidatorTest.java:226">
P2: The new tests never verify that empty `oneOf` or `anyOf` lists are ignored. Add empty-list fixtures and assert zero errors to cover the rule’s explicit non-empty condition.</violation>

<violation number="2" location="lib/src/test/java/org/openapitools/openapistylevalidator/OpenApiSpecStyleValidatorTest.java:226">
P2: These fixtures do not test the documented inline-composition exclusion. Add an inline schema containing `oneOf` or `anyOf` and assert that validation reports no discriminator error.</violation>
</file>

<file name="README.md">

<violation number="1" location="README.md:119">
P3: This description overstates the rule: validation only covers named schemas in `components/schemas` with a non-empty `oneOf` or `anyOf`, not inline compositions. Clarify that scope so users do not expect inline schemas to be checked.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

Comment thread README.md Resolved
…r rule

- add fixtures asserting that an empty oneOf or anyOf list does not
  trigger the missing-discriminator error (an empty composition list
  declares nothing to discriminate)
- add a fixture asserting that a composition declared inline, inside a
  property of a named schema, is not reported: the rule is deliberately
  scoped to the named schemas of components/schemas
- qualify the README options-table row and the Models section
  accordingly

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Validate that oneOf/anyOf has a discriminator defined

1 participant