Versioning and Migrating Saved Draft Schemas

Drafts outlive deployments: a user starts a form on Monday, you ship a release on Tuesday that renames phone to phoneNumber, and on Wednesday their restored draft silently drops the phone number — or crashes the form because a field that is now an array was saved as a string.

Draft persistence and autosave treats a stored draft as data about the user’s intent. Like any persisted data it has a schema, and the schema changes. This page applies the discipline of database migrations to client-side drafts: version every record, migrate step by step on read, validate the result, and fail safe.

Context and prerequisites

Form changes that break old drafts are routine:

Renames — phone becomes phoneNumber.
Splits and merges — name becomes firstName and lastName.
Type changes — a single tag string becomes a tags array; a free-text country becomes an ISO code.
Removed fields — the “fax” field is gone.
New required fields — the old draft simply lacks them; that is normal and not a migration problem.

Without a version stamp you can only guess which shape a stored draft has. With one, restore becomes deterministic: read the version, apply every migration from that version up to the current one in order, then validate against the current schema before the values reach the form.

The core pattern: ordered migrations with a validation gate

import { z } from "zod";

export const CURRENT_VERSION = 3;

type Json = Record<string, unknown>;
type Migration = (draft: Json) => Json;

// migrations[n] upgrades a draft FROM version n TO version n + 1.
// Never edit a migration after it has shipped: drafts in the wild depend on it.
const migrations: Record<number, Migration> = {
  1: ({ phone, ...rest }) => ({ ...rest, phoneNumber: phone }),
  2: ({ name, ...rest }) => {
    const full = typeof name === "string" ? name.trim() : "";
    const cut = full.lastIndexOf(" ");
    return cut === -1
      ? { ...rest, firstName: full, lastName: "" }
      : { ...rest, firstName: full.slice(0, cut), lastName: full.slice(cut + 1) };
  },
};

// The CURRENT shape, all optional: a draft is by definition incomplete.
const DraftSchema = z.object({
  firstName: z.string(),
  lastName: z.string(),
  phoneNumber: z.string(),
  email: z.string(),
}).partial().strip();   // strip() drops keys from removed fields

export type Draft = z.infer<typeof DraftSchema>;

export type RestoreResult =
  | { ok: true; values: Draft; migratedFrom: number }
  | { ok: false; reason: "future-version" | "migration-failed" | "invalid" };

export function restoreDraft(stored: { schemaVersion?: number; values: Json }): RestoreResult {
  // Drafts saved before versioning existed are treated as version 1.
  const from = stored.schemaVersion ?? 1;
  if (from > CURRENT_VERSION) return { ok: false, reason: "future-version" }; // rolled-back deploy

  let values = stored.values;
  try {
    for (let v = from; v < CURRENT_VERSION; v++) {
      const step = migrations[v];
      if (!step) throw new Error(`missing migration ${v}→${v + 1}`);
      values = step(values);
    }
  } catch {
    return { ok: false, reason: "migration-failed" };
  }
  const parsed = DraftSchema.safeParse(values);
  return parsed.success
    ? { ok: true, values: parsed.data, migratedFrom: from }
    : { ok: false, reason: "invalid" };
}

Saving always writes schemaVersion: CURRENT_VERSION, so a draft migrated on restore is stored in the new shape at the next autosave and never migrated again.

Step-by-step walkthrough

Stamp every stored draft with schemaVersion. Treat unstamped legacy drafts as version 1 so the first release that adds versioning can still read them.
Write one migration per version step. Each is a pure function from the old shape to the next. Chaining small steps is far easier to review and test than one function that knows every historical shape.
Never edit a shipped migration. Fix a mistake with a new migration. A draft saved at version 2 must go through exactly the code that produced version 3 for everyone else.
Validate the migrated result against a partial schema. Use the same schema you use for step or draft validation — see partial Zod schemas for drafts and wizard steps — with unknown keys stripped.
Fail safe and say so. If the version is from the future, a migration throws, or validation fails, do not load a half-migrated draft. Keep the stored copy, start a fresh form, and tell the user their earlier draft could not be restored.
Re-save in the current version. The next autosave writes the migrated values with the new version stamp.

Failure modes and edge cases

1. Rollbacks

If you roll back a release, the older code finds drafts stamped with a version it has never heard of. It must not attempt to read them as its own version. Returning future-version and leaving the draft untouched means that when the fix is redeployed, the draft is still there.

2. Migrations that lose information

Splitting a full name on the last space mangles “Jean de la Fontaine”. When a migration cannot be exact, prefer putting the whole value in the first field and flagging the draft for review, and let the restored form show an info message on those fields asking the user to check them.

3. Changed option lists

A select whose options changed — a plan called “pro” is now “professional”, or was retired — needs a mapping migration. For retired values, drop the field so it validates as missing and the user chooses again, rather than loading a value the select cannot display.

4. Drafts containing files

Migrations run on the values object; File entries pass through untouched as long as migrations spread the rest of the object rather than rebuilding it from a list of known keys. See storing large drafts in IndexedDB.

5. Testing migrations

Keep a fixture of a real stored draft for every historical version and assert that each restores to the expected current shape. Those fixtures are the only way a future refactor of the migration table cannot quietly break old drafts.

Verification checklist

Every saved draft carries schemaVersion.
A fixture draft from each historical version restores to the correct current shape in tests.
A draft with a version higher than the code is left in storage and not loaded.
A migration that throws results in a fresh form, a visible notice, and the stored draft kept.
Keys for removed fields are stripped before values reach the form.
Restored drafts are re-saved with the current version on the next autosave.
File attachments survive every migration step.
Fields whose values were changed by a lossy migration show a “please check” note.

Frequently Asked Questions

Can I just discard drafts whenever the form changes?

You can, and for low-value forms that is reasonable — bump a key prefix and old drafts are ignored. For anything a user spends more than a minute on, discarding their work because you renamed a field is a poor trade when a migration is a few lines.

How is this different from server-side database migrations?

The logic is the same, but client migrations run lazily, on each device, whenever an old draft is read — possibly months later. That is why they must be pure, ordered and never edited after shipping, and why a failed migration must leave the original intact.

Where should the schema version number come from?

A hand-maintained integer next to the migrations table, incremented in the same commit as the migration. Do not derive it from the app version or a build hash; those change on every release, while the draft shape changes rarely.

← Draft Persistence and Autosave