feat(diff/breaking/changelog/summary): --auto-upgrade for cross-version specs (#923)

reuvenharrison · claude · web-flow · commit effffd717909 · 2026-05-11T00:14:20.000+03:00
* feat(diff/breaking/changelog/summary): --auto-upgrade for cross-version specs

When --auto-upgrade is set, both base and revision are canonicalised
to the latest OpenAPI 3.x (via the same openapi3conv.Upgrade helper
the new 'oasdiff upgrade' subcommand uses) right after load and before
diff. This makes cross-version comparisons (e.g. a 3.0 base against a
3.1 revision) produce a meaningful result instead of a noisy diff
dominated by dialect-level differences (nullable shape, type arrays,
exclusiveMinimum, example/examples).

The walker is idempotent on already-canonical specs, so calling it on
a same-version pair is a safe no-op. Off by default; opt in per
invocation. Applies to diff, breaking, changelog, and summary because
all four flow through normalDiff / composedDiff.

Tests cover the cross-version-equivalent case (a 3.0 spec and its 3.1
canonical form produce 'No changes detected' under --auto-upgrade) and
the same-version idempotency case (output unchanged whether the flag
is set or not).

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;

* docs(3.1): document --auto-upgrade for cross-version comparison

Extend the 'Migrating from 3.0 to 3.1' section with a 'Comparing
across versions with --auto-upgrade' subsection covering the new
flag on diff/breaking/changelog/summary.

Explains the use case (cross-version diff produces dialect-level
noise without the flag) and that the walker is idempotent so
setting the flag is safe even for same-version pairs.

---------

Co-authored-by: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/data/upgrade/equivalent-31.yaml b/data/upgrade/equivalent-31.yaml
@@ -0,0 +1,21 @@
+openapi: 3.1.0
+info:
+  title: upgrade-test
+  version: '1.0'
+paths:
+  /items:
+    get:
+      parameters:
+        - in: query
+          name: q
+          schema:
+            type: [string, "null"]
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema:
+                type: integer
+                exclusiveMinimum: 0
+                examples: [7]
diff --git a/docs/OPENAPI-31.md b/docs/OPENAPI-31.md
@@ -40,6 +40,52 @@ Changes are detected for all 3.1-specific fields:
 - **unevaluatedItems/unevaluatedProperties**: added/removed
 - **contentSchema/contentMediaType/contentEncoding**: added/removed/changed
 
+## Migrating from 3.0 to 3.1
+
+OpenAPI 3.1 changes the shape of several constructs:
+
+| 3.0 | 3.1 |
+|---|---|
+| `nullable: true` on `type: string` | `type: ["string", "null"]` |
+| `exclusiveMinimum: true` + `minimum: 0` | `exclusiveMinimum: 0` (numeric) |
+| `example: 7` | `examples: [7]` |
+
+A team migrating their spec from 3.0 to 3.1 has two problems oasdiff can help with: producing the migrated spec, and verifying the migration doesn't break clients.
+
+### Converting a spec with `oasdiff upgrade`
+
+The `upgrade` subcommand rewrites a 3.0 spec into the latest 3.x canonical form (currently 3.2.0). The transforms are idempotent, so running it on an already-canonical spec just bumps the version string.
+
+```
+oasdiff upgrade old-spec.yaml > new-spec.yaml
+oasdiff upgrade old-spec.yaml --format json > new-spec.json
+cat old-spec.yaml | oasdiff upgrade -
+```
+
+The output goes to stdout; redirect to a file to keep it. The default output format is `yaml`; pass `--format json` for JSON.
+
+The walker handles 3.0 → 3.x only. Swagger 2.0 → 3.0 is out of scope.
+
+Available since `v1.16.0`.
+
+### Comparing across versions with `--auto-upgrade`
+
+`diff`, `breaking`, `changelog`, and `summary` accept an `--auto-upgrade` flag that runs the same canonicalisation on both specs in-memory right after load. This makes cross-version comparisons (e.g. a 3.0 base against a 3.1 revision) produce a meaningful result instead of a noisy diff dominated by dialect-level differences.
+
+```
+# old.yaml is 3.0, new.yaml is 3.1
+oasdiff breaking  old.yaml new.yaml --auto-upgrade
+oasdiff changelog old.yaml new.yaml --auto-upgrade
+oasdiff diff      old.yaml new.yaml --auto-upgrade
+oasdiff summary   old.yaml new.yaml --auto-upgrade
+```
+
+Without the flag, the diff surfaces the 3.0→3.1 dialect rewrites (`nullable` becomes `type: ["string", "null"]`, etc.) as if they were schema changes. With the flag, both sides are canonicalised first, so only the genuine schema-level differences remain.
+
+The flag is off by default; opt in per invocation. Safe to set even when both specs are already the same version: the walker is idempotent on already-canonical input.
+
+Available since `v1.16.0`.
+
 ## Caveats
 
 The following 3.1 features are not yet fully supported by [`kin-openapi`](https://github.com/getkin/kin-openapi) (the parser oasdiff uses) and therefore do not appear in oasdiff diffs:
diff --git a/docs/README.md b/docs/README.md
@@ -62,13 +62,14 @@ Pre-built binaries for macOS, Linux, and Windows (both x86_64 and arm64) are on
 Grouped by what you're trying to do. New to oasdiff? Start with **Commands**.
 
 ### Commands
-The six top-level subcommands.
+The seven top-level subcommands.
 
 - [`diff`](DIFF.md) — full diff between two OpenAPI specs (output: html, json, markdown, markup, text, or yaml — default yaml)
 - [`summary`](DIFF.md) — high-level count of changes between two specs (built on the diff engine; same shared options)
 - [`breaking`](BREAKING-CHANGES.md) — only breaking changes
 - [`changelog`](BREAKING-CHANGES.md) — every significant change, breaking or not, in human-readable form
 - [`flatten`](ALLOF.md) — replace `allOf` schemas with a merged equivalent
+- [`upgrade`](OPENAPI-31.md#converting-a-spec-with-oasdiff-upgrade) — canonicalize an OpenAPI 3.0 spec to the latest 3.x
 - [`checks`](CHECKS.md) — list the rules oasdiff uses to classify changes ([customize them](CUSTOMIZING-CHECKS.md))
 
 ### Inputs
diff --git a/internal/cmd_flags.go b/internal/cmd_flags.go
@@ -22,6 +22,7 @@ func addCommonDiffFlags(cmd *cobra.Command) {
 	cmd.PersistentFlags().Bool("case-insensitive-headers", false, "case-insensitive header name comparison")
 	cmd.PersistentFlags().StringSlice("exclude-extensions", nil, "OpenAPI Extension names to exclude from diff (e.g., x-internal)")
 	cmd.PersistentFlags().Bool("allow-external-refs", true, "allow external $refs in specs; disable to prevent SSRF when processing untrusted specs")
+	cmd.PersistentFlags().Bool("auto-upgrade", false, "canonicalize both specs to the latest OpenAPI 3.x before diffing; useful for cross-version comparisons (e.g. 3.0 vs 3.1)")
 
 	addHiddenFlattenFlag(cmd)
 	addHiddenCircularDepFlag(cmd)
diff --git a/internal/diff.go b/internal/diff.go
@@ -116,6 +116,8 @@ func normalDiff(loader *openapi3.Loader, flags *Flags) (*diffResult, *ReturnErro
 		s2.Spec = s1.Spec
 	}
 
+	autoUpgradeSpecs(flags.getAutoUpgrade(), s1, s2)
+
 	diffReport, operationsSources, err := diff.GetWithOperationsSourcesMap(flags.toConfig(), s1, s2)
 	if err != nil {
 		return nil, getErrDiffFailed(err)
@@ -140,6 +142,11 @@ func composedDiff(loader *openapi3.Loader, flags *Flags) (*diffResult, *ReturnEr
 		return nil, getErrFailedToLoadSpecs("revision", flags.getRevision().Path, err)
 	}
 
+	if flags.getAutoUpgrade() {
+		autoUpgradeSpecs(true, s1...)
+		autoUpgradeSpecs(true, s2...)
+	}
+
 	diffReport, operationsSources, err := diff.GetPathsDiff(flags.toConfig(), s1, s2)
 	if err != nil {
 		return nil, getErrDiffFailed(err)
diff --git a/internal/flags.go b/internal/flags.go
@@ -71,6 +71,10 @@ func (flags *Flags) getAllowExternalRefs() bool {
 	return flags.v.GetBool("allow-external-refs")
 }
 
+func (flags *Flags) getAutoUpgrade() bool {
+	return flags.v.GetBool("auto-upgrade")
+}
+
 func (flags *Flags) getIncludeChecks() []string {
 	return fixViperStringSlice(flags.v.GetStringSlice("include-checks"))
 }
diff --git a/internal/run_test.go b/internal/run_test.go
@@ -348,6 +348,32 @@ func Test_UpgradeCmdInvalid(t *testing.T) {
 	require.Contains(t, stderr.String(), "failed to load original spec")
 }
 
+func Test_AutoUpgradeBreaking_CrossVersionEquivalent(t *testing.T) {
+	// simple-30.yaml and equivalent-31.yaml describe the same API; the latter
+	// is the 3.1 canonical form of the former (nullable -> type array, etc).
+	// With --auto-upgrade, both specs are canonicalised so the dialect diff
+	// disappears and oasdiff reports no changes.
+	var stdout bytes.Buffer
+	require.Zero(t, internal.Run(cmdToArgs("oasdiff breaking ../data/upgrade/simple-30.yaml ../data/upgrade/equivalent-31.yaml --auto-upgrade --fail-on ERR"), &stdout, io.Discard))
+	require.Contains(t, stdout.String(), "No changes detected")
+}
+
+func Test_AutoUpgradeChangelog_CrossVersionEquivalent(t *testing.T) {
+	var stdout bytes.Buffer
+	require.Zero(t, internal.Run(cmdToArgs("oasdiff changelog ../data/upgrade/simple-30.yaml ../data/upgrade/equivalent-31.yaml --auto-upgrade --fail-on ERR"), &stdout, io.Discard))
+	require.Contains(t, stdout.String(), "No changes detected")
+}
+
+func Test_AutoUpgradeDiff_SameVersionIsHarmless(t *testing.T) {
+	// When both specs are already on the same version, --auto-upgrade still
+	// canonicalises them (idempotent). The diff result must not change.
+	withoutFlag := bytes.Buffer{}
+	require.Zero(t, internal.Run(cmdToArgs("oasdiff summary ../data/upgrade/already-31.yaml ../data/upgrade/already-31.yaml"), &withoutFlag, io.Discard))
+	withFlag := bytes.Buffer{}
+	require.Zero(t, internal.Run(cmdToArgs("oasdiff summary ../data/upgrade/already-31.yaml ../data/upgrade/already-31.yaml --auto-upgrade"), &withFlag, io.Discard))
+	require.Equal(t, withoutFlag.String(), withFlag.String())
+}
+
 func Test_Checks(t *testing.T) {
 	require.Zero(t, internal.Run(cmdToArgs("oasdiff checks -l ru --tags decrease,parameters --severity info,warn,error"), io.Discard, io.Discard))
 }
diff --git a/internal/upgrade.go b/internal/upgrade.go
@@ -58,6 +58,25 @@ func runUpgrade(flags *Flags, stdout io.Writer) (bool, *ReturnError) {
 	return false, nil
 }
 
+// autoUpgradeSpecs canonicalizes the given specs to the latest OpenAPI 3.x
+// when --auto-upgrade is set. The walker is idempotent on already-canonical
+// specs, so calling it on a same-version pair is a safe no-op (the version
+// string bumps to the latest 3.x). Used by diff/breaking/changelog/summary
+// to make cross-version comparisons (e.g. 3.0 vs 3.1) just work.
+//
+// Nil entries are skipped; callers don't have to filter.
+func autoUpgradeSpecs(enabled bool, specs ...*load.SpecInfo) {
+	if !enabled {
+		return
+	}
+	for _, s := range specs {
+		if s == nil || s.Spec == nil {
+			continue
+		}
+		openapi3conv.Upgrade(s.Spec)
+	}
+}
+
 func outputUpgradedSpec(stdout io.Writer, spec *openapi3.T, format string) *ReturnError {
 	// Reuse the flatten output path: both subcommands serialize a full
 	// *openapi3.T to JSON/YAML and the rendering is identical. If a future
diff --git a/internal/viper.go b/internal/viper.go
@@ -206,6 +206,7 @@ type Config struct {
 	StripPrefixRevision    string   `mapstructure:"strip-prefix-revision"`
 	IncludePathParams      bool     `mapstructure:"include-path-params"`
 	AllowExternalRefs      bool     `mapstructure:"allow-external-refs"`
+	AutoUpgrade            bool     `mapstructure:"auto-upgrade"`
 	Template               string   `mapstructure:"template"`
 }
 

Original file line number	Diff line number	Diff line change
`@@ -71,6 +71,10 @@ func (flags *Flags) getAllowExternalRefs() bool {`
`71`	`71`	`return flags.v.GetBool("allow-external-refs")`
`72`	`72`	`}`
`73`	`73`
	`74`	`+func (flags *Flags) getAutoUpgrade() bool {`
	`75`	`+ return flags.v.GetBool("auto-upgrade")`
	`76`	`+}`
	`77`	`+`
`74`	`78`	`func (flags *Flags) getIncludeChecks() []string {`
`75`	`79`	`return fixViperStringSlice(flags.v.GetStringSlice("include-checks"))`
`76`	`80`	`}`
Original file line number	Diff line number	Diff line change
`@@ -206,6 +206,7 @@ type Config struct {`
`206`	`206`	StripPrefixRevision string `mapstructure:"strip-prefix-revision"`
`207`	`207`	IncludePathParams bool `mapstructure:"include-path-params"`
`208`	`208`	AllowExternalRefs bool `mapstructure:"allow-external-refs"`
	`209`	+ AutoUpgrade bool `mapstructure:"auto-upgrade"`
`209`	`210`	Template string `mapstructure:"template"`
`210`	`211`	`}`
`211`	`212`