Skip to content

Add OpenAPI 3.1 paired-fixture test harness (Phase 0) - #961

Open
Inf1mum wants to merge 1 commit into
OpenAPITools:masterfrom
Inf1mum:feat/948-phase0-harness
Open

Inf1mum wants to merge 1 commit into
OpenAPITools:masterfrom
Inf1mum:feat/948-phase0-harness

Conversation

@Inf1mum

@Inf1mum Inf1mum commented Nov 16, 2026 •

Copy link
Copy Markdown

Fixes #948

What this provides

Phase 0: the test setup every later phase of the Stage 1 plan builds on. A fixture convention plus a harness that keeps the "same change, same verdict in every version" contract visible while the engine grows 3.1 support.

The harness (Oas31PairedFixturesTest) does three things:

  1. Pins the 3.0 baseline. A parameterized test asserts the documented 3.0->3.0 verdict per rule, so the stage goal "verdicts for 3.0 specs stay unchanged" is guarded from day one.
  2. Checks the Swagger 2.0 pair against the 3.0 verdict of the same rule (both go through the 3.0-shaped model today).
  3. Holds the not-yet-working parts of the contract as disabled tests, each naming the phase that fixes it, so the build stays green and each phase un-disables its own tests when it lands.

Fixture inventory

core/src/test/resources/oas31/<rule>/ with old-3.0.yaml, new-3.0.yaml, old-3.1.yaml, new-3.1.yaml - the same minimal document written in both syntaxes, one change per pair:

Rule Change 3.0 vs 3.1 spelling 3.0 verdict
type-change property weight integer -> string scalar type in both incompatible
nullable property notes becomes nullable nullable: true vs type: [string, "null"] compatible
exclusive-bounds request minimum becomes exclusive boolean exclusiveMinimum: true vs numeric exclusiveMinimum: 0 incompatible
array-items items of an array string -> integer type: array + items in both incompatible
all-of property type change inside an allOf member allOf of refs in both incompatible
one-of property type change inside a oneOf member oneOf of refs in both incompatible
swagger2 the type-change rule in Swagger 2.0 definitions + swagger: "2.0" incompatible (2.0->2.0)

Known 3.1 gaps (disabled, with the phase that fixes each)

Same-version comparisons (3.1->3.1 must agree with 3.0->3.0) - all fixed by Phase 2, the engine reading 3.1 fields [#950]:

Cross-version comparisons and the written equivalence - fixed by Phase 3, converter wired in [#951]:

Fixture discipline follows the pattern used in #938: one rule per directory, minimal single-operation documents, and every comparison executable in isolation.


Summary by cubic

Adds the paired-fixture test harness that Phase 0 of the OpenAPI 3.1 support plan (#948) builds on. For six rules, the same minimal change is expressed as a 3.0 pair and a 3.1 pair under core/src/test/resources/oas31/<rule>/; the harness pins the documented 3.0→3.0 verdict, checks that a Swagger 2.0 pair for the type-change rule matches it, and keeps the comparisons that fail on today's engine as disabled tests so the build stays green.

Known gaps (disabled, with the phase that fixes each)

Written for commit 3382b3e. Summary will update on new commits.

View guided diff

Phase 0 of the OpenAPI 3.1 plan: the test setup every later phase uses.

Fixture convention under core/src/test/resources/oas31/<rule>/: the same
minimal document as old-3.0.yaml/new-3.0.yaml and old-3.1.yaml/new-3.1.yaml
so the same change is expressed in 3.0 and in 3.1 syntax. First fixtures:
type-change, nullable, exclusive-bounds, array-items, all-of, one-of, plus
one Swagger 2.0 pair.

Oas31PairedFixturesTest pins the documented 3.0->3.0 verdict per rule,
checks the Swagger 2.0 pair matches the 3.0 verdict, and keeps the parts
of the harness contract that fail on today's engine as disabled tests,
each naming the phase that fixes it:
- 3.1->3.1 verdict agreement: Phase 2 (OpenAPITools#950), engine reads 3.1 fields
- 3.0->3.1 verdict agreement and the 3.0-vs-3.1 written equivalence:
  Phase 3 (OpenAPITools#951), converter wired in

Fixes OpenAPITools#948

Signed-off-by: Inf1mum <[email protected]>

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

2 issues found across 27 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="core/src/test/resources/oas31/one-of/new-3.0.yaml">

<violation number="1" location="core/src/test/resources/oas31/one-of/new-3.0.yaml:37">
P2: This `one-of` pair does not change any `oneOf` member: the only edit is `doodad_prop1` going from `string` to `integer`, which is a type change. The pinned INCOMPATIBLE verdict would therefore still pass if oneOf comparison broke. Remove or add a member in `WidgetCreateRequest`'s `oneOf` (for example drop `Gadget`, which is a request oneOf decrease) so the fixture exercises the rule it is named for, and keep the 3.1 pair in sync.</violation>
</file>

<file name="core/src/test/resources/oas31/one-of/old-3.0.yaml">

<violation number="1" location="core/src/test/resources/oas31/one-of/old-3.0.yaml:24">
P2: This `type: object` sits next to `oneOf` only in the 3.0 pair, while old-3.1.yaml drops it. That breaks the fixture convention that 3.0 and 3.1 files hold the same document. Remove this line here and the matching one in new-3.0.yaml, or add the line to the 3.1 files. Otherwise the Phase 3 `writtenVersionsAgree` check for `one-of` can fail for a reason unrelated to version spelling.</violation>
</file>

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

View guided diff | Re-trigger cubic

type: object
properties:
doodad_prop1:
type: integer

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2: This one-of pair does not change any oneOf member: the only edit is doodad_prop1 going from string to integer, which is a type change. The pinned INCOMPATIBLE verdict would therefore still pass if oneOf comparison broke. Remove or add a member in WidgetCreateRequest's oneOf (for example drop Gadget, which is a request oneOf decrease) so the fixture exercises the rule it is named for, and keep the 3.1 pair in sync.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. 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. At core/src/test/resources/oas31/one-of/new-3.0.yaml, line 37:

<comment>This `one-of` pair does not change any `oneOf` member: the only edit is `doodad_prop1` going from `string` to `integer`, which is a type change. The pinned INCOMPATIBLE verdict would therefore still pass if oneOf comparison broke. Remove or add a member in `WidgetCreateRequest`'s `oneOf` (for example drop `Gadget`, which is a request oneOf decrease) so the fixture exercises the rule it is named for, and keep the 3.1 pair in sync.</comment>

<file context>
@@ -0,0 +1,42 @@
+      type: object
+      properties:
+        doodad_prop1:
+          type: integer
+    Gadget:
+      type: object
</file context>

components:
schemas:
WidgetCreateRequest:
type: object

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2: This type: object sits next to oneOf only in the 3.0 pair, while old-3.1.yaml drops it. That breaks the fixture convention that 3.0 and 3.1 files hold the same document. Remove this line here and the matching one in new-3.0.yaml, or add the line to the 3.1 files. Otherwise the Phase 3 writtenVersionsAgree check for one-of can fail for a reason unrelated to version spelling.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. 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. At core/src/test/resources/oas31/one-of/old-3.0.yaml, line 24:

<comment>This `type: object` sits next to `oneOf` only in the 3.0 pair, while old-3.1.yaml drops it. That breaks the fixture convention that 3.0 and 3.1 files hold the same document. Remove this line here and the matching one in new-3.0.yaml, or add the line to the 3.1 files. Otherwise the Phase 3 `writtenVersionsAgree` check for `one-of` can fail for a reason unrelated to version spelling.</comment>

<file context>
@@ -0,0 +1,42 @@
+components:
+  schemas:
+    WidgetCreateRequest:
+      type: object
+      oneOf:
+        - $ref: "#/components/schemas/Doodad"
</file context>

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.

[OpenAPI 3.1] Phase 0: test harness for paired 3.0/3.1 fixtures

1 participant