@maroonedog/luq 2.4.4 → 2.6.0

package/dist/json-schema/assert-object-keyword-values.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `required` is an array of property names (§6.5.3), and whatever the document
+ * put there is refused when it is anything else.
+ *
+ * UNIQUENESS IS NOT ENFORCED, although the meta-schema's `stringArray` asks
+ * for it. A repeated name asks for nothing the single name does not — the
+ * property is required either way, so the verdict is identical — and this
+ * check exists to stop a validator enforcing LESS than its document, not to
+ * lint a document that is enforced exactly as written. Refusing a duplicate
+ * would reject working schemas for no gain in correctness.
+ */
+export declare function assertRequiredIsNameList(value: unknown): void;
+/**
+ * `properties` maps property names to schemas (§6.5.4), and a schema is an
+ * object or a boolean; the map itself and every member of it are refused when
+ * they are not. The key is named in the reason so the message points at the
+ * offending node rather than at the whole document.
+ */
+export declare function assertPropertiesIsSchemaMap(value: unknown): void;
+/**
+ * `additionalProperties` is a schema, and §4.4 makes a boolean one (§6.5.6).
+ * Both of those forms pass through unchanged; only a value the meta-schema
+ * already forbids — a string, a number, an array, null — is refused.
+ */
+export declare function assertAdditionalPropertiesIsSchema(value: unknown): void;
+/**
+ * `patternProperties` maps regular expressions to schemas (§6.5.5). The map
+ * itself and every member of it are refused when they are not schemas, and the
+ * pattern is named in the reason so the message points at the one offending
+ * entry rather than at a map that may hold a dozen.
+ *
+ * THE KEYS ARE DELIBERATELY NOT COMPILED HERE, although Draft-07 says each
+ * SHOULD be a valid ECMA-262 pattern. A key that will not compile is not the
+ * failure this module exists to stop: the plugin compiles every key while
+ * building its rule, so such a key already kills the build, loudly, before any
+ * validator exists — it is a SyntaxError rather than a typed refusal, but
+ * nothing is silently under-enforced. Compiling one here as well would put a
+ * SECOND `new RegExp` in the converter, which holds exactly one — the `pattern`
+ * keyword's, over the document's own source string — so that regex
+ * construction and its flag handling stay in a single place.
+ */
+export declare function assertPatternPropertiesIsSchemaMap(value: unknown): void;
+/**
+ * `propertyNames` is ONE schema, applied to every property name (§6.5.8), and
+ * §4.4 makes a boolean one. An ARRAY is the shape of a schema list and is not
+ * itself a schema, so it is refused along with every primitive. An object
+ * stands whatever keywords it carries, because §4.3 has a schema ignore the
+ * keywords it does not recognise rather than be invalid for holding them.
+ */
+export declare function assertPropertyNamesIsSchema(value: unknown): void;
+/**
+ * `dependencies` maps a property name to what its presence demands (§6.5.7),
+ * and the draft gives that two equally lawful forms under the same key: an
+ * ARRAY of property names, which makes those names required alongside it, or a
+ * SCHEMA the whole instance must then satisfy. Both are kept; only a value
+ * that is neither is refused, and the key is named so the message points at
+ * the one offending entry rather than at the whole map.
+ */
+export declare function assertDependenciesIsSchemaOrNameListMap(value: unknown): void;

package/dist/json-schema/assert-object-keyword-values.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertRequiredIsNameList = assertRequiredIsNameList;
+exports.assertPropertiesIsSchemaMap = assertPropertiesIsSchemaMap;
+exports.assertAdditionalPropertiesIsSchema = assertAdditionalPropertiesIsSchema;
+exports.assertPatternPropertiesIsSchemaMap = assertPatternPropertiesIsSchemaMap;
+exports.assertPropertyNamesIsSchema = assertPropertyNamesIsSchema;
+exports.assertDependenciesIsSchemaOrNameListMap = assertDependenciesIsSchemaOrNameListMap;
+// ===========================================================================
+// L8  src/json-schema/assert-object-keyword-values.ts — the meta-schema check
+// on the VALUES of the object-family keywords: `required`, `properties`,
+// `additionalProperties`, `patternProperties`, `propertyNames` and
+// `dependencies`.
+//
+// They live together because they fail together: every one is read in a place
+// that trusts the declared type, and untyped JSON reaches all six. `required:
+// "name"` is iterated as a string and declares one phantom child per
+// CHARACTER; `properties: {a: null}` is read for a pointer; the remaining four
+// take the sub-schema route with a value that is not a schema at all, and the
+// walker finds no keys on a primitive, so it yields a branch holding no rules.
+//
+// That last outcome is the SILENT one, and it is the one that matters most: a
+// document saying "no extra properties", or "every key beginning with a_ holds
+// a string", compiles to a validator that accepts everything. It is what a
+// config service serialising booleans as strings produces, and what a
+// hand-edited document with a quoted sub-schema produces. The loud failures
+// are loud in the wrong place — a raw TypeError read off null somewhere deep
+// in the walker, naming neither the keyword nor the document.
+//
+// Refusal is therefore always at BUILD time, and every well-formed shape is
+// untouched: a name list, a map of schemas (including the §4.4 boolean form),
+// a single schema, and — under `dependencies` — either a schema or an array of
+// property names, which §6.5.7 makes equally lawful under the same key.
+// ===========================================================================
+const types_1 = require("../types");
+const draft07_types_1 = require("./draft07.types");
+const malformed_schema_error_1 = require("./malformed-schema-error");
+/**
+ * `required` is an array of property names (§6.5.3), and whatever the document
+ * put there is refused when it is anything else.
+ *
+ * UNIQUENESS IS NOT ENFORCED, although the meta-schema's `stringArray` asks
+ * for it. A repeated name asks for nothing the single name does not — the
+ * property is required either way, so the verdict is identical — and this
+ * check exists to stop a validator enforcing LESS than its document, not to
+ * lint a document that is enforced exactly as written. Refusing a duplicate
+ * would reject working schemas for no gain in correctness.
+ */
+function assertRequiredIsNameList(value) {
+    if (value === undefined || (0, types_1.isStringArray)(value))
+        return;
+    throw new malformed_schema_error_1.MalformedSchemaError("required", "the value must be an array of property names", value);
+}
+/**
+ * `properties` and `patternProperties` differ only in what their KEYS mean, so
+ * they are checked the same way: the map itself, then every member of it, and
+ * the offending key named in the reason so the message points at one entry
+ * rather than at a map that may hold a dozen. `dependencies` is not routed
+ * through here — §6.5.7 gives its members a second lawful form, which is a
+ * different member check and a different sentence.
+ *
+ * `mapReason` is the keyword's own, because "an object mapping property names
+ * to schemas" and "an object mapping regular expressions to schemas" are the
+ * only part of the requirement the two keywords do not share.
+ */
+function assertSchemaMap(keyword, mapReason, value) {
+    if (value === undefined)
+        return;
+    if (!(0, types_1.isPlainObject)(value)) {
+        throw new malformed_schema_error_1.MalformedSchemaError(keyword, mapReason, value);
+    }
+    for (const [key, member] of Object.entries(value)) {
+        if ((0, draft07_types_1.isDraft07Schema)(member))
+            continue;
+        throw new malformed_schema_error_1.MalformedSchemaError(keyword, `the schema under "${key}" ${malformed_schema_error_1.SCHEMA_FORMS}`, member);
+    }
+}
+/**
+ * `properties` maps property names to schemas (§6.5.4), and a schema is an
+ * object or a boolean; the map itself and every member of it are refused when
+ * they are not. The key is named in the reason so the message points at the
+ * offending node rather than at the whole document.
+ */
+function assertPropertiesIsSchemaMap(value) {
+    assertSchemaMap("properties", "the value must be an object mapping property names to schemas", value);
+}
+/**
+ * `additionalProperties` is a schema, and §4.4 makes a boolean one (§6.5.6).
+ * Both of those forms pass through unchanged; only a value the meta-schema
+ * already forbids — a string, a number, an array, null — is refused.
+ */
+function assertAdditionalPropertiesIsSchema(value) {
+    if (value === undefined || (0, draft07_types_1.isDraft07Schema)(value))
+        return;
+    throw new malformed_schema_error_1.MalformedSchemaError("additionalProperties", `the value ${malformed_schema_error_1.SCHEMA_FORMS}`, value);
+}
+/**
+ * `patternProperties` maps regular expressions to schemas (§6.5.5). The map
+ * itself and every member of it are refused when they are not schemas, and the
+ * pattern is named in the reason so the message points at the one offending
+ * entry rather than at a map that may hold a dozen.
+ *
+ * THE KEYS ARE DELIBERATELY NOT COMPILED HERE, although Draft-07 says each
+ * SHOULD be a valid ECMA-262 pattern. A key that will not compile is not the
+ * failure this module exists to stop: the plugin compiles every key while
+ * building its rule, so such a key already kills the build, loudly, before any
+ * validator exists — it is a SyntaxError rather than a typed refusal, but
+ * nothing is silently under-enforced. Compiling one here as well would put a
+ * SECOND `new RegExp` in the converter, which holds exactly one — the `pattern`
+ * keyword's, over the document's own source string — so that regex
+ * construction and its flag handling stay in a single place.
+ */
+function assertPatternPropertiesIsSchemaMap(value) {
+    assertSchemaMap("patternProperties", "the value must be an object mapping regular expressions to schemas", value);
+}
+/**
+ * `propertyNames` is ONE schema, applied to every property name (§6.5.8), and
+ * §4.4 makes a boolean one. An ARRAY is the shape of a schema list and is not
+ * itself a schema, so it is refused along with every primitive. An object
+ * stands whatever keywords it carries, because §4.3 has a schema ignore the
+ * keywords it does not recognise rather than be invalid for holding them.
+ */
+function assertPropertyNamesIsSchema(value) {
+    if (value === undefined || (0, draft07_types_1.isDraft07Schema)(value))
+        return;
+    throw new malformed_schema_error_1.MalformedSchemaError("propertyNames", `the value ${malformed_schema_error_1.SCHEMA_FORMS}`, value);
+}
+/**
+ * `dependencies` maps a property name to what its presence demands (§6.5.7),
+ * and the draft gives that two equally lawful forms under the same key: an
+ * ARRAY of property names, which makes those names required alongside it, or a
+ * SCHEMA the whole instance must then satisfy. Both are kept; only a value
+ * that is neither is refused, and the key is named so the message points at
+ * the one offending entry rather than at the whole map.
+ */
+function assertDependenciesIsSchemaOrNameListMap(value) {
+    if (value === undefined)
+        return;
+    if (!(0, types_1.isPlainObject)(value)) {
+        throw new malformed_schema_error_1.MalformedSchemaError("dependencies", "the value must be an object mapping property names to schemas or to " +
+            "arrays of property names", value);
+    }
+    for (const [key, dependency] of Object.entries(value)) {
+        if ((0, types_1.isStringArray)(dependency) || (0, draft07_types_1.isDraft07Schema)(dependency))
+            continue;
+        throw new malformed_schema_error_1.MalformedSchemaError("dependencies", `the dependency under "${key}" ${malformed_schema_error_1.SCHEMA_FORMS}, or an array of ` +
+            "property names", dependency);
+    }
+}

package/dist/json-schema/assert-object-keyword-values.mjs

@@ -0,0 +1,141 @@
+// ===========================================================================
+// L8  src/json-schema/assert-object-keyword-values.ts — the meta-schema check
+// on the VALUES of the object-family keywords: `required`, `properties`,
+// `additionalProperties`, `patternProperties`, `propertyNames` and
+// `dependencies`.
+//
+// They live together because they fail together: every one is read in a place
+// that trusts the declared type, and untyped JSON reaches all six. `required:
+// "name"` is iterated as a string and declares one phantom child per
+// CHARACTER; `properties: {a: null}` is read for a pointer; the remaining four
+// take the sub-schema route with a value that is not a schema at all, and the
+// walker finds no keys on a primitive, so it yields a branch holding no rules.
+//
+// That last outcome is the SILENT one, and it is the one that matters most: a
+// document saying "no extra properties", or "every key beginning with a_ holds
+// a string", compiles to a validator that accepts everything. It is what a
+// config service serialising booleans as strings produces, and what a
+// hand-edited document with a quoted sub-schema produces. The loud failures
+// are loud in the wrong place — a raw TypeError read off null somewhere deep
+// in the walker, naming neither the keyword nor the document.
+//
+// Refusal is therefore always at BUILD time, and every well-formed shape is
+// untouched: a name list, a map of schemas (including the §4.4 boolean form),
+// a single schema, and — under `dependencies` — either a schema or an array of
+// property names, which §6.5.7 makes equally lawful under the same key.
+// ===========================================================================
+import { isPlainObject, isStringArray } from "../types/index.mjs";
+import { isDraft07Schema } from "./draft07.types.mjs";
+import { MalformedSchemaError, SCHEMA_FORMS } from "./malformed-schema-error.mjs";
+/**
+ * `required` is an array of property names (§6.5.3), and whatever the document
+ * put there is refused when it is anything else.
+ *
+ * UNIQUENESS IS NOT ENFORCED, although the meta-schema's `stringArray` asks
+ * for it. A repeated name asks for nothing the single name does not — the
+ * property is required either way, so the verdict is identical — and this
+ * check exists to stop a validator enforcing LESS than its document, not to
+ * lint a document that is enforced exactly as written. Refusing a duplicate
+ * would reject working schemas for no gain in correctness.
+ */
+export function assertRequiredIsNameList(value) {
+    if (value === undefined || isStringArray(value))
+        return;
+    throw new MalformedSchemaError("required", "the value must be an array of property names", value);
+}
+/**
+ * `properties` and `patternProperties` differ only in what their KEYS mean, so
+ * they are checked the same way: the map itself, then every member of it, and
+ * the offending key named in the reason so the message points at one entry
+ * rather than at a map that may hold a dozen. `dependencies` is not routed
+ * through here — §6.5.7 gives its members a second lawful form, which is a
+ * different member check and a different sentence.
+ *
+ * `mapReason` is the keyword's own, because "an object mapping property names
+ * to schemas" and "an object mapping regular expressions to schemas" are the
+ * only part of the requirement the two keywords do not share.
+ */
+function assertSchemaMap(keyword, mapReason, value) {
+    if (value === undefined)
+        return;
+    if (!isPlainObject(value)) {
+        throw new MalformedSchemaError(keyword, mapReason, value);
+    }
+    for (const [key, member] of Object.entries(value)) {
+        if (isDraft07Schema(member))
+            continue;
+        throw new MalformedSchemaError(keyword, `the schema under "${key}" ${SCHEMA_FORMS}`, member);
+    }
+}
+/**
+ * `properties` maps property names to schemas (§6.5.4), and a schema is an
+ * object or a boolean; the map itself and every member of it are refused when
+ * they are not. The key is named in the reason so the message points at the
+ * offending node rather than at the whole document.
+ */
+export function assertPropertiesIsSchemaMap(value) {
+    assertSchemaMap("properties", "the value must be an object mapping property names to schemas", value);
+}
+/**
+ * `additionalProperties` is a schema, and §4.4 makes a boolean one (§6.5.6).
+ * Both of those forms pass through unchanged; only a value the meta-schema
+ * already forbids — a string, a number, an array, null — is refused.
+ */
+export function assertAdditionalPropertiesIsSchema(value) {
+    if (value === undefined || isDraft07Schema(value))
+        return;
+    throw new MalformedSchemaError("additionalProperties", `the value ${SCHEMA_FORMS}`, value);
+}
+/**
+ * `patternProperties` maps regular expressions to schemas (§6.5.5). The map
+ * itself and every member of it are refused when they are not schemas, and the
+ * pattern is named in the reason so the message points at the one offending
+ * entry rather than at a map that may hold a dozen.
+ *
+ * THE KEYS ARE DELIBERATELY NOT COMPILED HERE, although Draft-07 says each
+ * SHOULD be a valid ECMA-262 pattern. A key that will not compile is not the
+ * failure this module exists to stop: the plugin compiles every key while
+ * building its rule, so such a key already kills the build, loudly, before any
+ * validator exists — it is a SyntaxError rather than a typed refusal, but
+ * nothing is silently under-enforced. Compiling one here as well would put a
+ * SECOND `new RegExp` in the converter, which holds exactly one — the `pattern`
+ * keyword's, over the document's own source string — so that regex
+ * construction and its flag handling stay in a single place.
+ */
+export function assertPatternPropertiesIsSchemaMap(value) {
+    assertSchemaMap("patternProperties", "the value must be an object mapping regular expressions to schemas", value);
+}
+/**
+ * `propertyNames` is ONE schema, applied to every property name (§6.5.8), and
+ * §4.4 makes a boolean one. An ARRAY is the shape of a schema list and is not
+ * itself a schema, so it is refused along with every primitive. An object
+ * stands whatever keywords it carries, because §4.3 has a schema ignore the
+ * keywords it does not recognise rather than be invalid for holding them.
+ */
+export function assertPropertyNamesIsSchema(value) {
+    if (value === undefined || isDraft07Schema(value))
+        return;
+    throw new MalformedSchemaError("propertyNames", `the value ${SCHEMA_FORMS}`, value);
+}
+/**
+ * `dependencies` maps a property name to what its presence demands (§6.5.7),
+ * and the draft gives that two equally lawful forms under the same key: an
+ * ARRAY of property names, which makes those names required alongside it, or a
+ * SCHEMA the whole instance must then satisfy. Both are kept; only a value
+ * that is neither is refused, and the key is named so the message points at
+ * the one offending entry rather than at the whole map.
+ */
+export function assertDependenciesIsSchemaOrNameListMap(value) {
+    if (value === undefined)
+        return;
+    if (!isPlainObject(value)) {
+        throw new MalformedSchemaError("dependencies", "the value must be an object mapping property names to schemas or to " +
+            "arrays of property names", value);
+    }
+    for (const [key, dependency] of Object.entries(value)) {
+        if (isStringArray(dependency) || isDraft07Schema(dependency))
+            continue;
+        throw new MalformedSchemaError("dependencies", `the dependency under "${key}" ${SCHEMA_FORMS}, or an array of ` +
+            "property names", dependency);
+    }
+}

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>;