Skip to content

Validate that the license url and identifier are not both set - #813

Open
Inf1mum wants to merge 2 commits into
OpenAPITools:masterfrom
Inf1mum:fix/92-license-url-identifier
Open

Inf1mum wants to merge 2 commits into
OpenAPITools:masterfrom
Inf1mum:fix/92-license-url-identifier

Conversation

@Inf1mum

@Inf1mum Inf1mum commented Nov 15, 2026 •

Copy link
Copy Markdown

What

The identifier field of the license object was introduced by OpenAPI 3.1.0, where it is mutually exclusive of the url field (an SPDX license expression and a license URL cannot both be declared). The validator now reports a license declaring both when the info license validation is enabled (default):

*ERROR* Section: APIInfo: 'url|identifier' in license -> The license url and identifier are mutually exclusive, only one of them should be set

A license declaring only one of the two fields is not affected, and neither are licenses validated against OAS 3.0 (where identifier cannot appear).

Why

The specification states that the identifier field is mutually exclusive of the url field, but the validator had no awareness of it (#92), so a specification declaring both passed validation silently.

How

  • the check lives in the existing license validation of validateInfo(), right after the name|url minimum check - no new option, since flagging it is never noisy: a license declaring both is invalid in every case
  • one caveat drove the implementation: the MicroProfile OpenAPI API the library is built against (3.1) declares no identifier accessor on the license model, and the CLI, Gradle and Maven plugins convert parsed specifications through empoa-swagger-core, whose license wrapper (SwLicense) keeps the swagger model - which does carry identifier - behind its getSw() accessor. The identifier is therefore read reflectively: first through getIdentifier() when the model provides it (e.g. a MicroProfile OpenAPI 4.0 implementation), then through the swagger model behind an empoa wrapper, and no identifier is reported when neither is available. Once the MicroProfile OpenAPI dependency is aligned with OAS 3.1 (#798), the first lookup handles it directly
  • end-to-end note: the swagger-parser itself only carries license.identifier for licenses declaring no url - a license declaring both is already rejected by the parser as an unexpected attribute (in its own parse messages, which the CLI does not surface) before the validator sees it. So for file-based usage the parser reports the problem first; the new check covers model-based usage of the lib today and file-based usage if the parser ever models both fields
  • 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 (as noted in Validate that object schemas declare additionalProperties #812)

Tests

lib module (plain @Test):

  • url only -> clean
  • identifier only -> clean, through both a model exposing getIdentifier() (the way an OAS 3.1-aware model, e.g. MicroProfile OpenAPI 4.0, does) and a wrapper hiding it behind getSw() (the empoa-swagger-core contract)
  • both set -> flagged with the exact message, again through both lookup paths
  • ErrorAggregatorTest covers the new aggregator method

cli module (end-to-end):

  • a 3.1 spec using identifier alone passes validation with the default options, which exercises the real parse -> empoa conversion -> reflective read chain

./gradlew build is green with JDK 17.


Summary by cubic

Reports an error when an OpenAPI 3.1 license sets both url and identifier; either field alone remains valid. The check runs when info-license validation is enabled, which is the default.

  • Reads identifier reflectively because the model and wrapper APIs do not expose it directly.
  • For file-based input, swagger-parser generally rejects both fields before the validator sees them, so this mainly covers model-based usage.

Written for commit 14ec313. Summary will update on new commits.

View guided diff

What: the license object of an OpenAPI 3.1.0 document must not declare
both url and identifier: an SPDX license expression and a license URL
are mutually exclusive. A license declaring both is now reported when
the info license validation is enabled (default): *ERROR* Section:
APIInfo: 'url|identifier' in license -> The license url and identifier
are mutually exclusive, only one of them should be set

Why: the identifier field was introduced by OpenAPI 3.1.0 and the
specification states that it is mutually exclusive of the url field,
but the validator had no awareness of it (OpenAPITools#92).

How: the check lives in the existing license validation of
validateInfo(). The MicroProfile OpenAPI API the library is built
against (3.1) declares no identifier accessor, and the CLI, Gradle and
Maven plugins convert parsed specifications through empoa-swagger-core,
whose license wrapper keeps the swagger model - carrying identifier -
behind its getSw() accessor. The identifier is therefore read
reflectively, first through getIdentifier() when the model provides it
(e.g. MicroProfile OpenAPI 4.0), then through the swagger model behind
an empoa wrapper, and no identifier is reported when neither is
available. Note that the swagger-parser itself only carries
license.identifier for licenses declaring no url: a license declaring
both is rejected by the parser before the validator sees it, so
file-based usage relies on the parser message until the parser models
both fields. 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#92

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 8 files

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

View guided diff | Re-trigger cubic

Comment thread README.md Resolved
… url and identifier

What: rewords the README bullet for the license url/identifier check from
"only one of them should be set", which reads as one of the two being
required, to "at most one of them may be set", matching what the check
enforces: it reports a license declaring both fields, and a license
declaring either one alone is fine.

Why: addresses the review note on PR OpenAPITools#813.

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.

1 participant