Skip to content

Commit 6f0b0d8

Browse files
committed
docs: minor updates
1 parent 0277f4c commit 6f0b0d8

File tree

1 file changed

+71
-50
lines changed

1 file changed

+71
-50
lines changed

README.md

+71-50
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,16 @@ type CompileOptions = {
6161
// if format-validations should create errors. Defaults to true
6262
formatAssertion: boolean | "meta-schema";
6363
// default options for all calls to node.getData()
64-
getDataDefaultOptions?: TemplateOptions;
64+
getDataDefaultOptions?: {
65+
// Add all properties (required and optional) to the generated data
66+
addOptionalProps?: boolean;
67+
// Remove data that does not match input schema. Defaults to false
68+
removeInvalidData?: boolean;
69+
// Set to false to take default values as they are and not extend them. Defaults to true
70+
extendDefaults?: boolean;
71+
// Limits how often a $ref should be followed before aborting. Prevents infinite data-structure. Defaults to 1
72+
recursionLimit?: number;
73+
};
6574
};
6675
```
6776

@@ -172,27 +181,27 @@ Please note that these benchmarks refer to validation only. _json-schema-library
172181

173182
## SchemaNode methods
174183

175-
[**addRemoteSchema**](#addremoteschema) ·
176-
[**compileSchema**](#compileSchema-1) ·
177-
[**createSchema**](#createSchema) ·
178-
[**getChildSelection**](#getchildselection) ·
179-
[**getData**](#getdata) ·
180-
[**getNode**](#getnode) ·
181-
[**getNodeChild**](#getnodechild) ·
182-
[**getNodeRef**](#getnoderef) ·
183-
[**getNodeRoot**](#getnoderoot) ·
184-
[**reduceNode**](#reducenode) ·
185-
[**toDataNodes**](#todatanodes) ·
186-
[**toSchemaNodes**](#toschemanodes) ·
187-
[**validate**](#validate)
184+
[addRemoteSchema](#addremoteschema) ·
185+
[compileSchema](#compileSchema-1) ·
186+
[createSchema](#createSchema) ·
187+
[getChildSelection](#getchildselection) ·
188+
[getData](#getdata) ·
189+
[getNode](#getnode) ·
190+
[getNodeChild](#getnodechild) ·
191+
[getNodeRef](#getnoderef) ·
192+
[getNodeRoot](#getnoderoot) ·
193+
[reduceNode](#reducenode) ·
194+
[toDataNodes](#todatanodes) ·
195+
[toSchemaNodes](#toschemanodes) ·
196+
[validate](#validate)
188197

189198
</details>
190199

191200
### addRemoteSchema
192201

193202
`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.
194203

195-
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`.
204+
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`.
196205

197206
On a compiled schema
198207

@@ -383,35 +392,35 @@ const myData = compileSchema(myJsonSchema).getData(inputData, { recursionLimit:
383392
<details><summary>Example</summary>
384393

385394
```ts
386-
import { compileSchema, JsonSchema } from 'json-schema-library';
395+
import { compileSchema, JsonSchema } from "json-schema-library";
387396

388397
const myJsonSchema: JsonSchema = {
389-
type: 'object',
390-
required: ['name', 'option', 'list'],
391-
properties: {
392-
name: { type: 'string' },
393-
option: {
394-
type: 'string',
395-
enum: ['first-option', 'second-option']
396-
},
397-
list: {
398-
type: 'array',
399-
items: {
400-
type: 'string',
401-
default: 'new item'
402-
},
403-
minItems: 1
398+
type: "object",
399+
required: ["name", "option", "list"],
400+
properties: {
401+
name: { type: "string" },
402+
option: {
403+
type: "string",
404+
enum: ["first-option", "second-option"]
405+
},
406+
list: {
407+
type: "array",
408+
items: {
409+
type: "string",
410+
default: "new item"
411+
},
412+
minItems: 1
413+
}
404414
}
405-
}
406415
};
407416

408417
const schemaNode = new compileSchema(myJsonSchema);
409418
const myData = schemaNode.getData();
410419

411420
expect(myData).to.deep.equal({
412-
name: ',
413-
option: 'first-option',
414-
list: ['new item']
421+
name: "",
422+
option: "first-option",
423+
list: ["new item"]
415424
});
416425
```
417426

@@ -846,10 +855,7 @@ In almost all cases, a JSON Pointer is given on _error.data.pointer_, which poin
846855
<details><summary>Example</summary>
847856

848857
```ts
849-
const myJsonSchema: JsonSchema = {
850-
type: "object",
851-
additionalProperties: false
852-
};
858+
const myJsonSchema: JsonSchema = { type: "object", additionalProperties: false };
853859

854860
const { errors } = compileSchema(myJsonSchema).validate({ name: "my-data" });
855861

@@ -868,14 +874,14 @@ expect(errors).to.deep.equal([
868874
You can also use async validators to validate data with json-schema. For this, another property asyncErrors is exposed on validate:
869875

870876
```ts
871-
const { isValid, errors, errorsAsync } = compileSchema(myJsonSchema).validate(myData);
877+
const { errorsAsync } = compileSchema(myJsonSchema).validate(myData);
872878

873879
if (errorsAsync.length > 0) {
874880
const additionalErrors = (await Promise.all(errorsAsync)).filter((err) => err != null);
875881
}
876882
```
877883

878-
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.
884+
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.
879885

880886
> **Note** `isValid` only refers to errors. `errorsAsync` has to be evaluated separately
881887
@@ -1051,17 +1057,9 @@ const myDraft = extendDraft(draft2020, {
10511057
});
10521058
```
10531059

1054-
<details><summary>About `oneOfFuzzyKeyword`</summary>
1055-
1056-
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.
1057-
1058-
`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.
1059-
1060-
</details>
1061-
10621060
### Keyword
10631061

1064-
`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`:
1062+
**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`:
10651063

10661064
- a `Keyword` is only processed if the specified `keyword` is available as property on the JSON Schema
10671065
- an optional `order` property may be added as order of keyword execution is sometimes important (`additionalItems` last, `$ref` evaluation first)
@@ -1157,6 +1155,13 @@ function reduceType({ node, pointer, data }: JsonSchemaReducerParams): undefined
11571155

11581156
</details>
11591157

1158+
Currently **keywords** are not exposed per default. You can still access any keyword implementation by retrieving them from a draft:
1159+
1160+
```ts
1161+
import { draft07 } from "json-schema-library";
1162+
const dependentSchemasKeyword = draft2020.keywords.find((f) => f.keyword === "dependentSchemas");
1163+
```
1164+
11601165
## Keyword extensions
11611166

11621167
### oneOfProperty
@@ -1193,6 +1198,22 @@ expect(resolvedNode?.schema).to.deep.eq({
11931198
});
11941199
```
11951200

1201+
### oneOfFuzzyKeyword
1202+
1203+
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.
1204+
1205+
`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.
1206+
1207+
`oneOfFuzzyKeyword` is exposed by _json-schema-library_ and can be used to extend any draft.
1208+
1209+
```ts
1210+
import { extendDraft, oneOfFuzzyKeyword, draft2020 } from "json-schema-library";
1211+
1212+
const myDraft = extendDraft(draft2020, {
1213+
keywords: [oneOfFuzzyKeyword]
1214+
});
1215+
```
1216+
11961217
## Breaking Changes
11971218

11981219
### v10.0.0

0 commit comments

Comments
 (0)