chore(deps): update dependency tufin/oasdiff to v1.31.0

[Workleap IT (Infra-Workleap)]

ℹ️ Note

This PR body was truncated due to platform limits.

This PR contains the following updates:

Package	Update	Change	Age
Tufin/oasdiff	minor	1.12.4 → 1.31.0

---

Release Notes

Tufin/oasdiff (Tufin/oasdiff)

v1.31.0

Compare Source

Complete set/unset coverage, and read-only properties reported right

Every ordered constraint keyword (maximum, minimum, multipleOf, maxLength, minLength, maxItems, minItems, maxProperties, minProperties, minContains, maxContains) now has set and unset checks on both sides of the wire, at body, property, parameter, and response-header level: 106 new checks, taking the catalog from 575 to 681, each with its severity derived from the same reviewed model introduced in v1.30.0. And changes to read-only request properties are no longer false breaking errors: oasdiff now knows a readOnly property never appears in a request, reports such changes at info with a comment saying why, and applies the mirror rule to writeOnly properties in responses.

CLI changes

Changes that now fail oasdiff breaking

• Removing a constraint from a response is an error (#​1215, #​1219). Dropping maximum: 100 from a response property means the server may now return values no old client had to handle, the same widening that removing maxLength already reported. Every keyword now has the unset check, on response bodies, properties, and headers. If a specific case is intended, lower the check with --severity-levels.
• Setting a constraint on a request parameter is an error for every keyword (#​1219). multipleOf, minLength, maxItems, maxProperties, minProperties, minContains, and maxContains set on a parameter previously reported nothing (or misreported, see below); setting a bound rejects values the previous contract accepted, so they now match the existing max-set family, with the same explanatory comment.

Changes that no longer fail

• Restricting a read-only request property is informational (#​1213, closes #​1211). A readOnly property never appears in a request, so adding a pattern, setting a maximum, changing its type, or any other request-side restriction cannot invalidate one. Forty-one checks previously reported these as errors; they now report info with the comment "The property is read-only, so it never appears in requests and this change cannot invalidate one." The mirror applies to writeOnly properties in responses. An explicit --severity-levels entry for a check keeps whatever level you set. The breaking changes documentation describes both this rule and the existing allOf case.
• Previously dropped read-only changes are visible again (#​1217, closes #​1189). Twenty-five checks used to skip read-only request properties (and write-only response properties) entirely, reporting nothing at all; those changes now appear at info with the same comment.

Misreport fixes

• Setting a lower bound where none existed no longer reports as an increase (#​1215, #​1219). For minLength and minProperties on bodies and properties, and minLength and minItems on parameters, going from absent to a value reported as "increased from 0" and removing the bound as "decreased to 0". These now report as set and unset, the same fix minItems received in v1.30.

New checks not listed above

• The remaining set/unset cells at info level: unsetting a request constraint (the request accepts more, visible in the changelog for the first time) and setting a response constraint (the response promises more). All 106 new checks appear in oasdiff checks changelog and in the coverage listing.

Go package changes

• The severity model is callable (#​1212). rules.DeriveLevel(effect, direction, guards...) is the severity law as a function, and Rule.DerivedLevel() applies it to a rule's own metadata. Every rule's registered level equals its derived level, enforced in CI.
• diff.SchemaBounds lists the ordered constraint keywords (#​1215, #​1219). Each entry names the keyword, where its diff lives, and how that diff encodes absence (nil for pointer-backed fields, 0 for the plain-uint64 lower bounds), with WasSet and WasUnset classification methods. The checker's generated rules and any library caller share one definition of "this bound appeared or disappeared".
• checker.GetAllRules includes generated rules (#​1215). The set/unset rules are generated from a keyword table rather than written by hand; they carry ids, levels, and locations like any other rule, so callers that enumerate rules see them transparently.

v1.30.0

Compare Source

Provable check coverage, derived severities, boolean schemas, positional prefixItems

The largest change to breaking-change detection since the checker was introduced: every check's severity is now derived from a single reviewed model of what each change does to the API contract, enforced in CI, with zero recorded exceptions. That audit produced 58 new checks and corrected the severity of 36 existing ones, so some changes that previously passed oasdiff breaking with a warning now fail it, and some that failed now pass. Teams that disagree with any individual verdict can override it with --severity-levels. The release also brings OpenAPI 3.1 boolean schemas (items: false tuples), positional prefixItems comparison, OpenAPI 3.2 QUERY and custom methods, and a new breaking-files command for pre-commit hooks.

CLI changes

Severity corrections: changes that now fail oasdiff breaking

• Setting a bound where none existed is an error, not a warning (#​1174). All 18 request-*-{max,max-length,min,min-items,exclusive-max,exclusive-min}-set checks: adding a bound rejects values the previous contract accepted, the same shape as became-enum, const-added and pattern-added, which were already errors. If your clients are known to stay within the new limit, lower the check with --severity-levels.
• Security requirement and scope changes are errors, not info (#​1174). api-security-removed, api-global-security-removed, api-security-scope-added, api-global-security-scope-added: requirements are alternatives, so removing one strands clients authenticating with it, and scopes are conjunctive, so adding one rejects tokens that lack it.
• Adding a branch or value to a response union is an error (#​1174). response-body-any-of-added and response-property-any-of-added now match response-body-one-of-added, and response-property-enum-value-added is an error: the server may return a value no client was written to handle (use x-extensible-enum for value sets that are meant to grow). response-property-pattern-removed is an error and response-property-pattern-changed a warning for the same reason.

Severity corrections: changes that no longer fail

• Request parameter defaults are informational (#​1174). request-parameter-default-value-{added,changed,removed} drop from error to info, matching the body and property default checks: a default is a server-side fallback and does not change which requests are valid.
• Removing an optional response element is informational (#​1174). response-optional-property-removed and optional-response-header-removed: a conforming client already tolerates the element's absence. request-body-all-of-removed, request-property-all-of-removed and response-required-property-became-not-write-only drop to info on similar reasoning, and response-media-type-name-changed becomes a warning with a comment naming what cannot be determined.
• oneOf wrapping splits on whether the original schema survives (#​1174). Wrapping a body in a oneOf that keeps the original schema as one of the alternatives is now the new request-body-wrapped-in-one-of-original-preserved / response-body-wrapped-in-one-of-original-preserved at warning level, with a comment explaining the residual risk; a wrapping where no alternative accepts what the original did keeps the error.

New checks

• 44 constraint-keyword checks (#​1174). maxItems, maxProperties, minProperties, multipleOf and uniqueItems were not checked at all; they now are, across request body, property and parameter and the response side, in both directions, including read-only variants and the multipleOf generalized/specialized cases where one bound divides the other. The multipleOf comparison is exact rational arithmetic, so 0.3 to 0.1 is a generalization and a ratio merely close to an integer is not (#​1205).
• 14 boolean-schema checks (#​1191, #​1203). See below.

Boolean schemas (OpenAPI 3.1)

• true and false schemas load and diff (#​1184, #​1191). A schema written as a JSON Schema boolean failed to parse before; it now loads, and the diff models it. A schema becoming false accepts nothing: the new *-schema-became-false checks report it as an error on the request side and for a response body (the client's media type can no longer be inhabited), across body, property, parameter, parameter property and response header. The reverse transitions report as *-schema-became-not-false. A change between {} and true is a document edit with no contract effect: visible in oasdiff diff, silent in the changelog.
• Closing a tuple with items: false is detected (#​1203). Adding items: false to a schema that had no items invalidates every array longer than the prefix and previously reported nothing.
• A schema arriving as false or true is classified, not just counted (#​1191). A media-type schema added as false reports as schema-became-false instead of an informational "schema added", and one added as true or {} (which accepts exactly what the absent schema accepted) reports nothing instead of a spurious error on the request side.

prefixItems is positional

• Reordering entries is detected (#​1192). prefixItems entries were matched as an unordered set, so swapping [string, integer] to [integer, string] reported no change when every position now validates against a different schema. Entries are now paired by index, so a reorder or in-place edit reports as a located type change (prefixItems[subschema #​1]), and oasdiff diff shows per-position modifications.
• prefixItems verdicts follow the items schema (#​1200). An entry that restates the items schema it displaces changes nothing and now reports nothing; otherwise the eight added/removed checks report a warning with a comment explaining why the direction cannot be determined: an added entry constrains an open position when items is absent but lengthens the tuple when items is false, so the old fixed verdicts (info one way, error the other) asserted a direction the spec does not fix.

OpenAPI 3.2

• QUERY and custom methods are compared (#​1135). Operations under the 3.2 query field and additionalOperations map were invisible to the diff (parked in extensions, then skipped by the fixed method list); they are now diffed like any other operation.
• New validate rules for 3.2 and boolean schemas (#​1184). additional-operations-*, query-field-for-3-2-plus, boolean-schema-for-3-1-plus and boolean-schema-with-other-keywords join oasdiff validate.

New commands

• oasdiff breaking-files checks each changed spec against a git ref (#​1183, thanks @​ChrisJr404): one comparison per spec against the same path in the ref, an aggregated exit code, and a skip with a fetch hint for specs not in the base. Designed for pre-commit hooks; an example .pre-commit-config.yaml ships in examples/.
• oasdiff checks changelog coverage shows what the checker covers (#​1174). Every possible edit to an OpenAPI document, derived mechanically from the object model (5,564 locations, 15,255 edits), with the checks that cover it or the reason it is waived. --tags filters by direction, area, kind, action and status; --patterns lists the claim patterns. Uncovered edits and stale waivers fail the build, so the coverage listing is enforced, not aspirational.

Misc

• oasdiff validate findings always carry a line and column (#​1177). duplicate-required-field and duplicate-tag reported a file with no location.
• An unsupported --template format is rejected before the specs load (#​1178), like the equivalent --color mismatch, instead of after the full diff run.
• Localization is complete and enforced (#​1202). Six response-header checks had no description in any language and one message was missing in Russian; a test now fails on any check id without a message and description in every locale.

Go package changes

• Rule metadata is public: checker/rules (#​1174). Every rule declares its Direction, Area, Kind, Effect (widens, narrows, incomparable, unknown, none, violation) and Guards, and checker.BackwardCompatibilityRule carries them. Severity is derived from that metadata by a law enforced in tests: narrowing a request or widening a response is an error, the reverse is info, undecidable is a warning. checker/metaschema (the edit-space model) and checker/coverage (the audit) are new packages.
• diff understands boolean schemas (#​1191). SchemaDiff.AlwaysDiff carries transitions of the JSON Schema boolean form, and SchemaRefsValidationEquivalent treats true as the empty schema while keeping false distinct.
• diff pairs prefixItems by index (#​1192). SchemaDiff.PrefixItemsDiff reports positional modifications instead of set-matched additions and deletions; consumers of the diff JSON see modified entries where reorders previously produced nothing. PrefixItemsValidationEquivalent reports whether two schemas validate every prefix-covered position identically (#​1200), and OneOfWrappingDiff.OriginalPreserved reports whether a oneOf wrapping keeps the base schema as an alternative (#​1174).
• Color primitives moved to a colorize package (#​1174). checker keeps type and constant aliases, so existing callers compile unchanged.
• Breaking: the unused checker/generator package is removed (#​1174).

Misc

• Builds lift to Go 1.26.7 (#​1202). The toolchain directive picks up standard-library security fixes (crypto/tls, net/url, html/template, encoding/asn1) for release binaries, go install builds and local builds alike; golang.org/x/text moves past CVE-2026-56852.

v1.29.1

Compare Source

--flatten-allof now flattens what your diff actually reads

A single-fix release: schemas reached through a $ref (the most common shape in real specs) were escaping allOf flattening entirely, so --flatten-allof often had no effect. Anyone using the flag with oasdiff breaking or changelog (via the CLI, GitHub Action, or Docker image) will see the flag start doing its job on these specs, with sharper verdicts and cleaner property paths.

CLI changes

--flatten-allof

• allOf is now merged where a schema is used, not only where it is defined (#​1154). A $ref is a separate reference sharing the definition's schema value, and the merger previously repointed only the definition's reference, leaving every use of the schema (for example schema: { $ref: '#/components/schemas/Pet' } under a response) reading the unmerged original. Since the diff traverses schemas through their uses, an allOf reached under a $ref survived --flatten-allof completely, and oasdiff breaking --flatten-allof could produce output identical to running without the flag. The merged content is now written into the schema every $ref already points at, so flattening takes effect at the point of use. Serialized output of oasdiff flatten was already correct and is unchanged.
• Expected output changes when the fix kicks in (#​1154). On specs that hit this bug, property paths lose their allOf[...] prefix (the branch is no longer part of the path), verdicts sharpen where a sibling allOf branch previously hid a change, and changes under such an allOf stop carrying the unmerged-allOf disclaimer, which had been advising users to pass a flag they had already passed. All three are the intended behaviour of the flag, now applied consistently.

v1.29.0

Compare Source

OpenAPI 3.2 streamed bodies, honest verdicts under unflattened allOf, sharper severities

oasdiff now checks the contract of streamed bodies (SSE, JSON Lines) via OpenAPI 3.2's itemSchema, tells you when a verdict rests on an allOf it could not compare exactly (and caps it at warning), reports a removed response schema as the error it always was, and stops the allOf flattener from dropping sixteen OpenAPI 3.1 keywords.

CLI changes

OpenAPI 3.2 streamed bodies (itemSchema)

• Changes to streamed item schemas are now detected (#​1139). An OpenAPI 3.2 media type can carry an itemSchema typing each item of a streamed body (an SSE event, a JSON Lines record); oasdiff previously ignored it, so a breaking change to a streamed item's contract came back clean. All existing body checks now run against the item schema as well as the body schema, with an (item schema) marker on the message so you can tell which one changed. Five new change IDs cover an item schema appearing or disappearing: request-body-media-type-item-schema-added, response-body-media-type-item-schema-removed, and response-body-media-type-item-schema-removed-untyped are errors; the reverse directions are info. docs/OPENAPI-31.md gained a 3.2 section.
• Enum and property-stability checks cover streamed items too (#​1143, #​1151). These checks were moved onto the shared media-type traversal, which also fixed a real output gap: enum changes on a body with multiple media types now say which media type they belong to, e.g. request body enum value removed 'b' (media type: application/json), instead of printing two indistinguishable lines.

Disclaimers: saying what the comparison could not see (#​1147)

• Changes inside an unflattened allOf are capped at warning, with an explanation. Without --flatten-allof, oasdiff compares allOf branches one by one, so it cannot tell whether a sibling branch still provides what one branch dropped. Such verdicts previously came out as flat errors that could vanish (or appear) when the flag was added. They are now reported at most as warnings, with an appended note naming the uncertainty and the flag that resolves it, and a disclaimers array (["all-of-not-flattened"]) in json and yaml output. A level you set explicitly via --severity-levels still wins over the cap.
• request-body-all-of-added now reports warning instead of error as a consequence: on its own fixture, --flatten-allof reports nothing, so the unconditional error was a false positive.
• The required-version-bump check follows the reported level. It previously read each rule's declared level, so a change downgraded to warning by a disclaimer still demanded a major version bump. It now reads the level actually reported for the change.

Severity correction

• Removing a response schema is now an error (#​1142). response-body-media-type-schema-removed was a warning while both the change that contains it (removing the media type) and the change it contains (removing one required property) were errors. A media type with no schema places no constraint on the body at all, so every guarantee the consumer had is gone. oasdiff breaking reports the same set of changes as before, but pipelines gating on --fail-on ERR that tolerated this will now fail, which is the point of the change.

Flatten

• Sixteen OpenAPI 3.1 keywords are no longer dropped by the allOf flattener (#​1145). unevaluatedProperties, if/then/else, dependentSchemas, and thirteen more JSON Schema 2020-12 keywords on the outer schema were silently lost from every merge, including a schema with no allOf at all, so a closed schema became open and whole validation branches disappeared from --flatten-allof comparisons. They now pass through, and oasdiff diff between a spec and its flattened output no longer reports the loss. A keyword on an allOf subschema is still not merged; docs/ALLOF.md documents that remaining limitation.

Misc

• Encrypted review uploads identify the client software (#​1138). The upload's User-Agent is now oasdiff-cli/<version> (plus the CI platform when one is declared, e.g. github-actions) instead of an unversioned oasdiff-cli. Nothing identifying is added; this names the client, not the user.

Go package changes

Disclaimers surface

• Breaking: the checker.Change interface gained GetDisclaimers() []Disclaimer (#​1147). Any external implementation of Change must add the method (returning nil is fine; ComponentChange and SecurityChange do exactly that). ApiChange carries a new Disclaimers field and a WithDisclaimers method, which is additive and de-duplicating, and the new checker.Disclaimer type serializes by name (all-of-not-flattened) in json and yaml.

Misc

• New diff.MediaTypeDiff.ItemSchemaDiff field (#​1139). A *SchemaDiff for the OpenAPI 3.2 itemSchema, serialized as itemSchema in diff output, alongside the existing SchemaDiff for the whole-body schema.

v1.28.0

Compare Source

Lower memory through a diff

A single dependency bump, to kin-openapi v0.146.0, which cuts the memory a diff holds for its whole run by about a third on large specs. No CLI or behaviour changes.

CLI changes

Memory

• A diff holds roughly a third less memory (#​1134). oasdiff loads both specs with source origins enabled, and both documents stay resident for the length of the operation, so the memory the origins occupy is a floor on the whole run rather than a spike during load. Two changes in kin-openapi v0.146.0 lower that floor: Origin.Fields became a slice, and a document's origin tree is now retained only when a $ref can actually reach into it untyped.

  Measured by loading two APIs.guru specs (11.4 MB and 10.3 MB) with origins on and reading the heap after a forced GC:

  	retained heap	total allocated
  v1.27.0	262 MB	2042 MB
  v1.28.0	179 MB	1959 MB

  Peak RSS is not meaningfully different. The saving is in what stays held, which is what matters to a long-running service holding parsed specs and to a memory-capped container, rather than to the high-water mark of a short CLI run.

Go package changes

Breaking: Origin.Fields is a slice

• openapi3.Origin.Fields is now FieldLocations, not map[string]Location (#​1134). This comes from kin-openapi v0.146.0 and reaches you through oasdiff's dependency on it. A Go caller that reads a field location by name changes from an index to a lookup:

  // before
  loc, ok := origin.Fields[name]
  // after
  loc, ok := origin.Fields.Lookup(name)

  Lookup returns the same (Location, bool) pair, so the surrounding code is unchanged. Ranging over Fields and taking its length still work. Each Location carries its own Name, which is what the lookup matches on.

  JSON and YAML output are unaffected: FieldLocations marshals as the same name-keyed object the map produced, so anything consuming oasdiff diff -f json sees no difference.

v1.27.0

Compare Source

This release adds a versioning policy, more validate lints, and reorganizes oasdiff checks into one listing per rule set.

CLI changes

Versioning policy

• A breaking change now reports the version bump it did not get. If you version your API with semver, oasdiff compares info.version on each side against the severity of the changes it found, and reports a breaking change that shipped without a major version increase. There are three ids, one per way to violate the policy: api-version-not-bumped (the version is unchanged), api-version-decreased (it moved backwards), and api-major-version-not-bumped (it moved, but not the major). All default to INFO, so nothing fails on their own; raise them to err with --severity-levels to enforce, or set them to none to switch them off (#​1133, closing #​1007, from a request by @​rethab in oasdiff-action#154). Nothing is reported unless a breaking change is present and both versions parse as semver, so specs versioned by date, by a bare v1, or not at all are left alone. Below 1.0.0 a minor bump satisfies the policy, since semver gives the minor the major's role there. See VERSIONING.md.

oasdiff checks now names its rule set

• oasdiff checks on its own prints the available listings instead of the changelog rules. There is now one listing per rule set: oasdiff checks changelog for the rules breaking and changelog apply, and oasdiff checks validate for the rules validate reports (#​1132). If you script oasdiff checks, add the changelog subcommand. The validate rules had no listing at all before this.

New validate lints

• Schema constraints that nothing can satisfy are reported as errors: minimum above maximum, and the same for minLength/maxLength, minItems/maxItems, minProperties/maxProperties and minContains/maxContains (#​1122).
• type-format-mismatch: a format that belongs to a different type is reported as a warning, since it is silently ignored at runtime, for example format: date-time on an integer (#​1120).

Severity and flag changes

• request-body-enum-value-removed is now breaking by default. Removing an enum value from a request body rejects payloads that were valid before, which is an error, not an informational note (#​1118).
• --include-checks is deprecated and ignored, and the optional-checks mechanism behind it is retired. All checks now run, and severity is the only lever. If you used --include-checks to make an optional check fail the build, it no longer does: the check now reports at its default severity, so move those ids into --severity-levels with err to keep the gate. The flag still parses and prints a notice on stderr. --flatten and --max-circular-dep are likewise deprecated, each pointing at its replacement (#​1119).

Misc

• A revision starting with a dash is no longer parsed as a git option (#​1125).
• Documented that source locations require a YAML spec (#​1129) and how to pass arguments safely from a script or CI (#​1126).
• Dependency bumps: kin-openapi 0.145.0, goldmark 1.8.5, yaml/v3 3.0.5.

Go package changes

• diff.Diff carries BaseInfo and RevisionInfo (*openapi3.Info), the info object from each spec, following the same Base/Revision convention as PathsDiff and SchemaDiff. They are populated only on a non-empty diff and excluded from JSON and YAML output, so Empty() and the diff output are unchanged (#​1133).
• New checker.InfoChange, for findings whose subject is the document rather than an endpoint. It implements checker.Change like ApiChange, ComponentChange and SecurityChange, with an empty path and operation and GetSection() == "info". Code that type-switches over change types should expect it (#​1133).
• The optional-checks API is gone with the mechanism it served: GetOptionalChecks, GetOptionalRules and the WithOptionalChecks option no longer exist, and GetAllChecks returns every check. Callers that enabled optional checks should set the severity of the ids they care about instead (#​1119).

v1.26.1

Compare Source

Security patch release. Cut directly off v1.26.0 so it contains this fix and nothing else.

CLI changes

Security: a git revision could be parsed by git as an option (GHSA-m3wq-w7x2-4q6m)

• Git revisions are no longer parsed as git options. oasdiff passed git revisions to git as operands without an end-of-options separator, so a revision beginning with - was parsed by git as an option rather than a revision. git show --output=<path> writes git's output to that path, an arbitrary file overwrite running as the invoking user, and git fetch --upload-pack=<program> makes git execute that program (reachable through the opt-in --fetch flag).

  Running oasdiff directly from a shell was not the exposed path: the CLI's own flag parser rejects a leading-dash positional. The issue was reachable after a -- separator, and, more importantly, through the Go library API, which an embedding program can call with a revision from an untrusted source, and through wrappers that pass a revision through from input or configuration.

  Fixed in two layers: every git invocation now passes --end-of-options, so git treats what follows as an operand, and a revision beginning with - is rejected before git is invoked. The second layer does not depend on the git version (--end-of-options landed in git 2.24) and produces a clear error instead of a confusing one from git. No legitimate git revision begins with -, so nothing valid is refused.

Who should upgrade: anyone calling the load package (or any oasdiff API that loads from a git revision) with a revision that is not a hardcoded literal, and anyone wrapping the CLI in a script that interpolates untrusted input into a revision argument.

Users of the oasdiff GitHub Action get this in oasdiff-action v0.1.10. If you pin the action at @v0 you already have it.

Go package changes

• New exported error load.ErrRefLooksLikeOption, returned for a git revision beginning with -.

v1.26.0

Compare Source

Response header schema checks (#​1116)

oasdiff now inspects a response header's schema, not just whether the header exists. Six new checks report type, format, and nullability changes on response headers, closing a gap where a change like Retry-After going from string/date-time to integer was silent in both breaking and changelog:

• response-header-type-changed, response-header-type-generalized (breaking)
• response-header-type-specialized, response-header-type-compatible (info)
• response-header-became-nullable (breaking), response-header-became-not-nullable (info)

A header value is text on the wire, so a response header is classified the same way a scalar parameter is: a bare string to integer swap is backward compatible (the value is still valid text), while dropping a parsed format (date-time to integer) or widening the returned type is breaking.

Note: because these are new detections, a spec with response-header type, format, or nullability changes will now surface findings that earlier versions did not, including new breaking-change errors from oasdiff breaking. Use --severity-levels to adjust any check that does not fit your API.

Thanks to @​nrutman for reporting this against a real API change (a response Retry-After header going from string/date-time to integer) in #​1094.

validate: required with a default (#​1111)

oasdiff validate now flags a parameter or property that is both required and carries a default. A default only applies when a value is omitted, so it can never take effect for a value the client is required to send. The two together are usually a mistake.

Encrypted review bundle records its origin (#​1113)

A --open review bundle now carries the oasdiff version and platform that produced it, so the review page can tell when a review was created by an outdated client.

Docs and dependencies

• The online rule catalog link now points to the consolidated breaking-changes page (#​1112).
• Bump kin-openapi to 0.144.0 (#​1115).

v1.25.1

Compare Source

A required request property with a default is now a breaking change (error)

new-required-request-property-with-default and request-property-became-required-with-default are now reported as error (breaking). In v1.25.0 they were briefly reported as warning, and before that as info.

Breaking-ness is a property of the contract your OpenAPI definition declares, not of how a lenient server behaves. A request that omits a required property is invalid under the new contract, whether or not the property has a default. The default is a server-side fallback value; it does not make the omitted property valid. Whether a particular server applies the default and accepts the request anyway is that operator's choice, and other consumers of the same contract (generated client SDKs that make the property a mandatory argument, and strict API gateways that reject the missing field) break regardless.

Each change carries a comment explaining why the default does not make it safe. If the change is safe for your specific ecosystem, downgrade exactly these checks with a severity-levels file, for example a line reading new-required-request-property-with-default info, passed via --severity-levels.

A new section, "How oasdiff decides what is breaking," has been added to the breaking-changes documentation.

Full Changelog: oasdiff/oasdiff@v1.25.0...v1.25.1

v1.25.0

Compare Source

Superseded by v1.25.1. This release briefly reported required-request-property-with-default as a warning; v1.25.1 corrects it to error. Use v1.25.1 or later.

v1.24.0

Compare Source

Richer validate, per-endpoint review blocks, kin-openapi v0.143.0

Two new validate lints (duplicate enum values, ambiguous parameter serialization), validation rule IDs now sourced from kin-openapi's stable codes, per-endpoint block extraction so the --open review scales to large specs, and correct source locations for $refs into arbitrary top-level keys. Built on kin-openapi v0.143.0.

CLI changes

validate

• New lint: duplicate enum values (#​1023, closes #​980). oasdiff validate now warns (duplicate-enum-value) when an enum lists the same value more than once. JSON Schema says enum values SHOULD be unique and kin-openapi does not reject them, so this is an oasdiff-native SHOULD-level check. It visits every schema in the document via WalkSchemas, so components, paths, webhooks, and all sub-schema keywords are covered, and the finding points at the exact JSON Pointer.
• New lint: ambiguous parameter serialization (#​1103, closes #​1055). Warns (ambiguous-parameter-serialization) when a parameter's schema type union mixes a structured type (array / object) with a scalar, e.g. type: [array, integer]. Style serialization is defined per type, so a server cannot tell whether ?token=5 is the array ["5"] or the integer 5. null is excluded from the check (it carries no serialization of its own) and two scalars are fine.
• Rule IDs now come from kin-openapi's declared codes (#​1101, #​1106). The IDs validate emits are the stable codes kin-openapi declares on each validation error, gated against a fixed registry so the public ID surface cannot drift silently on a dependency bump. Spellings are unchanged, with one refinement: two errors that previously reported the generic spec-validation-error now report their specific codes, duplicate-required-field and duplicate-tag.

--open review

• Per-endpoint block extraction for large specs (#​1068). The side-by-side review slices each change into its own structural block per endpoint, so a very large spec renders the affected operation or schema rather than the whole document. Combined with the origin fix below, a change behind a cross-file $ref, including a $ref to a schema under an arbitrary top-level key, is sliced from the file it actually lives in.

Fixes

• Correct source locations for $refs into arbitrary top-level keys (via kin-openapi v0.143.0). A $ref to a schema stored under a non-components top-level key (./schemas.yaml#/User, the Swagger-2-era "definitions bag") used to lose its origin, so a change to it was reported at the referencing operation. It now reports the schema's own file and line, in -f json sources and in the review.

Go package changes

• Dependency: kin-openapi v0.143.0 (#​1105, #​1098). Removes the exported openapi3.StringMap[V] type (an internal helper, now just map[string]V), adds T.WalkParameters, preserves origins for $refs into arbitrary top-level keys, and declares stable codes on validation errors (openapi3.CodedError, openapi3.ValidationErrorCodes()). If your Go code referenced openapi3.StringMap, switch to map[string]V.
• Modernization (#​1100, #​1096). The errors.As dispatch is converted to Go 1.26 errors.AsType, and the flatten package now walks schemas via openapi3.WalkSchemas instead of a hand-rolled traversal.

Plus routine dependency bumps (#​1099, #​1104).

v1.23.0

Compare Source

Nullability changes recognized in every form, at every level

OpenAPI has three equivalent ways to make a schema nullable: the nullable keyword (3.0), a "null" entry in the type array (3.1), and wrapping the schema in oneOf: [{type: "null"}, X], the common idiom for $ref'd schemas. oasdiff now recognizes all three as one thing and reports a single became-nullable or became-not-nullable finding, in both directions, for bodies, properties, parameters, and parameter properties. The new nullability guide explains the model, when a nullability change is breaking, and the deliberate limits.

CLI changes

• Wrapping a schema in oneOf: [{type: "null"}, X] is one INFO finding, not false breaking errors (#​1089, fixes #​1088, thanks @​katepol for the report). The wrap moves the schema one level down, so the enum used to read as removed (two false request-property-enum-value-removed errors per wrapped enum), plus pattern-removed, one-of-added, and type-generalized noise. oasdiff now proves the wrapped branch is equivalent to the original and reports one became-nullable. The recognition declines conservatively when the edit is more than a pure wrap: an already-nullable schema, a branch that also changed (the constraint reports remain), or a null branch added to a multi-branch oneOf.
• Removing the wrapper is one became-not-nullable finding (#​1092, fixes #​1091). The reverse edit used to report echoes, including a false request-property-became-enum and a false new-required-request-property. On the request side this is an error (the request no longer accepts null); on the response side it is informational, via the new response-body-became-not-nullable and response-property-became-not-nullable verdicts, which also cover the keyword and type-array forms that previously reported nothing at all on responses.
• Parameters get nullability checks (#​1093, fixes #​1017). A query, path, or header parameter flipping between type: [string, "null"] and type: string was silent in both directions, although the removal direction is breaking. New verdicts: request-parameter-became-nullable (info), request-parameter-became-not-nullable (error), and the request-parameter-property-* pair for properties of object parameters. Response headers are not covered yet (#​1094).
• Changelog output schema additions: six new rule ids (the response and parameter became-(not-)nullable families), localized in all four locales.

Go package changes

• Breaking: Formatter.RenderChangelog no longer takes version strings (#​1085). Only the HTML and markup formatters render the base and revision versions, so the versions moved into those formatters' options and off the shared interface; the other six formatters no longer carry dead parameters.
• Breaking: ComputeFingerprint moved from formatters to checker (#​1086). It computes a change's stable identity from checker.Change fields and has no formatting logic; callers that only need a fingerprint no longer depend on the output-rendering package. Call sites change from formatters.ComputeFingerprint to checker.ComputeFingerprint; output is byte-identical.
• New: ApiChange.WithSchema and the schema transitions table (#​1089, #​1092). Checkers no longer carry suppression code: a change built with WithSchema(node) is dropped automatically when a recognized schema transition at that node explains it (checker/transition_claims.go pairs each recognition with the finding kinds it claims and the rules that report it). diff.SchemaDiff gains NullableWrappingDiff.

Changelog

• 48c3e04 docs: note the response-header limitation in NULLABILITY.md (#​1094) (#​1095)
• b3a5250 feat(checker): nullability checks for parameters (#​1017) (#​1093)
• 3433af9 fix: report nullability removal as became-not-nullable (#​1091) (#​1092)
• 1e3edff fix(diff): recognize the nullable oneOf wrapping (#​1088) (#​1089)
• a5118c9 chore: apply gopls modernize suggestions (#​1087)
• 7663150 checker: move ComputeFingerprint out of formatters (#​1086)
• 1bb851f formatters: carry changelog versions only in HTML and Markup (#​1085)

v1.22.0

Compare Source

Exact source locations, an OpenAPI 3.1 allOf fix, and a published output schema

Every change reported by breaking and changelog now carries a precise source location, down to the exact field or value that changed. OpenAPI 3.1 multi-type arrays no longer fail --flatten-allof, and a new oasdiff schema command publishes a JSON Schema for the machine-readable output so CI tooling can validate against it.

CLI changes

• OpenAPI 3.1 multi-type arrays no longer fail --flatten-allof (#​1079). Any multi-type array such as type: [integer, "null"] (the idiomatic 3.1 way to express nullable) inside a schema touched by allOf merging used to fail with unable to resolve Type conflict: all Type values must be identical, even when there was no conflict at all. The merge now keeps each schema's type array intact and intersects across allOf branches: a multi-type array in a single branch passes through unchanged, identical arrays across branches merge, and integer still resolves as a subset of number. A genuinely empty intersection (e.g. [string, "null"] with [integer]) reports the same conflict error as before. Fixes #​1078 (thanks @​katepol for the report) and #​535.
• New oasdiff schema command (#​1075, thanks @​fuleinist for the request in #​1074). Prints a JSON Schema describing the --format json/yaml output of breaking and changelog, reflected directly from the output type so it cannot drift. Non-Go CI tooling can pin the schema to an oasdiff version to validate or type results. The diff JSON is intentionally not covered yet, since its from/to values are too loosely typed for a useful reflected schema.

Exact source locations

• Security changes now report a source location (#​1069). Global security, operation-level security, and component OAuth changes (api-global-security-*, api-security-*, api-security-component-oauth-*) previously appeared with no baseSource/revisionSource. They now anchor to the relevant security field or scheme. Known limitation: the two scope-added cases point at their container rather than the exact scope line, pending an upstream parser origin enhancement.
• Stability and sunset-parse changes now report a source location (#​1070). The api-stability-*, api-invalid-stability-level, and property stability changes anchor to the exact x-stability-level field, and request-parameter-sunset-parse is located consistently from both checks that emit it. With this, every checker emits a location.
• Sunset and x-extensible-enum changes point at the exact field or value (#​1073). api-sunset-* and request-parameter-sunset-* now point at the x-sunset field instead of the containing operation or parameter, and the x-extensible-enum-value-removed checks point at the exact removed value, matching how the enum checks already behave.
• Tag changes point at the tag, not the tags: field (#​1076). api-tag-removed / api-tag-added now source the specific tag entry (so removing tag security points at the - security line) and set only the side the tag exists on.

Changelog verdicts

• A loosely-typed type swap is no longer called "narrowed" or "widened" (#​1076). A body or property type change such as string to object under a loosely typed media type like application/xml is backward compatible only because everything on the wire is a string, not a genuine narrowing, yet it was reported as response-body-type-specialized ("was narrowed from string to object"). Such swaps are now rerouted to four new INFO verdicts, request-body-type-compatible, request-property-type-compatible, response-body-type-compatible, and response-property-type-compatible, worded "changed from X to Y (backward compatible)". Genuine narrowing or widening, and adding or removing the type constraint entirely, keep their existing verdicts.

Misc

• Type generalize/specialize messages now read "widened" and "narrowed" (#​1067). "The type was specialized from number to integer" becomes "was narrowed from number to integer", matching the phrasing the list-of-types messages already use, in all four locales. Message text only: the rule ids and their descriptions keep the generalize/specialize terms.
• changelog - - builds both sides from a single stdin read (#​1082). When base and revision are both -, the revision was previously loaded from the already-exhausted stdin and patched afterwards, leaving its spec version internally inconsistent and relying on the parser accepting empty input. Both sides are now constructed from one read; output is unchanged (no changes reported, exit 0).

Go package changes

• Breaking: five internal-only checker helpers are unexported (#​1072). `OperationFiel

✂ Note

PR body was truncated to here.

---

Configuration

📅 Schedule: (UTC)

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

🚦 Automerge: Enabled.

♻ Rebasing: Whenever PR is behind base branch, 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 has been generated by Mend Renovate CLI.

[Workleap IT (Infra-Workleap)]

Branch automerge failure

This PR was configured for branch automerge. However, this is not possible, so it has been raised as a PR instead.

---

• Branch has one or more failed status checks

[Copilot]

Pull request overview

This PR bumps the bundled OasDiff CLI version used by the MSBuild task to keep OpenAPI diffing behavior up to date.

Changes:

• Update the pinned Tufin/oasdiff version from 1.12.4 to 1.15.3 for the downloaded CLI binary.