Changing a section's config safely
Reconciliation runs on every mount, so most
config edits are safe automatically. But “safe” and “breaking” both have a
precise meaning, grounded in exactly how reconcileFields /
reconcileSections match saved data against config. This page is the
practical checklist; the deep mechanics live at Reconciliation in
depth.
The rule everything else follows
Section titled “The rule everything else follows”Matching is by handle, not by label or position. Every field,
sections/children array item, and tab in the stored data is looked up
against the config by its
handle string. Nothing else (not the field’s position in the fields:
array, not its label, not its options) participates in the match.
Safe edits
Section titled “Safe edits”These change how a field looks or is organised without touching its identity, so reconciliation matches saved values exactly as before:
- Reordering fields in a section’s
fields:list.reconcileFieldsbuilds aMapkeyed by handle before it looks anything up: array order is never consulted. - Renaming a field’s
label. The label is display-only; onlyhandleis the lookup key. - Adding a new field. On the next mount it gets its type’s default value
(
createEmptyValues’s per-type defaults, applied inline inreconcileFields’s Step 1): existing pages simply pick it up empty. - Changing a field’s
options,validation,description,adornment, orshowWhen. None of these participate in matching. One caveat worth knowing: reconciliation does not re-validate a stored value against a changed option set. If you narrow aselect’s options and a saved value no longer appears among them, that value is preserved as-is rather than cleared: it simply won’t highlight any option in the picker until the author changes it. - Changing
templatePath.reconcileSectioncopiestemplatePathfresh from the currentSectionConfigon every reconcile, so every existing instance of that section picks up the new path on its next mount: no separate migration step needed.
Breaking edits (recoverable, not destructive)
Section titled “Breaking edits (recoverable, not destructive)”Two edits break the handle match. Both are treated as data loss by the
field, but not by the system: the value moves to
lostValues, preserved rather than dropped:
- Changing a field’s
handle. The old handle no longer matches anything inconfigFieldsByHandle, soreconcileFields’s Step 3 files the old value underlostValues[oldHandle]. The new handle (being new to the config) gets a fresh default, same as any newly-added field. - Removing a field. Identical mechanism: no new handle appears to
claim the old value, so it lands in
lostValuesand stays recoverable. Re-adding the same handle later restores it automatically (Step 2 ofreconcileFieldsreapplies any lost value whose key now matches an empty field in the config).
If you’re deliberately renaming a handle and want the old value to land
directly under the new one, rather than round-tripping through
lostValues and a manual re-entry, that’s what an explicit migration rule
is for. See Per-section migration rules.
One case reconciliation does not safety-net: changing a field’s type
Section titled “One case reconciliation does not safety-net: changing a field’s type”Keeping the same handle but changing type is not caught by the
handle-rename/removal path above: the value stays under the same key, and
reconcileFields dispatches purely on the new type’s category
(COMPOUND_OBJECT_TYPES, COMPOUND_ARRAY_TYPES, isMultiValueField, or
the scalar fallback). A scalar-to-scalar change (e.g. text → select)
carries the old string through untouched: harmless, if possibly
meaningless against the new options. A shape change (e.g. a compound type
like link → a scalar type like text) carries the old object through
into values[handle] verbatim, because the scalar fallback branch is just
currentValue ?? '': no type coercion happens. Treat a type change on
an existing handle the same as a rename: expect the old value to need
manual attention, and prefer adding a new field over repurposing an old
handle’s type when the stored shape actually changes.
sections / children fields resolving to nothing
Section titled “sections / children fields resolving to nothing”If a sections or children field’s resolved section list is empty (a
misconfigured reference, an unwired global.yaml, a YAML typo), the loaded
array is preserved as-is, not cleared to []. The field can’t render a
picker without a resolvable config, but the underlying content is not
destroyed while you fix the reference.
Where to go next
Section titled “Where to go next”- Reconciliation: the concept-level overview this page assumes.
- Reconciliation in depth:
the full recursive-descent mechanics and the
lostValuesstore. - Lost values: what an author sees and can do once a value has been orphaned.
- Per-section migration rules: the
explicit alternative when you want an old value to land directly at its
new handle instead of round-tripping through
lostValues.