Skip to content

feat: add OpenAPI 3.1 support#791

Open
reuvenharrison wants to merge 20 commits intomainfrom
feat/openapi-3.1-support
Open

feat: add OpenAPI 3.1 support#791
reuvenharrison wants to merge 20 commits intomainfrom
feat/openapi-3.1-support

Conversation

@reuvenharrison
Copy link
Copy Markdown
Collaborator

@reuvenharrison reuvenharrison commented Feb 5, 2026

Summary

Changes

Document Level

  • WebhooksDiff: Diff webhooks (new in OpenAPI 3.1)
  • JSONSchemaDialectDiff: Diff JSON Schema dialect specification

Info Object

  • SummaryDiff: Diff Info.Summary field (new in OpenAPI 3.1)

License Object

  • IdentifierDiff: Diff SPDX license identifiers (new in OpenAPI 3.1)

Schema Object (JSON Schema 2020-12)

Field Description
ConstDiff Constant value validation
ExamplesDiff Examples array (replaces singular example)
PrefixItemsDiff Tuple validation for arrays
ContainsDiff Array containment schema
MinContainsDiff Minimum contains count
MaxContainsDiff Maximum contains count
PatternPropertiesDiff Pattern-based property matching
DependentSchemasDiff Conditional schema dependencies
PropertyNamesDiff Property name validation
UnevaluatedItemsAllowedDiff Unevaluated items boolean (true/false)
UnevaluatedItemsDiff Unevaluated items schema
UnevaluatedPropertiesAllowedDiff Unevaluated properties boolean (true/false)
UnevaluatedPropertiesDiff Unevaluated properties schema
IfDiff Conditional if sub-schema
ThenDiff Conditional then sub-schema
ElseDiff Conditional else sub-schema
DependentRequiredDiff Dependent required properties
SchemaIDDiff $id keyword
AnchorDiff $anchor keyword
DynamicRefDiff $dynamicRef keyword
DynamicAnchorDiff $dynamicAnchor keyword
ContentMediaTypeDiff Content media type for string encoding
ContentEncodingDiff Content encoding for strings
ContentSchemaDiff Content schema for encoded strings
DefsDiff $defs schema definitions
SchemaDialectDiff $schema dialect keyword
CommentDiff $comment keyword

Dependency change

Switched from the oasdiff/kin-openapi fork to getkin/kin-openapi upstream (PR getkin/kin-openapi#1125). A temporary replace directive points to the PR branch commit; it will be removed once the PR merges and a release is cut.

Test plan

🤖 Generated with Claude Code

@reuvenharrison reuvenharrison force-pushed the feat/openapi-3.1-support branch from 92992de to 95dce83 Compare February 5, 2026 21:30
@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Feb 5, 2026

Codecov Report

❌ Patch coverage is 94.43879% with 164 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.49%. Comparing base (ee46712) to head (455bb6d).
⚠️ Report is 3 commits behind head on main.

Files with missing lines Patch % Lines
diff/schema_diff.go 54.71% 12 Missing and 12 partials ⚠️
checker/checks-utils.go 78.66% 8 Missing and 8 partials ⚠️
checker/check_request_property_content_updated.go 89.34% 11 Missing and 2 partials ⚠️
checker/check_response_property_content_updated.go 89.43% 11 Missing and 2 partials ⚠️
diff/value_diff.go 60.00% 5 Missing and 3 partials ⚠️
diff/dependent_required_diff.go 70.83% 4 Missing and 3 partials ⚠️
checker/check_response_property_max_increased.go 85.00% 3 Missing and 3 partials ⚠️
checker/check_response_property_min_decreased.go 85.00% 3 Missing and 3 partials ⚠️
checker/check_api_tag_updated.go 50.00% 2 Missing and 2 partials ⚠️
checker/check_request_parameters_type_changed.go 0.00% 2 Missing and 2 partials ⚠️
... and 26 more
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #791      +/-   ##
==========================================
+ Coverage   89.16%   90.49%   +1.33%     
==========================================
  Files         239      264      +25     
  Lines       12815    15650    +2835     
==========================================
+ Hits        11426    14163    +2737     
- Misses        926      957      +31     
- Partials      463      530      +67     
Flag Coverage Δ
unittests 90.49% <94.43%> (+1.33%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@reuvenharrison reuvenharrison force-pushed the feat/openapi-3.1-support branch from a9484af to d6f8063 Compare February 6, 2026 10:04
@reuvenharrison reuvenharrison force-pushed the feat/openapi-3.1-support branch 3 times, most recently from c034fe7 to d66fafa Compare March 15, 2026 21:26
@reuvenharrison reuvenharrison force-pushed the feat/openapi-3.1-support branch 2 times, most recently from e41e060 to b2216d6 Compare March 30, 2026 21:49
@reuvenharrison reuvenharrison force-pushed the feat/openapi-3.1-support branch 2 times, most recently from c7b8782 to 67038b7 Compare April 6, 2026 16:35
@reuvenharrison reuvenharrison force-pushed the feat/openapi-3.1-support branch from 760b550 to ef6d14d Compare April 13, 2026 19:48
reuvenharrison and others added 14 commits April 15, 2026 15:23
Squash-rebases the OpenAPI 3.1 support branch onto current main,
integrating the sunset date deprecation IDs added by PR #795.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…red checkers

Add tests for response body removed, property-level add/remove, and
body/property-level minContains/maxContains changes. Also adds a
containsId() helper to reduce test boilerplate.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace the getkin/kin-openapi replace directive with a direct dependency
on the oasdiff/kin-openapi feat/openapi-3.1-support-oasdiff branch, which
mirrors feat/openapi-3.1-support but declares module path
github.com/oasdiff/kin-openapi. This eliminates the module path mismatch
that caused go vet to fail on flatten/allof (undefined ExclusiveBound).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Picks up yaml/yaml3 v0.0.3 fixes for YAML anchor/alias handling.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds $schema/$defs support and additional 3.1 fixes.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Bumps github.com/oasdiff/kin-openapi to v0.137.0-openapi31.beta.8,
which adds OAS 3.1 support for sibling keywords alongside $ref
(e.g. deprecated:true). Removes the t.Skip from TestOAS31_RefSiblingKeyword
now that kin-openapi correctly honours the sibling and the test passes.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The rebase switched from getkin/kin-openapi to oasdiff/kin-openapi.
The prefix-matched restore-keys were restoring stale caches from
main-branch runs that contained getkin modules, causing build failures
for oasdiff/kin-openapi-only types like ExclusiveBound.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The rebase onto main brought in #842's migration to getkin/kin-openapi,
but the 3.1 branch requires oasdiff/kin-openapi for ExclusiveBound and
other 3.1-specific types. This replaces all remaining getkin imports and
sets IsExternalRefsAllowed in the external ref test.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds 37 new tests and 16 test data files covering the uncovered paths
in 3.1-specific checkers: body removed, property added, and property
removed for dependent_schemas, pattern_properties, prefix_items,
property_names, if/then/else, content, and min_decreased.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
… and utils

Adds 20 tests covering: exclusiveMin decreased / exclusiveMax increased
paths, 3.1-style type array nullable detection, property-level
dependentRequired changes, all interfaceToString branches, and 3.1
sub-schema traversal (if/then/else/contains/prefixItems/propertyNames/
unevaluatedItems/unevaluatedProperties/contentSchema/patternProperties/
dependentSchemas).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Depend directly on getkin/kin-openapi (PR #1125 branch) instead of the
oasdiff fork. This eliminates the fork sync step and resolves the
transitive module path mismatch that broke flatten/allof tests.

Also adds BoolSchema support for unevaluatedProperties/unevaluatedItems
diff (fixes #844).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@reuvenharrison reuvenharrison force-pushed the feat/openapi-3.1-support branch from fbd7ec6 to 96703dd Compare April 15, 2026 12:24
reuvenharrison and others added 2 commits April 15, 2026 15:29
Replace pseudo-version with proper tag for the kin-openapi fork.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Remove feature branches from Docker workflow triggers
- Only apply 'stable' tag for non-prerelease version tags

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@reuvenharrison reuvenharrison force-pushed the feat/openapi-3.1-support branch 2 times, most recently from 68474fa to fcedde1 Compare April 16, 2026 09:11
Picks up yaml3 v0.0.10 which tracks mapping-valued fields in origin,
fixing missing source locations for dependentRequired, patternProperties,
and dependentSchemas in changelog output.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@reuvenharrison reuvenharrison force-pushed the feat/openapi-3.1-support branch from fcedde1 to 790192d Compare April 16, 2026 12:10
reuvenharrison and others added 3 commits April 16, 2026 16:34
* refactor: replace ValueDiff with structured DependentRequiredDiff type

DependentRequired was diffed as an opaque ValueDiff, producing Go-native
formatting like map[name:[age]] in changelog messages. Replace with a
structured DependentRequiredDiff that tracks per-key Added/Deleted/Modified
entries, and update checkers to emit per-key human-readable messages.

Before: "dependentRequired changed from map[name:[age]] to map[name:[email]]"
After:  "dependentRequired for name was updated: email added, age removed"

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: point source locations to specific schema keys, not parent field

dependentSchemas and patternProperties checkers reported the source
location of the parent field key (e.g., line of `dependentSchemas:`)
instead of the specific schema key (e.g., line of `credit_card:`).

Add SchemaMapItemSource helper that looks up the individual schema's
own Origin, and use it for all added/deleted items in both checkers.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* style: fix alignment after go fmt

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: add make lint step to commit skill

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Translate 302 previously untranslated messages per locale covering
dependentRequired, exclusive-min/max, prefix-items, if/then/else,
min/max-contains, contains, property-names, unevaluated,
dependent-schema, pattern-property, content-encoding/media-type,
and contentSchema.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
For api-tag-added and api-tag-removed, use NewSourceFromSequenceItem
to report the exact line of the added/deleted tag value instead of
the `tags:` field key. Also set only baseSource for deletions and
only revisionSource for additions.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
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.

[3.1] Failed to unmarshal unevaluatedProperties: false (boolean form) OpenAPI 3.1 support?

2 participants