Ignore errors settings

[jeremyfiel]

I'm using OAS3.0.3 and heavily using JSON Schema defined external references. Each of these files indicates the $schema keyword and this is not supported in 3.0.x. My linting report is showing me over 90 thousand errors for $schema is not expected here. How can I add a specific output message to the ignore list rather than the entire "spec" error. I don't want to ignore all spec errors, only this particular one.

2:3     error    spec  Property `$schema` is not expected here.

 Validation failed with 91051 errors and 705 warnings.

This is my ignore file but it's not picking up the ignore request. My intention is to lint an entire folder with the * and I want to ignore all occurrences in any folder

# This file instructs Redocly's linter to ignore the rules contained for specific parts of your API.
# See https://redoc.ly/docs/cli/ for more information.
api-library-releases/*:
  spec:
    - '#/$schema'

[adamaltman]

Is using 3.1.0 out of the question? The $schema keyword can be used with 3.1.0 as far as I recall.

Validation failed with 91051 errors

Also, I think this is a new record. :tada: (Amazing)

[jeremyfiel]

At this moment, 3.1.0 is not possible because we have a bunch of internal tooling dependencies and making that change at scale is not in our appetite for now. I'm right there with ya for using 3.1.0 though haha

I also have a discussion thread on your vs code extension repo about a similar issue. I never received a reply on that one.

re: error record. Thanks? Hahaha I'm linting the entire repo at once so the number is huge. Btw, the type tree is pretty amazing at scale. It burns through the entire repo in less than a min. (Almost 1000 definitions with hundreds of external refs) major kudos to the team. 🥳🥳

[tatomyr]

We discussed this with @RomanHotsiy and decided to try adding the $schema support for 3.0.

[RomanHotsiy]

Actually, we discussed it a little bit more.

@jeremyfiel can you use a plugin? We have a mechanism for types tree extension so you can modify/extend it from the plugin.

I'll try to prepare an example if you're interested.

[jeremyfiel]

Ya I'll take a look at the example thanks

[jeremyfiel]

Can you help me understand how to use the ignore file for wildcard? Maybe that's the easier part until you add the additional support

[jeremyfiel]

i wonder if it's possible to use wildcard on the actual value too..

i have this example where I know the api name to define the rule, but inside the path object I want to wildcard search for a term to ignore. We are generating externally referenced files on the build but the OAS definition has a $ref to the future location of this file so it's throwing an error for unresolved ref when linting. I want to ignore these particular errors.

This is the generated ignore file output

no-unresolved-refs:
    - >-
      #/paths/~1payroll~1v3~1deduction-configurations~1meta/get/responses/200/content/application~1json/schema

I want to make it a wildcard for any ref with meta in the $ref filename path

path/to/my/openapi.yaml:
  no-unresolved-refs: 
  - >-
      #paths/*meta*

[RomanHotsiy]

@jeremyfiel we don't support wildcards in ignore files unfortunately. This is a nice idea to consider.

I think we need to support a way to append to the ignore file. Because right now it rewrites the file on every run. I'll prepare you a short example on type tree extension tomorrow.

[jeremyfiel]

i agree, append will be a nice addition.

thanks Roman. have a nice evening

[RomanHotsiy]

Follow the custom plugins docs and use the following types extension: https://redocly.com/docs/cli/resources/custom-rules/#type-extensions-in-plugins

module.exports = {
  id: 'my-plugin-id',
  typeExtension: {
    oas3(types) {
      // modify types here
      return {
        ...types,
        Schema: {
          ...types.Schema,
          properties: {
            ...types.Schema.properties,
            $schema: { type: 'string' }
          }
        }
      };
    },
  }
};

Let me know if this works.

[adamaltman]

@jeremyfiel let us know if this works for you.

I think this could be some good content too.

[jeremyfiel]

i still have this on my backlog, I haven't tried it out yet.

[xavianaxw]

I've given this a go since I had a similar scenario. Here is the code that I've used.

module.exports = {
  id: 'extend-id-and-schema',
  typeExtension: {
    oas3(types) {
      return {
        ...types,
        Schema: {
          ...types.Schema,
          properties: {
            ...types.Schema.properties,
            $id: { type: 'string' },
            $schema: { type: 'string' }
          }
        }
      };
    },
  }
};

which I then added to my .redocly.yaml

plugins: 
  -  src/schemata/plugins/extend-id-and-schema.js

Bonus content. I've also added an example below to depict how one would make $id and $schema required in your Operation > 200 only Responses > Schema

apis:
  main@v1:
    rules:
      assert/required-id-and-schema:
        where:
          - subject: 
              type: Operation
              property: operationId
            assertions: 
              pattern: ^((?!(smoke|health)).)*$ # this are some internal endpoints that I excluded 
          - subject:
              type: Response
              filterInParentKeys:
                - '200'
            assertions: 
              defined: true
        subject: 
          type: Schema
        assertions:
          defined: true
          required: 
            - $id
            - $schema
        message: Must have $id and $schema in Schema properties
        severity: error

Hope that helps someone :)

[adamaltman]

@bandantonio it would be great to turn this into a guide.

[lornajane]

This is brilliant but I don't think it needs further action from our side so I'll close the issue.