json-schema-library 10.0.0-rc9 → 10.1.0

package/.mocharc.js

@@ -0,0 +1,5 @@
+process.env.TS_NODE_PROJECT = "./tsconfig.test.json";
+
+module.exports = {
+    require: "ts-node/register"
+};

package/CHANGELOG.md

@@ -1,5 +1,7 @@
 ## Changelog
 
+-   reference for error-format: https://json-schema.org/blog/posts/fixing-json-schema-output
+
 ### v9.0.0
 
 -   [Breaking] error data to always contain `schema` and `value`

package/README.md

@@ -16,8 +16,6 @@
 
 ---
 
-> ⚠️ This **documentation** refers to the upcoming release **version 10**, which can be installed by `npm install json-schema-library@10.0.0-rc9`. For the latest release please refer to the **[documentation of version 9.3.5](https://github.com/sagold/json-schema-library/tree/v9.3.5)**.
-
 **Quick start**
 
 `npm install json-schema-library`
@@ -61,7 +59,16 @@ type CompileOptions = {
     // if format-validations should create errors. Defaults to true
     formatAssertion: boolean | "meta-schema";
     // default options for all calls to node.getData()
-    getDataDefaultOptions?: TemplateOptions;
+    getDataDefaultOptions?: {
+        // Add all properties (required and optional) to the generated data
+        addOptionalProps?: boolean;
+        // Remove data that does not match input schema. Defaults to false
+        removeInvalidData?: boolean;
+        // Set to false to take default values as they are and not extend them. Defaults to true
+        extendDefaults?: boolean;
+        // Limits how often a $ref should be followed before aborting. Prevents infinite data-structure. Defaults to 1
+        recursionLimit?: number;
+    };
 };
 ```
 
@@ -103,12 +110,12 @@ const titleData = titleNode?.getData();
 
 ```ts
 const titleNode = compileSchema(mySchema).getNode("#/image/title");
-console.log(titleNode.spointer); // #/properties/image/properties/title
-console.log(titleNode.schemaId); // #/properties/image/properties/title
+console.log(titleNode.evaluationPath); // #/properties/image/properties/title
+console.log(titleNode.schemaLocation); // #/properties/image/properties/title
 ```
 
--   `spointer` refers to the path in schema and is extended by `$ref`, e.g. if image is defined on `$defs`: `#/properties/image/$ref/properties/title`
--   `schemaId` refers to the absolute path within the schema and will not change, e.g. `#/$defs/properties/title`
+-   `evaluationPath` refers to the path in schema and is extended by `$ref`, e.g. if image is defined on `$defs`: `#/properties/image/$ref/properties/title`
+-   `schemaLocation` refers to the absolute path within the schema and will not change, e.g. `#/$defs/properties/title`
 
 </details>
 
@@ -172,19 +179,19 @@ Please note that these benchmarks refer to validation only. _json-schema-library
 
 ## SchemaNode methods
 
-[**addRemoteSchema**](#addremoteschema) ·
-[**compileSchema**](#compileSchema-1) ·
-[**createSchema**](#createSchema) ·
-[**getChildSelection**](#getchildselection) ·
-[**getData**](#getdata) ·
-[**getNode**](#getnode) ·
-[**getNodeChild**](#getnodechild) ·
-[**getNodeRef**](#getnoderef) ·
-[**getNodeRoot**](#getnoderoot) ·
-[**reduceNode**](#reducenode) ·
-[**toDataNodes**](#todatanodes) ·
-[**toSchemaNodes**](#toschemanodes) ·
-[**validate**](#validate)
+[addRemoteSchema](#addremoteschema) ·
+[compileSchema](#compileSchema-1) ·
+[createSchema](#createSchema) ·
+[getChildSelection](#getchildselection) ·
+[getData](#getdata) ·
+[getNode](#getnode) ·
+[getNodeChild](#getnodechild) ·
+[getNodeRef](#getnoderef) ·
+[getNodeRoot](#getnoderoot) ·
+[reduceNode](#reducenode) ·
+[toDataNodes](#todatanodes) ·
+[toSchemaNodes](#toschemanodes) ·
+[validate](#validate)
 
 </details>
 
@@ -192,7 +199,7 @@ Please note that these benchmarks refer to validation only. _json-schema-library
 
 `addRemoteSchema` lets you add additional schemas that can be referenced by an URL using `$ref`. Use this to combine multiple schemas without changing the actual schema.
 
-Each schemas is referenced by their unique `$id` (since draft-06, previously `id`). Usually an `$id` is specified as an url, for example `https://mydomain.com/schema/schema-name` or with a file extension like `https://mydomain.com/schema/schema-name.json`.
+Each schema is referenced by their unique `$id` (since draft-06, previously `id`). Usually an `$id` is specified as an url, for example `https://mydomain.com/schema/schema-name` or with a file extension like `https://mydomain.com/schema/schema-name.json`.
 
 On a compiled schema
 
@@ -383,35 +390,35 @@ const myData = compileSchema(myJsonSchema).getData(inputData, { recursionLimit:
 <details><summary>Example</summary>
 
 ```ts
-import { compileSchema, JsonSchema } from 'json-schema-library';
+import { compileSchema, JsonSchema } from "json-schema-library";
 
 const myJsonSchema: JsonSchema = {
-  type: 'object',
-  required: ['name', 'option', 'list'],
-  properties: {
-    name: { type: 'string' },
-    option: {
-      type: 'string',
-      enum: ['first-option', 'second-option']
-    },
-    list: {
-      type: 'array',
-      items: {
-        type: 'string',
-        default: 'new item'
-      },
-      minItems: 1
+    type: "object",
+    required: ["name", "option", "list"],
+    properties: {
+        name: { type: "string" },
+        option: {
+            type: "string",
+            enum: ["first-option", "second-option"]
+        },
+        list: {
+            type: "array",
+            items: {
+                type: "string",
+                default: "new item"
+            },
+            minItems: 1
+        }
     }
-  }
 };
 
 const schemaNode = new compileSchema(myJsonSchema);
 const myData = schemaNode.getData();
 
 expect(myData).to.deep.equal({
-  name: ',
-  option: 'first-option',
-  list: ['new item']
+    name: "",
+    option: "first-option",
+    list: ["new item"]
 });
 ```
 
@@ -743,7 +750,7 @@ expect(reducedNode.schema).to.deep.eq({
 
 ### toDataNodes
 
-`each` iterates over each data-item (_object_, _array_ and _value_) and emits the data-item, schema and location to a callback.
+`toDataNodes` collects all data-items (_object_, _array_ and _value_) and their SchemaNode and return them as a list of **DataNodes**:
 
 ```ts
 type DataNode = { pointer: string; value: unknown; node: SchemaNode };
@@ -779,7 +786,7 @@ expect(calls).to.deep.equal([
 
 ### toSchemaNodes
 
-`eachSchema` emits each sub-schema definition to a callback. A sub-schema is any schema-definition like in `properties["property"]`, `anyOf[1]`, `contains`, `$defs["name"]`, etc.
+`toSchemaNodes` collects all sub-schema definitions, like in `properties["property"]`, `anyOf[1]`, `contains`, `$defs["name"]`, etc. and returns them as a list of **SchemaNodes**:
 
 ```ts
 const nodes: SchemaNode[] = compileSchema(mySchema).toSchemaNodes();
@@ -846,10 +853,7 @@ In almost all cases, a JSON Pointer is given on _error.data.pointer_, which poin
 <details><summary>Example</summary>
 
 ```ts
-const myJsonSchema: JsonSchema = {
-    type: "object",
-    additionalProperties: false
-};
+const myJsonSchema: JsonSchema = { type: "object", additionalProperties: false };
 
 const { errors } = compileSchema(myJsonSchema).validate({ name: "my-data" });
 
@@ -868,14 +872,14 @@ expect(errors).to.deep.equal([
 You can also use async validators to validate data with json-schema. For this, another property asyncErrors is exposed on validate:
 
 ```ts
-const { isValid, errors, errorsAsync } = compileSchema(myJsonSchema).validate(myData);
+const { errorsAsync } = compileSchema(myJsonSchema).validate(myData);
 
 if (errorsAsync.length > 0) {
     const additionalErrors = (await Promise.all(errorsAsync)).filter((err) => err != null);
 }
 ```
 
-Per default _json-schema-library_ does not have async validators, so `errorsAsync` is always empty. If you add async validators, a list of `Promise<JsonError|undefined>` is return and you need to resolve and filter non-errors (undefined) yourself.
+Per default _json-schema-library_ does not contain async validators, so `errorsAsync` is always empty. If you add async validators, a list of `Promise<JsonError|undefined>` is return and you need to resolve and filter non-errors (undefined) yourself.
 
 > **Note** `isValid` only refers to errors. `errorsAsync` has to be evaluated separately
 
@@ -1051,17 +1055,73 @@ const myDraft = extendDraft(draft2020, {
 });
 ```
 
-<details><summary>About `oneOfFuzzyKeyword`</summary>
+### Overwrite a format validator
 
-If you're working with complex schemas that use the `oneOf` keyword to validate multiple options, `oneOfFuzzyKeyword` offers an alternative approach. It scores the schemas to return the best match, even if none of the schemas fully validate the input data. This makes error messages more readable and helps identify the most appropriate schema when multiple options exist.
+The built-in format validators may not always align with your specific requirements. For instance, you might need to validate the output of an `<input type="time" />`, which produces values in formats like `HH:MM` or `HH:MM:SS`. In such cases, you can customize or overwrite the format validators to suit your needs using `extendDraft`
 
-`oneOfFuzzyKeyword` helps when no schema fully validates the data but you want to prioritize schemas based on how well they fit the input. This makes it easier to interpret validation results for complex conditions.
+<details>
+<summary>Example of overwriting a format validator</summary>
+
+```ts
+import { extendDraft, draft2020 } from "json-schema-library";
+
+/**
+ * A Regexp that extends http://tools.ietf.org/html/rfc3339#section-5.6 spec.
+ * The specification requires seconds and timezones to be a valid date format.
+ *
+ * matchTimeSecondsAndTimeOptional matches:
+ * - HH:MM:SSz
+ * - HH:MM:SS(+/-)HH:MM
+ * - HH:MM:SS
+ * - HH:MMz
+ * - HH:MM(+/-)HH:MM
+ * - HH:MM
+ */
+const matchTimeSecondsAndTimeOptional =
+    /^(?<time>(?:([0-1]\d|2[0-3]):[0-5]\d(:(?<second>[0-5]\d|60))?))(?:\.\d+)?(?<offset>(?:z|[+-]([0-1]\d|2[0-3])(?::?[0-5]\d)?)?)$/i;
+
+const customTimeFormatDraft = extendDraft(draft2020, {
+    formats: {
+        // This example extends the default time formatter which validates against RFC3339
+        time: ({ node, pointer, data }) => {
+            const { schema } = node;
+            if (typeof data !== "string" || data === "") {
+                return undefined;
+            }
+
+            // Use the Custom Regex to validate the date and time.
+            const matches = data.match(matchTimeSecondsAndTimeOptional);
+            if (!matches) {
+                return node.createError("format-date-time-error", { value: data, pointer, schema });
+            }
+
+            // leap second
+            if (matches.groups.second === "60") {
+                // Omitted the code here for brevity.
+            }
+
+            return undefined;
+        }
+    }
+});
+
+const { errors, valid } = compileSchema(
+    {
+        type: "string",
+        format: "time",
+        $schema: "https://json-schema.org/draft/2020-12/schema"
+    },
+    { drafts: [customTimeFormatDraft] }
+).validate("15:31:12");
+
+console.assert(valid, errors.at(0)?.message);
+```
 
 </details>
 
 ### Keyword
 
-`Keywords` hold the main logic for JSON Schema functionality. Each `Keyword` corresponds to a JSON Schema keyword like `properties`, `prefixItems`, `oneOf`, etc and offers implementations to `parse`, `validate`, `resolve` and `reduce`. Note that support for each implementation is optional, dependending on the feature requirements. The main properties of a `Keyword`:
+**Keywords** hold the main logic for JSON Schema functionality. Each `Keyword` corresponds to a JSON Schema keyword like `properties`, `prefixItems`, `oneOf`, etc and offers implementations to `parse`, `validate`, `resolve` and `reduce`. Note that support for each implementation is optional, dependending on the feature requirements. The main properties of a `Keyword`:
 
 -   a `Keyword` is only processed if the specified `keyword` is available as property on the JSON Schema
 -   an optional `order` property may be added as order of keyword execution is sometimes important (`additionalItems` last, `$ref` evaluation first)
@@ -1099,9 +1159,9 @@ export const notKeyword: Keyword = {
 };
 
 export function parseNot(node: SchemaNode) {
-    const { schema, spointer, schemaId } = node;
+    const { schema, evaluationPath, schemaLocation } = node;
     if (schema.not != null) {
-        node.not = node.compileSchema(schema.not, `${spointer}/not`, `${schemaId}/not`);
+        node.not = node.compileSchema(schema.not, `${evaluationPath}/not`, `${schemaLocation}/not`);
     }
 }
 ```
@@ -1149,7 +1209,7 @@ export const typeKeyword: Keyword = {
 function reduceType({ node, pointer, data }: JsonSchemaReducerParams): undefined | SchemaNode {
     const dataType = getJsonSchemaType(data, node.schema.type);
     if (dataType !== "undefined" && Array.isArray(node.schema.type) && node.schema.type.includes(dataType)) {
-        return node.compileSchema({ ...node.schema, pointer, type: dataType }, node.spointer);
+        return node.compileSchema({ ...node.schema, pointer, type: dataType }, node.evaluationPath);
     }
     return undefined;
 }
@@ -1157,6 +1217,13 @@ function reduceType({ node, pointer, data }: JsonSchemaReducerParams): undefined
 
 </details>
 
+Currently **keywords** are not exposed per default. You can still access any keyword implementation by retrieving them from a draft:
+
+```ts
+import { draft07 } from "json-schema-library";
+const dependentSchemasKeyword = draft2020.keywords.find((f) => f.keyword === "dependentSchemas");
+```
+
 ## Keyword extensions
 
 ### oneOfProperty
@@ -1193,8 +1260,45 @@ expect(resolvedNode?.schema).to.deep.eq({
 });
 ```
 
+### oneOfFuzzyKeyword
+
+If you're working with complex schemas that use the `oneOf` keyword to validate multiple options, `oneOfFuzzyKeyword` offers an alternative approach. It scores the schemas to return the best match, even if none of the schemas fully validate the input data. This makes error messages more readable and helps identify the most appropriate schema when multiple options exist.
+
+`oneOfFuzzyKeyword` helps when no schema fully validates the data but you want to prioritize schemas based on how well they fit the input. This makes it easier to interpret validation results for complex conditions.
+
+`oneOfFuzzyKeyword` is exposed by _json-schema-library_ and can be used to extend any draft.
+
+```ts
+import { extendDraft, oneOfFuzzyKeyword, draft2020 } from "json-schema-library";
+
+const myDraft = extendDraft(draft2020, {
+    keywords: [oneOfFuzzyKeyword]
+});
+```
+
+### errorMessages
+
+You can set custom errors messages locally by using the errors-keyword:
+
+```ts
+const { errors } = compileSchema({
+    type: "array",
+    minItems: 2,
+    errorMessages: {
+        "min-items-error": "Custom error {{minItems}}"
+    }
+}).validate([1]);
+
+assert.deepEqual(errors[0].message, "Custom error 2");
+```
+
 ## Breaking Changes
 
+### v10.1.0
+
+-   replaced `node.additionalItems` by `node.items` for drafts below 2020-12
+-   fixed `additionalItems` behaviour to be ignored when `schema.items` is not an array
+
 ### v10.0.0
 
 > This update involves some significant changes in how you work with the library, so please carefully review the migration guide and adjust your implementation accordingly.
@@ -1212,13 +1316,13 @@ The new implementation revolves around compiling schemas into a **SchemaNode** t
 
 **`compileSchema`** is now a standalone function and replaces the `Draft` class. All return values for JSON Schema are now `SchemaNode` objects that contain a `schema` property.
 
-    ```ts
-    // PREVIOUSLY
-    const draft = new Draft(schema);
+```ts
+// PREVIOUSLY
+const draft = new Draft(schema);
 
-    // NOW
-    const node = compileSchema(schema);
-    ```
+// NOW
+const node = compileSchema(schema);
+```
 
 **Changed Methods**:
 

package/bowtie_jlib.js

@@ -0,0 +1,140 @@
+/**
+ * test file for bowtie integration
+ *
+ * - Tutorial: https://docs.bowtie.report/en/stable/implementers/
+ *
+ * Build Dockerfile:
+ *
+ * ```
+ * docker build -t localhost/jlib .
+ * ````
+ *
+ * Test setup:
+ *
+ * ```
+bowtie run -i localhost/jlib -V <<EOF
+{"description": "test case 1", "schema": {}, "tests": [{"description": "a test", "instance": {}}] }
+{"description": "test case 2", "schema": {"const": 37}, "tests": [{"description": "not 37", "instance": {}}, {"description": "is 37", "instance": 37}] }
+EOF
+ *
+ * Test draft
+ *
+ * ```
+ * bowtie suite -i localhost/jlib draft7 | bowtie summary --show failures
+ * ```
+ *
+ */
+const readline = require("readline/promises");
+const process = require("process");
+const os = require("os");
+const packageJson = require("./package.json");
+const jlib = require("./dist/jsonSchemaLibrary.js");
+
+const compileSchema = jlib.compileSchema;
+
+const stdio = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false
+});
+
+// const schemaIds: { [id: string]: SchemaDraft } = {
+//     "https://json-schema.org/draft/2020-12/schema": SchemaDraft.v2020_12,
+//     "https://json-schema.org/draft/2019-09/schema": SchemaDraft.v2019_09,
+//     "http://json-schema.org/draft-07/schema#": SchemaDraft.v7,
+//     "http://json-schema.org/draft-06/schema#": SchemaDraft.v6,
+//     "http://json-schema.org/draft-04/schema#": SchemaDraft.v4
+// };
+
+function send(data) {
+    console.log(JSON.stringify(data));
+}
+
+let started = false;
+// let dialect;
+
+const cmds = {
+    start: async (args) => {
+        console.assert(args.version === 1, { args });
+        started = true;
+        return {
+            version: 1,
+            implementation: {
+                language: "javascript",
+                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(started, "Not started!");
+        // dialect = schemaIds[args.dialect];
+        return { ok: true };
+    },
+
+    run: async (args) => {
+        console.assert(started, "Not started!");
+
+        // for (const id in testCase.registry) {
+        //         ajv.addSchema(testCase.registry[id], id);
+        // }
+
+        const testCase = args.case;
+        //  as {
+        //     registry: Recors<sring, string>;
+        //     schema: Record<string, any>;
+        //     tests: {
+        //         /** testdata */
+        //         instance: unknown;
+        //     }[];
+        // };
+
+        const node = compileSchema(testCase.schema);
+        const results = testCase.tests.map((test) => {
+            try {
+                const errors = node.validate(test.instance);
+                return { valid: errors.length === 0 };
+            } catch (error) {
+                return {
+                    errored: true,
+                    context: {
+                        traceback: error.stack,
+                        message: error.message
+                    }
+                };
+            }
+        });
+
+        return { seq: args.seq, results: results };
+    },
+
+    stop: async (_) => {
+        console.assert(started, "Not started!");
+        process.exit(0);
+    }
+};
+
+async function main() {
+    for await (const line of stdio) {
+        const request = JSON.parse(line);
+        const response = await cmds[request.cmd](request);
+        send(response);
+    }
+}
+
+main();

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { compileSchema } from "./src/compileSchema";
 export type { CompileOptions } from "./src/compileSchema";
-export type { Context, SchemaNode, GetNodeOptions } from "./src/SchemaNode";
+export type { Context, SchemaNode, GetNodeOptions, ValidateReturnType } from "./src/SchemaNode";
 export type { DataNode } from "./src/methods/toDataNodes";
 export type { Draft, DraftVersion } from "./src/Draft";
 export type { JsonError, JsonPointer, JsonSchema, OptionalNodeOrError, NodeOrError } from "./src/types";
@@ -9,6 +9,7 @@ export { draft04 } from "./src/draft04";
 export { draft06 } from "./src/draft06";
 export { draft07 } from "./src/draft07";
 export { draft2019 } from "./src/draft2019";
+export { draft2020 } from "./src/draft2020";
 export { draftEditor } from "./src/draftEditor";
 export { oneOfFuzzyKeyword, oneOfKeyword } from "./src/keywords/oneOf";
 export { render } from "./src/errors/render";
@@ -19,4 +20,5 @@ export { isJsonError, isSchemaNode } from "./src/types";
 export { extendDraft, addKeywords } from "./src/Draft";
 export { mergeNode } from "./src/mergeNode";
 export { mergeSchema } from "./src/utils/mergeSchema";
+export { getSchemaType } from "./src/utils/getSchemaType";
 export { remotes } from "./remotes";