Per-section migration rules
Reconciliation resolves shape: it makes sure every current config field
has a value. Migrations resolve content: they explicitly move or delete
values when you rename a handle, restructure a tab, or retire a field, so an
old value lands directly at its new address instead of sitting in
lostValues waiting for someone to
re-enter it by hand. See Changing a section’s config
safely for when you’d reach for
one over the other.
Where a migration rule lives
Section titled “Where a migration rule lives”Both SectionConfig and PostTypeConfig accept an optional migrations:
array (MigrationRule). Each entry is one of two shapes:
migrations: - from: oldHeading to: heading - from: legacyField delete: true{ from, to }: move the value atfromtoto.{ from, delete: true }: remove the value atfromentirely.
from and to are dotted paths (below), not bare handles: a rule can
target a field nested inside tabs, not only a section’s top-level fields.
The dotted-path scheme
Section titled “The dotted-path scheme”The dotted-path scheme converts between the Path array all state
operations use ((string | number)[], alternating string handles and
numeric array indices) and the dotted-string form a migration rule writes:
pathToDotted(path)joins every segment with.:['tabs', 'seo', 'meta_title']becomes"tabs.seo.meta_title". Numeric segments serialise as their string form.dottedToPath(s)parses back the other way: a segment matching/^(0|[1-9]\d*)$/is coerced to a number (an array index), everything else stays a string (a handle). A leading or trailing.throws.
No escaping is needed because the handle pattern
(^[a-zA-Z_][a-zA-Z0-9_-]*$) reserves . from handle names: a single
path segment can never itself contain a literal dot.
How valid destination paths are enumerated
Section titled “How valid destination paths are enumerated”getPathOptions(config) walks a SectionConfig / PostTypeConfig /
PageTypeConfig’s fields tree and returns every valid dotted path an
author could target:
- Array-shaped fields are skipped entirely:
repeater,sections, andchildrenare forbidden migration destinations, and nothing beneath them is walked either. A migration rule cannot target a value that lives inside a repeated or nested-section structure. tabsis the only field type that recurses. Eachtabinside atabsfield’sfieldsarray is walked with the path extended by[tabsHandle, tabHandle], so a field inside a tab produces a path liketabs.seo.meta_title.- Everything else is a leaf: its own handle is appended to the current
path and emitted as one
PathOption.
This is the same enumeration the migration-path
field type surfaces as a destination picker wherever an author configures a
migration rule visually rather than by hand-editing YAML: it is a
config-side field whose value is itself one of these dotted paths.
Migration runs after reconciliation, per instance
Section titled “Migration runs after reconciliation, per instance”migrateAfterReconcile(values, lostValues, fieldConfigs, migrations, sectionPath) applies a section or post type’s
migrations: array in order, against already-reconciled values /
lostValues for one section instance:
- For each rule, the source value is looked up first in
lostValues(both the flat dotted-key form reconciliation produces for orphaned tabs-nested fields, and nested-object traversal for legacy shapes), then invalues. A missing source is not a failure: it’s the common case once a migration has already run once. - A
{ from, to }rule validates the destination: the target field must resolve infieldConfigs, and it must not be one of the array-shaped types (repeater,sections,children), the same setgetPathOptionsforbids as destinations. An unresolvable or array-typed destination is recorded as a migration failure rather than applied silently. - On success, the value is written to the destination path and removed
from wherever it was found. A
{ from, delete: true }rule just removes it.
It descends the tree the same way reconciliation does
Section titled “It descends the tree the same way reconciliation does”Neither SectionConfig.migrations nor PostTypeConfig.migrations applies
only at the top level. migrateFieldsLevel mirrors reconcileFields’ own
recursive descent through sections / children / tabs wrappers, and invokes
migrateAfterReconcile at every section-instance boundary whose
SectionConfig carries a non-empty migrations array: not a flat
top-level list. A section three levels deep inside a tabbed layout runs its
own migrations exactly as a root-level section would; there is no
enumerable “list of places migrations apply” any more than there is for
reconciliation itself. See Reconciliation in
depth for the descent this
mirrors.
Where to go next
Section titled “Where to go next”- Reconciliation in depth: the descent contract migrations mirror.
- Mass Migration: running these same rules across every existing instance of a section at once, rather than waiting for each page to be reconciled on its own next edit.
- Field-types catalogue: the
migration-pathfield type’s entry.