skip to content

For a SwiftData app about to ship its first release, would you declare a VersionedSchema and SchemaMigrationPlan from day one, or wait for the first change that needs them?

level: principalimportance: should knowfreq 30%

answer

  1. automatic migration covers additive edits
  2. retrofitting means copying the shipped shape
  3. frozen types are the cost
  4. a mismatched V1 is not recognized

basics

~20 s

Both work: automatic migration covers additive changes without a plan, and a later plan can adopt an unversioned store if its first VersionedSchema matches the shipped models exactly. Day-one versioning records that shape while it is certain, at the cost of frozen types.

solid answer

~50 s

SwiftData migrates additive changes without any plan, so waiting is viable, and a plan can be added later: declare V1 as an exact copy of the shipped models (same class names, stored properties, types, optionality and attribute options), then V2 and a stage. The risk is that copy. If V1 differs from what users' stores hold, the store matches no schema the container knows; apps linked against the iOS 27 SDK get `SwiftDataError.unknownDataStoreSchema`, earlier ones `loadIssueModelContainer`. Versioning from the first release captures the shape while it is known and makes every model change a visible new version in review, at the price of nested types, a typealias and frozen copies that never go away. My default: version from day one when the store holds data that exists only on the device; consider waiting when the store is a cache the app can rebuild.

go deeper

for a junior

Recall that SwiftData migrates simple additive changes on its own, and that a migration plan can be added later.

for a middle

Explain what retrofitting requires: a first VersionedSchema that matches the shipped models exactly, and what happens when it does not.

for a senior

Show how you would de-risk either path with stores from shipped builds opened in tests, and with review rules against editing shipped versions.

for a principal

Make the call from where the data lives and how fast the models change, state the boilerplate you accept for it, and turn it into a team rule.

## What SwiftData does without a plan A plan is optional. Apple's `ModelContainer` documentation says the container migrates persisted data automatically as the schema evolves, and that a `SchemaMigrationPlan` is how you take part when the changes exceed what automatic migration can do. In practice: - Adding an optional property, or one with a default, opens fine with no plan. - Removing a property, or renaming one with `@Attribute(originalName:)`, is also inferred. - A split field, a type change or a unique rule over duplicates needs a custom stage, and a custom stage needs a plan. So the question is not whether you will ever need a plan, but **when the team starts paying for one**. ## Adding a plan later Retrofitting a plan onto a shipped, unversioned app works, provided one step is done exactly: 1. Recreate the shipped models as `V1`: the same class names, stored property names, types, optionality and attribute options, nested in a `VersionedSchema`. 2. Declare `V2` with the change, and a stage between them. 3. Build the container with `ModelContainer(for:migrationPlan:configurations:)`. 4. Before release, open a store **produced by the shipped build** and check the data arrives. Step 1 is the risk. It is reconstructed from source history, often months later, by someone who may tidy a name or add a property along the way. If `V1` does not match what users' stores hold, the store matches neither the current schema nor any schema in the plan. Apple's iOS 27 documentation names the error for that case: **`SwiftDataError.unknownDataStoreSchema`**, thrown only for apps linked on or after iOS 27; earlier builds get **`loadIssueModelContainer`**. Either way the container does not open, on every upgraded device. ## Versioning from day one Declaring `V1` and a plan before the first release changes the economics: - **The shipped shape is recorded while it is certain**, in the same commit that ships it, not rebuilt later. - **Every model change is visibly a new version.** A diff that edits a frozen `V1` type is easy to catch in review. - **Custom stages are available at once**, with no retrofit release that must get the copy right. - **The cost is permanent boilerplate:** nested types per version, a typealias for the current one, and frozen copies of every shipped shape that the plan keeps. - **Tooling sees two names.** Code that uses the typealias reads naturally, while the debugger and error messages show the nested name, such as `TripSchemaV2.Trip`. | | Version from day one | Add the plan later | |---|---|---| | First-release effort | A little more | None | | Risk at the first breaking change | Low: V1 already exists | V1 must be reconstructed exactly | | Review signal | A changed frozen type stands out | Model edits look like any other edit | | Ongoing cost | Frozen types, typealias | Same, once the plan exists | ## How a lead decides The factors that move the decision: - **Where the data lives.** Notes, health entries or drafts that exist only on the phone cannot be lost to a mismatched retrofit; a cache the app can download again can. - **How fast the models will change.** A model still settling in its first months will hit a non-lightweight change soon, so the plan arrives anyway. - **The team's review discipline.** Day-one versioning only pays off if reviewers reject edits to shipped versions. - **Who will do the retrofit.** If the person who knows the shipped models may have moved on by the first breaking change, recording the shape now is cheaper than reconstructing it from history later. - **Upgrade testing.** Either way, keep stores produced by shipped builds and open them in tests; the wider strategy of how far back to support, and what to do when a migration fails, is a separate design decision covered with on-device migration strategy. ## A workable team rule A rule many teams can adopt: version from the first release when the store holds data users created on the device; otherwise ship unversioned, and add the plan the first time a change is not lightweight, with a test that opens a store from the last shipped build. In both cases a shipped `VersionedSchema` is never edited. The honest answer in an interview names the trade-off, not just the API: the plan is cheap insurance whose premium is boilerplate, and its value grows with how irreplaceable the data is.

  • How do you retrofit a SchemaMigrationPlan onto a SwiftData app that shipped without one?
    Recreate the shipped models as V1 exactly, with the same class names, stored property names, types, optionality and attribute options, nested in a `VersionedSchema`. Add V2 with the change and a stage between them, and build the container with the plan. Before release, open a store made by the shipped build: a V1 that differs is not recognized and the container throws.
  • Once SwiftData versioning is in place, what rule should a team enforce in review?
    A shipped `VersionedSchema` is never edited: any model change adds a version and a stage, and the reviewer checks whether that stage can be lightweight. Migration code names frozen types, not the typealias. Keep stores from shipped builds as test fixtures; how many old versions to support is a separate strategy decision.

  • Without a SchemaMigrationPlan, SwiftData cannot migrate a store at all.
  • A plan cannot be added after release; unversioned stores must be wiped.
  • A retrofitted V1 is a good moment to tidy up names in the models.
  • Versioning from day one costs nothing, so there is no decision to make.

Assumes the iOS 27 SDK: SwiftDataError.unknownDataStoreSchema is new in iOS 27; apps linked earlier get loadIssueModelContainer for the same mismatch.