Question about `ibm-operationid-naming-convention` change – possible breaking impact

[tomo-kn]

First of all, thank you for providing this useful tool.

In PR #757, the rule ibm-operationid-naming-convention was described as “extended.” However, in our project this update causes many existing operationIds to fail validation unless we rename them, which feels like a breaking change rather than a simple extension.

What we confirmed

• PR feat(ibm-operationid-naming-convention): extend operationid naming check #757 was merged into main on 2025-08-27.
• According to the semantic-release bot comment, the change is included in @ibm-cloud/openapi-ruleset 1.32.0 and ibm-openapi-validator 1.36.0.

Impact

• We apply ibm-operationid-naming-convention at error severity.
• With this update, we now have to rename a large number of existing operationIds just to make CI pass.

Requests / Questions

1. Compatibility mode or option

   • For example:

     • A “legacy” mode to preserve previous behavior
     • Toggles to selectively disable stricter parts (noun inference, singular/plural checks, verb set, etc.)

2. Migration guide

   • Concrete before/after examples of operationId
   • Clear explanation of rule logic (noun extraction, plural rules, allowed verbs)
   • Guidance for bulk-renaming or codemod scripts

3. Release notes clarification

   • Since this breaks existing specs, should it be treated as major rather than minor?
   • At minimum, a changelog note highlighting “may cause existing specs to fail” would be very helpful.

Current workaround

• For stability, we pinned versions:

  • ibm-openapi-validator to 1.35.3 (pre-change)
  • or @ibm-cloud/openapi-ruleset to 1.31.2

• But for long-term we would really appreciate either a compatibility option or a migration guide.

Thanks again for your great work on this project, and we’d appreciate your guidance on how best to handle this change.

[pyrooka]

First off, thank you for the feedback @tomo-kn! We appreciate both the detailed write-up and the suggestions. We'll evaluate them and discuss the strategy for addressing this within the team.

As an early opinion: I think a configurable option would be the simplest and safest solution in the long run. We already have rules that can be configured, like this one. But we need to investigate it if's feasible or not, so can't say anything for sure right now. I'll get back to you in a few days, but feel free to leave a comment if there is anything else.

Also, we didn't consider this as a breaking change, because the rule where this is implemented has a warning severity by default. It wouldn't be possible to take all possible user configurations into account, so we mainly focus on the defaults - but of course we try to maintain compatibility as much as possible. Furthermore, our custom IBM rules are follow the guidance of the API Handbook.

[tomo-kn]

@pyrooka
Thanks a lot for the detailed response. I really appreciate that you and the team are taking the time to evaluate this.
I understand your point about considering the defaults and not treating this as a breaking change.
Looking forward to hearing back once you’ve had a chance to discuss feasibility.
Thanks again!

[pyrooka]

In the meantime we improved the logic around the discussed rule in commit 67a2f97. Starting from current latest release, the ibm-operationid-naming-convention rule can be configured to skip the "stricter" naming convention check. See the docs for the config option here.
Feel free to share your feedback!

[tomo-kn]

Thanks! I’ll take a look and share my feedback next Monday.

It might take me a little longer than expected — I’ll share my feedback when it’s ready. Appreciate your patience!

[tomo-kn]

@pyrooka
Sorry for the late reply.
Setting strict: false fixed the validation issue!
Thank you so much for your quick support!

[pyrooka]

No problem at all, thanks for the response! And I'm glad the fix worked out well.