Redocly / Redocly/redocly-cli

Configurable rules: can't target named schema in subject

Open
#1,301 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

configurable rules governance question Type: Bug
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.