Skip to content

Commit 99c3c8f

Browse files
authored
docs(repo): explain $refs caveat with overrides (#2127)
1 parent 7000ac2 commit 99c3c8f

File tree

1 file changed

+68
-0
lines changed

1 file changed

+68
-0
lines changed

docs/guides/4-custom-rulesets.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -454,3 +454,71 @@ overrides:
454454
```
455455

456456
In the event of multiple matches, the order of definition takes place, with the last one having the higher priority.
457+
458+
### Caveats
459+
460+
Please bear in mind that overrides are only applied to the _root_ documents. If your documents have any external dependencies, i.e. $refs, the overrides won't apply.
461+
462+
**Example:**
463+
464+
Given the following 2 YAML documents
465+
466+
```yaml
467+
# my-document.yaml
468+
openapi: "3.1.0"
469+
paths: {}
470+
components:
471+
schemas:
472+
User:
473+
$ref: "./User.yaml"
474+
```
475+
476+
```yaml
477+
# User.yaml
478+
title: ""
479+
type: object
480+
properties:
481+
id:
482+
type: string
483+
required:
484+
- id
485+
```
486+
487+
and the ruleset below
488+
489+
```json
490+
{
491+
"rules": {
492+
"empty-title-property": {
493+
"message": "Title must not be empty",
494+
"given": "$..title",
495+
"then": {
496+
"function": "truthy"
497+
}
498+
}
499+
},
500+
"overrides": [
501+
{
502+
"files": ["User.yaml"],
503+
"rules": {
504+
"empty-title-property": "off"
505+
}
506+
}
507+
]
508+
}
509+
```
510+
511+
running `spectral lint my-document.yaml` will result in
512+
513+
```
514+
/project/User.yaml
515+
1:8 warning empty-title-property Title must not be empty title
516+
517+
✖ 1 problem (0 errors, 1 warning, 0 infos, 0 hints)
518+
```
519+
520+
while executing `spectral lint User.yaml` will output
521+
522+
```
523+
No results with a severity of 'error' or higher found!
524+
```

0 commit comments

Comments
 (0)