@maroonedog/luq 2.5.0 → 2.7.0

package/README.md

@@ -42,6 +42,7 @@ compile error, not a rule that quietly never fires.
 | Descending into a built-in (`"when.getTime"` on a `Date`) | compile error |
 | A method that does not exist inside an element sub-chain | compile error |
 | A JSON Schema keyword bound to a chain method that does not exist | compile error |
+| A JSON Schema document declaring 2019-09 or 2020-12 | throws when the validator is built, rather than being read as Draft-07 |
 | A documented example drifting from the API | fails CI |
 
 That matters most when the code calling this library is generated rather than
@@ -136,13 +137,31 @@ const result = orderValidator.validate({ reference: "ab", quantity: 0 });
 if (!result.valid) {
   for (const issue of result.issues) {
     // issue.path  "reference"   — where, with array indices filled in
-    // issue.code  "stringMin"   — which rule, stable across messages
+    // issue.code  "stringMin"   — which rule; the vocabulary is pinned
     // issue.message             — the text, overridable per call
     // issue.severity "error"    — only "error" makes the value invalid
+    // issue.causes              — present only on a composite: why it failed
   }
 }
 ```
 
+`issue.code` is the machine-readable half: a plugin's own name by default,
+overridden per rule with `{ code }`. The set is not a convention. The codes the
+library reports are enumerated in `config/issue-code.lock.json`, derived from
+the source by `npm run generate:issue-codes` and checked by
+`npm run check:issue-code-lock`, so renaming one is a diff in a committed file
+and a deliberate act rather than a silent break. The lock records who reports
+each code, because some codes are shared on purpose — a missing root and a
+missing field both report `required`. Codes a gate carries (`skip`,
+`validateIf`) sit in a separate list: they are accepted from a caller but no
+issue can ever carry one.
+
+A composite reports which applicator failed — `allOf`, `anyOf`, `oneOf` — and
+that code cannot say why. `issue.causes` carries the branch failures behind it,
+each a full issue with its own code, so `allOf` can be read down to the
+`stringMin` underneath it. The key is **absent** on an ordinary issue rather
+than present and undefined, so `"causes" in issue` is a question worth asking.
+
 `.v(path, chain)` declares rules for one field. A path you do not declare is
 not validated, not required and not read, so covering a type partly is a normal
 state rather than a half-finished one.
@@ -203,7 +222,11 @@ accounts.pickAll(["email"]); //             several fields, same plan
 
 `validate` and `parse` return the same discriminated union: `{ valid: true,
 data, issues }` or `{ valid: false, issues }`. `validate` hands back the object
-you passed, by identity, when nothing was written.
+you passed, by identity, when nothing was written. Only `parse` runs your
+transform functions, so only `parse` can throw what one of them throws: a throw
+from a transform is a programmer error, not a validation issue, and zod, valibot
+and yup all propagate it the same way. To reject a value instead, use a check
+such as [`custom`](https://luq.dev/docs/api/validator#transform-throws).
 
 ### Slots
 
@@ -295,7 +318,7 @@ const forStringMin = PLUGIN_MANIFEST.filter((entry) =>
 | [Getting started](https://luq.dev/docs/getting-started) | the builder, defaults, `normalize`, reading a result |
 | [Core concepts](https://luq.dev/docs/core-concepts) | field paths, slots, presence, transforms |
 | [Plugins](https://luq.dev/plugins) | every subpath, symbol, chain method and slot |
-| [JSON Schema](https://luq.dev/json-schema) | reading a document in, writing one back out, measured Draft-07 conformance |
+| [JSON Schema](https://luq.dev/json-schema) | reading a Draft-07 document in, writing one back out, measured conformance, and why a newer-dialect document is refused |
 | [Standard Schema](https://luq.dev/standard-schema) | tRPC, TanStack Form, Hono, react-hook-form — and what does not cross that boundary |
 | [Benchmarks](https://luq.dev/benchmarks) | bundle size and throughput, with the method |
 | [Luq or zod?](https://luq.dev/luq-or-zod) | when schema-first is the better answer |
@@ -311,6 +334,8 @@ Breaking changes happen in a major and nowhere else, an API being removed is
 deprecated one major ahead, and each major ships with the codemod needed to
 cross it.
 
+- **[CHANGELOG.md](https://github.com/maroonedog/luq/blob/master/CHANGELOG.md)** — every released version, what a caller
+  sees change in each, and which ones need reading before you take them
 - **[CONTRIBUTING.md](https://github.com/maroonedog/luq/blob/master/CONTRIBUTING.md)** — `npm run verify` is the whole
   contract; the gates and what each one refuses
 - **[SECURITY.md](https://github.com/maroonedog/luq/blob/master/SECURITY.md)** — reporting, zero runtime dependencies, the
@@ -320,11 +345,13 @@ cross it.
 
 ## About the "universal platform" goal
 
-1.x described a `.luq` DSL that would generate validators for other languages,
-against dated milestones. Those dates have passed and none of it shipped, so the
-plan has been withdrawn rather than moved: no part of it is in this package, and
-this release makes no claim about when any of it will exist. What is in the box
-is the TypeScript validation library described above.
+The first published line — `0.1.0-alpha` through `0.1.2-alpha`, which the
+migration guide and the docs site both call "1.x" although no `1.x` was ever
+published — described a `.luq` DSL that would generate validators for other
+languages, against dated milestones. Those dates have passed and none of it
+shipped, so the plan has been withdrawn rather than moved: no part of it is in
+this package, and this release makes no claim about when any of it will exist.
+What is in the box is the TypeScript validation library described above.
 
 ## License
 

package/dist/chain/slot-type-guard.js

@@ -3,16 +3,30 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.slotTypeGuard = slotTypeGuard;
 const types_1 = require("../types");
 const create_rule_1 = require("../plugin-kit/create-rule");
+/**
+ * Each code is SPELLED here rather than interpolated from the slot name.
+ *
+ * `${slot}Type` produced the same six strings, and produced them nowhere a
+ * reader could find them: config/issue-code.lock.json enumerates every code
+ * the library can report, and a code that only exists once a template has been
+ * evaluated cannot be enumerated, so these six were missing from the published
+ * vocabulary while being among the most commonly reported codes there are.
+ */
 const SLOT_TYPES = Object.freeze({
-    string: { accepts: types_1.isString, noun: "a string" },
-    number: { accepts: types_1.isNumber, noun: "a number" },
+    string: { accepts: types_1.isString, code: "stringType", noun: "a string" },
+    number: { accepts: types_1.isNumber, code: "numberType", noun: "a number" },
     boolean: {
         accepts: (value) => typeof value === "boolean",
+        code: "booleanType",
         noun: "a boolean",
     },
-    date: { accepts: (value) => value instanceof Date, noun: "a Date" },
-    array: { accepts: types_1.isArray, noun: "an array" },
-    object: { accepts: types_1.isPlainObject, noun: "an object" },
+    date: {
+        accepts: (value) => value instanceof Date,
+        code: "dateType",
+        noun: "a Date",
+    },
+    array: { accepts: types_1.isArray, code: "arrayType", noun: "an array" },
+    object: { accepts: types_1.isPlainObject, code: "objectType", noun: "an object" },
 });
 /**
  * The rule `b.<slot>` starts its chain with, or null for a slot that claims
@@ -26,7 +40,7 @@ function slotTypeGuard(slot, severity) {
     if (slotType === undefined)
         return null;
     return (0, create_rule_1.check)({
-        code: `${slot}Type`,
+        code: slotType.code,
         severity,
         run: (value) => value === undefined || value === null || slotType.accepts(value)
             ? types_1.PASS

package/dist/chain/slot-type-guard.mjs

@@ -1,15 +1,29 @@
 import { PASS, fail, isArray, isNumber, isPlainObject, isString, } from "../types/index.mjs";
 import { check } from "../plugin-kit/create-rule.mjs";
+/**
+ * Each code is SPELLED here rather than interpolated from the slot name.
+ *
+ * `${slot}Type` produced the same six strings, and produced them nowhere a
+ * reader could find them: config/issue-code.lock.json enumerates every code
+ * the library can report, and a code that only exists once a template has been
+ * evaluated cannot be enumerated, so these six were missing from the published
+ * vocabulary while being among the most commonly reported codes there are.
+ */
 const SLOT_TYPES = Object.freeze({
-    string: { accepts: isString, noun: "a string" },
-    number: { accepts: isNumber, noun: "a number" },
+    string: { accepts: isString, code: "stringType", noun: "a string" },
+    number: { accepts: isNumber, code: "numberType", noun: "a number" },
     boolean: {
         accepts: (value) => typeof value === "boolean",
+        code: "booleanType",
         noun: "a boolean",
     },
-    date: { accepts: (value) => value instanceof Date, noun: "a Date" },
-    array: { accepts: isArray, noun: "an array" },
-    object: { accepts: isPlainObject, noun: "an object" },
+    date: {
+        accepts: (value) => value instanceof Date,
+        code: "dateType",
+        noun: "a Date",
+    },
+    array: { accepts: isArray, code: "arrayType", noun: "an array" },
+    object: { accepts: isPlainObject, code: "objectType", noun: "an object" },
 });
 /**
  * The rule `b.<slot>` starts its chain with, or null for a slot that claims
@@ -23,7 +37,7 @@ export function slotTypeGuard(slot, severity) {
     if (slotType === undefined)
         return null;
     return check({
-        code: `${slot}Type`,
+        code: slotType.code,
         severity,
         run: (value) => value === undefined || value === null || slotType.accepts(value)
             ? PASS

package/dist/compile/resolve-presence.js

@@ -38,13 +38,43 @@ function countRestrictions(rule) {
         (rule.allowNull ? 0 : 1) +
         (rule.emptyStringIsMissing ? 1 : 0));
 }
+/**
+ * Which of two equally restrictive rules is reported, decided on WHAT each one
+ * forbids: undefined first, then null, then the empty string.
+ *
+ * The order is declared here rather than falling out of something else. It
+ * runs from the broadest absence to the narrowest — a field that is not there
+ * at all, a field that is there holding null, a field holding "" — so the
+ * identity a caller sees names the largest thing that was missing.
+ *
+ * Nothing in this comparison reads a code. A code is a published name, pinned
+ * in config/issue-code.lock.json, and re-spelling one must not move which rule
+ * a failure is reported under; comparing the two codes made exactly that
+ * happen, silently, from a one-word rename.
+ *
+ * Two rules forbidding the identical three things are indistinguishable to
+ * every reader of the policy, so neither outranks the other and the one
+ * declared first stays. That is the only case where the order the methods were
+ * typed in is observable at all.
+ */
+function outranksOnRestriction(rule, incumbent) {
+    if (rule.allowUndefined !== incumbent.allowUndefined) {
+        return !rule.allowUndefined;
+    }
+    if (rule.allowNull !== incumbent.allowNull)
+        return !rule.allowNull;
+    if (rule.emptyStringIsMissing !== incumbent.emptyStringIsMissing) {
+        return rule.emptyStringIsMissing;
+    }
+    return false;
+}
 /**
  * The identity a failure is reported under: the rule that forbids the most,
- * ties broken by the lexicographically smaller code.
+ * ties broken by which absence it forbids.
  *
- * Tie-breaking on the CODE rather than on declaration order is what keeps the
- * whole policy — not merely its three flags — independent of the order the
- * rules arrived in. `.optional().nullable()` and `.nullable().optional()` are
+ * Both halves of the decision read only the three presence flags, so the whole
+ * policy — not merely its flags — is independent of the order the rules
+ * arrived in. `.optional().nullable()` and `.nullable().optional()` are
  * deep-equal, which is the property the tests assert.
  */
 function selectStrictestPresence(rules) {
@@ -55,7 +85,8 @@ function selectStrictestPresence(rules) {
             continue;
         }
         const difference = countRestrictions(rule) - countRestrictions(strictest);
-        if (difference > 0 || (difference === 0 && rule.code < strictest.code)) {
+        if (difference > 0 ||
+            (difference === 0 && outranksOnRestriction(rule, strictest))) {
             strictest = rule;
         }
     }

package/dist/compile/resolve-presence.mjs

@@ -34,13 +34,43 @@ function countRestrictions(rule) {
         (rule.allowNull ? 0 : 1) +
         (rule.emptyStringIsMissing ? 1 : 0));
 }
+/**
+ * Which of two equally restrictive rules is reported, decided on WHAT each one
+ * forbids: undefined first, then null, then the empty string.
+ *
+ * The order is declared here rather than falling out of something else. It
+ * runs from the broadest absence to the narrowest — a field that is not there
+ * at all, a field that is there holding null, a field holding "" — so the
+ * identity a caller sees names the largest thing that was missing.
+ *
+ * Nothing in this comparison reads a code. A code is a published name, pinned
+ * in config/issue-code.lock.json, and re-spelling one must not move which rule
+ * a failure is reported under; comparing the two codes made exactly that
+ * happen, silently, from a one-word rename.
+ *
+ * Two rules forbidding the identical three things are indistinguishable to
+ * every reader of the policy, so neither outranks the other and the one
+ * declared first stays. That is the only case where the order the methods were
+ * typed in is observable at all.
+ */
+function outranksOnRestriction(rule, incumbent) {
+    if (rule.allowUndefined !== incumbent.allowUndefined) {
+        return !rule.allowUndefined;
+    }
+    if (rule.allowNull !== incumbent.allowNull)
+        return !rule.allowNull;
+    if (rule.emptyStringIsMissing !== incumbent.emptyStringIsMissing) {
+        return rule.emptyStringIsMissing;
+    }
+    return false;
+}
 /**
  * The identity a failure is reported under: the rule that forbids the most,
- * ties broken by the lexicographically smaller code.
+ * ties broken by which absence it forbids.
  *
- * Tie-breaking on the CODE rather than on declaration order is what keeps the
- * whole policy — not merely its three flags — independent of the order the
- * rules arrived in. `.optional().nullable()` and `.nullable().optional()` are
+ * Both halves of the decision read only the three presence flags, so the whole
+ * policy — not merely its flags — is independent of the order the rules
+ * arrived in. `.optional().nullable()` and `.nullable().optional()` are
  * deep-equal, which is the property the tests assert.
  */
 function selectStrictestPresence(rules) {
@@ -51,7 +81,8 @@ function selectStrictestPresence(rules) {
             continue;
         }
         const difference = countRestrictions(rule) - countRestrictions(strictest);
-        if (difference > 0 || (difference === 0 && rule.code < strictest.code)) {
+        if (difference > 0 ||
+            (difference === 0 && outranksOnRestriction(rule, strictest))) {
             strictest = rule;
         }
     }

package/dist/json-schema/assert-supported-dialect.d.ts

@@ -0,0 +1,37 @@
+/**
+ * What the caller may say about the dialect. `JsonSchemaOptions` extends this,
+ * so the chain method and the conversion function offer the same word.
+ */
+export interface DialectOptions {
+    /**
+     * Read the document under Draft-07 rules whatever its `$schema` declares.
+     *
+     * The reading it buys is Draft-07's, exactly: `$ref` replaces the node it
+     * sits in, `format` asserts, and an array under `items` is the tuple form.
+     * A 2019-09 or 2020-12 document that relies on any of those meaning what the
+     * NEWER draft says will be enforced as less, or as something else, than it
+     * states.
+     */
+    readonly assumeDraft07?: boolean | undefined;
+}
+/**
+ * The released dialects Luq recognises the NAME of and does not implement,
+ * each with what it does that Draft-07 does not. They are written out so that
+ * "this is a dialect we know and did not build" and "we have never heard of
+ * this URI" stay different answers — the same distinction NON_DRAFT07_KEYWORDS
+ * draws between an out-of-dialect keyword and an invented one.
+ */
+export declare const NON_DRAFT07_DIALECTS: Readonly<Record<string, string>>;
+/**
+ * Reads the root `$schema` and refuses a dialect Luq does not implement.
+ *
+ * Called at both front doors, immediately after "is this a schema at all" and
+ * before any keyword is read, so no validator that enforces less than its
+ * document states can be reached by either route.
+ *
+ * A non-string `$schema` is a malformed VALUE rather than an unimplemented
+ * dialect — the meta-schema types it as a string — so it goes to the class that
+ * answers that question, and it is refused under the opt-out too: the opt-out
+ * says "read this dialect as Draft-07", and a number names no dialect.
+ */
+export declare function assertSupportedDialect(document: unknown, options: DialectOptions): void;

package/dist/json-schema/assert-supported-dialect.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NON_DRAFT07_DIALECTS = void 0;
+exports.assertSupportedDialect = assertSupportedDialect;
+// ===========================================================================
+// L8  src/json-schema/assert-supported-dialect.ts — the DIALECT gate, read
+// once at the document root before any keyword is.
+//
+// WHY A DEFAULT REFUSAL AND NOT A DIVERGENCE DETECTOR. Refusing only documents
+// that actually USE something 2019-09 changed sounds more precise and is the
+// worse trade. The divergences are not all spellable as keyword names: `$ref`
+// gains siblings, `format` and the two `content*` keywords stop asserting by
+// default, and 2020-12 moves the tuple form of `items` to `prefixItems`. A
+// detector would therefore have to carry a second semantic model of two
+// dialects this library does not implement, and every case it fails to think
+// of is a SILENT wrong answer — which is the exact failure this file exists to
+// stop. The `$ref`-sibling case was itself invisible until it was hunted for.
+// `$schema` is the document's own statement of what it means, so that is what
+// is read.
+//
+// WHAT THE DEFAULT COSTS, and why the opt-out exists. A newer `$schema` over a
+// body that happens to be Draft-07-compatible builds correctly today, and
+// people copy the newest `$schema` line into documents that use nothing new.
+// Refusing outright would break those. `assumeDraft07` gives them a one-word
+// fix that is written at the CALL SITE, in the caller's own source, where a
+// reviewer reads it — so the reading is a stated decision rather than a silent
+// default. There is no way to get the wrong answer without having written the
+// word down.
+//
+// A document with NO `$schema` is untouched. That is most real documents and
+// all 929 cases of the conformance corpus, and it is not a guess about the
+// dialect: nothing was declared, so nothing contradicts Draft-07.
+//
+// THE ROOT ONLY. `externalDocuments` is a map the caller loads, and the suite's
+// own map holds 37 documents across four dialects of which a given case follows
+// two or three; refusing at registration would refuse documents nothing reads.
+// A `$schema` deeper in a document is likewise not the document's dialect.
+// ===========================================================================
+const types_1 = require("../types");
+const malformed_schema_error_1 = require("./malformed-schema-error");
+const unsupported_dialect_error_1 = require("./unsupported-dialect-error");
+/**
+ * Comparable form of a meta-schema URI: case folded, scheme dropped, and a
+ * trailing "#" or "/" removed.
+ *
+ * The scheme is dropped because the two families disagree about it — Draft-07
+ * publishes `http://json-schema.org/draft-07/schema#` and 2020-12 publishes
+ * `https://json-schema.org/draft/2020-12/schema` — and a document that writes
+ * `https` for the first or `http` for the second is naming the same dialect,
+ * not a different one. Matching the published string exactly would make the
+ * gate depend on which of two equally common spellings a document picked.
+ */
+function normaliseDialectUri(uri) {
+    return uri
+        .trim()
+        .toLowerCase()
+        .replace(/^https?:\/\//, "")
+        .replace(/[#/]+$/, "");
+}
+const DRAFT07_NORMALISED = normaliseDialectUri("http://json-schema.org/draft-07/schema#");
+/**
+ * The released dialects Luq recognises the NAME of and does not implement,
+ * each with what it does that Draft-07 does not. They are written out so that
+ * "this is a dialect we know and did not build" and "we have never heard of
+ * this URI" stay different answers — the same distinction NON_DRAFT07_KEYWORDS
+ * draws between an out-of-dialect keyword and an invented one.
+ */
+exports.NON_DRAFT07_DIALECTS = Object.freeze({
+    "json-schema.org/schema": "the unversioned alias, which names whichever draft the site publishes " +
+        "as current rather than a fixed one",
+    "json-schema.org/draft-03/schema": "Draft-03, which spells `required` as a boolean on each property",
+    "json-schema.org/draft-04/schema": "Draft-04, whose `exclusiveMaximum` is a boolean modifier, not a bound",
+    "json-schema.org/draft-06/schema": "Draft-06, which has no `$comment` and reads `$ref` the Draft-07 way",
+    "json-schema.org/draft/2019-09/schema": "2019-09, where `$ref` is an ordinary applicator and its siblings are " +
+        "applied, and `format` asserts nothing unless the vocabulary asks",
+    "json-schema.org/draft/2020-12/schema": "2020-12, where `$ref` siblings are applied, the tuple form of `items` " +
+        "is spelled `prefixItems`, and `format` asserts nothing by default",
+});
+const UNRECOGNISED_DIALECT = "a meta-schema Luq has no reading for, so what its keywords mean is unknown";
+const DIALECT_VALUE_REASON = "the value must be a URI string";
+/**
+ * Reads the root `$schema` and refuses a dialect Luq does not implement.
+ *
+ * Called at both front doors, immediately after "is this a schema at all" and
+ * before any keyword is read, so no validator that enforces less than its
+ * document states can be reached by either route.
+ *
+ * A non-string `$schema` is a malformed VALUE rather than an unimplemented
+ * dialect — the meta-schema types it as a string — so it goes to the class that
+ * answers that question, and it is refused under the opt-out too: the opt-out
+ * says "read this dialect as Draft-07", and a number names no dialect.
+ */
+function assertSupportedDialect(document, options) {
+    // Read off an untyped object rather than through `Draft07SchemaObject`,
+    // which types `$schema` as a string: the document is whatever JSON.parse
+    // produced, and a `$schema` that is not a string is exactly what this has to
+    // be able to see. The §4.4 boolean form and every non-object fall out here,
+    // declaring no dialect.
+    if (!(0, types_1.isPlainObject)(document))
+        return;
+    const declared = document["$schema"];
+    if (declared === undefined)
+        return;
+    if (typeof declared !== "string") {
+        throw new malformed_schema_error_1.MalformedSchemaError("$schema", DIALECT_VALUE_REASON, declared);
+    }
+    const normalised = normaliseDialectUri(declared);
+    if (normalised === DRAFT07_NORMALISED)
+        return;
+    if (options.assumeDraft07 === true)
+        return;
+    throw new unsupported_dialect_error_1.UnsupportedDialectError(declared, exports.NON_DRAFT07_DIALECTS[normalised] ?? UNRECOGNISED_DIALECT);
+}

package/dist/json-schema/assert-supported-dialect.mjs

@@ -0,0 +1,109 @@
+// ===========================================================================
+// L8  src/json-schema/assert-supported-dialect.ts — the DIALECT gate, read
+// once at the document root before any keyword is.
+//
+// WHY A DEFAULT REFUSAL AND NOT A DIVERGENCE DETECTOR. Refusing only documents
+// that actually USE something 2019-09 changed sounds more precise and is the
+// worse trade. The divergences are not all spellable as keyword names: `$ref`
+// gains siblings, `format` and the two `content*` keywords stop asserting by
+// default, and 2020-12 moves the tuple form of `items` to `prefixItems`. A
+// detector would therefore have to carry a second semantic model of two
+// dialects this library does not implement, and every case it fails to think
+// of is a SILENT wrong answer — which is the exact failure this file exists to
+// stop. The `$ref`-sibling case was itself invisible until it was hunted for.
+// `$schema` is the document's own statement of what it means, so that is what
+// is read.
+//
+// WHAT THE DEFAULT COSTS, and why the opt-out exists. A newer `$schema` over a
+// body that happens to be Draft-07-compatible builds correctly today, and
+// people copy the newest `$schema` line into documents that use nothing new.
+// Refusing outright would break those. `assumeDraft07` gives them a one-word
+// fix that is written at the CALL SITE, in the caller's own source, where a
+// reviewer reads it — so the reading is a stated decision rather than a silent
+// default. There is no way to get the wrong answer without having written the
+// word down.
+//
+// A document with NO `$schema` is untouched. That is most real documents and
+// all 929 cases of the conformance corpus, and it is not a guess about the
+// dialect: nothing was declared, so nothing contradicts Draft-07.
+//
+// THE ROOT ONLY. `externalDocuments` is a map the caller loads, and the suite's
+// own map holds 37 documents across four dialects of which a given case follows
+// two or three; refusing at registration would refuse documents nothing reads.
+// A `$schema` deeper in a document is likewise not the document's dialect.
+// ===========================================================================
+import { isPlainObject } from "../types/index.mjs";
+import { MalformedSchemaError } from "./malformed-schema-error.mjs";
+import { UnsupportedDialectError } from "./unsupported-dialect-error.mjs";
+/**
+ * Comparable form of a meta-schema URI: case folded, scheme dropped, and a
+ * trailing "#" or "/" removed.
+ *
+ * The scheme is dropped because the two families disagree about it — Draft-07
+ * publishes `http://json-schema.org/draft-07/schema#` and 2020-12 publishes
+ * `https://json-schema.org/draft/2020-12/schema` — and a document that writes
+ * `https` for the first or `http` for the second is naming the same dialect,
+ * not a different one. Matching the published string exactly would make the
+ * gate depend on which of two equally common spellings a document picked.
+ */
+function normaliseDialectUri(uri) {
+    return uri
+        .trim()
+        .toLowerCase()
+        .replace(/^https?:\/\//, "")
+        .replace(/[#/]+$/, "");
+}
+const DRAFT07_NORMALISED = normaliseDialectUri("http://json-schema.org/draft-07/schema#");
+/**
+ * The released dialects Luq recognises the NAME of and does not implement,
+ * each with what it does that Draft-07 does not. They are written out so that
+ * "this is a dialect we know and did not build" and "we have never heard of
+ * this URI" stay different answers — the same distinction NON_DRAFT07_KEYWORDS
+ * draws between an out-of-dialect keyword and an invented one.
+ */
+export const NON_DRAFT07_DIALECTS = Object.freeze({
+    "json-schema.org/schema": "the unversioned alias, which names whichever draft the site publishes " +
+        "as current rather than a fixed one",
+    "json-schema.org/draft-03/schema": "Draft-03, which spells `required` as a boolean on each property",
+    "json-schema.org/draft-04/schema": "Draft-04, whose `exclusiveMaximum` is a boolean modifier, not a bound",
+    "json-schema.org/draft-06/schema": "Draft-06, which has no `$comment` and reads `$ref` the Draft-07 way",
+    "json-schema.org/draft/2019-09/schema": "2019-09, where `$ref` is an ordinary applicator and its siblings are " +
+        "applied, and `format` asserts nothing unless the vocabulary asks",
+    "json-schema.org/draft/2020-12/schema": "2020-12, where `$ref` siblings are applied, the tuple form of `items` " +
+        "is spelled `prefixItems`, and `format` asserts nothing by default",
+});
+const UNRECOGNISED_DIALECT = "a meta-schema Luq has no reading for, so what its keywords mean is unknown";
+const DIALECT_VALUE_REASON = "the value must be a URI string";
+/**
+ * Reads the root `$schema` and refuses a dialect Luq does not implement.
+ *
+ * Called at both front doors, immediately after "is this a schema at all" and
+ * before any keyword is read, so no validator that enforces less than its
+ * document states can be reached by either route.
+ *
+ * A non-string `$schema` is a malformed VALUE rather than an unimplemented
+ * dialect — the meta-schema types it as a string — so it goes to the class that
+ * answers that question, and it is refused under the opt-out too: the opt-out
+ * says "read this dialect as Draft-07", and a number names no dialect.
+ */
+export function assertSupportedDialect(document, options) {
+    // Read off an untyped object rather than through `Draft07SchemaObject`,
+    // which types `$schema` as a string: the document is whatever JSON.parse
+    // produced, and a `$schema` that is not a string is exactly what this has to
+    // be able to see. The §4.4 boolean form and every non-object fall out here,
+    // declaring no dialect.
+    if (!isPlainObject(document))
+        return;
+    const declared = document["$schema"];
+    if (declared === undefined)
+        return;
+    if (typeof declared !== "string") {
+        throw new MalformedSchemaError("$schema", DIALECT_VALUE_REASON, declared);
+    }
+    const normalised = normaliseDialectUri(declared);
+    if (normalised === DRAFT07_NORMALISED)
+        return;
+    if (options.assumeDraft07 === true)
+        return;
+    throw new UnsupportedDialectError(declared, NON_DRAFT07_DIALECTS[normalised] ?? UNRECOGNISED_DIALECT);
+}

package/dist/json-schema/build-from-schema.d.ts

@@ -2,6 +2,7 @@ import type { FieldBuilderSurface } from "../builder/builder-surface.types";
 import type { FieldEntry } from "../builder/field-entry.types";
 import type { Validator } from "../builder/validator.types";
 import type { GlobalConfig } from "../types/global-config";
+import type { DialectOptions } from "./assert-supported-dialect";
 import type { JsonSchemaBag } from "./json-schema-bag.types";
 /** A value that is not a schema at all. Named, and refused at the boundary. */
 export declare class NotASchemaError extends Error {
@@ -9,10 +10,28 @@ export declare class NotASchemaError extends Error {
     constructor(received: unknown);
 }
 /** One pending `.v()` per declared path, with its callback still unrun. */
-export declare function buildFieldEntries(bag: JsonSchemaBag, schema: unknown): readonly FieldEntry[];
+export declare function buildFieldEntries(bag: JsonSchemaBag, schema: unknown, options?: DialectOptions): readonly FieldEntry[];
 /** The erased front door: the declarations, with nothing compiled yet. */
-export declare function buildFromSchema(bag: JsonSchemaBag, schema: unknown, config?: GlobalConfig): FieldBuilderSurface;
+export declare function buildFromSchema(bag: JsonSchemaBag, schema: unknown, config?: GlobalConfig, options?: DialectOptions): FieldBuilderSurface;
 /**
+ * Converts a JSON Schema document into a validator.
+ *
+ * THE INPUT LIMIT IS DRAFT-07, and it is a limit on what may be handed in, not
+ * only a statement of how much of Draft-07 is covered. A document declaring
+ * 2019-09 or 2020-12 in its root `$schema` is REFUSED with an
+ * `UnsupportedDialectError` rather than read as Draft-07, because the two
+ * dialects disagree about what an unchanged keyword means: from 2019-09 on
+ * `$ref` is an ordinary applicator whose siblings are applied, while Draft-07
+ * §8.3 replaces the node, so `{"$ref": "#/$defs/name", "minLength": 5}` read as
+ * Draft-07 loses the `minLength` and accepts a value the document forbids. A
+ * document with NO `$schema` is read as Draft-07 and always has been. Pass
+ * `{ assumeDraft07: true }` as the fourth argument to read a newer-dialect
+ * document under Draft-07 rules deliberately, with that reading's consequences.
+ *
+ * `T` defaults to `Record<string, unknown>`, never `any`; under the default NO
+ * declared path is checked. See the header of this file, which owns that
+ * escape hatch.
+ *
  * The declared type is put back on by `eraseSchemaValidator`, the fourth
  * function in src/core/type-erasure.ts — the one file the code standard allows
  * to assert. Step 25 expressed this as an OVERLOAD PAIR instead, because
@@ -20,4 +39,4 @@ export declare function buildFromSchema(bag: JsonSchemaBag, schema: unknown, con
  * TypeScript on lenient compatibility rules and so was never audited anywhere.
  * The call below is, in the file where every escape hatch is reviewed together.
  */
-export declare function fromJsonSchema<T extends object = Record<string, unknown>>(bag: JsonSchemaBag, schema: unknown, config?: GlobalConfig): Validator<T>;
+export declare function fromJsonSchema<T extends object = Record<string, unknown>>(bag: JsonSchemaBag, schema: unknown, config?: GlobalConfig, options?: DialectOptions): Validator<T>;