Proposal: Native Rule Suppression Mechanism in OpenAPI

[apiarya]

Rationale

OpenAPI Specifications are commonly validated using linters, validators, or doctors to enforce best practices. These tools apply both standard and custom rules that evolve over time, introducing more refined checks. However, enforcing all rules strictly is not always practical—some violations are unavoidable due to legacy constraints or business requirements.

Current suppression mechanisms are too broad, often requiring disabling a rule entirely or ignoring an entire OpenAPI file—neither of which is feasible for APIs with operations distributed across multiple locations. A more granular approach is needed to suppress specific issues on a case-by-case basis while maintaining overall rule enforcement. Instead of fully suppressing a rule, a better alternative is to downgrade its severity, preventing it from negatively impacting the overall API score.

At present, inline rule suppression is handled using vendor extensions such as x-suppress-issues. This proposal advocates for formalizing rule suppression as an official notation in OpenAPI, providing a standardized mechanism to acknowledge and manage rule exceptions across tooling and implementations. Linters can recognize suppressions and take actions accordingly in their rule engine.

Proposed Solution

A structured mechanism like the following could be used to record and manage rule exceptions. In this example, the delete operation violates the rule no-http-verbs-in-path, but the issue cannot be resolved due to legacy constraints.

/bookings/{bookingId}/delete:
    suppress-issues:
      - ruleId: no-http-verbs-in-path
        reason: |
          This is a legacy operation that cannot be removed in this KTLO product line.
          Fixing this issue would be a breaking change.
          Exception #gov6145 approved by [email protected] on Feb 16, 2023.
        override-severity: info   
    parameters:
      - name: bookingId
        in: path
        ...
    delete:
      summary: Delete a booking
    ...

This approach ensures API quality without penalizing entire specifications for necessary legacy design choices. It provides a transparent, structured way to manage exceptions while maintaining governance, compliance, and alignment with evolving API standards.

Structure

The structure itself is open for discussion, but we propose starting with the following:

• suppress-issues – An array of rule suppressions. Multiple rules can be listed, each with its own justification.
• ruleId – The unique identifier of the rule to suppress. Optionally, * could be supported to suppress all rules for a specific case.
• reason – A detailed justification for the suppression, including why it is necessary. This can also capture organization-specific details such as who approved it, when, and under what circumstances.
• override-severity – If omitted, the issue is fully suppressed. When provided, it downgrades the severity instead of removing the issue, allowing it to be captured, recorded, and tracked externally.

References

• Disable Violation Pragmas zalando/zally#406
• Turning Sonar off for certain code

[handrews]

@apiarya Linting isn't really within the scope of the OpenAPI Specification, although obviously typical linting rules are based on the specification in some way. Why do you feel that is the OAS itself the best place to do this work? Keep in mind that our plans for the spec already exceed our volunteer capacity.

[handrews]

@apiarya to explain a bit more. I'm not against standardizing such things, I'm just asking why they should go in the main spec as opposed to a companion spec, either under the OpenAPI Initiative umbrella or elsewhere.

Historically any official fields have been defined in the OAS itself, but this feels orthogonal to OAS versioning and development in an interesting way. So it might be more beneficial to have it outside of the core OAS (although the x- prefix is inelegant, and we might want to talk about a way to relax that x- requirement for some sort of official companion spec).

[apiarya]

Yes. Companion spec may be better. Currently, I'm trying to repurpose Spectral's Overrides feature. If that works, above suppress-issues may get further reduced to...

/bookings/{bookingId}/delete:
    suppress-rules:
      - no-http-verbs-in-path
      - some-other-rule

Stay tuned.