Resolve "reference resolves to more than one schema" errors when AJV processes OpenAPI document and encounters unknown properties whose values include an id parameter.

[mdwheele]

Hello!

💁‍♂️ This PR addresses an issue with how AJV processes attributes that are outside of JSON Schema and are objects with an id parameter (which is treats as a special case).

Background

When someone uses Stoplight Studio to manage their OpenAPI specification, the editor injects x-stoplight attributes into various objects in order to create a link between the document and the editor. This x-stoplight attribute can look something like this:

components:
  schemas:
    Bear:
      title: Bear
      x-stoplight:
        id: ug68n9uynqll0
      <snip>

Referencing this schema in an Operation causes the middleware to throw an exception from AJV that looks something like this:

Error: reference "ug68n9uynqll0" resolves to more than one schema

When you dig into AJV internals, you see that when AJV does not know about a particular OpenAPI specified property (beyond JSON Schema), it will treat id as a special case and does a validation step to make sure identifiers are not duplicated. There are other examples of this happening in Spectral where a user reports that duplicate id parameters in examples cause the same issue.

Their solution was to "de-examplify" the document before handing off to AJV; stripping examples from the document entirely for purposes of validation and error reporting in their tool.

So I went about this the same way!

This PR strips x-stoplight values from the OpenAPIV3.Document any time createAjv is used. Admittedly, this is fairly ham-handed and you may have a better way of getting AJV to "chill out". However, this does work as expected and I imagine for folks using Stoplight, alleviates a headache moving to 5.x+ of this package.

Hehe, in fact, one of our projects is on the 4.x branch and I only became aware of this because two of my colleagues started a new project on 5.x, which upgrades AJV to 8.x.

[mdwheele]

Hello! Do we think this approach might be mergeable in the interim while ajv is patched to avoid this issue? As an alternative to this, users could also pre-process the document before passing to EOV.

Any user that wishes to use the latest version of express-openapi-validator along with Stoplight Studio (seemingly, the de facto visual editor for OpenAPI documents) would be impacted by this issue.