json-schema-library 11.3.1 → 11.4.1

package/CHANGELOG.md

@@ -1,9 +1,28 @@
 ## Changelog
 
+### v11.4.0
+
+- added schema annotation on `compileSchema` for unknown format
+- replaced option `withSchemaAnnotations` in favor of always creating all annotations
+
+**Breaking change**: Moved some large format-validators to separate entry point:
+
+- the following format-validators have been moved to a separate entry point "json-schema-library/formats": `hostname`, `idn-email`, `ipv4`, `ipv6`, `uri`, `uri-reference`, `uri-template`
+- the following additional format-validators are available through "json-schema-library/formats": `iri`, `iri-reference`, `idn-hostname`
+
+_Use the following to add the additional format validators to drafts per default:_
+
+```ts
+import { addFormats } from "json-schema-library/formats";
+import { draft04, draft06, draft07, draft2019, draft2020 } from "json-schema-library";
+// add additional formats to the following drafts
+addFormats([draft04, draft06, draft07, draft2019, draft2020]);
+```
+
 ### v11.3.0
 
-- added option 'draft' as fallback for a missing `$schema` id
-- added properties to merge when resolvinf a $ref to `settings.PROPERTIES_TO_MERGE`
+- added option `draft` as fallback for a missing `$schema` id
+- added setting for properties to merge when resolving a `$ref` to `settings.PROPERTIES_TO_MERGE`
 
 ### v11.2.0
 

package/README.md

@@ -6,6 +6,14 @@
     json-schema-library
 </h1>
 
+_json-schema-library_ is the [most compliant JSON Schema validator](https://bowtie.report/#/?language=typescript&language=javascript) for the web, fully supporting all major JSON Schema draft versions. Read [Draft Support](#draft-support) for more details.
+
+![draft-04](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/sagold/60138b5d728d1f8f92ba29546dee7c00/raw/jsl-draft04.json)
+![draft-06](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/sagold/60138b5d728d1f8f92ba29546dee7c00/raw/jsl-draft06.json)
+![draft-07](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/sagold/60138b5d728d1f8f92ba29546dee7c00/raw/jsl-draft07.json)
+![draft-2019-09](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/sagold/60138b5d728d1f8f92ba29546dee7c00/raw/jsl-draft2019-09.json)
+![draft-2020-12](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/sagold/60138b5d728d1f8f92ba29546dee7c00/raw/jsl-draft2020-12.json)
+
 > **json-schema-library** provides tools and utilities for working with JSON Schema - enabling creation, validation, and schema exploration. Unlike most validators and editors, which hide the inner workings, this library is designed for developers building custom tools around JSON Schema. It runs in both Node and browser environments, prioritizing flexibility and extensibility over minimal memory footprint or raw performance.
 
 ---
@@ -46,6 +54,11 @@ console.log(schemaNode.getDraftVersion()); // draft-07
 
 ## Overview
 
+[compileSchema](#compileschema) ·
+[validate input schema](#validate-input-schema) ·
+[SchemaNode](#schemanode) ·
+[Draft Support](#draft-support)
+
 ### compileSchema
 
 Use `compileSchema` once to turn a JSON Schema into a tree of SchemaNodes. After that, you'll work with individual nodes in the tree. You can also pass an options object to `compileSchema` to customize how the nodes are created.
@@ -54,25 +67,25 @@ Use `compileSchema` once to turn a JSON Schema into a tree of SchemaNodes. After
 type CompileOptions = {
   // set of drafts to use
   drafts: Draft[];
+  /** fallback draft version in case no draft_is specified by `schema.$schema` */
+  draft?: string;
   // a context to share
   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
+    // add all properties (required and optional) to the generated data
     addOptionalProps?: boolean;
-    // Remove data that does not match input schema. Defaults to false
+    // 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
+    // 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
+    // limits how often a $ref should be followed before aborting. Prevents infinite data-structure. Defaults to 1
     recursionLimit?: number;
   };
 };
@@ -102,18 +115,11 @@ 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:
+All JSON Schema passed to `compileSchema` are validated automatically. To retrieve any schema errors you can access the property `schemaErrors` of the main node. `schemaAnnotations` contains all JSON Schema keywords that are not part of the used draft and any custom keyword that does not start with `x-`.
 
 ```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
+const { schemaErrors, schemaAnnotations } = root; // JsonError[]
 ```
 
 <details><summary>Example for schema validation errors</summary>
@@ -140,15 +146,6 @@ console.log(schemaErrors[0]);
 
 </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>
 
 ---
@@ -175,6 +172,13 @@ console.log(schemaAnnotations[0]);
 
 </details>
 
+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
+```
+
 ### SchemaNode
 
 `compileSchema` builds a tree where each sub-schema becomes its own SchemaNode. Every node in the tree offers the same set of methods.
@@ -220,64 +224,39 @@ assert(root === childNode.parent);
 
 </details>
 
-<details><summary>All nodes share a context</summary>
-
----
-
-A context is shared across all nodes of a schema
-
-```ts
-const root = compileSchema(mySchema);
-const { node: childNode } = root.getNode("#/image");
-assert(root.context === childNode.context);
-```
-
-And some context properties are shared across all schema added as remotes. The property `rootNode` refers to the root-schema for the current node
-
-```ts
-const root = compileSchema(mySchema);
-const { node: childNode } = root.getNode("#/image");
-assert(root === childNode.context.rootNode);
-```
-
-Note that rootNodes will change when working across remote schema (using $ref).
-
----
-
-</details>
-
-> [!CAUTION]
-> It is not advised to work on context directly, but it might be useful in some situations
-
 ### Draft Support
 
-_json-schema-library_ fully supports all core features of draft versions draft-04, draft-06, draft-07, draft-2019-09 and draft-2020-12. Additionally, most format-validations are supported per default besides the listed format below. You can always override or extend format validation as is documented in [draft customization](#draft-customization).
+_json-schema-library_ fully supports all draft versions _draft-04, draft-06, draft-07, draft-2019-09 and draft-2020-12_.
 
-<details><summary>Overview draft support</summary>
+<details><summary>References</summary>
 
 ---
 
-Draft support is defined by running a validator against the official [json-schema-test-suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite).
-
-- Test results for _json-schema-library_ can be inspected in [github actions](https://github.com/sagold/json-schema-library/actions/workflows/ci.yaml)
-- A comparison to other validators is listed on [json-schema-benchmark](https://github.com/sagold/json-schema-benchmark)
-
-Please note that these benchmarks refer to validation only. _json-schema-library_ offers tooling outside of validation and strives to be as spec-compliant as possible.
+- Draft support is defined by running a validator against the official [json-schema-test-suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite).
+- _json-schema-library_ passes all tests from [json-schema-test-suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite) which can be inspected in [github actions](https://github.com/sagold/json-schema-library/actions/workflows/ci.yaml)
+- To compare _json-schema-library_ to other validators refer to the official [Bowtie Report](https://bowtie.report/#/?language=typescript&language=javascript), which runs a subset of _json-schema-test-suite_ on all registered validators
 
 ---
 
 </details>
 
-<details><summary>Overview format validation support</summary>
+> Please note that these reports refer to validation only. _json-schema-library_ offers tooling outside of validation and strives to be as spec-compliant as possible.
 
----
+**format validators**
 
-- **`❌ unsupported formats`** iri, iri-reference, idn-hostname
-- **`✅ supported formats`**: date, date-time, date, duration, ecmascript-regex, email, hostname, idn-email, ipv4, ipv6, json-pointer, regex, relative-json-pointer, time, unknown, uri-reference, uri-template, uri, uuid
+All JSON Schema format validators are supported:
 
----
+- **per default** the following formats available: `date`, `date-time`, `duration`, `email`, `json-pointer`, `relative-json-pointer`, `regex`, `time`, `url`, `uuid`
+- **add remaining format** validators `hostname`, `idn-email`, `ipv4`, `ipv6`, `uri`, `uri-reference`, `uri-template` to drafts with:
 
-</details>
+```ts
+import { addFormats } from "json-schema-library/formats";
+import { draft04, draft06, draft07, draft2019, draft2020 } from "json-schema-library";
+// add additional formats to the following drafts
+addFormats([draft04, draft06, draft07, draft2019, draft2020]);
+```
+
+You can always override or extend format validation as is documented in [draft customization](#draft-customization).
 
 ## SchemaNode methods
 
@@ -435,6 +414,22 @@ schemaNode.getNodeRef("https://sagold.com/remote#/properties/character");
 const someNode = node.compileSchema({ prefixItems: [{ type: "string" }, { $ref: "#/$defs/string" }] });
 ```
 
+#### custom error messages
+
+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");
+```
+
 ### createSchema
 
 `createSchema` returns a simple JSON Schema for the input data.
@@ -892,7 +887,8 @@ if (node) {
 }
 ```
 
----
+> [!CAUTION]
+> `getNode` returns the root of the current schema. If a remote schema was resolved, the returned node will be the remote-schema root - not the initial schema-root you passed in to compileSchema
 
 ### reduceNode
 
@@ -1150,7 +1146,7 @@ console.log(errors); /// [{ code: "type-error", value: "data", pointer: "#", ...
 
 ## Draft Customization
 
-[**Extending a Draft**](#extending-a-draft) · [**Keyword**](#keyword)
+[Extending a Draft](#extending-a-draft) · [Overwrite format validator](#overwrite-a-format-validator) · [Keyword](#keyword)
 
 _json-schema-library_ uses the concept of **drafts** to support different versions of the JSON Schema specification — such as Draft 04, Draft 07, or 2020-12 — and to allow customization of schema behavior.
 
@@ -1549,21 +1545,7 @@ const myDraft = extendDraft(draft2020, {
 });
 ```
 
-### 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");
-```
+## Settings
 
 ### regexFlags
 

package/dist/chunk-350yNsax.cjs

@@ -0,0 +1 @@
+var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports),s=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},c=(n,r,a)=>(a=n==null?{}:e(i(n)),s(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));Object.defineProperty(exports,`n`,{enumerable:!0,get:function(){return c}}),Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return o}});