Skip to content

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.

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.

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. reconcileFields builds a Map keyed by handle before it looks anything up: array order is never consulted.
  • Renaming a field’s label. The label is display-only; only handle is 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 in reconcileFields’s Step 1): existing pages simply pick it up empty.
  • Changing a field’s options, validation, description, adornment, or showWhen. 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 a select’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. reconcileSection copies templatePath fresh from the current SectionConfig on 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 in configFieldsByHandle, so reconcileFields’s Step 3 files the old value under lostValues[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 lostValues and stays recoverable. Re-adding the same handle later restores it automatically (Step 2 of reconcileFields reapplies 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.

  • Reconciliation: the concept-level overview this page assumes.
  • Reconciliation in depth: the full recursive-descent mechanics and the lostValues store.
  • 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.