[RFC] Teach overrides to honor JSON Pointers

[nulltoken]

Potential laxer locations syntaxes have been evoked in #939 and eventually dropped out to keep the PR on scope.

This issue is a placeholder to gather feedback, use cases and try and measure how important allowing less strict locations would be.

From #939 (comment)

Current location syntax is: <source>#<pointer> where

• source can be expressed as
  • an absolute uri (file or http based)
  • relatively to the to the rulesepath uri
• pointer is a Json pointer (cf. https://tools.ietf.org/html/rfc6901) describing the precise document path that should be ignored

Latest update to the proposal was to allow a more open location syntax where

• <source> could be optional feat(ruleset): optional source for exceptions #1423
• #<pointer> could be optional feat(ruleset): optional pointer for exceptions #1405
• at least one of them should be described feat(ruleset): optional source for exceptions #1423
• <pointer> meaning would change

Samples:

• models/awful.json: [ rule1, rule2]: Would ignore rule1 and rule2 results wheverever in the file
• #/info": [rule1, rule2]: Would ignore rule1 and rule2 results in any processed document provided they originate from a path that's #/info or below (eg. #/info/sub/path/1). This would be in line with @P0lip's comment

[marcoemidio]

hi @nulltoken

I'm trying the "except" funcionality, and this issue might solve some problems I'm facing, or perhaps there is already a solution that I'm not aware.

Assuming I have an openAPI2 specification and want to ignore errors from a given rule, e.g., oas2-valid-definition-example or no-$ref-siblings, inside a specific schema, like "/x-configuration-example/definitions".

Is it possible to achieve this in the current version, or this RFC will try to deal with this behaviour?

Thanks

[nulltoken]

Assuming I have an openAPI2 specification and want to ignore errors from a given rule, e.g., oas2-valid-definition-example or no-$ref-siblings, inside a specific schema, like "/x-configuration-example/definitions".

Is it possible to achieve this in the current version,

@marcoemidio I'd be happy to take a look at your issue, but I'm unsure to precisely understand the use case.
Could you please create a dedicated issue with a simple repro case?

[marcoemidio]

@marcoemidio I'd be happy to take a look at your issue, but I'm unsure to precisely understand the use case.
Could you please create a dedicated issue with a simple repro case?

Hi again @nulltoken,

I managed to use the except functionality but only when I give full JSON pointer path but not for sub paths. In the second sample you provided, this is possible:

• #/info": [rule1, rule2]: Would ignore rule1 and rule2 results in any processed document provided they originate from a path that's #/info or below (eg. #/info/sub/path/1). This would be in line with @P0lip's comment

My example:

extends: spectral:oas

except:
 "#/foo/bar": 
   - no-$ref-siblings

I can't ignore no-$ref-siblings in sub paths, like your example.
Am I missing something? I'm using latest version, 5.8.1.

Thank you for your help and keep it up!

[philipbjorge]

It would be useful for me if source could be expressed as a wildcard.
For example, descriptions/v1/*_api.yaml

We have OpenAPI specifications split apart conceptually for the purpose of our documentation rendering and then we combine them into a single file during a build stage. This would let me easily apply some laxer rules to the split apart specifications and apply a stricter ruleset to the combined file.

I suppose an alternative way to suffice this usecase might be to default to the lax ruleset and apply a stricter ruleset to the final document but it doesn't look like except supports that (specifically for disabling rules).

[ariatron]

@mnaumanali94 Wanting to get your review of this request.

[mnaumanali94]

@ariatron This has been added to the scope for v6! 🙏

[stoplight-bot]

🎉 This issue has been resolved in version @stoplight/spectral-core-v1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀