Rename a Field Without Orphaning Existing Data

A rename is a data migration, not a cosmetic refactor. The new name is the desired key and renameTo identifies the previous stored key.

Use renameTo and a safe default while documents migrate lazily to a new field name.

Use this when

• rename a field safely
• change a field name without losing data
• migrate an existing schema
• keep old documents working after a rename

Dyrected concepts

renameTo, defaultValue, schema evolution

Additional packages: No additional packages.

Complete recipe

This is the canonical source compiled and behavior-tested by @dyrected/knowledge.

import { defineCollection, defineTextField } from "@dyrected/core";

export const Customers = defineCollection({
  slug: "customers",
  fields: [
    defineTextField({
      name: "fullName",
      label: "Full name",
      renameTo: "name",
      defaultValue: "",
      required: true,
    }),
  ],
});

Migration sequence

1. Deploy code that can read the old key and write the new key.
2. Backfill or resave existing production documents.
3. Verify counts and representative values across both shapes.
4. Remove the fallback only after every active deployment and consumer accepts the new key.

Choose defaultValue carefully: a fallback can keep old documents renderable, but it can also hide a failed migration. Test actual adapter read/write behavior rather than only checking the configuration object.