@json-schema-engine/core 0.0.1

package/src/keywords/vocab2020.ts

@@ -0,0 +1,82 @@
+// Assembly of the 2020-12 dialect from its vocabularies (DESIGN.md D2).
+
+import { KeywordBehavior, DialectRegistry } from "../dialect.js";
+import { coreVocabulary, VOCAB_CORE, annotationOnly } from "./core.js";
+import { applicatorVocabulary, VOCAB_APPLICATOR } from "./applicator.js";
+import { validationVocabulary, VOCAB_VALIDATION } from "./validation.js";
+import { unevaluatedVocabulary, VOCAB_UNEVALUATED } from "./unevaluated.js";
+import { registerDialect2019 } from "./vocab2019.js";
+import { registerDialect07, registerDialect06 } from "./vocab7.js";
+
+/** 2020-12 meta-data vocabulary URI. */
+export const VOCAB_META_DATA =
+  "https://json-schema.org/draft/2020-12/vocab/meta-data";
+/** 2020-12 format-annotation vocabulary URI. */
+export const VOCAB_FORMAT_ANNOTATION =
+  "https://json-schema.org/draft/2020-12/vocab/format-annotation";
+/** 2020-12 content vocabulary URI. */
+export const VOCAB_CONTENT =
+  "https://json-schema.org/draft/2020-12/vocab/content";
+
+/** 2020-12 dialect URI. */
+export const DIALECT_2020_12 = "https://json-schema.org/draft/2020-12/schema";
+
+const metaDataVocabulary = Object.fromEntries(
+  [
+    "title",
+    "description",
+    "default",
+    "deprecated",
+    "readOnly",
+    "writeOnly",
+    "examples",
+  ].map((name) => [name, annotationOnly(`${VOCAB_META_DATA}#${name}`)]),
+);
+
+/**
+ * Options for {@link registerStandardDialects} (M7): `format` replaces the
+ * default annotation-only `format` behavior in every standard dialect —
+ * the `assertFormats` best-effort configuration.
+ */
+export interface StandardDialectOptions {
+  format?: (id: string) => KeywordBehavior;
+}
+
+// content* keywords are never assertions.
+const contentVocabulary = Object.fromEntries(
+  ["contentMediaType", "contentEncoding", "contentSchema"].map((name) => [
+    name,
+    annotationOnly(`${VOCAB_CONTENT}#${name}`),
+  ]),
+);
+
+/** Registers the 2020-12, 2019-09, draft-07, and draft-06 vocabularies and dialects. */
+export function registerStandardDialects(
+  registry: DialectRegistry,
+  options: StandardDialectOptions = {},
+): void {
+  const format = options.format ?? annotationOnly;
+  registry.registerVocabulary(VOCAB_CORE, coreVocabulary);
+  registry.registerVocabulary(VOCAB_APPLICATOR, applicatorVocabulary);
+  registry.registerVocabulary(VOCAB_VALIDATION, validationVocabulary);
+  registry.registerVocabulary(VOCAB_UNEVALUATED, unevaluatedVocabulary);
+  registry.registerVocabulary(VOCAB_META_DATA, metaDataVocabulary);
+  registry.registerVocabulary(VOCAB_FORMAT_ANNOTATION, {
+    format: format(`${VOCAB_FORMAT_ANNOTATION}#format`),
+  });
+  registry.registerVocabulary(VOCAB_CONTENT, contentVocabulary);
+
+  registry.registerDialect(DIALECT_2020_12, [
+    VOCAB_CORE,
+    VOCAB_APPLICATOR,
+    VOCAB_VALIDATION,
+    VOCAB_UNEVALUATED,
+    VOCAB_META_DATA,
+    VOCAB_FORMAT_ANNOTATION,
+    VOCAB_CONTENT,
+  ]);
+
+  registerDialect2019(registry, format);
+  registerDialect07(registry, format);
+  registerDialect06(registry, format);
+}

package/src/keywords/vocab7.ts

@@ -0,0 +1,393 @@
+// draft-07 and draft-06 dialects (DESIGN.md M4-B, D11, D18). These drafts
+// predate `$vocabulary`, so there are no official vocabulary URIs to assemble
+// from (contrast vocab2019.ts) — the URIs minted below are registry
+// identities only (D2/D18), never exposed as spec-meaningful vocabulary
+// documents. draft-06 is a strict keyword subset of draft-07 (D11 amendment),
+// so its vocabulary objects are built by omission from the draft-07 ones.
+
+import { isObject, JsonValue } from "../json.js";
+import {
+  DialectRegistry,
+  KeywordBehavior,
+  StaticFacts,
+  SubschemaApplication,
+  identifiersLegacy,
+} from "../dialect.js";
+import { childCursor } from "../cursor.js";
+import { LowerStmt, lowerIR } from "../lowering.js";
+import {
+  $ref,
+  structural,
+  annotationOnly,
+  mapPositions,
+  SELF,
+} from "./core.js";
+import {
+  allOf,
+  anyOf,
+  oneOf,
+  not,
+  ifKeyword,
+  conditionalBranch,
+  properties,
+  patternProperties,
+  propertyNames,
+  additionalProperties,
+} from "./applicator.js";
+import { items2019, additionalItems } from "./vocab2019.js";
+import { validationVocabulary } from "./validation.js";
+
+/** draft-07 core vocabulary identity (registry-internal; not a spec-meaningful URI, D2/D18). */
+export const VOCAB_CORE_07 = "urn:jse:vocab:draft-07:core";
+/** draft-07 applicator vocabulary identity (registry-internal; not a spec-meaningful URI, D2/D18). */
+export const VOCAB_APPLICATOR_07 = "urn:jse:vocab:draft-07:applicator";
+/** draft-07 validation vocabulary identity (registry-internal; not a spec-meaningful URI, D2/D18). */
+export const VOCAB_VALIDATION_07 = "urn:jse:vocab:draft-07:validation";
+/** draft-07 meta-data vocabulary identity (registry-internal; not a spec-meaningful URI, D2/D18). */
+export const VOCAB_META_DATA_07 = "urn:jse:vocab:draft-07:meta-data";
+/** draft-07 format vocabulary identity (registry-internal; not a spec-meaningful URI, D2/D18). */
+export const VOCAB_FORMAT_07 = "urn:jse:vocab:draft-07:format";
+/** draft-07 content vocabulary identity (registry-internal; not a spec-meaningful URI, D2/D18). */
+export const VOCAB_CONTENT_07 = "urn:jse:vocab:draft-07:content";
+
+/** draft-06 core vocabulary identity (registry-internal; not a spec-meaningful URI, D2/D18). */
+export const VOCAB_CORE_06 = "urn:jse:vocab:draft-06:core";
+/** draft-06 applicator vocabulary identity (registry-internal; not a spec-meaningful URI, D2/D18). */
+export const VOCAB_APPLICATOR_06 = "urn:jse:vocab:draft-06:applicator";
+/** draft-06 validation vocabulary identity (registry-internal; not a spec-meaningful URI, D2/D18). */
+export const VOCAB_VALIDATION_06 = "urn:jse:vocab:draft-06:validation";
+/** draft-06 meta-data vocabulary identity (registry-internal; not a spec-meaningful URI, D2/D18). */
+export const VOCAB_META_DATA_06 = "urn:jse:vocab:draft-06:meta-data";
+/** draft-06 format vocabulary identity (registry-internal; not a spec-meaningful URI, D2/D18). */
+export const VOCAB_FORMAT_06 = "urn:jse:vocab:draft-06:format";
+
+/** draft-07 dialect URI. */
+export const DIALECT_DRAFT_07 = "http://json-schema.org/draft-07/schema";
+/** draft-06 dialect URI. */
+export const DIALECT_DRAFT_06 = "http://json-schema.org/draft-06/schema";
+
+const id07 = (name: string): string => `${VOCAB_APPLICATOR_07}#${name}`;
+
+/**
+ * `contains` (draft-07/06): unlike 2020-12's `contains`, these drafts have
+ * no `minContains`/`maxContains` keywords at all — any occurrence of those
+ * names is just an unknown (annotation-only) keyword, never a sibling
+ * `contains` reads. So the count assertion is unconditionally "at least 1",
+ * with no min/max reads.
+ */
+export const containsLegacy: KeywordBehavior = {
+  id: id07("contains"),
+  // Per-item probes don't individually assert (the count does) — same
+  // asserts:false shape as 2020-12 contains' childSweep application.
+  analyze: (): StaticFacts => ({
+    ...SELF,
+    applications: [
+      { path: [], mode: "childSweep", conditional: false, asserts: false },
+    ],
+  }),
+  // Unconditional "at least 1" — countRange with no upper bound, matching
+  // evaluate()'s fixed message exactly (no minContains/maxContains reads
+  // exist in these drafts, so unlike 2020-12 `contains` there is no tally
+  // or params in the failure text).
+  lower: (_value, lctx) => {
+    const b = lctx.binding();
+    lctx.emit(
+      lowerIR.when(lowerIR.typeIs(lctx.instance, "array"), [
+        {
+          kind: "countRange",
+          target: lctx.instance,
+          binding: b,
+          countWhen: {
+            kind: "applyExpr",
+            apply: {
+              path: [],
+              cursor: {
+                kind: "child",
+                of: { kind: "here" },
+                segment: { kind: "binding", id: b },
+              },
+              fold: "discard",
+            },
+          },
+          min: 1,
+          max: Infinity,
+          outOfRangeMessage: ["no item matches the contains subschema"],
+        },
+      ]),
+    );
+  },
+  evaluate: (_value, cursor, ctx) => {
+    if (!Array.isArray(cursor.value)) return true;
+    const matched: number[] = [];
+    for (let i = 0; i < cursor.value.length; i++) {
+      if (ctx.apply(["contains"], childCursor(cursor, i, cursor.value[i]!)))
+        matched.push(i);
+    }
+    if (matched.length === 0) {
+      ctx.error("no item matches the contains subschema");
+      return false;
+    }
+    return true;
+  },
+};
+
+// Member values are exactly one of two shapes per the metaschema's `anyOf`
+// (schema vs stringArray) — a member is never both, so reading the JS type
+// of the value at evaluate/analyze time is sufficient to dispatch, no
+// declared-shape tracking needed.
+const isSchemaValue = (v: JsonValue): boolean =>
+  v === true || v === false || (isObject(v) && !Array.isArray(v));
+
+/**
+ * `dependencies` (draft-07/06): a single keyword folding what 2019-09+ split
+ * into `dependentRequired` (array-valued members) and `dependentSchemas`
+ * (schema-valued members).
+ */
+export const dependencies: KeywordBehavior = {
+  id: id07("dependencies"),
+  analyze: (value): StaticFacts => {
+    if (!isObject(value)) return {};
+    const schemaMembers = Object.entries(value).filter(([, v]) =>
+      isSchemaValue(v),
+    );
+    return {
+      subschemas: schemaMembers.map(([k]) => [k]),
+      // Only schema-valued members get an edge — array-valued members
+      // (dependentRequired's shape) have no subschema to plan/apply at all.
+      applications: schemaMembers.map(([k]): SubschemaApplication => ({
+        path: [k],
+        mode: "inPlace",
+        conditional: true,
+        asserts: true,
+      })),
+    };
+  },
+  // Per-member dispatch is plan-time (the value shape is static, just like
+  // evaluate()'s Array.isArray/isSchemaValue reads): array-valued members
+  // lower like dependentRequired (validation.ts), schema-valued members
+  // like dependentSchemas (applicator.ts, path ["dependencies", name]).
+  lower: (value, lctx) => {
+    if (!isObject(value)) return;
+    const branches = Object.entries(value as Record<string, JsonValue>).flatMap(
+      ([name, dep]): LowerStmt[] => {
+        if (Array.isArray(dep)) {
+          return [
+            lowerIR.when(
+              { kind: "hasOwn", target: lctx.instance, key: name },
+              (dep as string[]).map((required) =>
+                lowerIR.when(
+                  lowerIR.not({
+                    kind: "hasOwn",
+                    target: lctx.instance,
+                    key: required,
+                  }),
+                  [
+                    lowerIR.failWith(
+                      {
+                        property: lowerIR.constant(name),
+                        missingProperty: lowerIR.constant(required),
+                      },
+                      `'${name}' requires '${required}' to be present`,
+                    ),
+                  ],
+                ),
+              ),
+            ),
+          ];
+        }
+        if (isSchemaValue(dep)) {
+          return [
+            lowerIR.when({ kind: "hasOwn", target: lctx.instance, key: name }, [
+              {
+                kind: "apply",
+                apply: {
+                  path: [name],
+                  cursor: { kind: "here" },
+                  fold: "allMustPass",
+                },
+              },
+            ]),
+          ];
+        }
+        // Unreachable per the metaschema's anyOf (schema vs stringArray),
+        // mirrored defensively as evaluate()'s implicit no-op else branch.
+        return [];
+      },
+    );
+    if (branches.length === 0) return;
+    lctx.emit(lowerIR.when(lowerIR.typeIs(lctx.instance, "object"), branches));
+  },
+  evaluate: (value, cursor, ctx) => {
+    if (!isObject(cursor.value)) return true;
+    const instance = cursor.value;
+    let ok = true;
+    for (const [name, dep] of Object.entries(
+      value as Record<string, JsonValue>,
+    )) {
+      if (!Object.hasOwn(instance, name)) continue;
+      if (Array.isArray(dep)) {
+        for (const required of dep as string[]) {
+          if (!Object.hasOwn(instance, required)) {
+            ctx.error(`'${name}' requires '${required}' to be present`, {
+              property: name,
+              missingProperty: required,
+            });
+            ok = false;
+          }
+        }
+      } else if (isSchemaValue(dep)) {
+        if (!ctx.apply(["dependencies", name], cursor)) ok = false;
+      }
+    }
+    return ok;
+  },
+};
+
+const core07Vocabulary: Record<string, KeywordBehavior> = {
+  $ref,
+  $id: structural(`${VOCAB_CORE_07}#$id`),
+  $schema: structural(`${VOCAB_CORE_07}#$schema`),
+  $comment: structural(`${VOCAB_CORE_07}#$comment`),
+  // definitions is draft-07/06's pre-$defs name for the same inert-container
+  // shape: subschemas exist for identification/registration but nothing
+  // evaluates them directly.
+  definitions: {
+    id: `${VOCAB_CORE_07}#definitions`,
+    structural: true,
+    analyze: mapPositions,
+    evaluate: () => true,
+    lower: () => {
+      /* contents are reachable only by reference */
+    },
+  },
+};
+
+const applicator07Vocabulary: Record<string, KeywordBehavior> = {
+  allOf,
+  anyOf,
+  oneOf,
+  not,
+  if: ifKeyword,
+  then: conditionalBranch(id07("then"), "then", true),
+  else: conditionalBranch(id07("else"), "else", false),
+  dependencies,
+  properties,
+  patternProperties,
+  propertyNames,
+  additionalProperties,
+  items: items2019,
+  additionalItems,
+  contains: containsLegacy,
+};
+
+const metaData07Vocabulary = Object.fromEntries(
+  ["title", "description", "default", "readOnly", "writeOnly", "examples"].map(
+    (name) => [name, annotationOnly(`${VOCAB_META_DATA_07}#${name}`)],
+  ),
+);
+
+const content07Vocabulary = Object.fromEntries(
+  ["contentMediaType", "contentEncoding"].map((name) => [
+    name,
+    annotationOnly(`${VOCAB_CONTENT_07}#${name}`),
+  ]),
+);
+
+// draft-06: draft-07 minus if/then/else, $comment, readOnly/writeOnly,
+// contentMediaType/contentEncoding (D11 amendment — a compatible subset).
+const { $comment: _dropComment, ...core06Rest } = core07Vocabulary;
+const core06Vocabulary: Record<string, KeywordBehavior> = {
+  ...core06Rest,
+  $id: structural(`${VOCAB_CORE_06}#$id`),
+  $schema: structural(`${VOCAB_CORE_06}#$schema`),
+  definitions: {
+    id: `${VOCAB_CORE_06}#definitions`,
+    structural: true,
+    analyze: mapPositions,
+    evaluate: () => true,
+    lower: () => {
+      /* contents are reachable only by reference */
+    },
+  },
+};
+
+const {
+  if: _dropIf,
+  then: _dropThen,
+  else: _dropElse,
+  ...applicator06Rest
+} = applicator07Vocabulary;
+const applicator06Vocabulary: Record<string, KeywordBehavior> = {
+  ...applicator06Rest,
+};
+
+const {
+  readOnly: _dropReadOnly,
+  writeOnly: _dropWriteOnly,
+  ...metaData06Rest
+} = metaData07Vocabulary;
+const metaData06Vocabulary = metaData06Rest;
+
+// draft-07/06 predate minContains/maxContains/dependentRequired: those names
+// are unknown keywords (annotation-only) in these dialects — registering the
+// 2020-12 behaviors would silently enforce assertions these drafts don't have.
+const {
+  minContains: _dropMinContains,
+  maxContains: _dropMaxContains,
+  dependentRequired: _dropDependentRequired,
+  ...validationLegacyVocabulary
+} = validationVocabulary;
+
+/** Registers the draft-07 vocabularies and dialect. */
+export function registerDialect07(
+  registry: DialectRegistry,
+  format: (id: string) => KeywordBehavior = annotationOnly,
+): void {
+  registry.registerVocabulary(VOCAB_CORE_07, core07Vocabulary);
+  registry.registerVocabulary(VOCAB_APPLICATOR_07, applicator07Vocabulary);
+  registry.registerVocabulary(VOCAB_VALIDATION_07, validationLegacyVocabulary);
+  registry.registerVocabulary(VOCAB_META_DATA_07, metaData07Vocabulary);
+  registry.registerVocabulary(VOCAB_FORMAT_07, {
+    format: format(`${VOCAB_FORMAT_07}#format`),
+  });
+  registry.registerVocabulary(VOCAB_CONTENT_07, content07Vocabulary);
+
+  registry.registerDialect(
+    DIALECT_DRAFT_07,
+    [
+      VOCAB_CORE_07,
+      VOCAB_APPLICATOR_07,
+      VOCAB_VALIDATION_07,
+      VOCAB_META_DATA_07,
+      VOCAB_FORMAT_07,
+      VOCAB_CONTENT_07,
+    ],
+    { identifiers: identifiersLegacy, refIgnoresSiblings: true },
+  );
+}
+
+/** Registers the draft-06 vocabularies and dialect. */
+export function registerDialect06(
+  registry: DialectRegistry,
+  format: (id: string) => KeywordBehavior = annotationOnly,
+): void {
+  registry.registerVocabulary(VOCAB_CORE_06, core06Vocabulary);
+  registry.registerVocabulary(VOCAB_APPLICATOR_06, applicator06Vocabulary);
+  registry.registerVocabulary(VOCAB_VALIDATION_06, validationLegacyVocabulary);
+  registry.registerVocabulary(VOCAB_META_DATA_06, metaData06Vocabulary);
+  registry.registerVocabulary(VOCAB_FORMAT_06, {
+    format: format(`${VOCAB_FORMAT_06}#format`),
+  });
+
+  registry.registerDialect(
+    DIALECT_DRAFT_06,
+    [
+      VOCAB_CORE_06,
+      VOCAB_APPLICATOR_06,
+      VOCAB_VALIDATION_06,
+      VOCAB_META_DATA_06,
+      VOCAB_FORMAT_06,
+    ],
+    { identifiers: identifiersLegacy, refIgnoresSiblings: true },
+  );
+}

package/src/loader.ts

@@ -0,0 +1,60 @@
+// Resource loading types (DESIGN.md D7/D17). Loading is the only async
+// boundary: loaders feed Engine.load/loadSchema, which register documents
+// and their transitive references; compile and evaluate stay sync.
+//
+// D17 bridge: canonical schema locations are resource-rooted
+// (`resourceUri#/pointer`), but loaders report source positions
+// document-rooted, since a document can embed multiple resources via nested
+// `$id`. The registry's documentLocation(resourceUri) gives the containing
+// document plus the resource root's document-rooted pointer; a canonical
+// location's document-rooted pointer is then
+// `documentLocation(resourceUri).pointer + pointer`.
+
+import { JsonValue } from "./json.js";
+
+/** 1-based line/column; offset is 0-based when present. */
+export interface SourcePosition {
+  line: number;
+  column: number;
+  offset?: number;
+}
+
+/** A range between two source positions. */
+export interface SourceSpan {
+  start: SourcePosition;
+  end: SourcePosition;
+}
+
+/**
+ * Key vs value spans (D17): diagnostics point at the key for missing/extra-
+ * property errors and at the value for type errors; SARIF/LSP-class
+ * consumers need both.
+ */
+export interface SourceRange {
+  /** span of the member key, when the value is an object member */
+  key?: SourceSpan;
+  value: SourceSpan;
+}
+
+/** A document handed to the registry by a {@link SchemaLoader}. */
+export interface LoadedDocument {
+  value: JsonValue;
+  /**
+   * Source range for a document-rooted JSON Pointer (D17). A function rather
+   * than a materialized map so loaders can keep a parse AST and resolve
+   * lazily; returning undefined for any pointer is always allowed.
+   */
+  getRange?: (documentRootPointer: string) => SourceRange | undefined;
+}
+
+/** Fetches a schema document by URI. Returns undefined when this loader does not handle the URI. */
+export type SchemaLoader = (
+  uri: string,
+) => LoadedDocument | undefined | Promise<LoadedDocument | undefined>;
+
+/** Where a canonical schema location physically lives (D17 bridge). */
+export interface SourceLocation {
+  documentUri: string;
+  pointer: string;
+  range?: SourceRange;
+}