feat: add OpenAPI 3.1 support by reuvenharrison · Pull Request #791 · oasdiff/oasdiff

reuvenharrison · 2026-02-05T21:28:46Z

Summary

Add full support for diffing OpenAPI 3.1 documents
Closes OpenAPI 3.1 support? #52

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
`UnevaluatedItemsDiff`	Unevaluated items schema
`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

Dependencies

This PR uses a replace directive in go.mod to point github.com/getkin/kin-openapi to the oasdiff/kin-openapi fork, which includes OpenAPI 3.1 support (getkin/kin-openapi#1125). The replace directive can be removed once that PR is merged and a new kin-openapi release is published.

Test plan

go build ./... passes
go test ./... passes (all 14 packages)
20 OpenAPI 3.1 diff tests covering all new fields
Tested with OpenAPI 3.1 documents containing webhooks

🤖 Generated with Claude Code

Add full support for diffing OpenAPI 3.1 documents including: Document level: - WebhooksDiff for OpenAPI 3.1 webhooks - JSONSchemaDialectDiff for JSON Schema dialect specification Info object: - SummaryDiff for Info.Summary field License object: - IdentifierDiff for SPDX license identifiers Schema object (JSON Schema 2020-12): - ConstDiff for const keyword - ExamplesDiff for examples array - PrefixItemsDiff for tuple validation - ContainsDiff, MinContainsDiff, MaxContainsDiff for array containment - PatternPropertiesDiff for pattern-based properties - DependentSchemasDiff for conditional schemas - PropertyNamesDiff for property name validation - UnevaluatedItemsDiff, UnevaluatedPropertiesDiff Closes #52 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

codecov-commenter · 2026-02-05T21:31:57Z

Codecov Report

❌ Patch coverage is 71.62907% with 566 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.14%. Comparing base (77d93e0) to head (e68684f).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
checker/checks-utils.go	25.33%	31 Missing and 25 partials ⚠️
...hecker/check_response_property_contains_updated.go	46.66%	32 Missing and 8 partials ⚠️
checker/check_request_property_contains_updated.go	48.64%	31 Missing and 7 partials ⚠️
...er/check_response_property_prefix_items_updated.go	47.82%	34 Missing and 2 partials ⚠️
checker/check_response_property_min_decreased.go	15.78%	31 Missing and 1 partial ⚠️
checker/check_request_property_max_updated.go	57.37%	22 Missing and 4 partials ⚠️
checker/check_request_property_min_updated.go	57.37%	23 Missing and 3 partials ⚠️
...ker/check_request_property_prefix_items_updated.go	63.23%	24 Missing and 1 partial ⚠️
diff/schema_diff.go	52.94%	12 Missing and 12 partials ⚠️
...ker/check_request_property_became_not_nuallable.go	54.16%	20 Missing and 2 partials ⚠️
... and 29 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #791      +/-   ##
==========================================
- Coverage   89.55%   87.14%   -2.41%     
==========================================
  Files         239      262      +23     
  Lines       12154    14057    +1903     
==========================================
+ Hits        10884    12250    +1366     
- Misses        840     1257     +417     
- Partials      430      550     +120

Flag	Coverage Δ
unittests	`87.14% <71.62%> (-2.41%)`	⬇️

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.

Add comprehensive tests for webhooks and new OpenAPI 3.1 / JSON Schema 2020-12 fields: - Webhook add/delete/modify tests - JSONSchemaDialect diff tests - Info.Summary diff tests - License.Identifier diff tests - Schema fields: const, examples, prefixItems, contains, minContains, maxContains, patternProperties, dependentSchemas, propertyNames, unevaluatedItems, unevaluatedProperties Coverage improvements: - webhooks_diff.go: 87.5-100% - schema_diff.go: 86.4-100% - info_diff.go: 81.2-100% - license_diff.go: 83.3-94.1% Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add additional tests for webhook diff functionality: - Test Empty() with populated but empty diff struct - Test webhooks only in base spec (deletion case) - Test webhooks only in revision spec (addition case) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

OpenAPI 3.1 changed exclusiveMinimum/exclusiveMaximum from boolean modifiers to numeric bound values. Updated oasdiff to work with the new ExclusiveBound type from kin-openapi that supports both formats. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add score property with exclusive bounds to Order schema in test data - Add test for ExclusiveMinDiff/ExclusiveMaxDiff with numeric values - Fix exclusiveBoundToValue to extract actual values from ExclusiveBound struct Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

The docker/metadata-action automatically converts slashes to dashes, so use its output for feature branch builds to avoid invalid tag errors. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Update replace directive to oasdiff/kin-openapi@1da4078 which includes: - JSON Schema 2020-12 identity keywords ($id, $anchor, $dynamicRef, $dynamicAnchor) - Content vocabulary (contentMediaType, contentEncoding, contentSchema) - Discriminator support for anyOf - jsonSchemaDialect validation - mutualTLS security scheme - License url/identifier mutual exclusivity - Paths optional in 3.1 - JSON Schema 2020-12 validation in openapi3filter Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Support diffing if/then/else, dependentRequired, $id, $anchor, $dynamicRef, $dynamicAnchor, contentMediaType, contentEncoding, and contentSchema fields added in kin-openapi's OpenAPI 3.1 support. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…omment Update kin-openapi dependency to latest OpenAPI 3.1 fixes (da004e9) which adds $defs, $schema, and $comment keywords. Add corresponding diff fields and tests in oasdiff. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add checker rules for const field changes, webhook add/remove, and nullable type arrays (OpenAPI 3.1 style). Includes localized messages for en, es, pt-br, and ru. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat: add OpenAPI 3.1 breaking change checker rules

Add comprehensive documentation to package doc.go files: - checker: breaking change detection overview, configuration, rules - checker/generator: message generation from YAML - checker/localizations: localized message templates - diff: OpenAPI diff calculation, schema comparison - flatten/*: allof merging, common params, header normalization - formatters: output formats (json, yaml, html, junit, etc.) - load: spec loading from files, URLs, globs with preprocessing - report: legacy basic changelog (predates richer changelog) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

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

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

reuvenharrison and others added 6 commits February 5, 2026 23:48

build container for openapi 3.1

1d760e8

fix: sanitize branch name in Docker workflow for feature branches

d6f8063

The docker/metadata-action automatically converts slashes to dashes, so use its output for feature branch builds to avoid invalid tag errors. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

reuvenharrison force-pushed the feat/openapi-3.1-support branch from a9484af to d6f8063 Compare February 6, 2026 10:04

reuvenharrison mentioned this pull request Feb 6, 2026

Checker: Add OpenAPI 3.1 breaking change rules #793

Open

reuvenharrison and others added 8 commits February 9, 2026 16:04

Merge branch 'main' into feat/openapi-3.1-support

9fde2a0

feat: add OpenAPI 3.1 breaking change checker rules

4500a29

Add checker rules for const field changes, webhook add/remove, and nullable type arrays (OpenAPI 3.1 style). Includes localized messages for en, es, pt-br, and ru. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Merge pull request #796 from oasdiff/feat/openapi-3.1-checker

a193476

feat: add OpenAPI 3.1 breaking change checker rules

docs: add OpenAPI 3.1 documentation and feature listing

e68684f

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

feat: add OpenAPI 3.1 support#791

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

reuvenharrison commented Feb 5, 2026 •

edited

Loading

Uh oh!

codecov-commenter commented Feb 5, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

reuvenharrison commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Document Level

Info Object

License Object

Schema Object (JSON Schema 2020-12)

Dependencies

Test plan

Uh oh!

codecov-commenter commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

reuvenharrison commented Feb 5, 2026 •

edited

Loading

codecov-commenter commented Feb 5, 2026 •

edited

Loading