OpenAPI 3.1 - contextfull dereferencing and document boundaries

[char0n]

Here is graph of various documents where root of the document graph if OpenAPI 3.1 document.

root.yml

openapi: "3.1.0"
info:
  version: 1.0.0
  title: Swagger Petstore
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    $ref: "./pets/pets.yml"

pets/pets.yml

get:
  operationId: listPets
  responses:
    "200":
      $ref: "./response.yml"

pets/response.yml

content:
  application/json:
    schema:
      $ref: "./def.yml#/components/schemas/Pet"
  application/yaml:
    schema:
      $ref: "./def3.yml#Pet"

pets/def.yml

components:
  schemas:
    Pet:
      $ref: "./def2.yml#/components/schemas/Pet"

pets/def2.yml

components:
  schemas:
    Pet:
      type: number

pets/def3.yml

$defs:
  Pet:
    $anchor: Pet
    type: number

Deferencing

After the root document is dereferenced and all referenced are transcluded with referenced document fragments, it should look like this:

  {
    "openapi": "3.1.0",
    "info": {
      "title": "Swagger Petstore",
      "version": "1.0.0"
    },
    "paths": {
      "/pets": {
        "get": {
          "operationId": "listPets",
          "responses": {
            "200": {
              "content": {
                "application/json": {
                  "schema": {
                    "type": "number"
                  }
                },
                "application/yaml": {
                  "schema": {
                    "$anchor": "Pet",
                    "type": "number"
                  }
                }
              }
            }
          }
        }
      }
    },
    "servers": [
      {
        "url": "http://petstore.swagger.io/v1"
      }
    ]
  }

Dereferencing - JSON pointer

When there is JSON Schema reference $ref: "./def.yml#/components/schemas/Pet" which contains JSON Pointer, what we do is we parse the def.yml and evaluate the JSON Pointer on parsed generic ApiDOM. The result of evaluation is then refracted to JSON Schema Element and returned.

Dereferencing - JSON Schema anchor

When there is JSON Schema anchor $ref: "./def3.yml#Pet" which contains anchor, what we do is we parse the def3.yml and refract it whole to semantic ApiDOM (JSON Schema Element). Then we evaluate the anchor on semantic ApiDOM. The result of evaluation is then returned.