Linting OpenAPI definitions with external JSON Schema references

[jeremyfiel]

I have a scenario where we are using openapi-cli to lint our OpenAPI definitions and we are using a large amount of externally referenced JSON Schema Draft-04 definitions.

Initially, I tried to lint our OAS definitions unsuccessfully because the number of errors reported for $id and $schema are unbearable and the external definitions were never linted properly. This was due to OAS not fully supporting the full implementation of any JSON Schema dialect in prior versions (3.0.x)
After some investigation and chatting with Ben Hutton (JSON Schema core lead), it appears OpenAPI 3.1.0 supports a new property jsonSchemaDialect. The behavior of this field allows definition at the top-level of your OAS definition to define which JSON draft schema should be used. The default is 2020-12 which was adopted by OAS 3.1.0. This property also allows definition of a specific draft in any defined schema throughout the document. Here's an example of that:

{
  "openapi": "3.1.0",
  "info": {
    "version": "1.0.0",
    "title": "Support for a top-level `jsonSchemaDialect` declaration",
    "description": "https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#user-content-oasjsonschemadialect"
  },
  "jsonSchemaDialect": "http://json-schema.org/draft-04/schema#",
  "servers": [
    {
      "url": "https://httpbin.org"
    }
  ],
  "paths": {
    "/anything/numbers": {
      "parameters": [
        {
          "in": "query",
          "name": "id-exclusive-required",
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema#",
            "type": "number",
            "exclusiveMinimum": 10,
            "exclusiveMaximum": 20,
            "multipleOf": 2,
            "default": 12,
            "example": 14
          },
          "required": true
        },
        {
          "in": "query",
          "name": "id-exclusive-required-schema-v4",
          "schema": {
            "type": "number",
            "minimum": 10,
            "maximum": 20,
            "exclusiveMinimum": true,
            "exclusiveMaximum": true,
            "multipleOf": 2,
            "default": 12,
            "example": 14
          },
          "required": true
        }
      ],
      "get": {
        "summary": "Number validation",
        "description": "This operation has a top-level `jsonSchemaDialect` set to abide by [JSON Schema Draft 04](https://json-schema.org/specification-links.html#draft-4).",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}

source: https://github.com/readmeio/oas-examples/blob/main/3.1/json/schema-validation-top-level.json

The most interesting part of the behavior of jsonSchemaDialect is when a sub-schema has a different dialect defined from the top-level, that schema effectively becomes a sub-document of the original definition. That means, referencing a component from the top-level schema in the sub-schema doesn't resolve. Here's a great explanation of that behavior. http://json-schema.org/blog/posts/validating-openapi-and-json-schema#supporting-multiple-dialects

The other interesting point of this behavior is now that the sub-schema is considered an external document, it's effectively the same as using a $ref to point to an external definition. This is where it becomes more interesting for us and takes me back to the original scenario of linting our OAS definitions with external JSON schema definitions. We have 1000's of extension files and schemas written in JSON Schema Draft-04 being referenced from our OAS definitions. All of our external definitions are well formed using the $schema property to define the draft in use. With OpenAPI 3.1.0 implementing JSON Schema 2020-12 as the default jsonSchemaDialect, it brings the ability to lint our external definitions where $id and $schema properties have been defined. No longer am I seeing errors by upgrading our OAS definitions to use 3.1.0.

My questions for Redoc team are:

• How does openapi lint handle OAS 3.1.0 compatibility?
• is the tool properly linting prior JSON Schema dialects as expected?
• Which dialects are supported?
• Is proper error handling in place when an undefined dialect is used?

If the tooling is properly supporting OAS 3.1.0 and also older JSON Schema dialects, we have literally resurrected years of "legacy" efforts into useful, functional schemas that can be properly linted as part of our adoption of OpenAPI into our design-first workflow.