Add support for OpenAPI 3.2 schema dialect

Author: jdesrosiers

lib/openapi.js

@@ -3,6 +3,7 @@ import { addMediaTypePlugin } from "@hyperjump/browser";
 import { buildSchemaDocument } from "./schema.js";
 
 
+const is32 = RegExp.prototype.test.bind(/^3\.2\.\d+(-.+)?$/);
 const is31 = RegExp.prototype.test.bind(/^3\.1\.\d+(-.+)?$/);
 const is30 = RegExp.prototype.test.bind(/^3\.0\.\d+(-.+)?$/);
 
@@ -34,6 +35,22 @@ addMediaTypePlugin("application/openapi+json", {
       } else {
         defaultDialect = `https://spec.openapis.org/oas/3.1/schema?${encodeURIComponent(doc.jsonSchemaDialect)}`;
       }
+    } else if (is32(version)) {
+      if (!("jsonSchemaDialect" in doc) || doc.jsonSchemaDialect === "https://spec.openapis.org/oas/3.2/dialect/base") {
+        defaultDialect = "https://spec.openapis.org/oas/3.2/schema-base";
+      } else if (doc.jsonSchemaDialect === "https://json-schema.org/draft/2020-12/schema") {
+        defaultDialect = `https://spec.openapis.org/oas/3.2/schema-draft-2020-12`;
+      } else if (doc.jsonSchemaDialect === "https://json-schema.org/draft/2019-09/schema") {
+        defaultDialect = `https://spec.openapis.org/oas/3.2/schema-draft-2019-09`;
+      } else if (doc.jsonSchemaDialect === "http://json-schema.org/draft-07/schema#") {
+        defaultDialect = `https://spec.openapis.org/oas/3.2/schema-draft-07`;
+      } else if (doc.jsonSchemaDialect === "http://json-schema.org/draft-06/schema#") {
+        defaultDialect = `https://spec.openapis.org/oas/3.2/schema-draft-06`;
+      } else if (doc.jsonSchemaDialect === "http://json-schema.org/draft-04/schema#") {
+        defaultDialect = `https://spec.openapis.org/oas/3.2/schema-draft-04`;
+      } else {
+        defaultDialect = `https://spec.openapis.org/oas/3.2/schema?${encodeURIComponent(doc.jsonSchemaDialect)}`;
+      }
     } else {
       throw Error(`Encountered unsupported OpenAPI version '${version}' in ${response.url}`);
     }

openapi-3-2/dialect/base.js

@@ -0,0 +1,22 @@
+export default {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$vocabulary": {
+    "https://json-schema.org/draft/2020-12/vocab/core": true,
+    "https://json-schema.org/draft/2020-12/vocab/applicator": true,
+    "https://json-schema.org/draft/2020-12/vocab/unevaluated": true,
+    "https://json-schema.org/draft/2020-12/vocab/validation": true,
+    "https://json-schema.org/draft/2020-12/vocab/meta-data": true,
+    "https://json-schema.org/draft/2020-12/vocab/format-annotation": true,
+    "https://json-schema.org/draft/2020-12/vocab/content": true,
+    "https://spec.openapis.org/oas/3.2/vocab/base": false
+  },
+  "$dynamicAnchor": "meta",
+
+  "title": "OpenAPI 3.2 Schema Object Dialect",
+  "description": "A JSON Schema dialect describing schemas found in OpenAPI v3.2 Descriptions",
+
+  "allOf": [
+    { "$ref": "https://json-schema.org/draft/2020-12/schema" },
+    { "$ref": "https://spec.openapis.org/oas/3.2/meta/base" }
+  ]
+};

openapi-3-2/index.d.ts

@@ -0,0 +1,91 @@
+import type { Json } from "@hyperjump/json-pointer";
+import type { JsonSchemaType } from "../lib/common.js";
+
+
+export type OasSchema32 = boolean | {
+  $schema?: "https://spec.openapis.org/oas/3.2/dialect/base";
+  $id?: string;
+  $anchor?: string;
+  $ref?: string;
+  $dynamicRef?: string;
+  $dynamicAnchor?: string;
+  $vocabulary?: Record<string, boolean>;
+  $comment?: string;
+  $defs?: Record<string, OasSchema32>;
+  additionalItems?: OasSchema32;
+  unevaluatedItems?: OasSchema32;
+  prefixItems?: OasSchema32[];
+  items?: OasSchema32;
+  contains?: OasSchema32;
+  additionalProperties?: OasSchema32;
+  unevaluatedProperties?: OasSchema32;
+  properties?: Record<string, OasSchema32>;
+  patternProperties?: Record<string, OasSchema32>;
+  dependentSchemas?: Record<string, OasSchema32>;
+  propertyNames?: OasSchema32;
+  if?: OasSchema32;
+  then?: OasSchema32;
+  else?: OasSchema32;
+  allOf?: OasSchema32[];
+  anyOf?: OasSchema32[];
+  oneOf?: OasSchema32[];
+  not?: OasSchema32;
+  multipleOf?: number;
+  maximum?: number;
+  exclusiveMaximum?: number;
+  minimum?: number;
+  exclusiveMinimum?: number;
+  maxLength?: number;
+  minLength?: number;
+  pattern?: string;
+  maxItems?: number;
+  minItems?: number;
+  uniqueItems?: boolean;
+  maxContains?: number;
+  minContains?: number;
+  maxProperties?: number;
+  minProperties?: number;
+  required?: string[];
+  dependentRequired?: Record<string, string[]>;
+  const?: Json;
+  enum?: Json[];
+  type?: JsonSchemaType | JsonSchemaType[];
+  title?: string;
+  description?: string;
+  default?: Json;
+  deprecated?: boolean;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  examples?: Json[];
+  format?: "date-time" | "date" | "time" | "duration" | "email" | "idn-email" | "hostname" | "idn-hostname" | "ipv4" | "ipv6" | "uri" | "uri-reference" | "iri" | "iri-reference" | "uuid" | "uri-template" | "json-pointer" | "relative-json-pointer" | "regex";
+  contentMediaType?: string;
+  contentEncoding?: string;
+  contentSchema?: OasSchema32;
+  example?: Json;
+  discriminator?: Discriminator;
+  externalDocs?: ExternalDocs;
+  xml?: Xml;
+};
+
+type Discriminator = {
+  propertyName: string;
+  mappings?: Record<string, string>;
+};
+
+type ExternalDocs = {
+  url: string;
+  description?: string;
+};
+
+type Xml = {
+  name?: string;
+  namespace?: string;
+  prefix?: string;
+  attribute?: boolean;
+  wrapped?: boolean;
+};
+
+// TODO: Fill in this type when 3.2 is published
+export type OpenApi32 = unknown;
+
+export * from "../lib/index.js";

openapi-3-2/index.js

@@ -0,0 +1,49 @@
+import { addKeyword, defineVocabulary } from "../lib/keywords.js";
+import { registerSchema } from "../lib/index.js";
+import "../lib/openapi.js";
+
+import dialectSchema from "./dialect/base.js";
+import vocabularySchema from "./meta/base.js";
+import schema from "./schema.js";
+import schemaBase from "./schema-base.js";
+import schemaDraft2020 from "./schema-draft-2020-12.js";
+import schemaDraft2019 from "./schema-draft-2019-09.js";
+import schemaDraft07 from "./schema-draft-07.js";
+import schemaDraft06 from "./schema-draft-06.js";
+import schemaDraft04 from "./schema-draft-04.js";
+
+import discriminator from "../openapi-3-0/discriminator.js";
+import example from "../openapi-3-0/example.js";
+import externalDocs from "../openapi-3-0/externalDocs.js";
+import xml from "../openapi-3-0/xml.js";
+
+
+export * from "../draft-2020-12/index.js";
+
+addKeyword(discriminator);
+addKeyword(example);
+addKeyword(externalDocs);
+addKeyword(xml);
+
+defineVocabulary("https://spec.openapis.org/oas/3.2/vocab/base", {
+  "discriminator": "https://spec.openapis.org/oas/3.0/keyword/discriminator",
+  "example": "https://spec.openapis.org/oas/3.0/keyword/example",
+  "externalDocs": "https://spec.openapis.org/oas/3.0/keyword/externalDocs",
+  "xml": "https://spec.openapis.org/oas/3.0/keyword/xml"
+});
+
+registerSchema(vocabularySchema, "https://spec.openapis.org/oas/3.2/meta/base");
+registerSchema(dialectSchema, "https://spec.openapis.org/oas/3.2/dialect/base");
+
+// Current Schemas
+registerSchema(schema, "https://spec.openapis.org/oas/3.2/schema");
+registerSchema(schema, "https://spec.openapis.org/oas/3.2/schema/latest");
+registerSchema(schemaBase, "https://spec.openapis.org/oas/3.2/schema-base");
+registerSchema(schemaBase, "https://spec.openapis.org/oas/3.2/schema-base/latest");
+
+// Alternative dialect schemas
+registerSchema(schemaDraft2020, "https://spec.openapis.org/oas/3.2/schema-draft-2020-12");
+registerSchema(schemaDraft2019, "https://spec.openapis.org/oas/3.2/schema-draft-2019-09");
+registerSchema(schemaDraft07, "https://spec.openapis.org/oas/3.2/schema-draft-07");
+registerSchema(schemaDraft06, "https://spec.openapis.org/oas/3.2/schema-draft-06");
+registerSchema(schemaDraft04, "https://spec.openapis.org/oas/3.2/schema-draft-04");

openapi-3-2/json-schema-test-suite.spec.ts

@@ -0,0 +1,113 @@
+import fs from "node:fs";
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { toAbsoluteIri } from "@hyperjump/uri";
+import { registerSchema, unregisterSchema, validate } from "./index.js";
+
+import type { Json } from "@hyperjump/json-pointer";
+import type { OasSchema32, Validator } from "./index.js";
+
+
+type Suite = {
+  description: string;
+  schema: OasSchema32;
+  tests: Test[];
+};
+
+type Test = {
+  description: string;
+  data: Json;
+  valid: boolean;
+};
+
+// This package is indended to be a compatibility mode from stable JSON Schema.
+// Some edge cases might not work exactly as specified, but it should work for
+// any real-life schema.
+const skip = new Set<string>([
+  // Self-identifying with a `file:` URI is not allowed for security reasons.
+  "|draft2020-12|ref.json|$id with file URI still resolves pointers - *nix",
+  "|draft2020-12|ref.json|$id with file URI still resolves pointers - windows"
+]);
+
+const shouldSkip = (path: string[]): boolean => {
+  let key = "";
+  for (const segment of path) {
+    key = `${key}|${segment}`;
+    if (skip.has(key)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+const testSuitePath = "./node_modules/json-schema-test-suite";
+
+const addRemotes = (dialectId: string, filePath = `${testSuitePath}/remotes`, url = "") => {
+  fs.readdirSync(filePath, { withFileTypes: true })
+    .forEach((entry) => {
+      if (entry.isFile() && entry.name.endsWith(".json")) {
+        const remote = JSON.parse(fs.readFileSync(`${filePath}/${entry.name}`, "utf8")) as Exclude<OasSchema32, boolean>;
+        if (!remote.$schema || toAbsoluteIri(remote.$schema as string) === "https://json-schema.org/draft/2020-12/schema") {
+          registerSchema(remote, `http://localhost:1234${url}/${entry.name}`, dialectId);
+        }
+      } else if (entry.isDirectory()) {
+        addRemotes(dialectId, `${filePath}/${entry.name}`, `${url}/${entry.name}`);
+      }
+    });
+};
+
+const runTestSuite = (draft: string, dialectId: string) => {
+  const testSuiteFilePath = `${testSuitePath}/tests/${draft}`;
+
+  describe(`${draft} ${dialectId}`, () => {
+    beforeAll(() => {
+      addRemotes(dialectId);
+    });
+
+    fs.readdirSync(testSuiteFilePath, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .forEach((entry) => {
+        const file = `${testSuiteFilePath}/${entry.name}`;
+
+        describe(entry.name, () => {
+          const suites = JSON.parse(fs.readFileSync(file, "utf8")) as Suite[];
+
+          suites.forEach((suite) => {
+            describe(suite.description, () => {
+              let _validate: Validator;
+              let url: string;
+
+              beforeAll(async () => {
+                if (shouldSkip([draft, entry.name, suite.description])) {
+                  return;
+                }
+                url = `http://${draft}-test-suite.json-schema.org/${entry.name}/${encodeURIComponent(suite.description)}`;
+                if (typeof suite.schema === "object" && suite.schema.$schema === "https://json-schema.org/draft/2020-12/schema") {
+                  delete suite.schema.$schema;
+                }
+                registerSchema(suite.schema, url, dialectId);
+
+                _validate = await validate(url);
+              });
+
+              afterAll(() => {
+                unregisterSchema(url);
+              });
+
+              suite.tests.forEach((test) => {
+                if (shouldSkip([draft, entry.name, suite.description, test.description])) {
+                  it.skip(test.description, () => { /* empty */ });
+                } else {
+                  it(test.description, () => {
+                    const output = _validate(test.data);
+                    expect(output.valid).to.equal(test.valid);
+                  });
+                }
+              });
+            });
+          });
+        });
+      });
+  });
+};
+
+runTestSuite("draft2020-12", "https://spec.openapis.org/oas/3.2/dialect/base");

openapi-3-2/meta/base.js

@@ -0,0 +1,77 @@
+export default {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$dynamicAnchor": "meta",
+
+  "title": "OAS Base Vocabulary",
+  "description": "A JSON Schema Vocabulary used in the OpenAPI Schema Dialect",
+
+  "type": ["object", "boolean"],
+  "properties": {
+    "example": true,
+    "discriminator": { "$ref": "#/$defs/discriminator" },
+    "externalDocs": { "$ref": "#/$defs/external-docs" },
+    "xml": { "$ref": "#/$defs/xml" }
+  },
+  "$defs": {
+    "extensible": {
+      "patternProperties": {
+        "^x-": true
+      }
+    },
+    "discriminator": {
+      "$ref": "#/$defs/extensible",
+      "type": "object",
+      "properties": {
+        "propertyName": {
+          "type": "string"
+        },
+        "mapping": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      },
+      "required": ["propertyName"],
+      "unevaluatedProperties": false
+    },
+    "external-docs": {
+      "$ref": "#/$defs/extensible",
+      "type": "object",
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri-reference"
+        },
+        "description": {
+          "type": "string"
+        }
+      },
+      "required": ["url"],
+      "unevaluatedProperties": false
+    },
+    "xml": {
+      "$ref": "#/$defs/extensible",
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "namespace": {
+          "type": "string",
+          "format": "uri"
+        },
+        "prefix": {
+          "type": "string"
+        },
+        "attribute": {
+          "type": "boolean"
+        },
+        "wrapped": {
+          "type": "boolean"
+        }
+      },
+      "unevaluatedProperties": false
+    }
+  }
+};