Validate that the license url and identifier are not both set

IN
18h ago
+240-0

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