change: rename schemaId » schemaLocation, spointer » evaluationPath

Author: sagold

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`

README.md

@@ -112,12 +112,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>
 
@@ -1097,9 +1097,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`);
     }
 }
 ```
@@ -1147,7 +1147,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;
 }

src/SchemaNode.ts

@@ -77,10 +77,25 @@ export interface SchemaNode extends SchemaNodeMethodsType {
     context: Context;
     /** JSON Schema of node */
     schema: JsonSchema;
-    /** absolute path into JSON Schema, includes $ref for resolved schema */
-    spointer: string;
-    /** local path within JSON Schema (not extended by resolving ref) */
-    schemaId: string;
+    /**
+     * Evaluation Path - The location of the keyword that produced the annotation or error.
+     * The purpose of this data is to show the resolution path which resulted in the subschema
+     * that contains the keyword.
+     *
+     * - relative to the root of the principal schema; should include (inline) any $ref segments in the path
+     * - JSON pointer
+     */
+    evaluationPath: string;
+    /**
+     * Schema Location - The direct location to the keyword that produced the annotation
+     * or error. This is provided as a convenience to the user so that they don't have to resolve
+     * the keyword's subschema, which may not be trivial task. It is only provided if the relative
+     * location contains $refs (otherwise, the two locations will be the same).
+     *
+     * - absolute URI
+     * - may not have any association to the principal schema
+     */
+    schemaLocation: string;
     /** id created when combining subschemas */
     dynamicId: string;
     /** reference to parent node (node used to compile this node) */
@@ -163,19 +178,19 @@ export const SchemaNodeMethods = {
      */
     compileSchema(
         schema: JsonSchema,
-        spointer: string = this.spointer,
-        schemaId?: string,
+        evaluationPath: string = this.evaluationPath,
+        schemaLocation?: string,
         dynamicId?: string
     ): SchemaNode {
-        const nextFragment = spointer.split("/$ref")[0];
+        const nextFragment = evaluationPath.split("/$ref")[0];
         const parentNode = this as SchemaNode;
         const node: SchemaNode = {
             lastIdPointer: parentNode.lastIdPointer, // ref helper
             context: parentNode.context,
             parent: parentNode,
-            spointer,
+            evaluationPath,
             dynamicId: joinDynamicId(parentNode.dynamicId, dynamicId),
-            schemaId: schemaId ?? join(parentNode.schemaId, nextFragment),
+            schemaLocation: schemaLocation ?? join(parentNode.schemaLocation, nextFragment),
             reducers: [],
             resolvers: [],
             validators: [],
@@ -258,15 +273,15 @@ export const SchemaNodeMethods = {
             return { node, error: undefined };
             // @ts-expect-error bool schema
         } else if (node.schema === true) {
-            const nextNode = node.compileSchema(createSchema(data), node.spointer, node.schemaId);
+            const nextNode = node.compileSchema(createSchema(data), node.evaluationPath, node.schemaLocation);
             path?.push({ pointer, node });
             return { node: nextNode, error: undefined };
         }
 
         let schema;
         // we need to copy node to prevent modification of source
         // @todo does mergeNode break immutability?
-        let workingNode = node.compileSchema(node.schema, node.spointer, node.schemaId);
+        let workingNode = node.compileSchema(node.schema, node.evaluationPath, node.schemaLocation);
         const reducers = node.reducers;
         for (let i = 0; i < reducers.length; i += 1) {
             const result = reducers[i]({ data, key, node, pointer, path });
@@ -339,9 +354,9 @@ export const SchemaNodeMethods = {
         const draft = getDraft(context.drafts, schema?.$schema ?? this.context.rootNode.$schema);
 
         const node: SchemaNode = {
-            spointer: "#",
+            evaluationPath: "#",
             lastIdPointer: "#",
-            schemaId: "#",
+            schemaLocation: "#",
             dynamicId: "",
             reducers: [],
             resolvers: [],
@@ -379,7 +394,7 @@ export const SchemaNodeMethods = {
     },
 
     toJSON() {
-        return { ...this, context: undefined, errors: undefined, parent: this.parent?.spointer };
+        return { ...this, context: undefined, errors: undefined, parent: this.parent?.evaluationPath };
     }
 } as const;
 

src/compileSchema.reduceSchema.test.ts

@@ -821,7 +821,7 @@ describe("compileSchema : reduceNode", () => {
             assert.deepEqual(node.dynamicId, "#(dependencies/one,dependencies/two)");
         });
 
-        it("should prefix with schemaId", () => {
+        it("should prefix with schemaLocation", () => {
             const { node } =
                 compileSchema({
                     properties: {

src/compileSchema.test.ts

@@ -141,41 +141,41 @@ describe("compileSchema getDataDefaultOptions", () => {
     });
 });
 
-describe("compileSchema `schemaId`", () => {
-    it("should store path from rootSchema as schemaId", () => {
+describe("compileSchema `schemaLocation`", () => {
+    it("should store path from rootSchema as schemaLocation", () => {
         const node = compileSchema({
             if: { type: "string" },
             then: { type: "string" },
             properties: { title: { type: "string" } },
             $defs: { asset: { type: "string" } }
         });
 
-        assert.deepEqual(node.schemaId, "#");
-        assert.deepEqual(node.if.schemaId, "#/if");
-        assert.deepEqual(node.then.schemaId, "#/then");
-        assert.deepEqual(node.properties.title.schemaId, "#/properties/title");
-        assert.deepEqual(node.$defs.asset.schemaId, "#/$defs/asset");
+        assert.deepEqual(node.schemaLocation, "#");
+        assert.deepEqual(node.if.schemaLocation, "#/if");
+        assert.deepEqual(node.then.schemaLocation, "#/then");
+        assert.deepEqual(node.properties.title.schemaLocation, "#/properties/title");
+        assert.deepEqual(node.$defs.asset.schemaLocation, "#/$defs/asset");
     });
 
-    it("should maintain schemaId when resolved by ref", () => {
+    it("should maintain schemaLocation when resolved by ref", () => {
         const { node } = compileSchema({
             properties: { title: { $ref: "#/$defs/asset" } },
             $defs: { asset: { type: "string" } }
         }).getNodeChild("title");
 
         // @todo should have returned already resolved node?
         const result = node.resolveRef();
-        assert.deepEqual(result.schemaId, "#/$defs/asset");
+        assert.deepEqual(result.schemaLocation, "#/$defs/asset");
     });
 
-    it("should maintain schemaId when resolved by root-ref", () => {
+    it("should maintain schemaLocation when resolved by root-ref", () => {
         const { node } = compileSchema({
             properties: { title: { $ref: "#" } }
         }).getNodeChild("title");
 
         // @todo should have returned already resolved node?
         const result = node.resolveRef();
-        assert.deepEqual(result.schemaId, "#");
+        assert.deepEqual(result.schemaLocation, "#");
     });
 });
 

src/compileSchema.ts

@@ -35,9 +35,9 @@ export function compileSchema(schema: JsonSchema, options: CompileOptions = {})
     const draft = getDraft(drafts, schema?.$schema);
 
     const node: SchemaNode = {
-        spointer: "#",
+        evaluationPath: "#",
         lastIdPointer: "#",
-        schemaId: "#",
+        schemaLocation: "#",
         dynamicId: "",
         reducers: [],
         resolvers: [],

src/draft04/keywords/$ref.ts

@@ -25,7 +25,7 @@ function parseRef(node: SchemaNode) {
     let currentId = node.parent?.$id;
     if (node.schema?.$ref == null && node.schema?.id) {
         currentId = joinId(node.parent?.$id, node.schema.id);
-        // console.log("create id", node.spointer, ":", node.parent?.$id, node.schema?.id, "=>", currentId);
+        // console.log("create id", node.evaluationPath, ":", node.parent?.$id, node.schema?.id, "=>", currentId);
     }
     node.$id = currentId;
     node.lastIdPointer = node.parent?.lastIdPointer ?? "#";
@@ -40,17 +40,17 @@ function parseRef(node: SchemaNode) {
 
     const idChanged = currentId !== node.parent?.$id;
     if (idChanged) {
-        node.lastIdPointer = node.spointer;
+        node.lastIdPointer = node.evaluationPath;
     }
 
     // store this node for retrieval by id + json-pointer from id
-    if (node.lastIdPointer !== "#" && node.spointer.startsWith(node.lastIdPointer)) {
-        const localPointer = `#${node.spointer.replace(node.lastIdPointer, "")}`;
+    if (node.lastIdPointer !== "#" && node.evaluationPath.startsWith(node.lastIdPointer)) {
+        const localPointer = `#${node.evaluationPath.replace(node.lastIdPointer, "")}`;
         register(node, joinId(currentId, localPointer));
     } else {
-        register(node, joinId(currentId, node.spointer));
+        register(node, joinId(currentId, node.evaluationPath));
     }
-    register(node, joinId(node.context.rootNode.$id, node.spointer));
+    register(node, joinId(node.context.rootNode.$id, node.evaluationPath));
 
     // precompile reference
     if (node.schema.$ref) {
@@ -76,27 +76,27 @@ function resolveRef({ pointer, path }: { pointer?: string; path?: ValidationPath
     return resolvedNode;
 }
 
-function compileNext(referencedNode: SchemaNode, spointer = referencedNode.spointer) {
+function compileNext(referencedNode: SchemaNode, evaluationPath = referencedNode.evaluationPath) {
     const referencedSchema = isObject(referencedNode.schema)
         ? omit(referencedNode.schema, "id")
         : referencedNode.schema;
-    return referencedNode.compileSchema(referencedSchema, `${spointer}/$ref`, referencedSchema.schemaId);
+    return referencedNode.compileSchema(referencedSchema, `${evaluationPath}/$ref`, referencedSchema.schemaLocation);
 }
 
 function getRef(node: SchemaNode, $ref = node?.$ref): SchemaNode | undefined {
     if ($ref == null) {
         return node;
     }
 
-    // resolve $ref by json-spointer
+    // resolve $ref by json-evaluationPath
     if (node.context.refs[$ref]) {
         // console.log(`ref resolve ${$ref} from refs`, node.context.refs[$ref].ref);
-        return compileNext(node.context.refs[$ref], node.spointer);
+        return compileNext(node.context.refs[$ref], node.evaluationPath);
     }
 
     if (node.context.anchors[$ref]) {
         // console.log(`ref resolve ${$ref} from anchors`, node.context.anchors[$ref].ref);
-        return compileNext(node.context.anchors[$ref], node.spointer);
+        return compileNext(node.context.anchors[$ref], node.evaluationPath);
     }
 
     // check for remote-host + pointer pair to switch rootSchema
@@ -111,7 +111,7 @@ function getRef(node: SchemaNode, $ref = node?.$ref): SchemaNode | undefined {
         const $ref = fragments[0];
         // this is a reference to remote-host root node
         if (node.context.remotes[$ref]) {
-            return compileNext(node.context.remotes[$ref], node.spointer);
+            return compileNext(node.context.remotes[$ref], node.evaluationPath);
         }
         // console.error("REF: UNFOUND 1", $ref, Object.keys(node.context.remotes));
         return undefined;

src/draft06/keywords/$ref.ts

@@ -31,17 +31,17 @@ function parseRef(node: SchemaNode) {
 
     const idChanged = currentId !== node.parent?.$id;
     if (idChanged) {
-        node.lastIdPointer = node.spointer;
+        node.lastIdPointer = node.evaluationPath;
     }
 
     // store this node for retrieval by $id + json-pointer from $id
-    if (node.lastIdPointer !== "#" && node.spointer.startsWith(node.lastIdPointer)) {
-        const localPointer = `#${node.spointer.replace(node.lastIdPointer, "")}`;
+    if (node.lastIdPointer !== "#" && node.evaluationPath.startsWith(node.lastIdPointer)) {
+        const localPointer = `#${node.evaluationPath.replace(node.lastIdPointer, "")}`;
         node.context.refs[joinId(currentId, localPointer)] = node;
     } else {
-        node.context.refs[joinId(currentId, node.spointer)] = node;
+        node.context.refs[joinId(currentId, node.evaluationPath)] = node;
     }
-    node.context.refs[joinId(node.context.rootNode.$id, node.spointer)] = node;
+    node.context.refs[joinId(node.context.rootNode.$id, node.evaluationPath)] = node;
 
     // precompile reference
     if (node.schema.$ref) {

src/draft2019-09/keywords/$ref.ts

@@ -32,17 +32,17 @@ export function parseRef(node: SchemaNode) {
     const currentId = joinId(node.parent?.$id, node.schema?.$id);
     node.$id = currentId;
     node.lastIdPointer = node.parent?.lastIdPointer ?? "#";
-    if (currentId !== node.parent?.$id && node.spointer !== "#") {
-        node.lastIdPointer = node.spointer;
+    if (currentId !== node.parent?.$id && node.evaluationPath !== "#") {
+        node.lastIdPointer = node.evaluationPath;
     }
 
     // store this node for retrieval by $id + json-pointer from $id
-    if (node.lastIdPointer !== "#" && node.spointer.startsWith(node.lastIdPointer)) {
-        const localPointer = `#${node.spointer.replace(node.lastIdPointer, "")}`;
+    if (node.lastIdPointer !== "#" && node.evaluationPath.startsWith(node.lastIdPointer)) {
+        const localPointer = `#${node.evaluationPath.replace(node.lastIdPointer, "")}`;
         register(node, joinId(currentId, localPointer));
     }
     // store $rootId + json-pointer to this node
-    register(node, joinId(node.context.rootNode.$id, node.spointer));
+    register(node, joinId(node.context.rootNode.$id, node.evaluationPath));
     // store this node for retrieval by $id + anchor
     if (node.schema.$anchor) {
         node.context.anchors[`${currentId.replace(/#$/, "")}#${node.schema.$anchor}`] = node;
@@ -59,7 +59,7 @@ export function parseRef(node: SchemaNode) {
 
 // export function reduceRef({ node, data, key, pointer, path }: JsonSchemaReducerParams) {
 //     const resolvedNode = node.resolveRef({ pointer, path });
-//     if (resolvedNode.schemaId === node.schemaId) {
+//     if (resolvedNode.schemaLocation === node.schemaLocation) {
 //         return resolvedNode;
 //     }
 //     const result = resolvedNode.reduceNode(data, { key, pointer, path });
@@ -128,26 +128,26 @@ function resolveRecursiveRef(node: SchemaNode, path: ValidationPath): SchemaNode
     return nextNode;
 }
 
-function compileNext(referencedNode: SchemaNode, spointer = referencedNode.spointer) {
+function compileNext(referencedNode: SchemaNode, evaluationPath = referencedNode.evaluationPath) {
     const referencedSchema = isObject(referencedNode.schema)
         ? omit(referencedNode.schema, "$id")
         : referencedNode.schema;
 
-    return referencedNode.compileSchema(referencedSchema, `${spointer}/$ref`, referencedNode.schemaId);
+    return referencedNode.compileSchema(referencedSchema, `${evaluationPath}/$ref`, referencedNode.schemaLocation);
 }
 
 export default function getRef(node: SchemaNode, $ref = node?.$ref): SchemaNode | undefined {
     if ($ref == null) {
         return node;
     }
 
-    // resolve $ref by json-spointer
+    // resolve $ref by json-evaluationPath
     if (node.context.refs[$ref]) {
-        return compileNext(node.context.refs[$ref], node.spointer);
+        return compileNext(node.context.refs[$ref], node.evaluationPath);
     }
     // resolve $ref from $anchor
     if (node.context.anchors[$ref]) {
-        return compileNext(node.context.anchors[$ref], node.spointer);
+        return compileNext(node.context.anchors[$ref], node.evaluationPath);
     }
 
     // check for remote-host + pointer pair to switch rootSchema
@@ -162,7 +162,7 @@ export default function getRef(node: SchemaNode, $ref = node?.$ref): SchemaNode
         const $ref = fragments[0];
         // this is a reference to remote-host root node
         if (node.context.remotes[$ref]) {
-            return compileNext(node.context.remotes[$ref], node.spointer);
+            return compileNext(node.context.remotes[$ref], node.evaluationPath);
         }
         if ($ref[0] === "#") {
             // @todo there is a bug joining multiple fragments to e.g. #/base#/examples/0
@@ -172,7 +172,7 @@ export default function getRef(node: SchemaNode, $ref = node?.$ref): SchemaNode
             const rootSchema = node.context.rootNode.schema;
             const targetSchema = get(rootSchema, ref);
             if (targetSchema) {
-                return node.compileSchema(targetSchema, `${node.spointer}/$ref`, ref);
+                return node.compileSchema(targetSchema, `${node.evaluationPath}/$ref`, ref);
             }
         }
         // console.error("REF: UNFOUND 1", $ref);