json-schema-library 11.0.5 → 11.2.0

package/.mocharc.js

@@ -1,4 +1,5 @@
 process.env.TS_NODE_PROJECT = "./tsconfig.test.json";
+process.env.JLIB_TEST_RUN = "true";
 
 module.exports = {
     "node-option": ["import=tsx"]

package/CHANGELOG.md

@@ -1,8 +1,25 @@
 ## Changelog
 
+### v11.2.0
+
+- introduced `throwOnInvalidRef` to abort validation when a $ref cannot be resolved
+- added export of meta-schema for all drafts using `import "json-schema-library/remotes"`
+- added support for format validations: `idn-hostname`, `iri`, `iri-reference`
+
+### v11.1.0
+
+- introduced upcoming keyword `propertyDependenciesKeyword` to package export
+- added support for keyword `deprecatedMessage`
+- introduced schema validation
+
+### v11.0.4, v11.0.5
+
+- removed enforcing packageManager as this failed build-jobs
+
 ### v11.0.3
 
 - fixed type of main input-schema to support boolean
+- enforced yarn as a package manager
 
 ### v11.0.2
 

package/README.md

@@ -58,6 +58,12 @@ type CompileOptions = {
   remote: SchemaNode;
   // if format-validations should create errors. Defaults to true
   formatAssertion: boolean | "meta-schema";
+  /** set to true to throw an Error on errors in input schema. Defaults to false */
+  throwOnInvalidSchema?: boolean;
+  /** set to true to collect unknown keywords of input schema in `node.schemaAnnotations`. Defaults to false */
+  withSchemaAnnotations?: boolean;
+  /** set to true to throw an Error when encountering an unresolvable ref  */
+  throwOnInvalidRef?: boolean;
   // default options for all calls to node.getData()
   getDataDefaultOptions?: {
     // Add all properties (required and optional) to the generated data
@@ -94,6 +100,81 @@ compileSchema(mySchema, { getDataDefaultOptions: { addOptionalProps: true } });
 Details on _drafts_ are documented in [draft customization](#draft-customization).
 Details on `getDataDefaultOptions` are documented in [getData](#getData).
 
+### validate input schema
+
+All JSON Schema passed to `compileSchema` are validated automatically. To retrieve any schema errors you can access the property `schemaErrors` of the main node:
+
+```ts
+const root = compileSchema(mySchema);
+const { schemaErrors } = root; // JsonError[]
+```
+
+Use the option `throwOnInvalidSchema:true` of `compileSchema` to throw an Error for a input schema containing errors:
+
+```ts
+const root = compileSchema({ properties: 123 }, { throwOnInvalidSchema: true });
+// throws Error
+```
+
+<details><summary>Example for schema validation errors</summary>
+
+---
+
+```ts
+const { schemaErrors } = compileSchema({ $defs: 999 });
+console.log(schemaErrors[0]);
+{
+  type: 'error',
+  code: 'schema-error',
+  message: 'Invalid schema found at #: $defs must be an object - received: number',
+  data: {
+    pointer: '#',
+    schema: { '$defs': 999 },
+    value: 999,
+    message: '$defs must be an object - received: number'
+  }
+}
+```
+
+---
+
+</details>
+
+To collect JSON Schema annotations for unused keywords you can opt in with option `withSchemaAnnotations`:
+
+```ts
+const root = compileSchema(mySchema, { withSchemaAnnotations: true });
+const { schemaAnnotations } = root; // JsonAnnotation[]
+```
+
+This collects all JSON Schema keywords not part of the used draft and any custom keywords. Custom keywords starting with `x-` are allowed and thus will not create an annotation.
+
+<details><summary>Example for validation annotations</summary>
+
+---
+
+```ts
+const { schemaAnnotations } = compileSchema({ unknown: true }, { withSchemaAnnotations: true });
+console.log(schemaAnnotations[0]);
+{
+  type: "annotation",
+  code: "unknown-keyword-warning",
+  message: "Keyword 'unknown' is not a valid keyword to draft 'draft-2020-12'",
+  data: {
+    pointer: "#/unknown",
+    schema: {
+      unknown: true
+    },
+    value: "unknown",
+    draft: "draft-2020-12"
+  }
+}
+```
+
+---
+
+</details>
+
 ### SchemaNode
 
 `compileSchema` builds a tree where each sub-schema becomes its own SchemaNode. Every node in the tree offers the same set of methods.
@@ -1379,6 +1460,45 @@ const dependentSchemasKeyword = draft2020.keywords.find((f) => f.keyword === "de
 
 ## Keyword extensions
 
+### propertyDependencies
+
+Resolves an object-schema by `propertyName:propertyValue`
+
+```ts
+{
+  type: "object",
+  propertyDependencies: {
+     propertyName: {
+         propertyValue: {
+          properties: {
+            id: { type: "string" }
+          }
+         }
+     }
+}
+
+// matches and returns error for id
+{
+  "propertyName": "propertyValue",
+  "id": 123
+}
+```
+
+Note that this keyword is not added by default as it is not part yet of the JSONSchema spec. Add this keyword with:
+
+```ts
+import { compileSchema, draft2020, extendDraft, propertyDependenciesKeyword } from "json-schema-library";
+
+const draft = extendDraft(draft2020, {
+  keywords: [propertyDependenciesKeyword]
+});
+
+const node = compileSchema({ propertyDependencies: {} }, { drafts: [draft] });
+```
+
+- Note: this keyword may replace `OneOfProperty`
+- Reference: https://docs.google.com/presentation/d/1ajXlCQcsjjiMLsluFIILR7sN5aDRBnfqQ9DLbcFbqjI/mobilepresent?slide=id.g3ae4fb2e16d_0_15
+
 ### oneOfProperty
 
 For `oneOf` resolution, JSON Schema states that data is valid if it validates against exactly one of those sub-schemas. In some scenarios this is unwanted behaviour, as the actual `oneOf` schema is known and only validation errors of this exact sub-schema should be returned.

package/bowtie/.editorconfig

@@ -0,0 +1,21 @@
+# EditorConfig helps developers define and maintain consistent
+# coding styles between different editors and IDEs
+# editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+indent_size = 2
+
+[package.json]
+indent_style = space
+indent_size = 2

package/bowtie/.prettierrc

@@ -0,0 +1,6 @@
+{
+    "printWidth": 120,
+    "singleQuote": false,
+    "bracketSpacing": true,
+    "trailingComma": "none"
+}

package/bowtie/BOWTIE.md

@@ -0,0 +1,54 @@
+# install
+
+brew install bowtie-json-schema/tap/bowtie
+https://docs.bowtie.report/en/stable/implementers/
+
+> docker build -t localhost/jlib .
+> bowtie suite -i localhost/jlib https://github.com/json-schema-org/JSON-Schema-Test-Suite/tree/main/tests/draft2020-12 | bowtie summary --show failures
+> bowtie suite -i localhost/jlib https://github.com/json-schema-org/JSON-Schema-Test-Suite/blob/main/tests/draft7 --fail-fast
+
+# build
+
+docker build -t localhost/jlib .
+
+# test without bowtie
+
+docker run --rm localhost/jlib
+echo '{"cmd":"start","version":1}' | docker run -i jlib
+echo '{"cmd":"run","seq":1,"case":{"schema":{"type": "string"},"tests":["valid",999]}}' | docker run -i jlib
+echo '{"cmd":"dialect","dialect":"http://json-schema.org/draft-07/schema#"}' | docker run -i jlib
+echo '{"cmd":"stop"}' | docker run -i jlib
+
+# test with bowtie
+
+> docker build -t localhost/jlib .
+> then:
+
+bowtie smoke -i localhost/jlib
+bowtie suite -i localhost/jlib https://github.com/json-schema-org/JSON-Schema-Test-Suite/blob/main/tests/draft7/type.json | bowtie summary --show failures
+
+bowtie suite -i localhost/jlib https://github.com/json-schema-org/JSON-Schema-Test-Suite/tree/main/tests/draft7 > draft7.json
+bowtie suite -i localhost/jlib https://github.com/json-schema-org/JSON-Schema-Test-Suite/tree/main/tests/draft2019-09 > draft2019-09.json
+bowtie suite -i localhost/jlib https://github.com/json-schema-org/JSON-Schema-Test-Suite/tree/main/tests/draft2020-12 > draft2020-12.json
+
+bowtie suite -i localhost/jlib https://github.com/json-schema-org/JSON-Schema-Test-Suite/tree/main/tests/draft7 | bowtie summary --show failures
+bowtie suite -i localhost/jlib https://github.com/json-schema-org/JSON-Schema-Test-Suite/tree/main/tests/draft2019-09 | bowtie summary --show failures
+bowtie suite -i localhost/jlib https://github.com/json-schema-org/JSON-Schema-Test-Suite/tree/main/tests/draft2020-12 | bowtie summary --show failures
+
+**Fails**
+bowtie suite $(bowtie filter-implementations | sed 's/^/-i /') https://github.com/json-schema-org/JSON-Schema-Test-Suite/tree/main/tests/draft2020-12 >draft2020-12.json
+
+bowtie suite $(bowtie filter-implementations | sed 's/^jlib/-i /') https://github.com/json-schema-org/JSON-Schema-Test-Suite/tree/main/tests/draft2020-12 >draft2020-12.json
+
+bowtie suite -i localhost/jlib draft7 | bowtie summary
+bowtie suite -i localhost/jlib https://github.com/json-schema-org/JSON-Schema-Test-Suite/blob/main/tests/draft7/type.json | bowtie summary --show failures
+bowtie suite -i localhost/jlib https://github.com/json-schema-org/JSON-Schema-Test-Suite/blob/main/tests/draft7 | bowtie summary --show failures
+bowtie suite -i localhost/jlib draft7 | bowtie summary --show failures
+bowtie validate -i localhost/jlib draft7 | bowtie summary --show failures
+
+**Does not finish**
+bowtie run --dialect 7 -i localhost/jlib
+bowtie validate -i localhost/jlib <(printf '{"type": "integer"}') <(printf 37) <(printf '"foo"')
+bowtie run -i localhost/jlib draft7 | bowtie summary --show failures
+bowtie run -i localhost/jlib -V '{"description": "test case 1", "schema": {}, "tests": [{"description": "a test", "instance": {}}]}'
+bowtie run -i localhost/jlib -V --fail-fast

package/bowtie/Dockerfile

@@ -0,0 +1,6 @@
+FROM node:24-alpine
+COPY . /usr/app
+WORKDIR /usr/app
+RUN npm install --omit=dev
+RUN npm -g install tsm
+CMD ["tsm", "bowtie.ts"]

package/bowtie/bowtie-api.ts

@@ -0,0 +1,101 @@
+import readline from "readline/promises";
+import { JsonSchema } from "src/types";
+
+export type Dialect =
+    | "https://json-schema.org/draft/2020-12/schema"
+    | "https://json-schema.org/draft/2019-09/schema"
+    | "http://json-schema.org/draft-07/schema#"
+    | "http://json-schema.org/draft-06/schema#"
+    | "http://json-schema.org/draft-04/schema#"
+    | "http://json-schema.org/draft-03/schema#";
+
+type StartCmd = {
+    cmd: "start";
+    version: number;
+};
+
+type StartCmdResponse = {
+    version: number;
+    implementation: {
+        /** library language */
+        language: "typescript" | "typescript";
+        /** library name */
+        name: string;
+        /** library version */
+        version: string;
+        homepage: string;
+        issues: string;
+        source: string;
+        dialects: Dialect[];
+        /** operating system platform */
+        os: string;
+        /** operating system version */
+        os_version: string;
+        /** Node.js version */
+        language_version: string;
+    };
+};
+
+type DialectCommand = {
+    cmd: "dialect";
+    dialect: Dialect;
+};
+
+type DialectCmdResponse = { ok: true };
+
+type RunCmd = {
+    cmd: "run";
+    seq: number;
+    // dialect: Dialect;
+    case: {
+        schema: JsonSchema;
+        tests: {
+            description: string;
+            instance: unknown;
+        }[];
+        registry: Record<string, JsonSchema>;
+    };
+};
+
+export type RunCmdResponse = {
+    seq: number;
+    results: ({ valid: boolean } | ErrorResponse)[];
+};
+
+export type ErrorResponse = {
+    errored: true;
+    context: {
+        traceback?: string | undefined;
+        message: string | undefined;
+    };
+};
+
+type StopCommand = {
+    cmd: "stop";
+};
+
+export type Command = StartCmd | RunCmd | DialectCommand | StopCommand;
+export type CommandResponse = RunCmdResponse | StartCmdResponse | DialectCmdResponse | ErrorResponse | undefined;
+
+export type CommandMap = {
+    /** Start nxet test run, informing bowtie of suppored draft versions and general metadata */
+    start: (args: StartCmd) => Promise<StartCmdResponse>;
+    /** Set JSON Schema draft-version of following tests */
+    dialect: (args: DialectCommand) => Promise<DialectCmdResponse>;
+    /** Run test cases for a specfic schema */
+    run: (args: RunCmd) => Promise<RunCmdResponse>;
+    /** Finalize test run and exit container */
+    stop: (args: StopCommand, stdio?: readline.Interface) => Promise<void>;
+};
+
+export const createBowtieError = (message: string, stack?: string): ErrorResponse => ({
+    errored: true,
+    context: {
+        message: message,
+        traceback: stack
+    }
+});
+
+export function sendToBowtie(data?: Record<string, unknown>) {
+    console.log(JSON.stringify(data ?? createBowtieError("missing response")));
+}

package/bowtie/bowtie.test.ts

@@ -0,0 +1,76 @@
+import { strict as assert } from "node:assert";
+import { compileSchema } from "../src/compileSchema";
+import { remotes } from "json-schema-library/remotes";
+import { JsonSchema } from "../src/types";
+import { runCommand } from "./bowtie";
+import { ErrorResponse, RunCmdResponse } from "./bowtie-api";
+
+const isRunCmdResponse = (value: unknown): value is RunCmdResponse =>
+    value != null && typeof value === "object" && "results" in value && Array.isArray(value.results);
+
+const isErrorResponse = (value: unknown): value is ErrorResponse =>
+    value != null && typeof value === "object" && "errored" in value && value.errored === true;
+
+const remote = compileSchema({ $id: "draft2020-12" });
+remotes.map((schema: JsonSchema) => remote.addRemoteSchema(schema.$id ?? schema.id, schema));
+
+describe("bowtie (draft7)", async () => {
+    before(async () => {
+        await runCommand({ cmd: "start", version: 1 });
+        await runCommand({ cmd: "dialect", dialect: "http://json-schema.org/draft-07/schema#" });
+    });
+    after(async () => runCommand({ cmd: "stop" }));
+
+    it("additionalItems as schema - additional items match schema", async () => {
+        const response = await runCommand({
+            cmd: "run",
+            seq: 1,
+            case: {
+                description: "additionalItems as schema",
+                schema: { items: [{}], additionalItems: { type: "integer" } },
+                tests: [{ description: "additional items match schema", instance: [null, 2, 3, 4], valid: true }]
+            }
+        });
+        assert(isRunCmdResponse(response));
+        assert(!isErrorResponse(response.results[0]));
+        assert.equal(response.results[0].valid, true);
+    });
+
+    it("additionalItems as schema - additional items do not match schema", async () => {
+        const response = await runCommand({
+            cmd: "run",
+            seq: 1,
+            case: {
+                description: "additionalItems as schema",
+                schema: { items: [{}], additionalItems: { type: "integer" } },
+                tests: [
+                    { description: "additional items do not match schema", instance: [null, 2, 3, "foo"], valid: false }
+                ]
+            }
+        });
+        assert(isRunCmdResponse(response));
+        assert(!isErrorResponse(response.results[0]));
+        assert.equal(response.results[0].valid, false);
+    });
+});
+
+describe("bowtie (2020-12)", () => {
+    describe("validate definition against metaschema", () => {
+        const node = compileSchema(
+            {
+                $schema: "https://json-schema.org/draft/2020-12/schema",
+                $ref: "https://json-schema.org/draft/2020-12/schema"
+            },
+            { remote }
+        );
+
+        it("valid definition schema", () => {
+            const first = node.validate({ $defs: { foo: { type: "integer" } } });
+            assert.deepEqual(first.valid, true);
+        });
+        it("invalid definition schema", () => {
+            const second = node.validate({ $defs: { foo: { type: 1 } } });
+            assert.deepEqual(second.valid, false);
+        });
+    });
+});

package/bowtie/bowtie.ts

@@ -0,0 +1,156 @@
+/* json-schema-library bowtie integration (test harness) */
+import readline from "readline/promises";
+import process from "node:process";
+import os from "os";
+import packageJson from "json-schema-library/package.json";
+import { compileSchema, type SchemaNode } from "json-schema-library";
+import { remotes } from "json-schema-library/remotes";
+import {
+    createBowtieError,
+    type Command,
+    type CommandMap,
+    type CommandResponse,
+    type Dialect,
+    RunCmdResponse,
+    sendToBowtie
+} from "./bowtie-api";
+
+/** track command sequence and abort if something is off */
+let state: "started" | "dialect" | "testing" | "stopped" = "stopped";
+/** current JSON Schema draft version to test */
+let dialect: Dialect;
+let remote: SchemaNode;
+
+const cmds: CommandMap = {
+    start: async (args) => {
+        console.assert(args.version === 1, { args });
+        console.assert(state === "stopped");
+        state = "started";
+        return {
+            version: 1,
+            implementation: {
+                language: "typescript",
+                name: "json-schema-library",
+                version: packageJson.version,
+                homepage: "https://github.com/sagold/json-schema-library",
+                issues: "https://github.com/sagold/json-schema-library/issues",
+                source: "https://github.com/sagold/json-schema-library",
+
+                dialects: [
+                    "https://json-schema.org/draft/2020-12/schema",
+                    "https://json-schema.org/draft/2019-09/schema",
+                    "http://json-schema.org/draft-07/schema#",
+                    "http://json-schema.org/draft-06/schema#",
+                    "http://json-schema.org/draft-04/schema#"
+                ],
+                os: os.platform(),
+                os_version: os.release(),
+                language_version: process.version
+            }
+        };
+    },
+
+    dialect: async (args) => {
+        console.assert(state === "started");
+        state = "dialect";
+        dialect = args.dialect;
+
+        const node = compileSchema({ $schema: dialect });
+        remotes.forEach((schema) => {
+            node.addRemoteSchema(schema.$id ?? schema.id, schema);
+        });
+        remote = node;
+
+        return { ok: true };
+    },
+
+    run: async (args) => {
+        console.assert(state === "dialect" || state === "testing");
+        state = "testing";
+        const { schema, tests, registry } = args.case;
+        if (schema != null && typeof schema === "object") {
+            schema.$schema = dialect; // set draft version to non-boolean schema
+        }
+        // compile schema
+        const node = compileSchema(schema, { remote, formatAssertion: false });
+        // add remote schemata
+        for (const id in registry) {
+            node.addRemoteSchema(id, registry[id]);
+        }
+        // run test cases and collect results to be sent back to bowtie
+        const results: RunCmdResponse["results"] = tests.map((test) => {
+            try {
+                return { valid: node.validate(test.instance).valid };
+            } catch (e) {
+                return createBowtieError(e.message ?? e, e.stack);
+            }
+        });
+        // response to bowtie for run command
+        return { seq: args.seq, results: results };
+    },
+
+    stop: async (_, stdio) => {
+        console.assert(state === "testing");
+        state = "stopped";
+        if (process.env.JLIB_TEST_RUN !== "true") {
+            stdio?.close();
+            process.exit(0);
+        }
+    }
+} as const;
+
+export async function runCommand(request: Command, stdio?: readline.Interface) {
+    let response: CommandResponse = undefined;
+    switch (request.cmd) {
+        case "start":
+            response = await cmds.start(request);
+            break;
+        case "dialect":
+            response = await cmds.dialect(request);
+            break;
+        case "run":
+            try {
+                response = await cmds.run(request);
+                return response;
+            } catch (error) {
+                response = {
+                    seq: request.seq,
+                    ...createBowtieError((error as Error).message ?? error, (error as Error).stack)
+                };
+            }
+            break;
+        case "stop":
+            await cmds.stop(request, stdio);
+            break;
+    }
+    return response;
+}
+
+function isCommand(value: unknown): value is Command {
+    return value != null && typeof value === "object" && "cmd" in value && cmds[value.cmd as keyof typeof cmds] != null;
+}
+
+/** listen for commands to be sent to container */
+async function waitForBowtieCommands() {
+    const stdio = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: false
+    });
+    for await (const line of stdio) {
+        let response;
+        try {
+            const request = JSON.parse(line);
+            response = isCommand(request)
+                ? await runCommand(request, stdio)
+                : createBowtieError(`Unsupported command received: '${line}'`);
+        } catch (e) {
+            response = createBowtieError(`Invalid json received: '${line}': ${(e as Error)?.message}`);
+        }
+        sendToBowtie(response);
+    }
+}
+
+if (process.env.JLIB_TEST_RUN !== "true") {
+    waitForBowtieCommands();
+}

package/bowtie/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "bowtie-jlib",
+  "version": "1.0.0",
+  "scripts": {
+    "format": "prettier -w ."
+  },
+  "dependencies": {
+    "json-schema-library": "*",
+    "prettier": "^3.8.1"
+  }
+}

package/bowtie/tsconfig.json

@@ -0,0 +1,12 @@
+{
+    "extends": "../tsconfig.test.json",
+    "compilerOptions": {
+        "baseUrl": "..",
+        "rootDir": "..",
+        "paths": {
+            "json-schema-library": ["./index.ts"],
+            "json-schema-library/remotes": ["./remotes/index.ts"],
+            "json-schema-library/package.json": ["./package.json"]
+        }
+    }
+}