ng-form-foundry-transformers 0.5.0 → 0.5.2

package/README.md

@@ -155,6 +155,23 @@ enabled, so the output validates against the source schema (opt out with
 `schemaOptions: { optionalPresence: false }`); a required property mapping to a
 choice is marked `mandatory`.
 
+**The schema must agree with the document on container shapes.** A covered
+key whose schema says array where the document holds an object (or scalar
+where it holds a collection) makes `toSchema` throw a `SchemaShapeError`
+naming the path — such a form could not carry the section and saving would
+erase it. Catch it to fall back to inferred editing. Scalar-vs-scalar
+differences (a quoted `"0xe00"` under an `integer` schema) stay editable,
+and an integral edit writes back an integer literal.
+
+**The schema may cover any slice of the document.** Keys it does not mention
+are governed by `unknownKeys` (YAML, JSON, and libconfig alike):
+`'preserve'` (default) keeps them verbatim on save — a partial schema edits
+its fields without erasing the rest of a real-world config; `'drop'` deletes
+them — for an intentionally complete schema (sanitizing, template
+enforcement); `'edit'` surfaces them as editable fields typed by the
+document's own values, merged under the JSON Schema in document order, so
+nothing in the file is invisible.
+
 ## JSON transformer
 
 Same as YAML, for **JSON config files** — `jsonTransformer.toSchema(json, { schema? })`
@@ -292,6 +309,23 @@ npm test        # node:test on the compiled output (no Python needed)
 
 ## Status
 
+`0.5.2` — **shape safety and operator-friendly display**: a container-shape
+disagreement between document and schema (array declared where the document
+holds an object, or scalar where it holds a collection — inside choices
+included) throws a `SchemaShapeError` naming the path instead of producing
+an empty form whose save would erase the section; a type-changing integral
+edit writes an integer literal, never a float; and schema-driven fields
+display hex/octal/binary values in the base the document wrote them, in
+every `unknownKeys` mode. Adversarially proof-tested before release.
+
+`0.5.1` — **partial JSON Schemas edit safely**: the new `unknownKeys` option
+(YAML, JSON, libconfig) governs keys the schema does not cover — `'preserve'`
+(default) keeps them verbatim on save, `'drop'` deletes them for
+intentionally complete schemas, `'edit'` surfaces them as editable fields
+typed by the document's own values. The YAML binding is now
+`YamlBinding { doc, schema? }` instead of the bare parsed document (bindings
+are opaque; code that hands them straight back to `toSource` is unaffected).
+
 `0.5.0` — the **libconfig transformer is stable**: the one-time beta warning
 is gone (and with it the `resetLibconfigBetaWarning` helper), and the format's
 guarantees and known limitations are documented in the transformers guide.

package/dist/core/index.d.ts

@@ -14,3 +14,4 @@ export type { NodeGroup, NodeType, Leaf, LeafList, NodeGroupList, Choice, Choice
 export { CASE_KEY } from './schema';
 export type { Thesaurus, ThesaurusEntry } from './schema';
 export { applyThesaurus } from './thesaurus';
+export { SchemaShapeError } from './shape-check';

package/dist/core/index.js

@@ -7,7 +7,7 @@
  * map a JSON Schema) that any data-oriented transformer reuses.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyThesaurus = exports.CASE_KEY = exports.jsonSchemaToNodeGroup = exports.inferNodeGroup = exports.TransformerRegistry = void 0;
+exports.SchemaShapeError = exports.applyThesaurus = exports.CASE_KEY = exports.jsonSchemaToNodeGroup = exports.inferNodeGroup = exports.TransformerRegistry = void 0;
 var registry_1 = require("./registry");
 Object.defineProperty(exports, "TransformerRegistry", { enumerable: true, get: function () { return registry_1.TransformerRegistry; } });
 // Shared schema builders — used by the YAML and JSON transformers alike.
@@ -19,3 +19,5 @@ var schema_1 = require("./schema");
 Object.defineProperty(exports, "CASE_KEY", { enumerable: true, get: function () { return schema_1.CASE_KEY; } });
 var thesaurus_1 = require("./thesaurus");
 Object.defineProperty(exports, "applyThesaurus", { enumerable: true, get: function () { return thesaurus_1.applyThesaurus; } });
+var shape_check_1 = require("./shape-check");
+Object.defineProperty(exports, "SchemaShapeError", { enumerable: true, get: function () { return shape_check_1.SchemaShapeError; } });

package/dist/core/infer.d.ts

@@ -1,7 +1,8 @@
 import type { NodeGroup } from './schema';
 /**
- * Infer a root {@link NodeGroup} from a parsed data object when no schema is
- * given. Structure and types come from the values themselves:
+ * Infer a root {@link NodeGroup} from a parsed data object — the whole form
+ * when no JSON Schema is given, and the layer `mergeInferred` overlays under
+ * `unknownKeys: 'edit'`. Structure and types come from the values themselves:
  *
  *   - object            → nodeGroup (recursed)
  *   - array of objects  → nodeGroupList (item schema = union of the items' keys)

package/dist/core/infer.js

@@ -3,8 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.inferNodeGroup = inferNodeGroup;
 const ROOT = '__root__';
 /**
- * Infer a root {@link NodeGroup} from a parsed data object when no schema is
- * given. Structure and types come from the values themselves:
+ * Infer a root {@link NodeGroup} from a parsed data object — the whole form
+ * when no JSON Schema is given, and the layer `mergeInferred` overlays under
+ * `unknownKeys: 'edit'`. Structure and types come from the values themselves:
  *
  *   - object            → nodeGroup (recursed)
  *   - array of objects  → nodeGroupList (item schema = union of the items' keys)
@@ -21,7 +22,9 @@ function inferNodeGroup(data, name = ROOT) {
     return group;
 }
 function objectToNodeGroup(data, name) {
-    const children = {};
+    // Null prototype: data keys are arbitrary, and assigning a `__proto__` key
+    // onto a plain object would silently set the record's prototype instead.
+    const children = Object.create(null);
     for (const [key, value] of Object.entries(data)) {
         children[key] = inferNode(key, value);
     }
@@ -45,7 +48,7 @@ function inferArray(name, items) {
 }
 /** A representative object with every key seen across `items`, each mapped to the first non-null sample. */
 function unionKeys(items) {
-    const merged = {};
+    const merged = Object.create(null);
     for (const item of items) {
         for (const [key, value] of Object.entries(item)) {
             if (!(key in merged) || (merged[key] == null && value != null))

package/dist/core/merge-inferred.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Schema union for `unknownKeys: 'edit'`: overlay a user-supplied JSON
+ * Schema's {@link NodeGroup} onto the schema *inferred from the document
+ * itself*, so covered keys keep their typed, validated, labeled nodes while
+ * every key the JSON Schema does not mention still renders — editable, typed
+ * by inference (see `core/infer.ts` and the per-format inference in the
+ * transformers). Counterpart of `core/schema-keys.ts`, which handles the
+ * *preserve-invisibly* answer to the same question.
+ */
+import type { NodeGroup } from './schema';
+/**
+ * Merge per key, recursively. Document order wins for placement: the
+ * inferred children mirror the source document, so present keys render in
+ * file order with schema-only keys (e.g. presence-able additions) appended
+ * after, in schema order. Where both sides describe a key, the schema wins —
+ * except that groups and group-lists merge structurally, so a partially
+ * covered subtree keeps its uncovered fields at any depth. Group metadata
+ * (name, label, presence, bounds) comes from the schema side.
+ */
+export declare function mergeInferred(schema: NodeGroup, inferred: NodeGroup): NodeGroup;

package/dist/core/merge-inferred.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeInferred = mergeInferred;
+/**
+ * Merge per key, recursively. Document order wins for placement: the
+ * inferred children mirror the source document, so present keys render in
+ * file order with schema-only keys (e.g. presence-able additions) appended
+ * after, in schema order. Where both sides describe a key, the schema wins —
+ * except that groups and group-lists merge structurally, so a partially
+ * covered subtree keeps its uncovered fields at any depth. Group metadata
+ * (name, label, presence, bounds) comes from the schema side.
+ */
+function mergeInferred(schema, inferred) {
+    const children = Object.create(null);
+    for (const [name, inferredChild] of Object.entries(inferred.children)) {
+        const schemaChild = schema.children[name];
+        children[name] = schemaChild ? mergeNode(schemaChild, inferredChild) : inferredChild;
+    }
+    for (const [name, schemaChild] of Object.entries(schema.children)) {
+        if (!(name in children))
+            children[name] = schemaChild;
+    }
+    return { ...schema, children };
+}
+/**
+ * One key described by both sides: groups and group-lists merge recursively;
+ * everything else — leaves, choices, maps, and shape disagreements — takes
+ * the schema node, which is authoritative wherever it speaks. One inferred
+ * fact does carry over: a leaf's `radix` display hint, which only the
+ * document knows (JSON Schema has no radix vocabulary).
+ */
+function mergeNode(schema, inferred) {
+    if (schema.kind === 'nodeGroup' && inferred.kind === 'nodeGroup') {
+        return mergeInferred(schema, inferred);
+    }
+    if (schema.kind === 'nodeGroupList' && inferred.kind === 'nodeGroupList') {
+        return { ...schema, type: mergeInferred(schema.type, inferred.type) };
+    }
+    if ((schema.kind === 'leaf' || schema.kind === 'leafList') &&
+        schema.kind === inferred.kind &&
+        inferred.radix &&
+        !schema.radix) {
+        return { ...schema, radix: inferred.radix };
+    }
+    return schema;
+}

package/dist/core/schema-keys.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Schema-born key resolution for partial-schema reverts.
+ *
+ * A transformer given a JSON Schema builds its form from the produced
+ * {@link NodeGroup} — so `serializeForm` can only ever emit keys that schema
+ * describes. When the edited value is written back onto the original
+ * document, the value is authoritative for those **schema-born** paths only;
+ * every other key was never carried by the form and must be preserved.
+ * These helpers answer "which keys can the value legitimately speak for?" at
+ * each document level, mirroring the wire encoding of
+ * ng-form-foundry's `serializeForm`/`toWireValue`.
+ */
+import type { Choice, NodeGroup, NodeType } from './schema';
+/**
+ * The schema-born key set of one document level, as `name → child schema`
+ * for recursion. `undefined` means "no schema in play": every key is
+ * value-authoritative. A key absent from a defined map is not schema-born
+ * and must be preserved verbatim.
+ */
+export type SchemaKeys = Map<string, NodeType | undefined> | undefined;
+/**
+ * The keys `serializeForm` can emit for a schema node standing at a document
+ * object/group, with each key's schema for recursion. A nodeGroup
+ * contributes its children by key — a choice child included, since the wire
+ * value keeps a choice at its own key (`toWireValue` strips only the case
+ * discriminator). Standing at a choice, the keys are the union of every
+ * case's fields: the form only emits the active case, so the other cases'
+ * keys behave like any non-emitted schema key. A map is open-keyed — every
+ * key is schema-born and entries recurse with the map's value schema.
+ */
+export declare function childrenOf(node: NodeType): SchemaKeys;
+/** The per-item schema when `node` describes a list of groups, else undefined. */
+export declare function itemSchemaOf(node: NodeType | undefined): NodeGroup | undefined;
+/**
+ * A case body is a single node exactly when its `kind` is a *string* — a
+ * record body whose fields include one literally named `kind` (k8s-style
+ * schemas) holds a NodeType there, not a string. The `in` operator cannot
+ * tell the two apart.
+ */
+export declare function isSingleNodeBody(body: Choice['cases'][string]): body is NodeType;

package/dist/core/schema-keys.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.childrenOf = childrenOf;
+exports.itemSchemaOf = itemSchemaOf;
+exports.isSingleNodeBody = isSingleNodeBody;
+/**
+ * The keys `serializeForm` can emit for a schema node standing at a document
+ * object/group, with each key's schema for recursion. A nodeGroup
+ * contributes its children by key — a choice child included, since the wire
+ * value keeps a choice at its own key (`toWireValue` strips only the case
+ * discriminator). Standing at a choice, the keys are the union of every
+ * case's fields: the form only emits the active case, so the other cases'
+ * keys behave like any non-emitted schema key. A map is open-keyed — every
+ * key is schema-born and entries recurse with the map's value schema.
+ */
+function childrenOf(node) {
+    switch (node.kind) {
+        case 'nodeGroup':
+            return new Map(Object.entries(node.children));
+        case 'choice': {
+            const out = new Map();
+            for (const [name, field] of caseEntries(node))
+                out.set(name, field);
+            return out;
+        }
+        case 'map':
+            return new OpenKeys(node.value);
+        default:
+            return undefined; // leaf/leafList/list shapes carry no key semantics
+    }
+}
+/** The per-item schema when `node` describes a list of groups, else undefined. */
+function itemSchemaOf(node) {
+    return node?.kind === 'nodeGroupList' ? node.type : undefined;
+}
+/**
+ * A case body is a single node exactly when its `kind` is a *string* — a
+ * record body whose fields include one literally named `kind` (k8s-style
+ * schemas) holds a NodeType there, not a string. The `in` operator cannot
+ * tell the two apart.
+ */
+function isSingleNodeBody(body) {
+    return typeof body.kind === 'string';
+}
+/** Field name → schema across every case of a choice (leaf-bodied cases too). */
+function* caseEntries(choice) {
+    for (const body of Object.values(choice.cases)) {
+        if (isSingleNodeBody(body))
+            yield [body.name, body];
+        else
+            for (const [name, field] of Object.entries(body))
+                yield [name, field];
+    }
+}
+/** A `SchemaKeys` map matching every key — a map node's open dictionary. */
+class OpenKeys extends Map {
+    constructor(valueSchema) {
+        super();
+        this.valueSchema = valueSchema;
+    }
+    has(_key) {
+        return true;
+    }
+    get(_key) {
+        return this.valueSchema;
+    }
+}

package/dist/core/shape-check.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Container-shape validation between a parsed document and a user-supplied
+ * JSON Schema's {@link NodeGroup}.
+ *
+ * A schema that declares a section a list while the document holds a group
+ * (or scalar, or vice versa) produces a form that cannot carry the section's
+ * contents — the form builder coerces the unusable initial value to an empty
+ * control, the form looks valid, and a save erases the section. For config
+ * files that program live systems, that silent path is the worst failure
+ * mode, so schema-driven `toSchema` refuses up front: the consumer catches
+ * {@link SchemaShapeError} and falls back to inferred editing or fixes the
+ * schema. Scalar-vs-scalar differences are *not* errors — a quoted `"0xe00"`
+ * under an `integer` schema is a legitimate wild-file shape the form can
+ * carry and edit.
+ */
+import type { NodeGroup } from './schema';
+/** A document/schema container-shape disagreement, pointing at the key path. */
+export declare class SchemaShapeError extends Error {
+    /** Path of the offending key, e.g. `gNBs` or `cells[0].id`. */
+    readonly path: string;
+    /** What the document holds there. */
+    readonly found: 'object' | 'array' | 'scalar';
+    /** What the schema declares there. */
+    readonly expected: 'object' | 'array' | 'scalar';
+    constructor(
+    /** Path of the offending key, e.g. `gNBs` or `cells[0].id`. */
+    path: string, 
+    /** What the document holds there. */
+    found: 'object' | 'array' | 'scalar', 
+    /** What the schema declares there. */
+    expected: 'object' | 'array' | 'scalar');
+}
+/**
+ * Walk the extracted document value against the JSON-Schema-derived schema
+ * and throw {@link SchemaShapeError} on the first container-kind
+ * disagreement. Only schema-covered keys are checked (absent keys are
+ * presence, uncovered keys are inference's business, and inference always
+ * matches the document by construction).
+ */
+export declare function assertSchemaShapes(data: unknown, schema: NodeGroup): void;

package/dist/core/shape-check.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaShapeError = void 0;
+exports.assertSchemaShapes = assertSchemaShapes;
+const schema_keys_1 = require("./schema-keys");
+/** A document/schema container-shape disagreement, pointing at the key path. */
+class SchemaShapeError extends Error {
+    constructor(
+    /** Path of the offending key, e.g. `gNBs` or `cells[0].id`. */
+    path, 
+    /** What the document holds there. */
+    found, 
+    /** What the schema declares there. */
+    expected) {
+        super(`'${path}': the document holds ${article(found)} here, but the schema expects ` +
+            `${article(expected)} — the form cannot carry its contents, and saving would erase them. ` +
+            `Align the schema with the document, or leave this key out of the schema.`);
+        this.path = path;
+        this.found = found;
+        this.expected = expected;
+        this.name = 'SchemaShapeError';
+    }
+}
+exports.SchemaShapeError = SchemaShapeError;
+function article(shape) {
+    return shape === 'array' ? 'an array' : shape === 'object' ? 'an object' : 'a scalar';
+}
+/**
+ * Walk the extracted document value against the JSON-Schema-derived schema
+ * and throw {@link SchemaShapeError} on the first container-kind
+ * disagreement. Only schema-covered keys are checked (absent keys are
+ * presence, uncovered keys are inference's business, and inference always
+ * matches the document by construction).
+ */
+function assertSchemaShapes(data, schema) {
+    checkNode(data, schema, '');
+}
+function checkNode(value, node, path) {
+    // Absent is presence semantics; null is either a nullable leaf's value or
+    // the empty-container idiom (YAML `section:`) — nothing exists to erase.
+    if (value == null)
+        return;
+    switch (node.kind) {
+        case 'leaf':
+            // Any primitive is carryable (string carries, quoted ints). An *empty*
+            // collection is too: the libconfig empty-collection carry under a
+            // string leaf round-trips as a no-op — only content can be erased.
+            if (isRecord(value))
+                throw new SchemaShapeError(path, 'object', 'scalar');
+            if (Array.isArray(value) && value.length > 0)
+                throw new SchemaShapeError(path, 'array', 'scalar');
+            return;
+        case 'leafList':
+            if (!Array.isArray(value))
+                throw new SchemaShapeError(path, shapeOf(value), 'array');
+            value.forEach((item, i) => {
+                if (isRecord(item) || Array.isArray(item)) {
+                    throw new SchemaShapeError(`${path}[${i}]`, shapeOf(item), 'scalar');
+                }
+            });
+            return;
+        case 'nodeGroupList':
+            if (!Array.isArray(value))
+                throw new SchemaShapeError(path, shapeOf(value), 'array');
+            value.forEach((item, i) => {
+                if (!isRecord(item))
+                    throw new SchemaShapeError(`${path}[${i}]`, shapeOf(item), 'object');
+                checkChildren(item, node.type, `${path}[${i}]`);
+            });
+            return;
+        case 'nodeGroup':
+        case 'map':
+            if (!isRecord(value))
+                throw new SchemaShapeError(path, shapeOf(value), 'object');
+            checkChildren(value, node, path);
+            return;
+        case 'choice': {
+            // The document's shape must be one some case can carry: a record for
+            // record-bodied cases, an array for a collection-bodied case, a scalar
+            // for a leaf-bodied case. An array under object-only cases (or a
+            // record under scalar-only cases) is exactly the uncarryable-section
+            // erasure this check exists to refuse.
+            const allowed = caseShapes(node);
+            const found = shapeOf(value);
+            if (!allowed.has(found)) {
+                throw new SchemaShapeError(path, found, preferredShape(allowed));
+            }
+            if (isRecord(value))
+                checkChildren(value, node, path);
+            return;
+        }
+    }
+}
+/** The container shapes a choice's cases can carry, unioned across cases. */
+function caseShapes(choice) {
+    const shapes = new Set();
+    for (const body of Object.values(choice.cases)) {
+        if (!(0, schema_keys_1.isSingleNodeBody)(body)) {
+            shapes.add('object'); // a record of named fields
+            continue;
+        }
+        switch (body.kind) {
+            case 'nodeGroup':
+            case 'map':
+                shapes.add('object');
+                break;
+            case 'nodeGroupList':
+            case 'leafList':
+                shapes.add('array');
+                break;
+            case 'leaf':
+                shapes.add('scalar');
+                break;
+            case 'choice': // a nested choice's own cases are unknowable here: permissive
+                shapes.add('object').add('array').add('scalar');
+                break;
+        }
+    }
+    return shapes;
+}
+/** A single representative shape for the error message, objects first. */
+function preferredShape(allowed) {
+    if (allowed.has('object'))
+        return 'object';
+    if (allowed.has('array'))
+        return 'array';
+    return 'scalar';
+}
+/** Recurse a record's own keys through the node's schema-born children. */
+function checkChildren(record, node, path) {
+    const keys = (0, schema_keys_1.childrenOf)(node);
+    if (!keys)
+        return;
+    for (const key of Object.keys(record)) {
+        const child = keys.get(key);
+        if (child)
+            checkNode(record[key], child, path ? `${path}.${key}` : key);
+    }
+}
+function shapeOf(value) {
+    if (Array.isArray(value))
+        return 'array';
+    return isRecord(value) ? 'object' : 'scalar';
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/dist/transformers/json/index.d.ts

@@ -6,3 +6,4 @@
  */
 export { jsonTransformer } from './json-transformer';
 export type { JsonOptions, JsonFormat } from './json-transformer';
+export { SchemaShapeError } from '../../core/shape-check';

package/dist/transformers/json/index.js

@@ -6,6 +6,10 @@
  * schema builders in `core`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.jsonTransformer = void 0;
+exports.SchemaShapeError = exports.jsonTransformer = void 0;
 var json_transformer_1 = require("./json-transformer");
 Object.defineProperty(exports, "jsonTransformer", { enumerable: true, get: function () { return json_transformer_1.jsonTransformer; } });
+// Thrown by schema-driven toSchema; re-exported so subpath consumers can
+// catch it by instance.
+var shape_check_1 = require("../../core/shape-check");
+Object.defineProperty(exports, "SchemaShapeError", { enumerable: true, get: function () { return shape_check_1.SchemaShapeError; } });

package/dist/transformers/json/json-transformer.d.ts

@@ -1,4 +1,4 @@
-import type { FormValue, Thesaurus } from '../../core/schema';
+import type { FormValue, NodeGroup, Thesaurus } from '../../core/schema';
 import type { TransformResult } from '../../core/transformer';
 import { type JsonSchema, type JsonSchemaOptions } from '../../core/json-schema';
 /** Options for {@link jsonTransformer}'s `toSchema`. */
@@ -19,6 +19,18 @@ export interface JsonOptions {
      * case-insensitively; never paths.
      */
     thesaurus?: Thesaurus;
+    /**
+     * Schema-driven mode only: what happens to keys the JSON Schema does not
+     * cover. `'preserve'` (default) keeps them — the form never carried them,
+     * so a partial schema edits its slice without erasing the rest. `'drop'`
+     * makes the edited value authoritative for the whole document, deleting
+     * uncovered keys — for consumers whose schema is intentionally complete.
+     * `'edit'` surfaces them instead: uncovered keys render as editable fields
+     * typed by the data (the inferred schema merged under the JSON Schema), so
+     * nothing is invisible and the value covers the whole document. Ignored
+     * without a `schema`.
+     */
+    unknownKeys?: 'preserve' | 'drop' | 'edit';
 }
 /** How the source was formatted, so `toSource` re-emits it the same way. */
 export interface JsonFormat {
@@ -32,6 +44,19 @@ export interface JsonFormat {
      * them back as unquoted numbers so precision survives the round-trip.
      */
     bigInts: string[];
+    /**
+     * Present in schema-driven mode with `unknownKeys: 'preserve'` (the
+     * default) or `'edit'`: the original parsed data and the NodeGroup the
+     * form was built from (the JSON Schema's own under `'preserve'`, the
+     * inferred-merged one under `'edit'`). `toSource` then treats the value as
+     * authoritative for schema-born paths only and merges it over the
+     * original, so uncovered keys survive in their original key order — under
+     * `'edit'` that protection is left covering only the keys no form field
+     * can carry (e.g. a key inside a covered choice's object that no case
+     * names).
+     */
+    original?: FormValue;
+    schema?: NodeGroup;
 }
 /**
  * A JSON {@link Transformer}: turn a JSON config document into a form and write
@@ -39,12 +64,15 @@ export interface JsonFormat {
  * `core` builders the YAML transformer uses — only parsing (`JSON.parse`) and
  * serialization (`JSON.stringify`) are JSON-specific.
  *
- * Standard JSON has no comments, so revert re-serializes the edited value,
- * preserving the source's indent width and trailing newline. Key order follows
- * the form value (which follows the schema, derived from the original), so it is
- * preserved for untouched keys. For JSON **with comments** (JSONC), parse and
- * edit it as YAML with {@link import('../yaml/yaml-transformer').yamlTransformer}
- * instead — `JSON.parse` rejects comments.
+ * Standard JSON has no comments, so revert re-serializes, preserving the
+ * source's indent width and trailing newline. In schema-driven mode with
+ * `unknownKeys: 'preserve'` or `'edit'` the value is merged over the original
+ * data at schema-born paths ({@link mergeSchemaBorn}), so uncovered keys and
+ * the original key order survive; otherwise the edited value is serialized
+ * as-is, key order following the form value. For JSON **with comments**
+ * (JSONC), parse and edit it as YAML with
+ * {@link import('../yaml/yaml-transformer').yamlTransformer} instead —
+ * `JSON.parse` rejects comments.
  *
  * Integers beyond 2^53 can't survive a `number` round-trip, so they are carried
  * as strings in the form value and re-emitted verbatim as unquoted numbers (the