change!: getSchema signature and return errors consistently

- docs: update upcoming breaking changes
- chore: update dist
- fix: return oneOf error in reduceSchema
- change!: errors to always contain schema and value data
- change: getSchema to return error when a schema cannot be resolved
- fix: getSchema pointer and return type
- fix: createSchemaOf to return undefined for missing data

Author: Sascha Goldhofer

CHANGELOG.md

@@ -1,6 +1,12 @@
 ## Changelog
 
-### 8.0.0
+### v9.0.0
+
+-   [Breaking] error data to always contain `schema` and `value`
+-   [Breaking] getSchema arguments changed to options-object
+-   [Add] withSchemaWarning option for getSchema to always return an error fpr undefined schema
+
+### v8.0.0
 
 -   [Breaking] renamed `JSON` types and variables to `Json`
 -   [Breaking] remove `oneOfSchema` helper property in favor of `getOneOfOrigin()` non-enumerable function

README.md

@@ -357,12 +357,28 @@ expect(calls).to.deep.equal([
 
 ### getSchema
 
-`getSchema` retrieves the json-schema of a specific location in data. The location in data is given by a _json-pointer_. In many cases the schema can be retrieved without passing the actual data, but in situations where the schema is dynamic (e.g., in _oneOf_, _dependencies_, etc.), the data is required or will return a _JsonError_ if the location cannot be found.
+`getSchema` retrieves the json-schema of a specific location in data. The location in data is given by a _json-pointer_. In many cases the json-schema can be retrieved without passing any data, but in situations where the schema is dynamic (for example in _oneOf_, _dependencies_, etc.), the data is required or will return a _JsonError_ if the location cannot be found.
 
 ```ts
 const jsonSchema = new Draft07(mySchema);
-let schemaOfName: JsonSchema | JsonError;
-schemaOfName = jsonSchema.getSchema("/list/1/name", myData);
+let schemaOfName: JsonSchema | JsonError | undefined;
+schemaOfName = jsonSchema.getSchema({ pointer: "/list/1/name", data: myData });
+```
+
+**Note** that `getSchema` will return `undefined` for paths that lead to valid properties, but miss a schema definition. For example:
+
+```ts
+const jsonSchema = new Draft07({ type: "object" });
+let schemaOfName = jsonSchema.getSchema({ pointer: "/name" });
+console.log(schemaOfName); // undefined
+```
+
+In case this is unwanted behaviour, use the `withSchemaWarning` option to return a json-error with code `schema-warning` instead:
+
+```ts
+const jsonSchema = new Draft07({ type: "object" });
+let schemaOfName = jsonSchema.getSchema({ pointer: "/name", withSchemaWarning: true });
+console.log(schemaOfName); // { type: "error", code: "schema-warning" }
 ```
 
 <details><summary>Example</summary>
@@ -404,9 +420,12 @@ const mySchema = {
 };
 
 const jsonSchema = new Draft07(mySchema);
-let schemaOfItem: JsonSchema | JsonError;
-schemaOfItem = jsonSchema.getSchema("/list/1", {
-    list: [{ description: "..." }, { name: "my-item" }]
+let schemaOfItem: JsonSchema | JsonError | undefined;
+schemaOfItem = jsonSchema.getSchema({
+    pointer: "/list/1",
+    data: {
+        list: [{ description: "..." }, { name: "my-item" }]
+    }
 });
 
 expect(schemaOfItem).to.deep.equal({
@@ -423,6 +442,23 @@ expect(schemaOfItem).to.deep.equal({
 
 </details>
 
+<details><summary>Evaluating errors</summary>
+
+All returned json-errors have a data property with the following properties
+
+-   `pointer` json-pointer to the location where the error occured. In case of omitted data, this is the last json-schema location that could be resolved
+-   `schema` the json-schema of the last resolved location and the source of the error
+-   `value` the data value at this location that could not be resolved
+
+```ts
+const schema = jsonSchema.getSchema({ pointer: "/list/1" });
+if (isJsonError(schema)) {
+    console.log(Object.keys(schema.data)); // [pointer, schema, value]
+}
+```
+
+</details>
+
 <details><summary>About JsonPointer</summary>
 
 **[Json-Pointer](https://tools.ietf.org/html/rfc6901)** defines a string syntax for identifying a specific value within a Json document and is [supported by Json-Schema](https://json-schema.org/understanding-json-schema/structuring.html). Given a Json document, it behaves similar to a [lodash path](https://lodash.com/docs/4.17.5#get) (`a[0].b.c`), which follows JS-syntax, but instead uses `/` separators (e.g., `a/0/b/c`). In the end, you describe a path into the Json data to a specific point.
@@ -919,6 +955,17 @@ const error: JsonError = createError("EnumError", { data: { pointer: "#/location
 
 ## Breaking Changes
 
+### v9.0.0
+
+**breaking changes**:
+
+-   _getSchema_ signature changed in favor of an options object. Instead of `draft.getSchema(pointer, data)` arguments have to be passed as an object `draft.getSchema({ pointer, data })`. This removes setting unwanted optional arguments and keeps the api more stable in the future (e.g. `withSchemaWarning` option)
+-   _JsonError_ now must expose `pointer`, `schema` and `value` consistently on data property
+
+**updates**
+
+-   _getSchema_ consistently returns errors and can return errors for empty schema using `withSchemaWarning` option
+
 ### v8.0.0
 
 With version `v8.0.0`, _getTemplate_ was improved to better support optional properties and utilize existing core logic, making it more reliable. Breaking changes:

dist/index.d.ts

@@ -36,7 +36,8 @@ resolveOneOf, resolveOneOfFuzzy, resolveRef, resolveRefMerge, settings, validate
 import { DraftConfig } from "./lib/draft";
 import { EachCallback } from "./lib/each";
 import { EachSchemaCallback } from "./lib/eachSchema";
-import { ErrorData, CreateError } from "./lib/utils/createCustomError";
-import { JsonSchema, JsonPointer, JsonError, JsonValidator, JsonTypeValidator } from "./lib/types";
+import { CreateError } from "./lib/utils/createCustomError";
+import { GetSchemaOptions } from "./lib/getSchema";
+import { JsonSchema, JsonPointer, JsonError, JsonValidator, JsonTypeValidator, ErrorData } from "./lib/types";
 import { JSType } from "./lib/getTypeOf";
-export type { CreateError, DraftConfig, EachCallback, EachSchemaCallback, ErrorData, JsonError, JsonPointer, JsonSchema, JsonTypeValidator, JsonValidator, JSType };
+export type { CreateError, DraftConfig, EachCallback, EachSchemaCallback, ErrorData, GetSchemaOptions, JsonError, JsonPointer, JsonSchema, JsonTypeValidator, JsonValidator, JSType };

dist/jsonSchemaLibrary.js

@@ -2,6 +2,5 @@ import { JsonSchema } from "./types";
 /**
  * Create a simple json schema for the given input data
  * @param  data - data to get json schema for
- * @return schema
  */
-export default function createSchemaOf(data: any): JsonSchema;
+export default function createSchemaOf(data: unknown): JsonSchema | undefined;

dist/lib/createSchemaOf.d.ts

@@ -2,7 +2,7 @@ import addRemoteSchema from "../addRemoteSchema";
 import compileSchema from "../compileSchema";
 import createSchemaOf from "../createSchemaOf";
 import getChildSchemaSelection from "../getChildSchemaSelection";
-import getSchema from "../getSchema";
+import getSchema, { GetSchemaOptions } from "../getSchema";
 import getTemplate, { TemplateOptions } from "../getTemplate";
 import isValid from "../isValid";
 import resolveRef from "../resolveRef.strict";
@@ -83,16 +83,27 @@ export declare class Draft {
     getChildSchemaSelection(property: string | number, schema?: JsonSchema): JsonError | JsonSchema[];
     /**
      * Returns the json-schema of a data-json-pointer.
+     *
+     * To resolve dynamic schema where the type of json-schema is evaluated by
+     * its value, a data object has to be passed in options.
+     *
+     * Per default this function will return `undefined` for valid properties that
+     * do not have a defined schema. Use the option `withSchemaWarning: true` to
+     * receive an error with `code: schema-warning` containing the location of its
+     * last evaluated json-schema.
+     *
      * Notes
-     *   - Uses draft.step to walk through data and schema
+     *      - uses draft.step to walk through data and schema
      *
+     * @param draft
      * @param pointer - json pointer in data to get the json schema for
-     * @param [data] - the data object, which includes the json pointers value. This is optional, as
+     * @param [options.data] - the data object, which includes the json pointers value. This is optional, as
      *    long as no oneOf, anyOf, etc statement is part of the pointers schema
-     * @param [schema] - the json schema to iterate. Defaults to draft.rootSchema
-     * @return json schema object of the json-pointer or an error
+     * @param [options.schema] - the json schema to iterate. Defaults to draft.rootSchema
+     * @param [options.withSchemaWarning] - if true returns an error instead of `undefined` for valid properties missing a schema definition
+     * @return resolved json-schema object of requested json-pointer location
      */
-    getSchema(pointer?: JsonPointer, data?: any, schema?: JsonSchema): JsonSchema | JsonError;
+    getSchema(options?: GetSchemaOptions): JsonSchema | JsonError | undefined;
     /**
      * Create data object matching the given schema
      *

dist/lib/draft/index.d.ts

@@ -1,16 +1,31 @@
 import { JsonSchema, JsonPointer } from "./types";
 import { Draft } from "./draft";
+export type GetSchemaOptions = {
+    pointer?: JsonPointer;
+    data?: unknown;
+    schema?: JsonSchema;
+    withSchemaWarning?: boolean;
+};
 /**
  * Returns the json-schema of a data-json-pointer.
  *
- *  Notes
- *      - Uses draft.step to walk through data and schema
+ * To resolve dynamic schema where the type of json-schema is evaluated by
+ * its value, a data object has to be passed in options.
+ *
+ * Per default this function will return `undefined` for valid properties that
+ * do not have a defined schema. Use the option `withSchemaWarning: true` to
+ * receive an error with `code: schema-warning` containing the location of its
+ * last evaluated json-schema.
+ *
+ * Notes
+ *      - uses draft.step to walk through data and schema
  *
  * @param draft
  * @param pointer - json pointer in data to get the json schema for
- * @param [data] - the data object, which includes the json pointers value. This is optional, as
+ * @param [options.data] - the data object, which includes the json pointers value. This is optional, as
  *    long as no oneOf, anyOf, etc statement is part of the pointers schema
- * @param [schema] - the json schema to iterate. Defaults to draft.rootSchema
- * @return json schema object of the json-pointer or an error
+ * @param [options.schema] - the json schema to iterate. Defaults to draft.rootSchema
+ * @param [options.withSchemaWarning] - if true returns an error instead of `undefined` for valid properties missing a schema definition
+ * @return resolved json-schema object of requested json-pointer location or json-error
  */
-export default function getSchema(draft: Draft, pointer: JsonPointer, data?: unknown, schema?: JsonSchema): JsonSchema;
+export default function getSchema(draft: Draft, options?: GetSchemaOptions): JsonSchema;

dist/lib/getSchema.d.ts

@@ -1,4 +1,4 @@
-import { JsonSchema } from "./types";
+import { JsonSchema, JsonPointer } from "./types";
 import { Draft } from "./draft";
 /**
  * reduces json schema by merging dynamic constructs like if-then-else,
@@ -8,4 +8,4 @@ import { Draft } from "./draft";
  * @returns input schema reduced by dynamic schema definitions for the given
  * input data
  */
-export declare function reduceSchema(draft: Draft, schema: JsonSchema, data: unknown): JsonSchema;
+export declare function reduceSchema(draft: Draft, schema: JsonSchema, data: unknown, pointer: JsonPointer): JsonSchema;

dist/lib/reduceSchema.d.ts

@@ -1,4 +1,4 @@
-import { JsonSchema } from "./types";
+import { JsonPointer, JsonSchema } from "./types";
 import { Draft } from "./draft";
 import { JsonData } from "@sagold/json-pointer";
 export declare function isDynamicSchema(schema: JsonData): boolean;
@@ -18,4 +18,4 @@ export declare function isDynamicSchema(schema: JsonData): boolean;
  * @returns static schema from resolved dynamic schema definitions for this
  *  specific input data
  */
-export declare function resolveDynamicSchema(draft: Draft, schema: JsonSchema, data: unknown): Record<string, unknown>;
+export declare function resolveDynamicSchema(draft: Draft, schema: JsonSchema, data: unknown, pointer: JsonPointer): Record<string, unknown>;

dist/lib/resolveDynamicSchema.d.ts

@@ -3,15 +3,20 @@ export type JsonSchema = {
     [p: string]: any;
 };
 export type JsonPointer = string;
-export type JsonError = {
+export type ErrorData<T extends Record<string, unknown> = {
+    [p: string]: unknown;
+}> = T & {
+    pointer: string;
+    schema: JsonSchema;
+    value: unknown;
+};
+export type JsonError<T extends ErrorData = ErrorData> = {
     type: "error";
     name: string;
     code: string;
     message: string;
-    data?: {
-        [p: string]: any;
-    };
-    [p: string]: any;
+    data: T;
+    [p: string]: unknown;
 };
 /**
  * ts type guard for json error