Can I disable a rule violation (one time) in the source file?

Can I disable a rule in my source file so that a specific violation is not flagged, but not disable the rule globally in my rule set?

For example, consider the rule

operation-2xx-response: Operation must have at least one `2xx` response. 

We have a couple (rare) operations which are documented to return a 302 or other redirect; these operations never return a 200. (I don’t want to add a 2xx response to the OpenAPI definition just to quiesce this specific rule violation - that would be misleading.

I’d like to add a source annotation on the operation, such as

x-spectral-disabled: [ operation-2xx-response ]

as a means of turning off the rule violation. (This will help support our goal of “spectral clean” APi definition documents.)

Hey!
Yes, it’s totally possible.
We’ve added exceptions recently.
You can learn more about them in our documentation.
Let me know if you have any questions, happy to help further.

1 Like

Thanks.
I’ll give this a try.
I would like to suggest an OpenAPI source option as I suggested, as changing the rule set file for each API definition document does not work well for our pipeline. We have one ruleset file that we run in our CI environment as part of a “lint” job and we use a single managed rule set. So updating the rule set to add exceptions means updating the tool chain - this is not a clean separation of concerns (in my mind, the tool should not know about individual targets)

We can probably work out something where each source file manages a rule set fragment in its own repo and the tool then merges the global rule set with the local fragment. It looks like I can pass an array file rule set locations:

loadRuleset(uris: string[] | string, options?: IRulesetReadOptions): Promise<void>;

So I can have a main (centrally managed) rule set with rules: and then each repo can have a side file with just except in it, for example.
Do all the rule sets passed in have to be complete, or can they be partial like this?
Is there doc on how rule sets are combined? I.e. do later rulesets in the array override matching rules/options defined by earlier ones? (Merging YAML/JSON is somewhat easy for objects, but not for arrays, nor does merging provide a way to remove values)

Suggestion: add some doc to the public Javascript API :slight_smile:

There’s no need to update the CI chain as you don’t need to update the ruleset, you simply update your project specific ruleset using extends.

If your organization-wide ruleset is:

extends: spectral:oas

rules:
  # all your custom stuff

Then your project specific ruleset is:

extends: https://acme.org/ruleset.yaml

except:
  "subfolder/one.yaml#":
    - oas3-api-servers
  "/tmp/docs/one.yaml#/info":
    - info-contact
    - info-description

Then your exceptions are where they should be, in the repo with the files they’re describing. :slight_smile:

And yep, the JavaScript API will be getting a whole lot of love in future versions, you currently need to know far too much about the internals to use it. As we simplify the API we’ll extend the docs too, getting everything covered without writing 4395043545803458 words on it.

Hmm, I’ll have to figure out how to do what I want. We’re embedding the ruleset in the pipeline (i.e. building on top of and abstracting away Spectal from the user), and not publishing the ruleset for extension (yet). What is the behavior of passing multiple rule sets to the JavaScript API? (Is not not equivalent to merging, or are they processed independently/sequentially?)