@hyperjump/json-schema 1.0.0 → 1.1.0

package/README.md

@@ -4,6 +4,10 @@ A collection of modules for working with JSON Schemas.
 
 * Validate JSON-compatible values against a JSON Schema
   * Dialects: draft-2020-12, draft-2019-09, draft-07, draft-06, draft-04
+  * OpenAPI
+    * Versions/Dialects: 3.0, 3.1
+    * Validate an OpenAPI document
+    * Validate values against a schema from an OpenAPI document
   * Schemas can reference other schemas using a different dialect
   * Work directly with schemas on the filesystem or HTTP
 * Create custom keywords, vocabularies, and dialects
@@ -126,6 +130,31 @@ const isString = await validate(`file://${__dirname}/string.schema.yaml`);
 const output = isString("foo");
 ```
 
+**Open API**
+
+The OpenAPI 3.0 and 3.1 meta-schemas are pre-loaded and the OpenAPI JSON Schema
+dialects for each of those versions is supported. A document with a Content-Type
+of `application/openapi+json` (web) or a file extension of `openapi.json`
+(filesystem) is understood as an OpenAPI document.
+
+Use the pattern `@hyperjump/json-schema/*` to import the version you need. The
+available versions are `openapi-3-0` for 3.0 and `openapi-3-1` for 3.1.
+
+YAML support isn't built in, but you can add it by writing a MediaTypePlugin.
+You can use the one at `lib/openapi.js` as an example and replacing the JSON
+parts with YAML.
+
+```javascript
+import { addSchema, validate } from "@hyperjump/json-schema/openapi-3-1";
+
+
+// Validate an OpenAPI document
+const output = await validate("https://spec.openapis.org/oas/3.1/schema-base", openapi);
+
+// Validate an instance against a schema in an OpenAPI document
+const output = await validate(`file://${__dirname}/example.openapi.json#/components/schemas/foo`, 42);
+```
+
 ## API
 These are available from any of the exports that refer to a version of JSON
 Schema, such as `@hyperjump/json-schema/draft-2020-12`.

package/lib/openapi.js

@@ -0,0 +1,29 @@
+import { addMediaTypePlugin } from "./media-types.js";
+
+
+const is31 = RegExp.prototype.test.bind(/^3\.1\.\d+(-.+)?$/);
+const is30 = RegExp.prototype.test.bind(/^3\.0\.\d+(-.+)?$/);
+
+addMediaTypePlugin("application/openapi+json", {
+  parse: async (response, contentTypeParameters) => {
+    const doc = await response.json();
+
+    let defaultDialect;
+    const version = doc.openapi || contentTypeParameters.version;
+
+    if (is30(version)) {
+      defaultDialect = "https://spec.openapis.org/oas/3.0/schema";
+    } else if (is31(version)) {
+      if (!("jsonSchemaDialect" in doc) || doc.jsonSchemaDialect === "https://spec.openapis.org/oas/3.1/dialect/base") {
+        defaultDialect = "https://spec.openapis.org/oas/3.1/schema-base";
+      } else {
+        defaultDialect = `https://spec.openapis.org/oas/3.1/schema-${encodeURIComponent(doc.jsonSchemaDialect)}`;
+      }
+    } else {
+      throw Error("Invalid OpenAPI document. Add the 'openapi' field and try again.");
+    }
+
+    return [doc, defaultDialect];
+  },
+  matcher: (path) => /(\/|\.)openapi\.json$/.test(path)
+});

package/openapi-3-0/dialect.js

@@ -0,0 +1,174 @@
+export default {
+  "id": "https://spec.openapis.org/oas/3.0/dialect",
+  "$schema": "http://json-schema.org/draft-04/schema#",
+
+  "type": "object",
+  "properties": {
+    "title": { "type": "string" },
+    "multipleOf": {
+      "type": "number",
+      "minimum": 0,
+      "exclusiveMinimum": true
+    },
+    "maximum": { "type": "number" },
+    "exclusiveMaximum": {
+      "type": "boolean",
+      "default": false
+    },
+    "minimum": { "type": "number" },
+    "exclusiveMinimum": {
+      "type": "boolean",
+      "default": false
+    },
+    "maxLength": { "$ref": "#/definitions/positiveInteger" },
+    "minLength": { "$ref": "#/definitions/positiveIntegerDefault0" },
+    "pattern": {
+      "type": "string",
+      "format": "regex"
+    },
+    "maxItems": { "$ref": "#/definitions/positiveInteger" },
+    "minItems": { "$ref": "#/definitions/positiveIntegerDefault0" },
+    "uniqueItems": {
+      "type": "boolean",
+      "default": false
+    },
+    "maxProperties": { "$ref": "#/definitions/positiveInteger" },
+    "minProperties": { "$ref": "#/definitions/positiveIntegerDefault0" },
+    "required": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "enum": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": false
+    },
+    "type": { "enum": ["array", "boolean", "integer", "number", "object", "string"] },
+    "not": { "$ref": "#" },
+    "allOf": { "$ref": "#/definitions/schemaArray" },
+    "oneOf": { "$ref": "#/definitions/schemaArray" },
+    "anyOf": { "$ref": "#/definitions/schemaArray" },
+    "items": { "$ref": "#" },
+    "properties": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#" }
+    },
+    "additionalProperties": {
+      "anyOf": [
+        { "type": "boolean" },
+        { "$ref": "#" }
+      ],
+      "default": {}
+    },
+    "description": { "type": "string" },
+    "format": { "type": "string" },
+    "default": {},
+    "nullable": {
+      "type": "boolean",
+      "default": false
+    },
+    "discriminator": { "$ref": "#/definitions/Discriminator" },
+    "readOnly": {
+      "type": "boolean",
+      "default": false
+    },
+    "writeOnly": {
+      "type": "boolean",
+      "default": false
+    },
+    "example": {},
+    "externalDocs": { "$ref": "#/definitions/ExternalDocumentation" },
+    "deprecated": {
+      "type": "boolean",
+      "default": false
+    },
+    "xml": { "$ref": "#/definitions/XML" },
+    "$ref": {
+      "type": "string",
+      "format": "uri"
+    }
+  },
+  "patternProperties": {
+    "^x-": {}
+  },
+  "additionalProperties": false,
+
+  "anyOf": [
+    {
+      "not": { "required": ["$ref"] }
+    },
+    { "maxProperties": 1 }
+  ],
+
+  "definitions": {
+    "schemaArray": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#" }
+    },
+    "positiveInteger": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "positiveIntegerDefault0": {
+      "allOf": [{ "$ref": "#/definitions/positiveInteger" }, { "default": 0 }]
+    },
+    "Discriminator": {
+      "type": "object",
+      "required": [
+        "propertyName"
+      ],
+      "properties": {
+        "propertyName": {
+          "type": "string"
+        },
+        "mapping": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "ExternalDocumentation": {
+      "type": "object",
+      "required": ["url"],
+      "properties": {
+        "description": { "type": "string" },
+        "url": {
+          "type": "string",
+          "format": "uri-reference"
+        }
+      },
+      "patternProperties": {
+        "^x-": {}
+      },
+      "additionalProperties": false
+    },
+    "XML": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "namespace": {
+          "type": "string",
+          "format": "uri"
+        },
+        "prefix": { "type": "string" },
+        "attribute": {
+          "type": "boolean",
+          "default": false
+        },
+        "wrapped": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      "patternProperties": {
+        "^x-": {}
+      },
+      "additionalProperties": false
+    }
+  }
+};

package/openapi-3-0/discriminator.js

@@ -0,0 +1,4 @@
+import metaData from "../lib/keywords/meta-data.js";
+
+
+export default { id: "https://spec.openapis.org/oas/3.0/keyword/discriminator", ...metaData };

package/openapi-3-0/example.js

@@ -0,0 +1,4 @@
+import metaData from "../lib/keywords/meta-data.js";
+
+
+export default { id: "https://spec.openapis.org/oas/3.0/keyword/example", ...metaData };

package/openapi-3-0/externalDocs.js

@@ -0,0 +1,4 @@
+import metaData from "../lib/keywords/meta-data.js";
+
+
+export default { id: "https://spec.openapis.org/oas/3.0/keyword/externalDocs", ...metaData };

package/openapi-3-0/index.d.ts

@@ -0,0 +1,60 @@
+import type { Json } from "@hyperjump/json-pointer";
+import type { JsonSchemaType } from "../lib/common.js";
+
+
+export type OasSchema30 = {
+  $ref: string;
+} | {
+  title?: string;
+  description?: string;
+  default?: Json;
+  multipleOf?: number;
+  maximum?: number;
+  exclusiveMaximum?: boolean;
+  minimum?: number;
+  exclusiveMinimum?: boolean;
+  maxLength?: number;
+  minLength?: number;
+  pattern?: string;
+  items?: OasSchema30;
+  maxItems?: number;
+  minItems?: number;
+  uniqueItems?: boolean;
+  maxProperties?: number;
+  minProperties?: number;
+  required?: string[];
+  additionalProperties?: boolean | OasSchema30;
+  properties?: Record<string, OasSchema30>;
+  enum?: Json[];
+  type?: JsonSchemaType;
+  nullable?: boolean;
+  format?: "date-time" | "email" | "hostname" | "ipv4" | "ipv6" | "uri" | "int32" | "int64" | "float" | "double" | "byte" | "binary" | "date" | "password";
+  allOf?: OasSchema30[];
+  anyOf?: OasSchema30[];
+  oneOf?: OasSchema30[];
+  not?: OasSchema30;
+  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;
+};
+
+export * from "../lib/index.js";

package/openapi-3-0/index.js

@@ -0,0 +1,77 @@
+import { addKeyword, defineVocabulary, loadDialect } from "../lib/keywords.js";
+import { addSchema } from "../lib/core.js";
+import "../lib/openapi.js";
+
+import dialectSchema from "./dialect.js";
+import schema20210928 from "./schema/2021-09-28.js";
+
+import discriminator from "./discriminator.js";
+import example from "./example.js";
+import externalDocs from "./externalDocs.js";
+import nullable from "./nullable.js";
+import type from "./type.js";
+import xml from "./xml.js";
+
+
+addKeyword(discriminator);
+addKeyword(example);
+addKeyword(externalDocs);
+addKeyword(nullable);
+addKeyword(type);
+addKeyword(xml);
+
+const jsonSchemaVersion = "https://spec.openapis.org/oas/3.0/dialect";
+
+defineVocabulary(jsonSchemaVersion, {
+  "$ref": "https://json-schema.org/keyword/draft-04/ref",
+  "additionalProperties": "https://json-schema.org/keyword/additionalProperties",
+  "allOf": "https://json-schema.org/keyword/allOf",
+  "anyOf": "https://json-schema.org/keyword/anyOf",
+  "default": "https://json-schema.org/keyword/default",
+  "deprecated": "https://json-schema.org/keyword/deprecated",
+  "description": "https://json-schema.org/keyword/description",
+  "discriminator": "https://spec.openapis.org/oas/3.0/keyword/discriminator",
+  "enum": "https://json-schema.org/keyword/enum",
+  "example": "https://spec.openapis.org/oas/3.0/keyword/example",
+  "exclusiveMaximum": "https://json-schema.org/keyword/draft-04/exclusiveMaximum",
+  "exclusiveMinimum": "https://json-schema.org/keyword/draft-04/exclusiveMinimum",
+  "externalDocs": "https://spec.openapis.org/oas/3.0/keyword/externalDocs",
+  "format": "https://json-schema.org/keyword/format",
+  "items": "https://json-schema.org/keyword/draft-04/items",
+  "maxItems": "https://json-schema.org/keyword/maxItems",
+  "maxLength": "https://json-schema.org/keyword/maxLength",
+  "maxProperties": "https://json-schema.org/keyword/maxProperties",
+  "maximum": "https://json-schema.org/keyword/draft-04/maximum",
+  "minItems": "https://json-schema.org/keyword/minItems",
+  "minLength": "https://json-schema.org/keyword/minLength",
+  "minProperties": "https://json-schema.org/keyword/minProperties",
+  "minimum": "https://json-schema.org/keyword/draft-04/minimum",
+  "multipleOf": "https://json-schema.org/keyword/multipleOf",
+  "not": "https://json-schema.org/keyword/not",
+  "nullable": "https://spec.openapis.org/oas/3.0/keyword/nullable",
+  "oneOf": "https://json-schema.org/keyword/oneOf",
+  "pattern": "https://json-schema.org/keyword/pattern",
+  "properties": "https://json-schema.org/keyword/properties",
+  "readOnly": "https://json-schema.org/keyword/readOnly",
+  "required": "https://json-schema.org/keyword/required",
+  "title": "https://json-schema.org/keyword/title",
+  "type": "https://spec.openapis.org/oas/3.0/keyword/type",
+  "uniqueItems": "https://json-schema.org/keyword/uniqueItems",
+  "writeOnly": "https://json-schema.org/keyword/writeOnly",
+  "xml": "https://spec.openapis.org/oas/3.0/keyword/xml"
+});
+
+loadDialect(jsonSchemaVersion, {
+  [jsonSchemaVersion]: true
+});
+
+loadDialect("https://spec.openapis.org/oas/3.0/schema", {
+  [jsonSchemaVersion]: true
+});
+
+addSchema(dialectSchema);
+
+addSchema(schema20210928, "https://spec.openapis.org/oas/3.0/schema");
+addSchema(schema20210928, "https://spec.openapis.org/oas/3.0/schema/latest");
+
+export * from "../draft-04/index.js";

package/openapi-3-0/nullable.js

@@ -0,0 +1,4 @@
+import metaData from "../lib/keywords/meta-data.js";
+
+
+export default { id: "https://spec.openapis.org/oas/3.0/keyword/nullable", ...metaData };