[renovate]

Note

This PR body was truncated due to platform limits.

This PR contains the following updates:

Package	Update	Change
tufin/oasdiff	minor	v1.15.0 → v1.37.0

---

Release Notes

oasdiff/oasdiff (tufin/oasdiff)

v1.37.0

Compare Source

Nine new checks, correct severities in oasdiff checks validate, and localized messages that print their values

Moving a deprecated resource's sunset date earlier is now reported, for endpoints, parameters and properties alike, which the deprecation docs have described for years and the code did not do. oasdiff validate flags a schema that no payload can satisfy. Localized output no longer prints %!(EXTRA ...) in Spanish, Russian and Portuguese.

Detection rules

Nine new ids. A spec that moves a sunset date earlier, or deletes a deprecated property's sunset date, will report where it did not before.

• A sunset date moved earlier is breaking (#​1397, thanks @​BogdanYarotsky for the report in #​1363). api-sunset-date-changed-earlier, request-parameter-sunset-date-changed-earlier, request-property-sunset-date-changed-earlier and response-property-sunset-date-changed-earlier are new, at error. Until now the move was reported only when the new date fell inside the deprecation grace period, so with no --deprecation-days-* configured any future date passed silently, even though api-sunset-date-changed-too-small claimed the new date "must be not earlier than" the old one. The grace period now decides which id reports the move rather than whether it is reported at all: *-changed-too-small when the new date is inside the period, *-changed-earlier when it is not. The finding explains itself, since an error with no policy configured is surprising: the date clients were given has been withdrawn, and oasdiff treats a published x-sunset date as a commitment whether or not a policy is set. /checks/<id> documents how to downgrade it.

• A deprecated property's sunset date, deleted or moved too close (#​1359, thanks @​BogdanYarotsky). request-property-sunset-deleted, request-property-sunset-date-changed-too-small, response-property-sunset-deleted and response-property-sunset-date-changed-too-small are new, at error. Properties now get the sunset checks parameters already had. Fixes #​1315.

• validate reports a schema that can accept no payload (#​1396, found while reviewing @​pfeurean's report in #​1383, which is still open). required-property-forbidden, a warning: additionalProperties: false allows only the properties a schema declares, so requiring one it does not declare leaves a schema no object can satisfy. The document violates no MUST, which is why a parser accepts it and validate had nothing to say.

Two changes to what the sunset checks report (#​1390). An x-sunset date that cannot be parsed in the base spec is no longer reported when the revision replaces it with a valid one: clients had no date to rely on, and the unparseable value is already an error in the revision that introduced it. And a deleted or unparseable sunset date is now reported even when x-stability-level does not parse, which was already true for endpoints and parameters and is now true for properties. The three checks share one body, so the three families cannot drift apart again.

Messages

• A value that cannot be parsed is reported as the value (#​1391, #​1393). Six ids built an English sentence in Go and passed it as a message argument, so Spanish, Russian and Portuguese each carried a nested English one, and the value inside it was never delimited: an empty x-sunset ended the message at a colon, a value of one space was invisible, and a valid date padded with a space read as valid. The value is now the argument, quoted, and the sentence belongs to the template in every language. Affects api-deprecated-sunset-parse, api-path-sunset-parse, request-parameter-sunset-parse, request-property-deprecated-sunset-invalid, response-property-deprecated-sunset-invalid and api-invalid-stability-level.

• 30 localized messages printed %!(EXTRA ...) (#​1392). A message with fewer format verbs than the English one appended Go's error marker to its own text, so in Spanish a deprecated parameter read parámetro de solicitud deprecado%!(EXTRA string=query, string=id). Fifteen messages in es, eight in pt-br and seven in ru are fixed, and a test now formats every message in every locale and fails on any %! in the result.

• API is capitalized in the 50 messages that spelled it as a word (#​1397), and the allOf disclaimer is worded for every change it attaches to (#​1378).

validate

• oasdiff checks validate listed seven rules at the wrong severity (#​1395). minimum-exceeds-maximum, min-length-exceeds-max-length, min-items-exceeds-max-items, min-properties-exceeds-max-properties, min-contains-exceeds-max-contains, enum-empty and const-not-in-enum were listed as errors while the findings came out as warnings. The lint now reads its level from the same registry the listing does, so the two cannot disagree again. No finding changes level.

Go API

• The deprecated STABILITY_* constants are removed (#​1394). STABILITY_DRAFT, STABILITY_ALPHA, STABILITY_BETA and STABILITY_STABLE have been aliases of StabilityDraft and friends since v1.20.0. The replacement is a rename at the call site, with no behaviour change.

Upgrading

Change fingerprints move for the six ids whose argument changed, so a tool that carries review state by fingerprint, including the oasdiff Pro review, will show those findings once as new. Findings of other ids are unaffected.

If one of the eight new checker ids reports on a spec you consider correct, --severity-levels downgrades any of them individually, and each one has a page on oasdiff.com that explains the mechanism. The new validate rule is different: validate has no --severity-levels, so required-property-forbidden is a warning that --fail-on ERR already ignores.

v1.36.0

Compare Source

Source locations for JSON specs, correct severity for added request allOf branches, and --exclude-elements tags

JSON specs now report line and column on every finding, the same as YAML specs, which took a new YAML decoder in kin-openapi to reach. Adding an allOf branch to a request is reported as an error again. Sunset and parameter deprecation findings point at the right line, oasdiff validate output comes out in the same order on every run, and oasdiff diff can now ignore tags.

CLI changes

Source locations

• JSON specs report the line and column of each change (#​1384). Until now, only YAML specs carried source locations. Findings in a JSON spec now point at the changed field, so GitHub annotations land on the right line. Findings that had no location used to carry an in schema "A" suffix to tell components apart, and that suffix is gone. conflicting-paths and info-required also gained a line they used to lack. One limitation: positions are only as fine as the document's line breaks, so a minified spec, the whole document on one line, reports every change on line 1, with a column that is still exact. Source location tracking has the detail. Known regression: on some changes the endColumn now includes trailing whitespace on the line. Start positions are unchanged. Closes #​1128.
• Sunset findings point at x-sunset (#​1371). Six ids put their annotation on the deprecated field instead of the date they complain about: api-deprecated-sunset-parse, api-sunset-date-too-small, request-property-deprecated-sunset-invalid, request-property-sunset-date-too-small, response-property-deprecated-sunset-invalid and response-property-sunset-date-too-small. They now point at x-sunset. *-deprecated-sunset-missing and *-reactivated still point at deprecated, because those findings are about that field. When a sunset date fails to parse on only one side, the finding now carries a location for that side only.
• Parameter deprecation points at the parameter's deprecated field (#​1367). The check looked for deprecated in the parameter's schema. The annotation therefore landed on the operation line, or had no location at all when the schema also changed in that revision. Fixes #​1362.

Detection rules

• Adding a request allOf branch is an error again (#​1375, thanks @​mvanhorn). request-body-all-of-added and request-property-all-of-added were lowered to warnings, with a comment saying another branch might still keep a constraint that was dropped. Adding a branch to an allOf can only narrow what a request may send, so the comment did not apply. Both ids now report at their declared error level, without the comment. Fixes #​1308.

validate

• Findings come out in source order, the same on every run (#​1366). Before, the order changed between runs on the same spec. That broke CI steps that compare stored reports and reshuffled GitHub annotations on every push. Findings are now sorted by file, line, column, id and text.
• Callbacks are validated (#​1384). oasdiff validate now checks an operation's callbacks, which it never did before. A spec with an invalid example inside a callbacks: block can now fail validate where it used to pass.
• multiple-of-not-positive is renamed to schema-multiple-of-not-positive (#​1384). A multipleOf of zero or less used to produce two findings for one problem. The duplicate is gone. The surviving finding has a new id and points at the same multipleOf: line. Machine output that matches on the old id needs to be updated.

diff

• --exclude-elements tags (#​1364). This value drops tag changes from diff and summary in both places tags appear: the tags an operation is listed under, and the document's top-level tag definitions. Moving an operation between tags no longer shows up as a change. changelog and breaking are unaffected. Fixes #​1337.

Docker

• Git revisions work on a mounted repository (#​1339, thanks @​huguesducharme). Git refused to read a repository mounted from the host ("detected dubious ownership"), so the rev:path syntax failed inside the container. The image now trusts mounted repositories. docs/DOCKER.md has a new section on running the image as a non-root user with --user.

Misc

• Subschema names no longer end in / (#​1365). A finding inside an allOf, anyOf or oneOf branch now names it as nickname/allOf[subschema #​2] instead of nickname/allOf[subschema #​2]/. Because the name is part of the finding, fingerprints change for findings inside a subschema, and a stored approval keyed on one of them will be requested once more.
• flatten rejects an explicit enum: [] that conflicts with other allOf branches (#​1369). An empty enum was treated as no enum, so the flattened schema accepted values the original rejects. It now fails with the existing enum-conflict error. Fixes #​1262.
• Filter regex errors name their flag (#​1368). An invalid --match-path, --unmatch-path or --filter-extension pattern now names the flag in its error. --match-path and --unmatch-path used to share one message. Each pattern is also compiled once per diff instead of once per path pair.

Go package changes

• Breaking: checker/location and checker/schemawalk are now internal (#​1381). They moved under checker/internal and can no longer be imported. Use checker.Source to build a source location, for example &checker.Source{File: "base.yaml", Line: 10, Column: 5}. WithSources, GetBaseSource, GetRevisionSource and the BaseSource / RevisionSource fields are unchanged.
• diff.ExcludeTagsOption and IsExcludeTags (#​1364). Library support for the new tags value of --exclude-elements.
• load.IsExternalRefDisallowed matches a typed error (#​1384). It now detects kin-openapi's *openapi3.DisallowedExternalRefError with errors.As instead of matching the message text.
• github.com/oasdiff/yaml and github.com/oasdiff/yaml3 are no longer dependencies (#​1384).

v1.35.0

Compare Source

Deterministic diff output, a sunset-aware deprecation lifecycle, and the OAuth flows that were never checked

oasdiff diff now returns the same output on every run of the same comparison. Removing a deprecated request or response property follows its x-sunset date instead of reporting a plain removal. The OAuth security checks cover all four flows rather than only implicit, and compare URLs by meaning. Two crashes are fixed. This is the same code as v1.35.0-rc.1.

CLI changes

Deterministic output

• diff returns the same output on every run (#​1335). Parts of the diff were built by ranging over a map, and Go randomizes map iteration, so the order of added, deleted and modified entries moved between runs of the same comparison. Every map-based diff now goes through one helper that returns sorted lists, paths are listed by path then method, required and type lists are sorted, the YAML endpoints section is sorted, and an added and deleted media type that are equivalent are paired the same way every run. A new test compares 284 fixture pairs ten times each and requires identical JSON and YAML.
• The duplicate endpoint error names both paths and how to fix it (#​1336). It used to name one of the two clashing paths, picked at random, without saying what it clashed with. It now reports both paths with the file each came from, the same pair on every run, and suggests --include-path-params. The x-since-date error got the same treatment.

Deprecation

• Removing a deprecated property follows its sunset date (#​1305, thanks @​BogdanYarotsky). Request properties and required response properties now use the lifecycle that parameters and endpoints already had: removing a deprecated property with no x-sunset reports request-property-removed-with-deprecation or response-required-property-removed-with-deprecation at info, removing one before its sunset date reports request-property-removed-before-sunset or response-required-property-removed-before-sunset at error, and removing one after its sunset date is not reported. A sunset date that cannot be parsed keeps the plain removal id, since the deprecation checks already report the bad date.

Security schemes

• All four OAuth flows are checked (#​1328). The checks read only the implicit flow, so changes to authorizationCode, password and clientCredentials were never reported: moving an authorizationCode flow's URLs to another host and dropping one of its scopes gave "No changes to report". Every URL and scope finding now names its flow, since the same scope can appear in two flows of one scheme, and api-security-component-oauth-refresh-url-changed is new.
• Security scheme URLs are compared by meaning (#​1328). https://Login.Example.com:443/token and https://login.example.com/token are no longer reported as a change. The comparison follows RFC 3986: case in the scheme and host, a default port, an empty path, and percent-encoding of unreserved characters are all equivalent. The four URL checks now share one level, warning, with a comment explaining the verdict; api-security-component-openid-connect-url-changed was an error, and the authorization and token URL checks were info.

Crashes

• x-extensible-enum with numeric values no longer panics (#​1343). An integer parameter or property written as x-extensible-enum: [1, 2] crashed breaking and changelog when a value was removed, because the items were read as strings. A removed number is now reported like any other removed value.
• A self-referencing callback no longer overflows the stack (#​1344). A callback whose operation carries the same callback recursed until the stack overflowed, even when a spec was compared with itself. diff, breaking, changelog and summary are all fixed, and each change is reported once, where the callback is first compared.

External $refs

• One exit code for a refused external $ref (#​1354). With --allow-external-refs=false, a refused $ref exited 123 when oasdiff's own reader was installed, which --open does, and 102 otherwise, so a CI step keying off the code could not reliably offer the remedy. Both paths now exit 123, and the two forms of the refusal are recognized by one predicate.
• The capture reader applies the policy by default (#​1347, #​1352). The reader --open installs now refuses an external $ref before any read, and a call site that does not name a document gets the policy rather than silently getting none. The fix itself shipped in v1.34.1 and is published as GHSA-6h5x-f3qr-cp23; what is new here is that the reader fails closed.

Misc

• kin-openapi v0.151.0 (#​1332).
• Third-party actions are pinned by digest and workflow tokens are least-privilege (#​1340, thanks @​huguesducharme).
• A security policy (#​1346), so a reporter has somewhere to send a finding.

Go package changes

• New load.IsExternalRefDisallowed(err) (#​1354). Answers for both refusal paths, oasdiff's reader and kin-openapi's own check, so a caller no longer has to match either form. The kin match is pinned by a test that runs the real loader, so a wording change upstream fails the test rather than silently reverting the behaviour.
• utils.StringSet.ToStringList returns sorted values (#​1335). This is what makes string-list diffs such as required and type deterministic; a caller that relied on the previous arbitrary order now gets a stable one.
• Four new checker ids (#​1305): RequestPropertyRemovedWithDeprecationId, RequestPropertyRemovedBeforeSunsetId, ResponseRequiredPropertyRemovedWithDeprecationId, ResponseRequiredPropertyRemovedBeforeSunsetId. Machine-readable output gains these ids, so a consumer matching on removal ids should expect them.

v1.34.1

Compare Source

A security patch, cut from v1.34.0 with this change alone. If you run --open, or use the GitHub Action, upgrade.

CLI changes

• --allow-external-refs=false is now enforced when --open is passed (#​1347). --open installs a reader that captures the text of every file the loader reads, so the review can be sliced into per-endpoint blocks. kin-openapi checks the external-refs setting only when no custom reader is installed, and hands the policy to the reader when there is one, so the setting had no effect on file, URL and glob sources: a spec with an external $ref could read any local file or reach any URL, and the full bytes of what it read went into the review bundle. Refusing now returns the existing ExternalRefError (exit code 123), the same as the git-revision path, and --allow-external-refs=true is unaffected. Reported by Zachariah Mithani (AploSec). See GHSA-6h5x-f3qr-cp23; GitHub Action users should read GHSA-6h8r-wgc5-q3xv, where the affected combination is the default configuration.

Go package changes

• load.NewSpecInfoWithCapture and load.NewSpecInfoFromGlobWithCapture apply the external-refs policy before reading. A caller that set IsExternalRefsAllowed=false and loaded through either of them was not getting that setting honoured; a refused $ref now returns *load.ExternalRefError. No exported signature changes.

v1.34.0

Compare Source

Security checks, one finding per shared-schema change, faster large specs

Security requirements are now compared by the access they grant: securing an anonymous endpoint, replacing a top-level requirement and changing how a security scheme sends credentials are all reported as breaking. A change in a schema that many properties reference is reported once, naming the schema, which cuts the output on large specs by up to 97%. Large specs compare much faster, and several sources of run-to-run differences in the output are gone.

This release includes everything tested in the v1.33.1 release candidates. Thanks @​victorrentea for reporting five of the detection gaps fixed here (#​1280, #​1281, #​1282, #​1283, #​1284), @​ttyS15 for the shared-schema traversal fix (#​1263), @​bram96 for the --flatten-allof report and for testing the release candidate on a full spec (#​1279), and @​dreaded369 for the validate report (#​1304).

CLI changes

Security

• No security requirement means anonymous access (#​1290). Securing an operation that had no security requirement, directly or by adding a top-level security it inherits, is now reported as api-security-anonymous-access-removed (error), naming what the endpoint now accepts. Making a secured operation anonymous is api-security-anonymous-access-added (info), instead of the previous api-security-removed error. Operations that switch between inheriting the top-level security and declaring their own, including security: [], are compared using the security actually in effect.
• Top-level security changes are reported on each operation that inherits them (#​1326). Replacing or narrowing the top-level security list was always reported at info, so breaking passed although every inheriting operation now rejects existing clients. Each inheriting operation now gets api-security-removed, api-security-added, api-security-scope-added or api-security-scope-removed at its declared level, with a comment saying the endpoint inherits the API's top-level security requirements. The api-global-security-* findings now appear only when no operation inherits the list, at info. These findings have new ids and paths, so their fingerprints change.
• Security scheme fields that tell a client how to send credentials (#​1288). New checks, all errors: api-security-component-api-key-name-changed, api-security-component-api-key-in-changed, api-security-component-http-scheme-changed (compared case-insensitively) and api-security-component-openid-connect-url-changed. api-security-component-bearer-format-changed is info, since bearerFormat is a hint. When the scheme's type changes, only the type change is reported.
• Level change: api-security-component-type-changed is now an error (#​1288), so changing a security scheme's type fails oasdiff breaking. Use --severity-levels to set it back to info.
• apiKey header names are case-insensitive (#​1288). Renaming an apiKey scheme sent in a header from X-API-Key to x-api-key is no longer reported, matching other header names. --case-insensitive-headers=false turns this off.

Shared schemas

• A change in a shared schema is reported once per check (#​1273). A change in a schema that several properties of a payload reference was reported at some of them and silently left out at others, depending on how they nested. It is now reported once, at one of those properties, naming the schema, listing the first three properties it applies to and counting all of them, for example (shared schema: Shared, also at third/shared/id, fourth/shared/id and 1 more). On the Microsoft Graph description, 713,875 findings between two releases become 18,953.
• New sharedSchema field in JSON and YAML output (#​1273): name, properties and count, or cyclic when a cycle makes the count unbounded.
• What this means for stored results (#​1273). The findings for the same change at the other properties are no longer reported, so their fingerprints disappear and review decisions stored against them don't carry forward. The finding that is kept keeps its fingerprint, but its text now ends with the shared schema detail, so an --err-ignore or --warn-ignore line copied from the old text no longer matches it.

Detection rules

• readOnly and writeOnly flips (#​1293, fixes #​1282). A required response property becoming writeOnly is now an error, the same as removing it. In OpenAPI 3.0, a required request property that stops being readOnly is an error, because 3.0 applied required to it in responses only; in 3.1 and later it is reported as the new request-required-property-became-not-read-only-in-openapi-31 at info, since clients already had to send it. A request property becoming readOnly is now a warning, with a comment saying the spec lets the server either ignore or reject it.
• Removing or adding a whole enum is one change (#​1289, fixes #​1280). Dropping the enum keyword was reported as each value removed, which inverted the verdict: it is now info on requests (request-property-became-not-enum and the parameter and body variants) and an error on responses (response-property-became-not-enum, response-mediatype-became-not-enum), since the server may now return values the old enum excluded. Adding an enum to an unconstrained response property is response-property-became-enum (info) instead of one error per value.
• Enum changes on a body (#​1289). Adding a value to a response body enum is now reported as response-mediatype-enum-value-added (error); it was not reported at all. Adding an enum to a response body (response-mediatype-became-enum) and adding a value to a request body enum (request-body-enum-value-added) are reported at info.
• date or time to date-time is breaking (#​1285, fixes #​1281). It was treated as a widening, but a valid date is not a valid date-time, so on a request the change rejects every value that was valid before. It is now reported as a format change.
• Unwrapping a nullable header parameter reports one change (#​1275). Removing a oneOf: [{type: "null"}, X] wrapper from a header parameter, or a property of one, also reported new-required-request-header-property, request-header-property-became-required and request-header-property-became-enum. Only request-parameter-became-not-nullable is reported now, as for query parameters.

Large specs and stable output

• Faster on large specs (#​1291, #​1263). breaking on the Microsoft Graph description went from 152 to 24 seconds. A chain of shared schemas, each referenced twice, no longer makes breaking slow down exponentially with its depth (#​1263).
• --flatten-allof gives the same result on every run (#​1287, fixes #​1279). An allOf whose subschemas had their own allOf could be merged in an order that changed from run to run, so two identical copies of a spec were sometimes reported as different.
• Output order no longer changes between runs (#​1272, #​1292, #​1302). Changes that differ only in media type, the types named by a list-of-types change, and added or removed discriminator mapping keys, OAuth scopes and media type parameters now come out in a fixed order. For list-of-types findings this also makes the fingerprint stable (#​1292).

Misc

• validate keeps the same defect in different components apart in a JSON spec (#​1312, fixes #​1304). A JSON spec has no line numbers, so the same defect in several components was reported once. Each component now gets its own finding, naming the component. The fingerprints of components-rooted findings change, for YAML specs too.
• oasdiff diff shows an operation declaring or dropping its own security list (#​1290), as listAdded / listDeleted, so security: [] appearing or disappearing is no longer invisible.
• The Docker image is built with Go 1.27 (#​1330), like the release binaries. Go toolchain updated to 1.27.2.

Go package changes

• Breaking: location helpers moved to checker/location (#​1267). checker.NewSource, checker.ParameterSources, checker.SchemaFieldSources and the other exported location helpers are now in checker/location. checker.Source remains as an alias.
• Breaking: the schema walker moved to checker/schemawalk (#​1269), with Walker.Walk, ModifiedProperties, AddedProperties, DeletedProperties and PropertyFullName.
• Breaking: ApiChange.WithSchema takes the root schema and property path as well as the node (#​1273). ApiChange.GetSharedSchema returns the new shared schema detail.
• Schema diffs name the component they compare (#​1264, #​1270). SchemaDiff.BaseComponent and RevisionComponent hold the components.schemas name, including for a $ref with a description override. They are not part of the diff output.
• The diff carries checker context (#​1290, #​1293): the top-level security lists, the operations present in both specs and each spec's openapi version, none of them in the output. CheckBackwardCompatibility filters this context on a copy, so the caller's diff is not modified.

v1.33.0

Compare Source

Recursive schemas: fast, deterministic, and no longer repeated per path

v1.32.0 could run for hours on a spec whose schemas reference each other in cycles, and v1.32.1 fixed that by returning to v1.31.0's cycle handling, which gave up the deterministic output v1.32.0 had introduced. This release reworks the handling so that both hold at once, on the two specs reported in #​1252 and on everything else.

Thanks @​simonbility for the report and the specs, @​philippnagel for the second spec and for testing the release candidate against it, and @​BigMichi1 for the determinism report that started this.

CLI changes

Recursive schemas

• Specs with cyclic schemas compare in about a second, with or without --flatten-allof (#​1254, fixes #​1252). The two specs reported there are the measure: one needed --flatten-allof and ran for hours, the other has 134 schemas referencing each other in a single cycle and never finished at all. Both now complete in about a second, including the combination v1.32.1 could not do.
• Structured output for a schema in more than one reference cycle is deterministic again (fixes #​1230). v1.32.0 fixed this, v1.32.1 had to revert it to get rid of the hang, and this release has both. Identical inputs produce identical bytes.
• --flatten-allof keeps one copy of each schema. It used to copy a schema once for every place that referenced it: one reported spec grew from 5,195 schema objects to 3.5 million in memory. The flattened output is unchanged, and flattening it now takes milliseconds rather than seconds.
• A change inside a recursive schema is reported once per entry into the cycle rather than once for every path through it. Every operation that reaches the change still reports it. On one reported spec a single added property produced 241,978 changelog lines before and 9,162 now.
• A cycle edge no longer repeats one level of the diff, and a $ref-to-inline refactor inside a cycle is recognized as a refactor, the same as one outside a cycle.

Upgrading from v1.32.1

• The circularRef field is removed from diff --format json|yaml output again, as in v1.32.0: cyclic-reference mismatches appear as ordinary field-level diffs, which say more. v1.32.1 had restored it along with v1.31.0's cycle handling.
• Diffs of schemas that take part in more than one reference cycle change once, and then hold steady.

Go package changes

• Breaking: diff.SchemaDiff.CircularRefDiff is removed again (#​1254), together with the ref-string circular guard, as in v1.32.0. v1.32.1 had restored both.
• flatten/allof.MergeSpec merges a document with one state (#​1254), so a schema referenced from several places stays one object after the merge.

v1.32.1

Compare Source

Fixes the v1.32.0 hang on cyclic schemas

v1.32.0 can run for hours on a spec whose schemas reference each other in cycles (#​1252, two reports within a day). This release reverts the two v1.32.0 changes to cycle handling in the diff, so recursive schemas are handled exactly as in v1.31.0, and keeps everything else from v1.32.0. A rewrite of the cycle handling that fixes the hang and the non-determinism together (#​1254) follows as a pre-release.

CLI changes

Cyclic schemas

• The v1.32.0 hang on cyclic schemas is fixed by returning to v1.31.0's cycle handling (#​1255, fixes #​1252). Both reported specs complete again: one that needed --flatten-allof, and one with 134 schemas on a single reference cycle that hung with no flag at all. One limit of v1.31.0 comes back with it: that second spec still does not finish with --flatten-allof; #​1254 fixes that too. Specs without cycles are unaffected; on a large real-world spec the changelog is identical, line for line, to both v1.31.0's and v1.32.0's. Thanks @​mako365-philippnagel for the second spec.
• Two things come back with the revert. The circularRef field is back in diff --format json / yaml output, exactly as in v1.31.0. And the non-deterministic structured output for a schema that takes part in more than one reference cycle (#​1230), which v1.32.0 had fixed, is back until #​1254 ships; identical inputs can again produce one of two outputs for such schemas.

checks command

• Look up a single check or location (#​1249). oasdiff checks changelog --id <check-id> shows one check (the full record in json/yaml; the flag shell-completes to the catalog ids, and an unknown id is an error). --location <string> keeps the checks whose claimed location contains the string, on the listing and on coverage alike. Generated rules are marked as such in the listing.
• Subcommands are grouped in --help and the README (#​1250): compare two specs (breaking, changelog, diff, summary), process a single spec (validate, upgrade, flatten), git integration (breaking-files, git-diff-driver), reference (checks, schema). No behavior change.

Docs

• CHECKS.md documents the guards dimension (#​1248): the GUARDS column of oasdiff checks and its six tags (read-only, write-only, sanctioned, non-success, has-default, negotiated), each defined in contract terms.

Go package changes

• diff.SchemaDiff.CircularRefDiff is back (#​1255), with the ref-string circular guard that powers it, as in v1.31.0. Code written against v1.32.0 that relied on the field being absent sees it again; it is removed once more by #​1254.

v1.32.0

Compare Source

56 new checks, cycle-proof diff and flatten

The generated-rule engine now covers every increase and decrease of every bound keyword (catalog: 699 to 755 checks), and recursive schemas are handled end to end: no more stack overflows in diff or flatten, deterministic structured output, and flattened recursion that always serializes under stable names.

CLI changes

Detection rules

• Every bound keyword's increase and decrease is now checked (#​1232). The rule engine that generates set/unset checks now also generates increased/decreased ones, closing 56 gaps at once: response headers get their first increase/decrease checks, parameters gain maxProperties/minProperties/minContains/maxContains coverage, and the widening response directions (for example response-body-max-decreased) are reported at info level. multipleOf is deliberately excluded: numeric order does not decide its effect, so it keeps its dedicated changed/generalized/specialized checks.
• Exclusive bounds join the generated rules, fixing three latent bugs (#​1226). In the OpenAPI 3.0 boolean form, exclusiveMaximum: false to true used to report nothing (it is a breaking set), adding exclusiveMaximum: false was reported as breaking (it changes nothing, false means not exclusive), and the false-to-true transition could be misreported as a value increase.
• Added and deleted properties under an unflattened allOf carry the disclaimer (#​1229). Existence changes inside allOf branches now get the same warning cap and --flatten-allof hint as other findings there, and a schema that itself has an allOf is recognized by presence rather than only when the allOf changed.
• oasdiff checks shows each rule's guards (#​1227). A GUARDS column and a --tags dimension expose the read-only / write-only guards, so a verdict downgraded by a guard is explained by the catalog instead of looking like a bug.

Recursive schemas: no crashes, deterministic output, serializable flatten

• Diffing ref-less cyclic schemas no longer overflows the stack (#​1231, thanks @​dimitropoulos). Schemas that reference themselves through in-memory links rather than $ref (for example after --flatten-allof merges a recursive component) are cut safely at the point of re-entry, whatever shape the cycle has.
• oasdiff flatten of recursive allOf merges always serializes (#​1233, #​1240, #​1245). A cycle keeps its $ref where one exists, a set that merges to a single schema reuses that schema with its name, and a genuinely anonymous merged cycle is hoisted into components.schemas under a name built from the merged component names (AllOfMerged_NodeA_NodeB), so the same cycle keeps the same name in every revision. Documented in docs/ALLOF.md (#​1244).
• A merge mixing a recursive branch with other constraints keeps them all (#​1243). Such a node becomes an allOf of the named cycle and the merged remaining constraints instead of silently dropping them, which could previously hide breaking changes in the flattened comparison.
• Structured output for multi-cycle schemas is deterministic (#​1237, thanks @​BigMichi1 for the precise report in #​1230). A schema participating in more than one reference cycle produced one of two different --format json/yaml outputs at random; identical inputs now produce identical bytes, and the output is also more complete, each cycle edge carrying its own diff. Diffs of such schemas change once when you upgrade.
• The circularRef output field is removed (#​1238). Cyclic-reference mismatches now appear as ordinary field-level diffs, which say strictly more; a pure rename of a cyclic $ref is no longer reported, matching how non-cyclic $ref renames behave.

Validate

• New lint: mutability flags no request or response can ever see (#​1228). A readOnly on a schema reachable only from requests, or writeOnly only from responses, can never take effect; oasdiff validate now flags both, walking webhooks and callbacks too.

Misc

• **Ignore and severity-level files no

[!IMPORTANT]
✂ PR body was truncated to here.

---

Configuration

📅 Schedule: (in timezone Etc/UTC)

• Branch creation
  • At any time (no schedule defined)
• Automerge
  • At any time (no schedule defined)

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

---

• If you want to rebase/retry this PR, check this box

---

This PR was generated by Mend Renovate. View the repository job log.