387 suppressed breaking changes in oasdiff — is there a plan to resolve the backlog?

[infracore]

I noticed the API v2 breaking change workflow uses oasdiff with an error ignore file (.github/oasdiff-err-ignore.txt) that currently has 387+ suppressed items. Most of these look like they came from the webhook trigger refactor and schema union changes.

I'm building an OAuth integration against the v2 API and the breaking change detection workflow gave me confidence to build against it. But when I looked at the ignore file, I realized a significant number of changes that would normally be classified as breaking are being whitelisted rather than versioned.

Some examples that concerned me as a consumer:

• Webhook trigger enum removals (my integration subscribes to specific triggers)
• Schema type transformations from string to array
• Response property additions via oneOf unions that change parsing behavior

From the outside it's hard to tell which of these are genuinely safe for consumers and which are "we needed to ship and suppressed the warning." Is there a plan to work through this backlog — either by bumping the API version, documenting the migration path for affected consumers, or splitting the ignore file into "reviewed safe" vs "needs resolution"?

For context, I've been looking at how other projects handle this. Some use tools that classify breaking changes by impact level (affecting all consumers vs. edge cases) and generate migration guides automatically. That might help triage the 387 items faster than manual review.

Appreciate the transparency of having the oasdiff workflow at all — most projects don't even get that far. Just want to understand the roadmap for the backlog as someone building against the API.

[CodeBySayak]

Thanks for raising this — this is a really important concern for API consumers.
I’d be interested in helping here, especially around improving visibility and reducing the backlog in the oasdiff ignore file.
A possible approach could be:

• Categorizing ignored entries into:
  • verified safe changes
  • potentially breaking / needs review
• Adding structure or annotations to the ignore file
• Proposing a clearer strategy for versioning or migration documentation
  I can start by auditing a subset of entries and proposing an initial classification to make this more manageable.
  Happy to proceed in this direction and iterate based on maintainer feedback.

[TanmayChaurasia24]

Hey @CodeBySayak , are you working on this issue?

[infracore]

@CodeBySayak the three-bucket split sounds right to me, especially separating "verified safe" from "needs review" so the file stops being a single opaque blob. Happy to help sanity-check entries from the consumer side once you have a first pass, or pair on any that are ambiguous.

Concretely, the three patterns that made me open the issue were webhook trigger enum removals, schema type transformations from string to array, and response property additions via oneOf unions. Those feel like "potentially breaking" rather than "verified safe" from a consumer perspective, since an OAuth integration subscribing to specific webhook triggers or parsing response fields would break silently on any of them. Could be a useful seed for the classification pass.

One process thought that might make future audits easier: dated suppressions with a one-line "# YYYY-MM reason" comment would let the file self-drain over time, since right now there is no way to tell which entries are recent intentional choices vs. legacy ones nobody remembers.

@TanmayChaurasia24 from where I sit, CodeBySayak has offered to lead the audit and that seems right. Happy to contribute consumer-side test cases and review PRs against whatever classification lands.

One question for the folks closest to this: @romitg2 quick question on the webhook-triggers string-to-array fix in #28288 — was that a one-off schema correction, or part of a broader pass where webhook-related types were wrong across the API? I'm trying to figure out whether I should be treating other webhook payload fields as suspect too, or whether that one was an isolated case. And @supalarry since you set up the breaking change CI workflow (#24999), would you accept a PR that restructures oasdiff-err-ignore.txt into categorized sections with inline justifications, as a no-op refactor before any entries are actually removed? Knowing the preferred format up front would let @CodeBySayak's audit land cleanly in one pass.