Skip to content

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.

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 at from to to.
  • { from, delete: true }: remove the value at from entirely.

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 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, and children are 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.
  • tabs is the only field type that recurses. Each tab inside a tabs field’s fields array is walked with the path extended by [tabsHandle, tabHandle], so a field inside a tab produces a path like tabs.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:

  1. 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 in values. A missing source is not a failure: it’s the common case once a migration has already run once.
  2. A { from, to } rule validates the destination: the target field must resolve in fieldConfigs, and it must not be one of the array-shaped types (repeater, sections, children), the same set getPathOptions forbids as destinations. An unresolvable or array-typed destination is recorded as a migration failure rather than applied silently.
  3. 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.

  • 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-path field type’s entry.