@hyperjump/json-schema 1.3.0 → 1.4.0

package/README.md

@@ -15,6 +15,7 @@ A collection of modules for working with JSON Schemas.
   * Uses the process defined in the 2020-12 specification but works with any
     dialect.
 * Provides utilities for building non-validation JSON Schema tooling
+* Provides utilities for working with annotations
 
 ## Install
 Includes support for node.js (ES Modules, TypeScript) and browsers.
@@ -238,11 +239,11 @@ The following types are used in the above definitions
 
 ## Bundling
 ### Usage
-You can bundle schemas with external references into single deliverable using
+You can bundle schemas with external references into a single deliverable using
 the official JSON Schema bundling process introduced in the 2020-12
 specification. Given a schema with external references, any external schemas
 will be embedded in the schema resulting in a Compound Schema Document with all
-the schemas necessary to evaluate the given schema in one document.
+the schemas necessary to evaluate the given schema in a single JSON document.
 
 The bundling process allows schemas to be embedded without needing to modify any
 references which means you get the same output details whether you validate the
@@ -374,9 +375,9 @@ addKeyword({
     return Schema.map(async (itemSchema) => Validation.compile(await itemSchema, ast), schema);
   },
 
-  interpret: (implies, instance, ast, dynamicAnchors) => {
+  interpret: (implies, instance, ast, dynamicAnchors, quiet) => {
     return implies.reduce((acc, schema) => {
-      return !acc || Validation.interpret(schema, instance, ast, dynamicAnchors);
+      return !acc || Validation.interpret(schema, instance, ast, dynamicAnchors, quiet);
     }, true);
   }
 });
@@ -518,7 +519,7 @@ These are available from the `@hyperjump/json-schema/experimental` export.
         needed for compiling sub-schemas. The `parentSchema` parameter is
         primarily useful for looking up the value of an adjacent keyword that
         might effect this one.
-    * interpret: (compiledKeywordValue: A, instance: JsonDocument, ast: AST, dynamicAnchors: Anchors) => boolean
+    * interpret: (compiledKeywordValue: A, instance: JsonDocument, ast: AST, dynamicAnchors: Anchors, quiet: boolean) => boolean
 
         This function takes the value returned by the `compile` function and the
         instance value that is being validated and returns whether the value is
@@ -643,6 +644,116 @@ set of functions for working with InstanceDocuments.
 
     Similar to `Array.prototype.length`.
 
+## Annotations (Experimental)
+JSON Schema is for annotating JSON instances as well as validating them. This
+module provides utilities for working with JSON documents annotated with JSON
+Schema.
+
+### Usage
+An annotated JSON document is represented as an AnnotatedInstance object. This
+object is a wrapper around your JSON document with functions that allow you to
+traverse the data structure and get annotations for the values within.
+
+```javascript
+import { annotate, annotatedWith, addSchema } from "@hyperjump/json-schema/annotations/experimental";
+import * as AnnotatedInstance from "@hyperjump/json-schema/annotated-instance/experimental";
+
+
+const schemaId = "https://example.com/foo";
+const dialectId = "https://json-schema.org/draft/2020-12/schema";
+
+addSchema({
+  "$schema": dialectId,
+
+  "title": "Person",
+  "unknown": "foo",
+
+  "type": "object",
+  "properties": {
+    "name": {
+      "$ref": "#/$defs/name",
+      "deprecated": true
+    },
+    "givenName": {
+      "$ref": "#/$defs/name",
+      "title": "Given Name"
+    },
+    "familyName": {
+      "$ref": "#/$defs/name",
+      "title": "Family Name"
+    }
+  },
+
+  "$defs": {
+    "name": {
+      "type": "string",
+      "title": "Name"
+    }
+  }
+}, schemaId);
+
+const instance = await annotate(schemaId, {
+  name: "Jason Desrosiers",
+  givenName: "Jason",
+  familyName: "Desrosiers"
+});
+
+// Get the title of the instance
+const titles = AnnotatedInstance.annotation(instance, "title", dialectId); // => ["Person"]
+
+// Unknown keywords are collected as annotations
+const unknowns = AnnotatedInstance.annotation(instance, "unknown", dialectId); // => ["foo"]
+
+// The type keyword doesn't produce annotations
+const types = AnnotatedInstance.annotation(instance, "type", dialectId); // => []
+
+// Get the title of each of the properties in the object
+AnnotatedInstance.entries(instance)
+  .map(([propertyName, propertyInstance]) => {
+    return { propertyName, titles: Instance.annotation(propertyInstance, "title", dialectId) }; // => (Example) { propertyName: "givenName", titles: ["Given Name", "Name"] });
+
+// List all locations in the instance that are deprecated
+for (const deprecated of AnnotatedInstance.annotatedWith(instance, "deprecated", dialectId)) {
+  if (AnnotatedInstance.annotation(instance, "deprecated", dialectId)[0]) {
+    logger.warn(`The value at '${deprecated.pointer}' has been deprecated.`); // => (Example) "WARN: The value at '/name' has been deprecated."
+  }
+}
+```
+
+### API
+These are available from the `@hyperjump/json-schema/annotations/experimental`
+export.
+
+* **annotate**: (schemaUri: string, instance: any, outputFormat: OutputFormat = FLAG) => Promise<AnnotatedInstance>
+
+    Annotate an instance using the given schema. The function is curried to
+    allow compiling the schema once and applying it to multiple instances. This
+    may throw an [InvalidSchemaError](#api) if there is a problem with the
+    schema or a ValidationError if the instance doesn't validate against the
+    schema.
+* **ValidationError**:
+    output: OutputUnit -- The errors that were found while validating the
+    instance.
+
+### AnnotatedInstance API
+These are available from the
+`@hyperjump/json-schema/annotated-instance/experimental` export. The
+following functions are available in addition to the functions available in the
+[Instance API](#instance-api).
+
+* **annotation**: (instance: AnnotatedInstance, keyword: string, dialectId?: string) => [any]
+
+    Get the annotations for a given keyword at the location represented by the
+    instance object.
+* **annotatedWith**: (instance: AnnotatedInstance, keyword: string, dialectId?: string) => [AnnotatedInstance]
+
+    Get an array of instances for all the locations that are annotated with the
+    given keyword.
+* **annotate**: (instance: AnnotatedInstance, keywordId: string, value: any) => AnnotatedInstance
+
+    Add an annotation to an instance. This is used internally, you probably
+    don't need it.
+
 ## Low-level Utilities (Experimental)
 ### API
 These are available from the `@hyperjump/json-schema/experimental` export.

package/annotations/annotated-instance.d.ts

@@ -0,0 +1,83 @@
+import type { JsonType } from "../lib/common.js";
+import type { Json, JsonObject } from "@hyperjump/json-pointer";
+
+
+export const annotate: (instance: AnnotatedJsonDocument, keyword: string, value: string) => AnnotatedJsonDocument;
+export const annotation: <A>(instance: AnnotatedJsonDocument, keyword: string, dialectId?: string) => A[];
+export const annotatedWith: (instance: AnnotatedJsonDocument, keyword: string, dialectId?: string) => AnnotatedJsonDocument[];
+export const nil: AnnotatedJsonDocument<undefined>;
+export const cons: (instance: Json, id?: string) => AnnotatedJsonDocument;
+export const get: (uri: string, context?: AnnotatedJsonDocument) => AnnotatedJsonDocument;
+export const uri: (doc: AnnotatedJsonDocument) => string;
+export const value: <A extends Json>(doc: AnnotatedJsonDocument<A>) => A;
+export const has: (key: string, doc: AnnotatedJsonDocument<JsonObject>) => boolean;
+export const typeOf: (
+  (doc: AnnotatedJsonDocument, type: "null") => doc is AnnotatedJsonDocument<null>
+) & (
+  (doc: AnnotatedJsonDocument, type: "boolean") => doc is AnnotatedJsonDocument<boolean>
+) & (
+  (doc: AnnotatedJsonDocument, type: "object") => doc is AnnotatedJsonDocument<JsonObject>
+) & (
+  (doc: AnnotatedJsonDocument, type: "array") => doc is AnnotatedJsonDocument<Json[]>
+) & (
+  (doc: AnnotatedJsonDocument, type: "number" | "integer") => doc is AnnotatedJsonDocument<number>
+) & (
+  (doc: AnnotatedJsonDocument, type: "string") => doc is AnnotatedJsonDocument<string>
+) & (
+  (doc: AnnotatedJsonDocument, type: JsonType) => boolean
+) & (
+  (doc: AnnotatedJsonDocument) => (type: JsonType) => boolean
+);
+export const step: (key: string, doc: AnnotatedJsonDocument<JsonObject | Json[]>) => AnnotatedJsonDocument<typeof doc.value>;
+export const entries: (doc: AnnotatedJsonDocument<JsonObject>) => [string, AnnotatedJsonDocument][];
+export const keys: (doc: AnnotatedJsonDocument<JsonObject>) => string[];
+export const map: (
+  <A>(fn: MapFn<A>, doc: AnnotatedJsonDocument<Json[]>) => A[]
+) & (
+  <A>(fn: MapFn<A>) => (doc: AnnotatedJsonDocument<Json[]>) => A[]
+);
+export const forEach: (
+  (fn: ForEachFn, doc: AnnotatedJsonDocument<Json[]>) => void
+) & (
+  (fn: ForEachFn) => (doc: AnnotatedJsonDocument<Json[]>) => void
+);
+export const filter: (
+  (fn: FilterFn, doc: AnnotatedJsonDocument<Json[]>) => AnnotatedJsonDocument[]
+) & (
+  (fn: FilterFn) => (doc: AnnotatedJsonDocument<Json[]>) => AnnotatedJsonDocument[]
+);
+export const reduce: (
+  <A>(fn: ReduceFn<A>, acc: A, doc: AnnotatedJsonDocument<Json[]>) => A
+) & (
+  <A>(fn: ReduceFn<A>) => (acc: A, doc: AnnotatedJsonDocument<Json[]>) => A
+) & (
+  <A>(fn: ReduceFn<A>) => (acc: A) => (doc: AnnotatedJsonDocument<Json[]>) => A
+);
+export const every: (
+  (fn: FilterFn, doc: AnnotatedJsonDocument<Json[]>) => boolean
+) & (
+  (fn: FilterFn) => (doc: AnnotatedJsonDocument<Json[]>) => boolean
+);
+export const some: (
+  (fn: FilterFn, doc: AnnotatedJsonDocument<Json[]>) => boolean
+) & (
+  (fn: FilterFn) => (doc: AnnotatedJsonDocument<Json[]>) => boolean
+);
+export const length: (doc: AnnotatedJsonDocument<Json[] | string>) => number;
+
+type MapFn<A> = (element: AnnotatedJsonDocument, index: number) => A;
+type ForEachFn = (element: AnnotatedJsonDocument, index: number) => void;
+type FilterFn = (element: AnnotatedJsonDocument, index: number) => boolean;
+type ReduceFn<A> = (accumulator: A, currentValue: AnnotatedJsonDocument, index: number) => A;
+
+export type AnnotatedJsonDocument<A extends Json | undefined = Json> = {
+  id: string;
+  pointer: string;
+  instance: Json;
+  value: A;
+  annotations: {
+    [pointer: string]: {
+      [keyword: string]: unknown[]
+    }
+  }
+};

package/annotations/annotated-instance.js

@@ -0,0 +1,50 @@
+import { toAbsoluteUri } from "../lib/common.js";
+import { nil as nilInstance, get } from "../lib/instance.js";
+import { getKeywordId } from "../lib/keywords.js";
+
+
+const defaultDialectId = "https://json-schema.org/validation";
+
+export const nil = { ...nilInstance, annotations: {} };
+export const cons = (instance, id = undefined) => ({
+  ...nil,
+  id: id ? toAbsoluteUri(id) : "",
+  instance,
+  value: instance
+});
+
+export const annotation = (instance, keyword, dialectId = defaultDialectId) => {
+  const keywordId = getKeywordId(dialectId, keyword);
+  return instance.annotations?.[instance.pointer]?.[keywordId] || [];
+};
+
+export const annotate = (instance, keyword, value) => {
+  return Object.freeze({
+    ...instance,
+    annotations: {
+      ...instance.annotations,
+      [instance.pointer]: {
+        ...instance.annotations[instance.pointer],
+        [keyword]: [
+          value,
+          ...instance.annotations[instance.pointer]?.[keyword] || []
+        ]
+      }
+    }
+  });
+};
+
+export const annotatedWith = (instance, keyword, dialectId = defaultDialectId) => {
+  const instances = [];
+
+  const keywordId = getKeywordId(dialectId, keyword);
+  for (const instancePointer in instance.annotations) {
+    if (keywordId in instance.annotations[instancePointer]) {
+      instances.push(get(`#${instancePointer}`, instance));
+    }
+  }
+
+  return instances;
+};
+
+export * from "../lib/instance.js";

package/annotations/index.d.ts

@@ -0,0 +1,11 @@
+import type { OutputFormat } from "../lib/core.js";
+import type { AnnotatedJsonDocument } from "./annotated-instance.js";
+
+
+export const annotate: (
+  (schemaUrl: string, value: unknown, outputFormat?: OutputFormat) => Promise<Annotator>
+) & (
+  (schemaUrl: string) => Promise<Annotator>
+);
+
+export type Annotator = (value: unknown, outputFormat?: OutputFormat) => AnnotatedJsonDocument;

package/annotations/index.js

@@ -0,0 +1,123 @@
+import { subscribe, unsubscribe } from "../lib/pubsub.js";
+import { compile, interpret as validate, BASIC } from "../lib/core.js";
+import { getKeyword } from "../lib/keywords.js";
+import * as Instance from "./annotated-instance.js";
+import { ValidationError } from "./validation-error.js";
+
+
+export const annotate = async (schemaUri, json = undefined, outputFormat = undefined) => {
+  loadKeywordSupport();
+  const compiled = await compile(schemaUri);
+  const interpretAst = (json, outputFormat) => interpret(compiled, Instance.cons(json), outputFormat);
+
+  return json === undefined ? interpretAst : interpretAst(json, outputFormat);
+};
+
+const interpret = ({ ast, schemaUri }, instance, outputFormat = BASIC) => {
+  const output = [instance];
+  const subscriptionToken = subscribe("result", outputHandler(output));
+
+  try {
+    const result = validate({ ast, schemaUri }, instance, outputFormat);
+    if (!result.valid) {
+      throw new ValidationError(result);
+    }
+  } finally {
+    unsubscribe("result", subscriptionToken);
+  }
+
+  return output[0];
+};
+
+const outputHandler = (output) => {
+  let isPassing = true;
+  const instanceStack = [];
+
+  return (message, resultNode) => {
+    if (message === "result.start") {
+      instanceStack.push(output[0]);
+      isPassing = true;
+    } else if (message === "result" && isPassing) {
+      output[0] = Instance.get(resultNode.instanceLocation, output[0]);
+
+      if (resultNode.valid) {
+        const keywordHandler = getKeyword(resultNode.keyword);
+        if (keywordHandler?.annotation) {
+          const annotation = keywordHandler.annotation(resultNode.ast);
+          output[0] = Instance.annotate(output[0], resultNode.keyword, annotation);
+        }
+      } else {
+        output[0] = instanceStack[instanceStack.length - 1];
+        isPassing = false;
+      }
+    } else if (message === "result.end") {
+      instanceStack.pop();
+    }
+  };
+};
+
+const identity = (a) => a;
+
+const loadKeywordSupport = () => {
+  const title = getKeyword("https://json-schema.org/keyword/title");
+  if (title) {
+    title.annotation = identity;
+  }
+
+  const description = getKeyword("https://json-schema.org/keyword/description");
+  if (description) {
+    description.annotation = identity;
+  }
+
+  const _default = getKeyword("https://json-schema.org/keyword/default");
+  if (_default) {
+    _default.annotation = identity;
+  }
+
+  const deprecated = getKeyword("https://json-schema.org/keyword/deprecated");
+  if (deprecated) {
+    deprecated.annotation = identity;
+  }
+
+  const readOnly = getKeyword("https://json-schema.org/keyword/readOnly");
+  if (readOnly) {
+    readOnly.annotation = identity;
+  }
+
+  const writeOnly = getKeyword("https://json-schema.org/keyword/writeOnly");
+  if (writeOnly) {
+    writeOnly.annotation = identity;
+  }
+
+  const examples = getKeyword("https://json-schema.org/keyword/examples");
+  if (examples) {
+    examples.annotation = identity;
+  }
+
+  const format = getKeyword("https://json-schema.org/keyword/format");
+  if (format) {
+    format.annotation = identity;
+  }
+
+  const contentMediaType = getKeyword("https://json-schema.org/keyword/contentMediaType");
+  if (contentMediaType) {
+    contentMediaType.annotation = identity;
+  }
+
+  const contentEncoding = getKeyword("https://json-schema.org/keyword/contentEncoding");
+  if (contentEncoding) {
+    contentEncoding.annotation = identity;
+  }
+
+  const contentSchema = getKeyword("https://json-schema.org/keyword/contentSchema");
+  if (contentSchema) {
+    contentSchema.annotation = identity;
+  }
+
+  const unknown = getKeyword("https://json-schema.org/keyword/unknown");
+  if (unknown) {
+    unknown.annotation = identity;
+  }
+};
+
+export { ValidationError } from "./validation-error.js";