Configurable rules: can't target named schema in subject
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 1.5k
- Forks
- 228
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 48
Description
Motivation
I'm ultimately to write a configurable rule to check that all SchemaProperties are in kebab-case with some exceptions. I thought that I could do this by using some combination of where and filterInParentKeys, but I'm running into unexpected issues. I'm not sure if it's a bug or my misunderstanding.
Here's a pared down version of my schema, defined under components.schemas as a named schema:
MySchema:
type: object
properties:
id:
type: string
badKeyA:
type: object
properties:
valid-key-a:
type: object
properties:
valid-key-b:
type: string
headers:
type: object
properties:
Accept:
type: string
User-Agent:
type: string
badKeyC:
type: string
badKeyB:
type: string
format: date-time
I'd like to write a rule to validate that every schema property in my entire spec is in kebab-case except anything under headers for this specific schema only.
Attempts and Issues
So, to start, this "works", in the sense that it doesn't return a validation error for the Accept or User-Agent properties and it does return one for all the badKeys.
rule/my-schema-kebab-case:
where:
- subject:
type: Schema
filterOutParentKeys:
- headers
assertions:
defined: true
subject:
type: SchemaProperties
assertions:
casing: kebab-case
However, what if I have header keys in other schemas that I do want to validate case within? So, I attempted to write a rule that targeted only MySchema:
rule/my-schema-kebab-case:
where:
- subject:
type: Schema
filterInParentKeys:
- MySchema
assertions:
defined: true
subject:
type: SchemaProperties
assertions:
casing: kebab-case
This, inexplicably to me, does not work. Running lint says my schema is valid. However, running lint with this rule (changing MySchema to badKey), tells me that badKeyB is invalid:
rule/my-schema-kebab-case:
where:
- subject:
type: Schema
filterInParentKeys:
- badKey
assertions:
defined: true
subject:
type: SchemaProperties
assertions:
casing: kebab-case
Expected behavior
Since the node type for MySchema and badKey are both Schema, I would expect targeting MySchema as a parent key to work similar to how I can target badKey. In the case where I filter by the parent key MySchema, I would expect the output of lint to at least tell me that badKey is invalid.
OpenAPI version
3.1.0
Redocly Version(s)
1.2.0
Node.js Version(s)
v16.15.1
Additional Notes
I tried to keep this mostly focused on the one problem of not being able to target MySchema as a parent key, but I would greatly appreciate any general help on writing the rule(s) that I ultimately want!
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at the lint rule evaluation path for filterInParentKeys and reproduce the supplied OpenAPI 3.1 example with the MySchema and badKey variants. Trace how named schemas and nested schema nodes are selected; done means MySchema selects its nested properties while equivalent keys in other schemas remain unaffected.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, typescript
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100