Skip to content

Validate that object schemas declare additionalProperties - #812

Open
Inf1mum wants to merge 2 commits into
OpenAPITools:masterfrom
Inf1mum:feat/741-additional-properties-rule
Open

Inf1mum wants to merge 2 commits into
OpenAPITools:masterfrom
Inf1mum:feat/741-additional-properties-rule

Conversation

@Inf1mum

@Inf1mum Inf1mum commented Nov 13, 2026 •

Copy link
Copy Markdown

What

This adds a new model rule, enabled by the validateModelAdditionalProperties option, that flags named schemas in components/schemas which are objects but do not declare additionalProperties - neither a boolean nor a schema.

A schema counts as an object when it says so explicitly (type: object) or when it declares properties (the type keyword is optional in that case). Schemas of other types, compositions that declare no properties of their own (e.g. an allOf used for inheritance) and empty properties maps are left alone.

The rule is opt-in, false by default: most existing specs do not declare additionalProperties on every object, so flagging them by default would be too noisy for a validator that enables everything else out of the box. Users who want the strictness can turn it on in their options file (CLI), Gradle extension or Maven configuration. A finding looks like:

*ERROR* in Model 'MyObject', field 'additionalProperties' -> An object schema should declare additionalProperties

Why

When additionalProperties is absent, whether an object accepts properties that are not listed in the spec is left to the implementation (see the Schema Object definition). Declaring the keyword makes the contract explicit - that is what #741 asks for.

How

  • new AdditionalPropertiesValidator in lib, invoked from validateModels() behind the new flag, in the same style as the discriminator rule
  • ModelStyleError.toString() now omits the property part when a finding concerns the schema itself rather than one of its properties (same hardening as Validate that oneOf and anyOf compositions define a discriminator #811 - model-level findings have no property name, and the old format printed property 'null')
  • the option is wired through ValidatorParameters, the CLI options file, the Gradle plugin task and the Maven plugin mojo, with the default documented in the README options table and in the sample specs/options.json
  • unit tests cover the flagged case (explicit and inferred objects, with the expected message), the clean cases (keyword declared as true, false or as a schema) and the opt-in behavior (no violation with default parameters, none when the rule is disabled)

The wiring follows #809, #810 and #811 as precedent.

One implementation note: the new tests use plain @Test methods on purpose. junit-jupiter-params is declared testCompileOnly in the root build.gradle, so @ParameterizedTest methods compile but are silently skipped at runtime (this affects the existing parameterized tests too - happy to see that fixed in a separate change).

The full suite (./gradlew build, including the Gradle plugin functional tests and the Maven plugin integration test) is green.

Fixes #741


Summary by cubic

Adds an opt-in model rule that flags named object schemas in components/schemas which do not declare additionalProperties. The rule is off by default (validateModelAdditionalProperties: false) because most existing specs omit the keyword; when the keyword is absent, whether an object accepts properties outside the spec is left to the implementation. Enable it via the CLI options file, Gradle task, or Maven mojo to make object contracts explicit.

  • A schema counts as an object when it declares type: object (even with no properties) or when it declares properties without a type; other types, compositions without properties of their own, and inferred objects with empty properties maps are ignored.
  • Declaring additionalProperties as a boolean or a schema satisfies the rule.
  • Model-level findings no longer print property 'null' in the error message.
  • Wires the new option through ValidatorParameters, the CLI, the Gradle plugin, and the Maven plugin.

Fixes #741.

Written for commit 77b4c80. Summary will update on new commits.

View guided diff

What: adds the validateModelAdditionalProperties option (default: false):
a named schema in components/schemas that is an object - either
explicitly (type: object) or inferred from declared properties - should
declare additionalProperties, as either a boolean or a schema. Schemas
of other types, compositions without properties of their own (e.g. an
allOf used for inheritance) and empty properties maps are not affected.

Why: when additionalProperties is absent, whether an object accepts
properties outside of the spec is left to the implementation, so models
can silently accept undocumented properties (OpenAPITools#741). The rule is opt-in
because most existing specs do not declare the keyword on every object,
so flagging them by default would be too noisy.

How: new AdditionalPropertiesValidator (lib) invoked from validateModels()
behind the new flag; ModelStyleError.toString() omits the property part
when a finding concerns the schema itself rather than one of its
properties (same hardening as PR OpenAPITools#811); option wired through
ValidatorParameters, the CLI options file, the Gradle plugin task and the
Maven plugin mojo; README options table and sample specs/options.json
updated. Tests use plain @test methods: junit-jupiter-params is declared
testCompileOnly in the root build.gradle, so @ParameterizedTest methods
compile but are silently skipped at runtime.

Fixes OpenAPITools#741

Signed-off-by: Inf1mum <vadimlazuk5@gmail.com>

@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.

All reported issues were addressed across 17 files

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

View guided diff | Re-trigger cubic

… objects with no properties

What: testAllGetterSetters now sets validateModelAdditionalProperties to
true and asserts it - the false it assigned before was already the value
provided by the factory, so the setter was never exercised with a state
change. Adds a case for an explicit `type: object` with an empty
properties map: the declared type makes it an object, so it is reported
like any other object without additionalProperties. Only the inferred
path (no `type` keyword) needs a non-empty properties map to count as
an object.

Why: addresses the two review notes on PR OpenAPITools#812.

Signed-off-by: Inf1mum <vadimlazuk5@gmail.com>

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.

Add checking for additionalProperties in object definitions

1 participant