yaml-dsl-spec 0.1.2 → 0.1.3

package/README.md

@@ -9,20 +9,4 @@ if (read.problems) for (const problem of read.problems) console.error(String(pro
 else for (const { definition } of read.dsls) console.log(definition.id);
 ```
 
-| Export | Is |
-|---|---|
-| `readDslDefinitions(file, text)` | `{ dsls }`, each DSL of a `yaml-dsl.yml`, `{ definition, block }`, validated against its version's schema and the checks the schema cannot state; or `{ problems }`, every problem at the field it is about |
-| `Diagnostic`, `Position` | a problem at its place: `message`, `position` and `notes` (`label`, `rule`, `help`) |
-| `yamlReader.parseYaml(file, text, tagKeys)` | `{ node }`, YAML read with each value's place, or `{ problem }` |
-| `Node`, `numberJson` | a YAML value as written, and a number's text as JSON |
-| `dslDefinition.dslDefinitionFromJson(block)` | a DSL block with its defaults, its fields named as the standard names them |
-| `jsonPath` | `PathPattern` and `PathSet`, the standard's JSONPath subset |
-| `resolved` | `Value`, a resolved document's value with its place |
-| `functionTable` | `FunctionTable`, a schema's `x-yaml-dsl-functions` |
-| `schemaValidation` | `SchemaCache` and `LoadedSchema`, a document validated against its schema, each problem at its place |
-| `parseCallKey`, `closestName` | a call written in a key, and the allowed name closest to a misspelt one |
-| `yamlDslSchema(version)`, `yamlDslSchemas` | the JSON Schema of `yaml-dsl.yml`, at a version, or by version |
-| `functionTableSchema(version)`, `functionTableSchemas` | the JSON Schema of a DSL's function table, `x-yaml-dsl-functions`, at a version, or by version |
-| `YAML_DSL_VERSIONS`, `FUNCTION_TABLE_VERSIONS` | the versions the package reads |
-
-A version is a minor, such as `1.0`, or a major, such as `1`, which is its newest minor in the package.
+Its API is the core's, designed in the [package design](https://github.com/litebitus/yaml-dsl-spec/blob/main/docs/package-design.md).

package/index.js

@@ -49,6 +49,7 @@ module.exports = {
   schemaValidation: {
     SchemaCache: schemaValidation.SchemaCache,
     LoadedSchema: schemaValidation.LoadedSchema,
+    ValidationRules: schemaValidation.ValidationRules,
     childValue: schemaValidation.childValue,
   },
 };

package/lib/definition-reader.js

@@ -13,6 +13,7 @@ const { compilePattern, groupNamesOf } = require('./pattern-dialect');
 const { Position } = require('./source-position');
 const { Value } = require('./resolved-value');
 const { SchemaCache, closestName, nodeJsonText } = require('./schema-validation');
+const { ValidationRules } = require('./validation-rules');
 const { parseYaml } = require('./yaml-reader');
 const { YAML_DSL_VERSIONS, yamlDslSchemaFile } = require('./schema-catalog');
 
@@ -37,7 +38,7 @@ function readDslDefinitions(file, text) {
   } catch (error) {
     return { problems: [Diagnostic.unplaced(error.message)] };
   }
-  const schemaProblems = schema.validate(Value.fromNode(root), []);
+  const schemaProblems = schema.validate(Value.fromNode(root), new ValidationRules());
   if (schemaProblems.length > 0) return { problems: schemaProblems };
   const blocks = (root.get('dsls') && root.get('dsls').items()) || [];
   const problems = [];

package/lib/dsl-definition.js

@@ -125,7 +125,9 @@ const DSL_FIELDS = {
   })), emptyList),
   tag_keys: withDefault(listOf(struct({ tag: required(text), key: required(text) })), emptyList),
   validator: optional(struct({
+    merge_base_keys: withDefault(listOf(text), emptyList),
     child_values_from_parent_key: withDefault(listOf(struct({ pattern: required(text) })), emptyList),
+    allow_quoted_values: withDefault(listOf(oneOf(['boolean', 'integer', 'number'])), emptyList),
   })),
 };
 

package/lib/function-table.js

@@ -64,7 +64,7 @@ function compareText(first, second) {
 }
 
 function functionEntry(name, entry) {
-  const listed = isObject(entry) ? entry.arguments : undefined;
+  const listed = Array.isArray(entry) ? entry : isObject(entry) ? entry.arguments : undefined;
   if (!Array.isArray(listed)) throw new Error(`function \`${name}\` has no arguments list`);
   const functionArguments = listed.map((argument) => {
     const argumentName = isObject(argument) ? argument.name : undefined;
@@ -75,7 +75,9 @@ function functionEntry(name, entry) {
       default: hasOwn(argument, 'default') ? argument.default : null,
     };
   });
-  const macroEntry = hasOwn(entry, 'macro') ? macroEntryOf(name, entry.macro) : null;
+  const macroEntry = isObject(entry) && hasOwn(entry, 'macro')
+    ? macroEntryOf(name, entry.macro)
+    : null;
   return { arguments: functionArguments, macroEntry };
 }
 
@@ -101,6 +103,9 @@ function macroEntryOf(name, value) {
   for (const role of ROLE_NAMES) {
     if (typeof value[role] === 'string') roles[role] = value[role];
   }
+  if (!hasOwn(roles, 'loop_variables') && typeof value.loop_variable === 'string') {
+    roles.loop_variables = value.loop_variable;
+  }
   return new MacroEntry(kind, written || 'shallow', nameSuffix, roles);
 }
 

package/lib/json-path.js

@@ -11,6 +11,23 @@ function indexStep(index) {
   return { index };
 }
 
+/** A `['name']` step's name and the text after the step, or `null`. */
+function quotedName(text) {
+  if (!text.startsWith("['")) return null;
+  const close = text.indexOf("'", 2);
+  if (close <= 2 || text[close + 1] !== ']') return null;
+  return { name: text.slice(2, close), remaining: text.slice(close + 2) };
+}
+
+/** A dotted step's name, which runs to the next `.` or `[`, and the text after it, or `null`. */
+function dottedName(text) {
+  if (text.startsWith('*')) return null;
+  const stepEnd = text.search(/[.[]/);
+  const end = stepEnd === -1 ? text.length : stepEnd;
+  if (end === 0) return null;
+  return { name: text.slice(0, end), remaining: text.slice(end) };
+}
+
 /** A parsed path and the keys its wildcard steps do not select or descend into. */
 class PathPattern {
   constructor(selectors, skipKeys) {
@@ -23,38 +40,37 @@ class PathPattern {
     const invalid = () =>
       Diagnostic.unplaced(`\`${text}\` is not a path of the supported JSONPath subset`);
     if (!text.startsWith('$')) throw invalid();
-    const rest = text.slice(1);
+    let rest = text.slice(1);
     const selectors = [];
-    let index = 0;
-    while (index < rest.length) {
-      const descendant = rest.startsWith('..', index);
-      if (descendant) index += 2;
-      else if (rest[index] === '.') index += 1;
-      let name;
-      let consumed;
-      if (rest.startsWith("['", index)) {
-        const close = rest.indexOf("']", index + 2);
-        if (close === -1) throw invalid();
-        name = rest.slice(index + 2, close);
-        consumed = close - index + 2;
-      } else if (rest.startsWith('[*]', index)) {
-        name = null;
-        consumed = 3;
-      } else if (rest.startsWith('*', index)) {
-        name = null;
-        consumed = 1;
+    while (rest.length > 0) {
+      let step;
+      if (rest.startsWith('..')) {
+        const after = rest.slice(2);
+        if (after === '*') {
+          step = { selector: { kind: 'descendant_all' }, remaining: '' };
+        } else {
+          const named = quotedName(after) || dottedName(after);
+          if (!named) throw invalid();
+          step = {
+            selector: { kind: 'descendant_name', name: named.name },
+            remaining: named.remaining,
+          };
+        }
+      } else if (rest.startsWith('.*')) {
+        step = { selector: { kind: 'wildcard' }, remaining: rest.slice(2) };
+      } else if (rest.startsWith('.')) {
+        const named = dottedName(rest.slice(1));
+        if (!named) throw invalid();
+        step = { selector: { kind: 'name', name: named.name }, remaining: named.remaining };
+      } else if (rest.startsWith('[*]')) {
+        step = { selector: { kind: 'wildcard' }, remaining: rest.slice(3) };
       } else {
-        const ends = [rest.indexOf('.', index), rest.indexOf('[', index)].filter((end) => end !== -1);
-        const end = ends.length > 0 ? Math.min(...ends) : rest.length;
-        if (end === index) throw invalid();
-        name = rest.slice(index, end);
-        consumed = end - index;
+        const named = quotedName(rest);
+        if (!named) throw invalid();
+        step = { selector: { kind: 'name', name: named.name }, remaining: named.remaining };
       }
-      index += consumed;
-      if (!descendant) selectors.push(name === null ? { kind: 'wildcard' } : { kind: 'name', name });
-      else if (name !== null) selectors.push({ kind: 'descendant_name', name });
-      else if (index === rest.length) selectors.push({ kind: 'descendant_all' });
-      else throw invalid();
+      selectors.push(step.selector);
+      rest = step.remaining;
     }
     return new PathPattern(selectors, [...skipKeys]);
   }

package/lib/problem-wording.js

@@ -0,0 +1,223 @@
+'use strict';
+
+/* How a schema problem is worded: the field it names and the sentence about it. */
+
+const { descriptionText } = require('./requirement-markers');
+
+const DEPENDENCY_KEYWORDS = ['dependencies', 'dependentRequired', 'dependentSchemas'];
+const SCHEMA_MAP_KEYWORDS = [
+  '$defs',
+  'definitions',
+  'dependencies',
+  'dependentSchemas',
+  'patternProperties',
+  'properties',
+];
+const DEFINITION_KEYWORDS = ['$defs', 'definitions'];
+const UNSTATED_CONDITION = 'a condition the schema states';
+
+const hasOwn = (object, field) => Object.prototype.hasOwnProperty.call(object, field);
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function unescapePointer(step) {
+  return step.replaceAll('~1', '/').replaceAll('~0', '~');
+}
+
+function escapePointer(key) {
+  return key.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+
+function schemaNodeAt(root, pointer) {
+  if (pointer === '') return root;
+  let node = root;
+  for (const step of pointer.slice(1).split('/')) {
+    const key = unescapePointer(step);
+    if (node === null || typeof node !== 'object' || !hasOwn(node, key)) return undefined;
+    node = node[key];
+  }
+  return node;
+}
+
+/**
+ * The field a problem names: the key of the value at `pointer` in `document`, then
+ * `[<index>]` for each list index below it; the root is `the document`.
+ */
+function fieldName(document, pointer) {
+  if (pointer === '') return 'the document';
+  const steps = [];
+  let node = document;
+  for (const step of pointer.slice(1).split('/')) {
+    const key = unescapePointer(step);
+    const inList = Array.isArray(node);
+    if (inList) node = node[Number(key)];
+    else node = isObject(node) && hasOwn(node, key) ? node[key] : undefined;
+    steps.push({ key, inList });
+  }
+  let keyAt = steps.length - 1;
+  while (keyAt >= 0 && steps[keyAt].inList) keyAt -= 1;
+  const key = keyAt >= 0 ? steps[keyAt].key : '';
+  const indexes = steps.slice(keyAt + 1).map((step) => `[${step.key}]`).join('');
+  return `\`${key}${indexes}\``;
+}
+
+/** A JSON number as a report writes it. */
+function numberText(number) {
+  return String(number);
+}
+
+/**
+ * The sentence of an alternative none of whose forms holds: the first sentence of
+ * the definition holding the alternatives, where they are a described
+ * definition's, `#/$defs/<name>` or `#/definitions/<name>`; else `null`.
+ */
+function describedForm(schema, holderPointer) {
+  const steps = holderPointer.split('/').slice(1);
+  if (steps.length !== 2 || !DEFINITION_KEYWORDS.includes(steps[0])) return null;
+  const description = descriptionText(schemaNodeAt(schema, holderPointer));
+  if (!description) return null;
+  const sentence = description.split(/(?<=\.)\s/u)[0];
+  const firstSentence = sentence.endsWith('.') ? sentence.slice(0, -1) : sentence;
+  const leadingWord = /^[A-Za-z0-9]*/u.exec(firstSentence)[0];
+  if (leadingWord.length >= 2 && /^[A-Z]+$/u.test(leadingWord)) return firstSentence;
+  const [first, ...rest] = Array.from(firstSentence);
+  return first === undefined ? null : `${first.toLowerCase()}${rest.join('')}`;
+}
+
+/**
+ * The dependency keyword's pointer and the key it names, `{ keywordPointer, key }`,
+ * where `keywordPointer` lies inside a dependency: the key read from the pointer,
+ * or, for a dependency listing fields, from the field `holder` misses; else `null`.
+ */
+function dependencyOf(schema, keywordPointer, holder, missingField) {
+  const steps = keywordPointer.split('/').slice(1).map(unescapePointer);
+  let at = steps.length - 1;
+  while (at >= 0 && !(DEPENDENCY_KEYWORDS.includes(steps[at])
+    && (at === 0 || !SCHEMA_MAP_KEYWORDS.includes(steps[at - 1])))) at -= 1;
+  if (at < 0) return null;
+  const dependencyPointer = steps.slice(0, at + 1)
+    .map((step) => `/${escapePointer(step)}`)
+    .join('');
+  let key = steps[at + 1];
+  if (key === undefined) {
+    const listed = schemaNodeAt(schema, dependencyPointer);
+    if (typeof missingField !== 'string' || !isObject(listed)) return null;
+    key = Object.keys(listed).find((candidate) => isObject(holder) && hasOwn(holder, candidate)
+      && Array.isArray(listed[candidate]) && listed[candidate].includes(missingField));
+    if (key === undefined) return null;
+  }
+  if (!isObject(holder) || !hasOwn(holder, key)) return null;
+  return { keywordPointer: dependencyPointer, key };
+}
+
+/**
+ * `` `key` needs <what> ``: what each dependency of the node holding
+ * `keywordPointer` states for `key`.
+ */
+function dependencyMessage(schema, keywordPointer, key) {
+  const holder = schemaNodeAt(schema, keywordPointer.slice(0, keywordPointer.lastIndexOf('/')));
+  const statesKey = (keyword) => isObject(holder)
+    && isObject(holder[keyword])
+    && hasOwn(holder[keyword], key);
+  const neededTexts = DEPENDENCY_KEYWORDS
+    .filter(statesKey)
+    .map((keyword) => neededText(holder[keyword][key]));
+  return `\`${key}\` needs ${neededTexts.length > 0 ? neededTexts.join('; ') : UNSTATED_CONDITION}`;
+}
+
+function neededText(needed) {
+  if (Array.isArray(needed)) return keyList(needed);
+  return consequenceText(needed) || UNSTATED_CONDITION;
+}
+
+function consequenceText(node) {
+  if (!isObject(node)) return null;
+  const parts = [];
+  if (Array.isArray(node.required) && node.required.length > 0) parts.push(keyList(node.required));
+  if (isObject(node.not) && Array.isArray(node.not.required) && node.not.required.length > 0) {
+    parts.push(`${keyList(node.not.required)} must not be set`);
+  }
+  const properties = isObject(node.properties) ? node.properties : {};
+  for (const [field, fieldSchema] of Object.entries(properties)) {
+    if (isObject(fieldSchema) && typeof fieldSchema.$ref === 'string') {
+      parts.push(`\`${field}\` is a \`${referenceName(fieldSchema.$ref)}\``);
+    }
+  }
+  for (const part of Array.isArray(node.allOf) ? node.allOf : []) {
+    const partText = consequenceText(part);
+    if (partText) parts.push(partText);
+  }
+  const alternatives = ['anyOf', 'oneOf']
+    .flatMap((keyword) => (Array.isArray(node[keyword]) ? node[keyword] : []));
+  if (alternatives.length > 0) {
+    parts.push(alternatives
+      .map((alternative) => consequenceText(alternative) || UNSTATED_CONDITION)
+      .join(', or '));
+  }
+  if (parts.length === 0 && typeof node.$ref === 'string') {
+    parts.push(`a \`${referenceName(node.$ref)}\``);
+  }
+  return parts.length > 0 ? parts.join('; ') : null;
+}
+
+function referenceName(reference) {
+  return reference.slice(reference.lastIndexOf('/') + 1).replace(/^#/u, '');
+}
+
+function keyList(keys) {
+  const spans = keys.map((key) => `\`${typeof key === 'string' ? key : JSON.stringify(key)}\``);
+  return spans.length > 1 ? `${spans.slice(0, -1).join(', ')} and ${spans.at(-1)}` : spans.join('');
+}
+
+/**
+ * The indexes of the duplicate items a list reports, later first, `[later, earlier]`:
+ * from the last item back, the first one equal to an item after it, and the
+ * nearest such item; `null` for a list without duplicates.
+ */
+function duplicateItems(items) {
+  for (let earlier = items.length - 1; earlier >= 0; earlier -= 1) {
+    for (let later = earlier + 1; later < items.length; later += 1) {
+      if (jsonEqual(items[earlier], items[later])) return [later, earlier];
+    }
+  }
+  return null;
+}
+
+function jsonEqual(first, second) {
+  if (Array.isArray(first) && Array.isArray(second)) {
+    return first.length === second.length
+      && first.every((item, index) => jsonEqual(item, second[index]));
+  }
+  if (isObject(first) && isObject(second)) {
+    const keys = Object.keys(first);
+    return keys.length === Object.keys(second).length
+      && keys.every((key) => hasOwn(second, key) && jsonEqual(first[key], second[key]));
+  }
+  return first === second;
+}
+
+/**
+ * `must contain at least <min> valid item(s)`, with `and no more than <max>`
+ * where `holder` bounds it.
+ */
+function containsMessage(holder) {
+  const bound = (keyword) => (isObject(holder) && typeof holder[keyword] === 'number'
+    ? numberText(holder[keyword])
+    : null);
+  const minimum = bound('minContains') || '1';
+  const maximum = bound('maxContains');
+  return maximum === null
+    ? `must contain at least ${minimum} valid item(s)`
+    : `must contain at least ${minimum} and no more than ${maximum} valid item(s)`;
+}
+
+module.exports = {
+  fieldName,
+  numberText,
+  describedForm,
+  dependencyOf,
+  dependencyMessage,
+  duplicateItems,
+  containsMessage,
+  schemaNodeAt,
+  escapePointer,
+};

package/lib/requirement-markers.js

@@ -0,0 +1,128 @@
+'use strict';
+
+/*
+ * Requirement markers: a field's `description` opening with `[required]`,
+ * `[~required]` or `[optional]` decides whether the field is required, over its
+ * parent's `required` array.
+ */
+
+const REQUIRED_MARKER = '[required]';
+const REQUIREMENT_MARKERS = [REQUIRED_MARKER, '[~required]', '[optional]'];
+const CONDITION_KEYWORDS = new Set(['if', 'not']);
+const FORM_SELECTING_KEYWORDS = new Set(['anyOf', 'oneOf']);
+const SAME_INSTANCE_SCHEMA_KEYWORDS = new Set(['else', 'if', 'not', 'then']);
+const SAME_INSTANCE_LIST_KEYWORDS = new Set(['allOf', 'anyOf', 'oneOf']);
+const SCHEMA_MAP_KEYWORDS = new Set([
+  '$defs',
+  'definitions',
+  'dependentSchemas',
+  'patternProperties',
+  'properties',
+]);
+const DRAFT_KEYWORDS = {
+  'draft-07': {
+    childSchema: new Set([
+      'additionalItems',
+      'additionalProperties',
+      'contains',
+      'items',
+      'propertyNames',
+    ]),
+    schemaMap: new Set([
+      '$defs',
+      'definitions',
+      'dependencies',
+      'patternProperties',
+      'properties',
+    ]),
+  },
+  'draft 2019-09': {
+    childSchema: new Set([
+      'additionalItems',
+      'additionalProperties',
+      'contains',
+      'contentSchema',
+      'items',
+      'propertyNames',
+      'unevaluatedItems',
+      'unevaluatedProperties',
+    ]),
+    schemaMap: SCHEMA_MAP_KEYWORDS,
+  },
+  'draft 2020-12': {
+    childSchema: new Set([
+      'additionalProperties',
+      'contains',
+      'contentSchema',
+      'items',
+      'prefixItems',
+      'propertyNames',
+      'unevaluatedItems',
+      'unevaluatedProperties',
+    ]),
+    schemaMap: SCHEMA_MAP_KEYWORDS,
+  },
+};
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** The marker a schema node's `description` opens with, or `null`. */
+function requirementMarker(node) {
+  if (!isObject(node) || typeof node.description !== 'string') return null;
+  const description = node.description.trimStart();
+  return REQUIREMENT_MARKERS.find((marker) => description.startsWith(marker)) || null;
+}
+
+/** A node's description without the marker it opens with, or `null`. */
+function descriptionText(node) {
+  if (!isObject(node) || typeof node.description !== 'string') return null;
+  const marker = requirementMarker(node);
+  const text = marker ? node.description.trimStart().slice(marker.length) : node.description;
+  return text.trim() || null;
+}
+
+/** `schema`, read in the draft named `draftName`, with each `required` array decided by markers. */
+function markedSchema(schema, draftName) {
+  return markedNode(schema, null, DRAFT_KEYWORDS[draftName]);
+}
+
+function markersOfFields(properties) {
+  const markers = new Map();
+  for (const [key, field] of Object.entries(properties)) {
+    const marker = requirementMarker(field);
+    if (marker) markers.set(key, marker);
+  }
+  return markers;
+}
+
+function markedNode(node, inheritedMarkers, keywords) {
+  if (!isObject(node)) return node;
+  const ownMarkers = isObject(node.properties) ? markersOfFields(node.properties) : null;
+  const markers = ownMarkers || inheritedMarkers;
+  const marked = {};
+  const markedChild = (child) => markedNode(child, null, keywords);
+  for (const [keyword, value] of Object.entries(node)) {
+    if (keyword === 'required') continue;
+    if (CONDITION_KEYWORDS.has(keyword)) marked[keyword] = value;
+    else if (SAME_INSTANCE_SCHEMA_KEYWORDS.has(keyword)) {
+      marked[keyword] = markedNode(value, markers, keywords);
+    } else if (SAME_INSTANCE_LIST_KEYWORDS.has(keyword) && Array.isArray(value)) {
+      const branchMarkers = FORM_SELECTING_KEYWORDS.has(keyword) ? null : markers;
+      marked[keyword] = value.map((branch) => markedNode(branch, branchMarkers, keywords));
+    } else if (keywords.childSchema.has(keyword)) {
+      marked[keyword] = Array.isArray(value) ? value.map(markedChild) : markedChild(value);
+    } else if (keywords.schemaMap.has(keyword) && isObject(value)) {
+      marked[keyword] = Object.fromEntries(Object.entries(value)
+        .map(([name, schema]) => [name, markedChild(schema)]));
+    } else {
+      marked[keyword] = value;
+    }
+  }
+  const listed = Array.isArray(node.required) ? node.required : [];
+  const required = listed.filter((key) => !markers || !markers.has(key));
+  for (const [key, marker] of ownMarkers || []) if (marker === REQUIRED_MARKER) required.push(key);
+  if (required.length > 0) marked.required = required;
+  return marked;
+}
+
+module.exports = { requirementMarker, descriptionText, markedSchema };

package/lib/schema-validation.js

@@ -7,6 +7,24 @@ const AjvDraft202012 = require('ajv/dist/2020').default;
 const { Diagnostic } = require('./diagnostic-report');
 const { FunctionTable } = require('./function-table');
 const { numberJson, integerOfText } = require('./yaml-node');
+const { markedSchema } = require('./requirement-markers');
+const {
+  fieldName,
+  numberText,
+  describedForm,
+  dependencyOf,
+  dependencyMessage,
+  duplicateItems,
+  containsMessage,
+  schemaNodeAt,
+} = require('./problem-wording');
+const {
+  ValidationRules,
+  childValue,
+  mergedOver,
+  copiedPointers,
+  escapePointer,
+} = require('./validation-rules');
 
 const VALIDATOR_OPTIONS = {
   allErrors: true,
@@ -49,23 +67,22 @@ const READS_BELOW_KEYWORDS = new Set([
   'uniqueItems',
 ]);
 const REQUIRED_KEYWORDS = new Set(['required', 'dependentRequired', 'dependencies']);
-const LIMIT_PLURALS = {
-  maxLength: ['is longer than', 'character', 'characters'],
-  minLength: ['is shorter than', 'character', 'characters'],
-  maxItems: ['has more than', 'item', 'items'],
-  minItems: ['has less than', 'item', 'items'],
-  maxProperties: ['has more than', 'property', 'properties'],
-  minProperties: ['has less than', 'property', 'properties'],
+const BOUND_COMPARISONS = {
+  minimum: '>=',
+  maximum: '<=',
+  exclusiveMinimum: '>',
+  exclusiveMaximum: '<',
 };
-const BOUNDS = {
-  maximum: 'is greater than the maximum of',
-  minimum: 'is less than the minimum of',
-  exclusiveMaximum: 'is greater than or equal to the maximum of',
-  exclusiveMinimum: 'is less than or equal to the minimum of',
+const LENGTH_LIMITS = {
+  minLength: ['fewer', 'characters'],
+  maxLength: ['more', 'characters'],
+  minItems: ['fewer', 'items'],
+  maxItems: ['more', 'items'],
+  minProperties: ['fewer', 'properties'],
+  maxProperties: ['more', 'properties'],
 };
-const KEYWORD_NAMES = { 'false schema': 'falseSchema', items: 'additionalItems' };
+const KEYWORD_NAMES = { 'false schema': 'falseSchema' };
 const FALSE_SCHEMA_STEP = /\/false schema$/;
-const SHOWN_ENUM_OPTIONS = 3;
 
 const hasOwn = (object, field) => Object.prototype.hasOwnProperty.call(object, field);
 const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -88,10 +105,11 @@ function draftOfSchema(schema) {
 
 /** A document's schema, as its caller hands it over: its function table, and the validation against it. */
 class LoadedSchema {
-  constructor(table, validator, schema, name, pointersBySchemaObject) {
+  constructor(table, validator, schema, marked, name, pointersBySchemaObject) {
     this.table = table;
     this.validator = validator;
     this.schema = schema;
+    this.marked = marked;
     this.name = name;
     this.pointersBySchemaObject = pointersBySchemaObject;
   }
@@ -112,119 +130,234 @@ class LoadedSchema {
   /** The schema `text` holds, named `name` in reports, or throws why it holds none. */
   static parse(name, text) {
     const failed = (error) => new Error(`schema ${name}: ${error.message}`);
-    let schema;
-    let table;
-    let validator;
     try {
-      schema = JSON.parse(text);
-      table = FunctionTable.fromSchema(schema);
+      const schema = JSON.parse(text);
+      const table = FunctionTable.fromSchema(schema);
       const draft = draftOfSchema(schema);
-      const compiled = isObject(schema) && schema.$schema !== undefined && OLDER_DRAFT_URIS.includes(schema.$schema)
+      const declaresOlderDraft = isObject(schema)
+        && schema.$schema !== undefined
+        && OLDER_DRAFT_URIS.includes(schema.$schema);
+      const declared = declaresOlderDraft
         ? { ...schema, $schema: ASSUMED_DRAFT.schemaUris[0] }
         : schema;
-      validator = new draft.ValidatorClass(VALIDATOR_OPTIONS).compile(compiled);
-      return new LoadedSchema(table, validator, schema, name, schemaObjectPointers(compiled));
+      const marked = markedSchema(declared, draft.name);
+      const validator = new draft.ValidatorClass(VALIDATOR_OPTIONS).compile(marked);
+      const pointers = schemaObjectPointers(marked);
+      return new LoadedSchema(table, validator, schema, marked, name, pointers);
     } catch (error) {
       throw failed(error);
     }
   }
 
   /**
-   * Validates `document`, a resolved value. A value not known when the document
-   * compiles, such as a call or a reference to a declaration, is not checked.
+   * Validates `document`, a resolved value, read by `rules`. A value not known
+   * when the document compiles, such as a call or a reference to a declaration,
+   * is not checked.
    */
-  validate(document, childValuePatterns = []) {
-    const instance = new InstanceRecord(childValuePatterns);
-    const json = instance.json(document, '', document.position);
+  validate(document, rules) {
+    const instance = new InstanceRecord(rules);
+    const json = this.withQuotedValuesRead(instance.json(document, '', document.position), rules);
     this.validator(json);
-    const errors = reportedErrors(this.validator.errors || [], this.schema)
+    const errors = reportedErrors(this.validator.errors || [], this.marked)
       .filter((error) => !instance.readsUnknown(error.instancePath, error.keyword));
-    const diagnostics = errors.flatMap((error) => this.errorDiagnostics(error, instance));
+    const reported = { dependencies: new Set(), itemLists: new Set(), propertyNames: new Set() };
+    const diagnostics = errors
+      .flatMap((error) => this.errorProblems(error, json, instance, reported))
+      .filter((problem) => !instance.isCopied(problem.subject))
+      .map((problem) => problem.diagnostic);
     diagnostics.sort(compareDiagnostics);
     return diagnostics.filter((diagnostic, index) =>
       index === 0 || !sameDiagnostic(diagnostic, diagnostics[index - 1]));
   }
 
   /**
-   * A schema error as the report a reader fixes it from: placed at the value or
-   * the field that is wrong, labeled with what is wrong there, naming the rule it
-   * breaks, and the allowed name closest to a misspelt one.
+   * `json` with each quoted value that spells a type the schema expects of it, and
+   * `rules` allow, read as that type, until no more are read.
    */
-  errorDiagnostics(error, instance) {
+  withQuotedValuesRead(json, rules) {
+    if (rules.quotedValueTypes.length === 0) return json;
+    let read = json;
+    for (;;) {
+      this.validator(read);
+      const readings = new Map();
+      for (const error of this.validator.errors || []) {
+        if (error.keyword !== 'type' || typeof error.data !== 'string') continue;
+        const reading = rules.quotedValue(error.data, [].concat(error.schema));
+        if (reading !== null && !readings.has(error.instancePath)) {
+          readings.set(error.instancePath, reading.value);
+        }
+      }
+      if (readings.size === 0) return read;
+      for (const [pointer, value] of readings) read = withValueAt(read, pointer, value);
+    }
+  }
+
+  /**
+   * A schema error as the problems a reader fixes it from, `{ subject, diagnostic }`:
+   * placed at the value or the field that is wrong, worded by the standard,
+   * labeled with what is wrong there, naming the rule it breaks, and the allowed
+   * name closest to a misspelt one.
+   */
+  errorProblems(error, json, instance, reported) {
     const pointer = error.instancePath;
     const keyword = keywordName(error);
     const schemaPointer = this.keywordPointer(error);
-    const rule = `${keyword}, at ${this.name}#${schemaPointer}`;
-    if (error.propertyName !== undefined) {
-      return [
-        Diagnostic.at(instance.valuePosition(pointer), `${displayPointer(pointer)}: ${errorText(error, instance)}`)
-          .withLabel(`breaks \`${keyword}\``)
-          .withRule(rule),
-      ];
-    }
-    if (error.keyword === 'items' && error.schema === false) {
-      const extra = Array.isArray(error.data) ? error.data.slice(error.params.limit) : [];
-      return extra.map((item, index) => {
-        const itemPointer = `${pointer}/${error.params.limit + index}`;
-        return Diagnostic.at(
-          instance.valuePosition(itemPointer),
-          `${displayPointer(itemPointer)}: False schema does not allow ${instance.jsonText(item, itemPointer)}`,
+    const ruleAt = (name, at) => `${name}, at ${this.name}#${at}`;
+    const rule = ruleAt(keyword, schemaPointer);
+    const field = fieldName(json, pointer);
+    const missingField = REQUIRED_KEYWORDS.has(error.keyword)
+      ? error.params.missingProperty
+      : null;
+    const dependency = error.propertyName === undefined
+      ? dependencyOf(this.marked, schemaPointer, valueAt(json, pointer), missingField)
+      : null;
+    if (dependency !== null) {
+      const subject = `${pointer}/${escapePointer(dependency.key)}`;
+      if (reported.dependencies.has(subject)) return [];
+      reported.dependencies.add(subject);
+      const { keywordPointer } = dependency;
+      const dependencyKeyword = keywordPointer.slice(keywordPointer.lastIndexOf('/') + 1);
+      const at = `${dependency.keywordPointer}/${escapePointer(dependency.key)}`;
+      return [{
+        subject,
+        diagnostic: Diagnostic.at(
+          instance.position(subject),
+          dependencyMessage(this.marked, dependency.keywordPointer, dependency.key),
         )
-          .withLabel('breaks `falseSchema`')
-          .withRule(`falseSchema, at ${this.name}#${schemaPointer}`);
-      });
+          .withLabel(`breaks \`${dependencyKeyword}\``)
+          .withRule(ruleAt(dependencyKeyword, at)),
+      }];
     }
-    const step = lastStep(pointer);
-    const holder = step === null ? 'the document' : `\`${step}\``;
     const suggestion = (name, candidates) => {
       const closest = closestName(name, candidates);
       return closest === null ? null : `did you mean \`${closest}\`?`;
     };
+    const atValue = (message) => [{
+      subject: pointer,
+      diagnostic: Diagnostic.at(instance.valuePosition(pointer), message)
+        .withLabel(`breaks \`${keyword}\``)
+        .withRule(rule),
+    }];
+    if (error.propertyName !== undefined) {
+      const subject = `${pointer}/${escapePointer(error.propertyName)}`;
+      if (reported.propertyNames.has(subject)) return [];
+      reported.propertyNames.add(subject);
+      return [{
+        subject,
+        diagnostic: Diagnostic.at(
+          instance.position(subject),
+          `\`${error.propertyName}\` is not a valid key of ${field}`,
+        )
+          .withLabel('breaks `propertyNames`')
+          .withRule(rule),
+      }];
+    }
+    const itemsBeyondTuple = (error.keyword === 'items' && error.schema === false)
+      || error.keyword === 'additionalItems';
+    if (itemsBeyondTuple) {
+      if (reported.itemLists.has(pointer)) return [];
+      reported.itemLists.add(pointer);
+      const listKeyword = schemaPointer.slice(schemaPointer.lastIndexOf('/') + 1);
+      return [{
+        subject: pointer,
+        diagnostic: Diagnostic.at(
+          instance.valuePosition(pointer),
+          `${field} must NOT have more than ${error.params.limit} items`,
+        )
+          .withLabel(`breaks \`${listKeyword}\``)
+          .withRule(ruleAt(listKeyword, schemaPointer)),
+      }];
+    }
     if (error.keyword === 'additionalProperties' || error.keyword === 'unevaluatedProperties') {
       const name = error.keyword === 'additionalProperties'
         ? error.params.additionalProperty
         : error.params.unevaluatedProperty;
       const allowed = allowedFields(this.schema, schemaPointer);
-      const field = `${pointer}/${escapePointer(name)}`;
-      return [
-        Diagnostic.at(instance.position(field), `field \`${name}\` is not allowed`)
-          .withLabel(`${holder} has no field \`${name}\``)
+      const subject = `${pointer}/${escapePointer(name)}`;
+      return [{
+        subject,
+        diagnostic: Diagnostic.at(
+          instance.position(subject),
+          `\`${name}\` is not a field of ${field}`,
+        )
+          .withLabel(`${field} has no field \`${name}\``)
           .withRule(rule)
           .withHelp(suggestion(name, allowed)),
-      ];
+      }];
     }
     if (error.keyword === 'enum') {
       const options = Array.isArray(error.schema) ? error.schema : [];
       const allowed = options.filter((option) => typeof option === 'string');
-      const value = error.data;
-      return [
-        Diagnostic.at(instance.valuePosition(pointer), `\`${shownValue(value, pointer, instance)}\` is not an allowed value`)
+      const shown = options.map((option) => `\`${jsonText(option)}\``).join(', ');
+      return [{
+        subject: pointer,
+        diagnostic: Diagnostic.at(
+          instance.valuePosition(pointer),
+          `${field} must be one of ${shown}`,
+        )
           .withLabel(`not one of the ${options.length} values \`enum\` allows`)
           .withRule(rule)
-          .withHelp(typeof value === 'string' ? suggestion(value, allowed) : null),
-      ];
+          .withHelp(typeof error.data === 'string' ? suggestion(error.data, allowed) : null),
+      }];
     }
     if (error.keyword === 'type') {
-      const expected = typesOf(error.schema);
-      return [
-        Diagnostic.at(instance.valuePosition(pointer), `${holder} is not ${withArticle(expected.join(' or '))}`)
+      const expected = [].concat(error.schema);
+      return [{
+        subject: pointer,
+        diagnostic: Diagnostic.at(
+          instance.valuePosition(pointer),
+          `${field} must be ${expected.join(' or ')}`,
+        )
           .withLabel(`is ${withArticle(instance.jsonType(pointer, error.data))}`)
           .withRule(rule),
-      ];
+      }];
     }
     if (REQUIRED_KEYWORDS.has(error.keyword)) {
       const name = error.params.missingProperty;
-      return [
-        Diagnostic.at(instance.position(pointer), `field \`${name}\` is required`)
-          .withLabel(`${holder} has no field \`${name}\``)
+      return [{
+        subject: pointer,
+        diagnostic: Diagnostic.at(instance.position(pointer), `\`${name}\` is required`)
+          .withLabel(`${field} has no field \`${name}\``)
           .withRule(rule),
-      ];
+      }];
+    }
+    if (ALTERNATIVE_KEYWORDS.has(error.keyword)) {
+      if (Array.isArray(error.params.passingSchemas)) {
+        return atValue(`${field} matches more than one of its allowed forms`);
+      }
+      const holderPointer = schemaPointer.slice(0, schemaPointer.lastIndexOf('/'));
+      const form = describedForm(this.schema, holderPointer);
+      return atValue(form === null
+        ? `${field} matches none of its allowed forms`
+        : `${field} must be ${form}`);
+    }
+    if (hasOwn(BOUND_COMPARISONS, error.keyword)) {
+      const comparison = BOUND_COMPARISONS[error.keyword];
+      return atValue(`${field} must be ${comparison} ${numberText(error.schema)}`);
+    }
+    if (hasOwn(LENGTH_LIMITS, error.keyword)) {
+      const [comparison, unit] = LENGTH_LIMITS[error.keyword];
+      return atValue(`${field} must NOT have ${comparison} than ${error.params.limit} ${unit}`);
+    }
+    switch (error.keyword) {
+      case 'const': return atValue(`${field} must be equal to constant`);
+      case 'multipleOf':
+        return atValue(`${field} must be multiple of ${numberText(error.schema)}`);
+      case 'pattern': return atValue(`${field} must match pattern "${error.params.pattern}"`);
+      case 'uniqueItems': {
+        const items = Array.isArray(error.data) ? error.data : [];
+        const [later, earlier] = duplicateItems(items) || [0, 0];
+        return atValue(
+          `${field} must NOT have duplicate items (items ## ${later} and ${earlier} are identical)`,
+        );
+      }
+      case 'contains': return atValue(`${field} ${containsMessage(error.parentSchema)}`);
+      case 'not': return atValue(`${field} must NOT be valid`);
+      case 'false schema': return atValue(`${field} boolean schema is false`);
+      case 'unevaluatedItems':
+        return atValue(`${field} must NOT have more than ${error.params.len} items`);
+      default: return atValue(`${field} breaks \`${keyword}\``);
     }
-    return [
-      Diagnostic.at(instance.valuePosition(pointer), `${displayPointer(pointer)}: ${errorText(error, instance)}`)
-        .withLabel(`breaks \`${keyword}\``)
-        .withRule(rule),
-    ];
   }
 }
 
@@ -322,17 +455,6 @@ function pointerOfSchemaPath(path) {
   }
 }
 
-function schemaNodeAt(root, pointer) {
-  if (pointer === '') return root;
-  let node = root;
-  for (const step of pointer.slice(1).split('/')) {
-    const key = step.replaceAll('~1', '/').replaceAll('~0', '~');
-    if (node === null || typeof node !== 'object' || !hasOwn(node, key)) return undefined;
-    node = node[key];
-  }
-  return node;
-}
-
 /**
  * The fields a schema node allows, by the `properties` of the node holding the
  * keyword at `keywordPointer`, of the schemas it references and of those it
@@ -397,61 +519,10 @@ function editDistance(first, second) {
   return previous[secondCharacters.length];
 }
 
-/**
- * What a JSON pointer names, as a report shows it: its last key, or for a list
- * item, the list's key and the item's index, such as `dsls[0]`; `null` for the
- * document's root.
- */
-function lastStep(pointer) {
-  const slash = pointer.lastIndexOf('/');
-  if (slash === -1) return null;
-  const parent = pointer.slice(0, slash);
-  const step = pointer.slice(slash + 1);
-  if (/^\d+$/.test(step)) {
-    const list = lastStep(parent);
-    if (list !== null) return `${list}[${step}]`;
-  }
-  return step.replaceAll('~1', '/').replaceAll('~0', '~');
-}
-
-function escapePointer(key) {
-  return key.replaceAll('~', '~0').replaceAll('/', '~1');
-}
-
-function displayPointer(pointer) {
-  if (pointer === '') return 'the document';
-  const steps = pointer.slice(1).split('/').map((step) => step.replaceAll('~1', '/').replaceAll('~0', '~'));
-  return `\`${steps.join('.')}\``;
-}
-
 function withArticle(noun) {
   return `${/^[aeiou]/.test(noun) ? 'an' : 'a'} ${noun}`;
 }
 
-/** A schema's `type` as the crate lists several: in its fixed order of JSON types. */
-function typesOf(typeKeyword) {
-  if (!Array.isArray(typeKeyword)) return [String(typeKeyword)];
-  const order = ['null', 'boolean', 'integer', 'number', 'string', 'array', 'object'];
-  return order.filter((type) => typeKeyword.includes(type));
-}
-
-/** A string as Rust's `Debug` writes it. */
-function debugText(text) {
-  let written = '"';
-  for (const character of text) {
-    const code = character.codePointAt(0);
-    if (character === '"') written += '\\"';
-    else if (character === '\\') written += '\\\\';
-    else if (character === '\n') written += '\\n';
-    else if (character === '\r') written += '\\r';
-    else if (character === '\t') written += '\\t';
-    else if (character === '\0') written += '\\0';
-    else if (code < 0x20 || code === 0x7f) written += `\\u{${code.toString(16)}}`;
-    else written += character;
-  }
-  return `${written}"`;
-}
-
 /** A floating-point number as `serde_json` writes one. */
 function floatText(number) {
   if (Object.is(number, -0)) return '-0.0';
@@ -496,72 +567,6 @@ function nodeJsonText(node) {
   return jsonText(node.toJson(), (at) => (numberTexts.has(at) ? numberTexts.get(at) : null));
 }
 
-function shownValue(value, pointer, instance) {
-  return typeof value === 'string' ? debugText(value) : instance.jsonText(value, pointer);
-}
-
-function plural(count, words) {
-  return count === 1 ? words[1] : words[2];
-}
-
-/** An error's text as the crate's validator words it. */
-function errorText(error, instance) {
-  const shown = instance.jsonText(error.data, error.instancePath);
-  const { keyword, params } = error;
-  if (hasOwn(LIMIT_PLURALS, keyword)) {
-    const words = LIMIT_PLURALS[keyword];
-    return `${shown} ${words[0]} ${params.limit} ${plural(params.limit, words)}`;
-  }
-  if (hasOwn(BOUNDS, keyword)) return `${shown} ${BOUNDS[keyword]} ${jsonText(params.limit)}`;
-  switch (keyword) {
-    case 'enum': return `${shown} is not one of ${enumOptionsText(Array.isArray(error.schema) ? error.schema : [])}`;
-    case 'type': {
-      const types = typesOf(error.schema);
-      return types.length === 1
-        ? `${shown} is not of type ${JSON.stringify(types[0])}`
-        : `${shown} is not of types ${types.map((type) => JSON.stringify(type)).join(', ')}`;
-    }
-    case 'const': return `${jsonText(error.schema)} was expected`;
-    case 'pattern': return `${shown} does not match "${params.pattern}"`;
-    case 'multipleOf': return `${shown} is not a multiple of ${params.multipleOf}`;
-    case 'uniqueItems': return `${shown} has non-unique elements`;
-    case 'not': return `${jsonText(error.schema)} is not allowed for ${shown}`;
-    case 'anyOf': return `${shown} is not valid under any of the schemas listed in the 'anyOf' keyword`;
-    case 'oneOf':
-      return params.passingSchemas
-        ? `${shown} is valid under more than one of the schemas listed in the 'oneOf' keyword`
-        : `${shown} is not valid under any of the schemas listed in the 'oneOf' keyword`;
-    case 'contains': return `None of ${shown} are valid under the given schema`;
-    case 'false schema': return `False schema does not allow ${shown}`;
-    case 'propertyNames': return `${JSON.stringify(params.propertyName)} is not valid under the property names schema`;
-    case 'items':
-    case 'additionalItems': {
-      const extra = Array.isArray(error.data) ? error.data.slice(params.limit) : [];
-      const listed = extra.map((item, index) =>
-        instance.jsonText(item, `${error.instancePath}/${params.limit + index}`));
-      return `Additional items are not allowed (${listed.join(', ')} ${extra.length === 1 ? 'was' : 'were'} unexpected)`;
-    }
-    case 'unevaluatedItems': {
-      const extra = Array.isArray(error.data) ? error.data.slice(params.len) : [];
-      const listed = extra.map((item, index) =>
-        `'${instance.jsonText(item, `${error.instancePath}/${params.len + index}`)}'`);
-      return `Unevaluated items are not allowed (${listed.join(', ')} ${extra.length === 1 ? 'was' : 'were'} unexpected)`;
-    }
-    default: return error.message;
-  }
-}
-
-/** An enum's options as the crate's validator lists them: a few, then how many more. */
-function enumOptionsText(options) {
-  const written = options.map((option) => jsonText(option));
-  if (written.length <= SHOWN_ENUM_OPTIONS) {
-    if (written.length <= 1) return written.join('');
-    return `${written.slice(0, -1).join(', ')} or ${written.at(-1)}`;
-  }
-  const shown = written.slice(0, SHOWN_ENUM_OPTIONS - 1);
-  return `${shown.join(', ')} or ${written.length - shown.length} other candidates`;
-}
-
 function compareDiagnostics(first, second) {
   const firstPlace = first.position ? [first.position.line, first.position.column] : [0, 0];
   const secondPlace = second.position ? [second.position.line, second.position.column] : [0, 0];
@@ -573,14 +578,39 @@ function sameDiagnostic(first, second) {
   return JSON.stringify(first) === JSON.stringify(second);
 }
 
+function pointerSteps(pointer) {
+  return pointer.slice(1).split('/')
+    .map((step) => step.replaceAll('~1', '/').replaceAll('~0', '~'));
+}
+
+/** The value at a JSON pointer of `json`, `null` where it holds none. */
+function valueAt(json, pointer) {
+  if (pointer === '') return json;
+  let node = json;
+  for (const step of pointerSteps(pointer)) {
+    if (node === null || typeof node !== 'object' || !hasOwn(node, step)) return null;
+    node = node[step];
+  }
+  return node;
+}
+
+/** `json` with the value at a JSON pointer it holds replaced by `value`. */
+function withValueAt(json, pointer, value) {
+  if (pointer === '') return value;
+  const holder = valueAt(json, pointer.slice(0, pointer.lastIndexOf('/')));
+  if (holder !== null && typeof holder === 'object') holder[pointerSteps(pointer).at(-1)] = value;
+  return json;
+}
+
 /** The document as JSON, and where each of its values was written. */
 class InstanceRecord {
-  constructor(childValuePatterns) {
-    this.childValuePatterns = childValuePatterns;
+  constructor(rules) {
+    this.rules = rules;
     this.positions = new Map();
     this.valuePositions = new Map();
     this.numberTexts = new Map();
     this.unknown = [];
+    this.copied = [];
   }
 
   json(value, pointer, keyPosition) {
@@ -604,6 +634,7 @@ class InstanceRecord {
           if (isObject(json)) this.setChildValue(entry.key, json);
           object[entry.key] = json;
         }
+        this.mergeBaseKeys(object, pointer);
         return object;
       }
       default:
@@ -614,10 +645,30 @@ class InstanceRecord {
 
   /** A key such as `name mock-orders` sets the field `name` of the entry it keys, unless it writes the field. */
   setChildValue(key, fields) {
-    const found = childValue(key, this.childValuePatterns);
+    const found = this.rules.childValue(key);
     if (found !== null && !hasOwn(fields, found.field)) fields[found.field] = found.value;
   }
 
+  /** Merges the content of each merge base key `object` holds into each sibling map. */
+  mergeBaseKeys(object, pointer) {
+    const { mergeBaseKeys } = this.rules;
+    for (const baseKey of mergeBaseKeys.filter((key) => hasOwn(object, key))) {
+      const base = object[baseKey];
+      for (const [key, written] of Object.entries(object)) {
+        if (mergeBaseKeys.includes(key) || !isObject(written)) continue;
+        const entryPointer = `${pointer}/${escapePointer(key)}`;
+        const merged = mergedOver(base, written, entryPointer, (at) => this.isUnknown(at));
+        this.copied.push(...copiedPointers(merged, written, entryPointer));
+        object[key] = merged;
+      }
+    }
+  }
+
+  /** Whether `pointer` names a value a merge base key copied in, or one below it. */
+  isCopied(pointer) {
+    return this.copied.some((copied) => pointer === copied || pointer.startsWith(`${copied}/`));
+  }
+
   /**
    * Whether an error at `pointer` comes from a value not known when the document
    * compiles: the value itself, or a check that reads a value below it through a
@@ -658,35 +709,15 @@ class InstanceRecord {
     }
     return 'object';
   }
-
-  jsonText(value, pointer) {
-    return jsonText(value, (at) => (this.numberTexts.has(at) ? this.numberTexts.get(at) : null), pointer);
-  }
-}
-
-/**
- * The field a key such as `name mock-orders` sets on the entry it keys, and the
- * value it sets, `{ field, value }`, by the first of `patterns` with `field` and
- * `value` groups that matches; else `null`.
- */
-function childValue(key, patterns) {
-  for (const pattern of patterns) {
-    const match = pattern.exec(key);
-    const groups = match && match.groups;
-    if (groups && groups.field !== undefined && groups.value !== undefined) {
-      return { field: groups.field, value: groups.value };
-    }
-  }
-  return null;
 }
 
 module.exports = {
   LoadedSchema,
   SchemaCache,
+  ValidationRules,
   childValue,
   closestName,
   nodeJsonText,
   draftOfSchema,
   compareText,
-  debugText,
 };

package/lib/validation-rules.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/*
+ * How a document is read before it is validated: the DSL definition's
+ * `validator` block, ready to apply.
+ */
+
+const { compilePattern } = require('./pattern-dialect');
+const { numberJson } = require('./yaml-node');
+
+const INTEGER_TEXT = /^-?(0|[1-9][0-9]*)$/;
+const NUMBER_TEXT = /^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?$/;
+const QUOTED_VALUE_READERS = {
+  boolean: (text) => ({ true: true, false: false })[text],
+  integer: (text) => (INTEGER_TEXT.test(text) ? numberJson(text) : undefined),
+  number: (text) => (NUMBER_TEXT.test(text) ? numberJson(text) : undefined),
+};
+
+const hasOwn = (object, field) => Object.prototype.hasOwnProperty.call(object, field);
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** A DSL's `validator` block with its patterns compiled. */
+class ValidationRules {
+  constructor({ mergeBaseKeys = [], childValuePatterns = [], quotedValueTypes = [] } = {}) {
+    this.mergeBaseKeys = mergeBaseKeys;
+    this.childValuePatterns = childValuePatterns;
+    this.quotedValueTypes = quotedValueTypes;
+  }
+
+  /** The rules a DSL's `validator` block states, or throws a pattern that does not compile. */
+  static fromValidator(validator) {
+    if (!validator) return new ValidationRules();
+    const childValuePatterns = validator.child_values_from_parent_key.map((rule) => {
+      const compiled = compilePattern(rule.pattern);
+      if (compiled === null) throw new Error(`\`${rule.pattern}\` is not a pattern`);
+      return compiled;
+    });
+    return new ValidationRules({
+      mergeBaseKeys: [...validator.merge_base_keys],
+      childValuePatterns,
+      quotedValueTypes: [...validator.allow_quoted_values],
+    });
+  }
+
+  /** The field a key such as `name mock-orders` sets, `{ field, value }`; else `null`. */
+  childValue(key) {
+    return childValue(key, this.childValuePatterns);
+  }
+
+  /**
+   * The value a quoted `text` is validated as where the schema expects one of
+   * `expectedTypes`, in their order, `{ value }`; `null` where it reads as none.
+   */
+  quotedValue(text, expectedTypes) {
+    for (const expectedType of expectedTypes) {
+      const allowed = this.quotedValueTypes.includes(expectedType)
+        && hasOwn(QUOTED_VALUE_READERS, expectedType);
+      if (!allowed) continue;
+      const value = QUOTED_VALUE_READERS[expectedType](text);
+      if (value !== undefined) return { value };
+    }
+    return null;
+  }
+}
+
+/**
+ * The field a key such as `name mock-orders` sets on the entry it keys, and the
+ * value it sets, `{ field, value }`, by the first of `patterns` with `field` and
+ * `value` groups that matches; else `null`.
+ */
+function childValue(key, patterns) {
+  for (const pattern of patterns) {
+    const match = pattern.exec(key);
+    const groups = match && match.groups;
+    if (groups && groups.field !== undefined && groups.value !== undefined) {
+      return { field: groups.field, value: groups.value };
+    }
+  }
+  return null;
+}
+
+/**
+ * `overlay` merged over `base` as an overlay merges over its common layer: maps
+ * merge key by key, an empty map or any other value replaces, and a null deletes
+ * the key unless `holdsUnknown` says the null stands for a value not yet known.
+ */
+function mergedOver(base, overlay, overlayPointer, holdsUnknown) {
+  const merged = isObject(base) ? structuredClone(base) : {};
+  mergeInto(merged, overlay, overlayPointer, holdsUnknown);
+  return merged;
+}
+
+function mergeInto(target, overlay, overlayPointer, holdsUnknown) {
+  for (const [key, value] of Object.entries(overlay)) {
+    const childPointer = `${overlayPointer}/${escapePointer(key)}`;
+    if (value === null && !holdsUnknown(childPointer)) {
+      delete target[key];
+      continue;
+    }
+    if (isObject(target[key]) && isObject(value) && Object.keys(value).length > 0) {
+      mergeInto(target[key], value, childPointer, holdsUnknown);
+    } else {
+      target[key] = structuredClone(value);
+    }
+  }
+}
+
+/** The pointers of `merged` that `written` does not hold: the values a merge copied in. */
+function copiedPointers(merged, written, pointer) {
+  if (!isObject(merged) || !isObject(written)) return [];
+  return Object.entries(merged).flatMap(([key, value]) => {
+    const childPointer = `${pointer}/${escapePointer(key)}`;
+    return hasOwn(written, key)
+      ? copiedPointers(value, written[key], childPointer)
+      : [childPointer];
+  });
+}
+
+function escapePointer(key) {
+  return key.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+
+module.exports = { ValidationRules, childValue, mergedOver, copiedPointers, escapePointer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaml-dsl-spec",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "The YAML DSL standard: the JSON Schemas of yaml-dsl.yml and of a DSL's function table, and a reader returning a yaml-dsl.yml's DSL definitions validated.",
   "license": "MIT",
   "repository": {