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?
answer
- automatic migration covers additive edits
- retrofitting means copying the shipped shape
- frozen types are the cost
- a mismatched V1 is not recognized
basics
~20 sBoth 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 sSwiftData 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
Recall that SwiftData migrates simple additive changes on its own, and that a migration plan can be added later.
Explain what retrofitting requires: a first VersionedSchema that matches the shipped models exactly, and what happens when it does not.
Show how you would de-risk either path with stores from shipped builds opened in tests, and with review rules against editing shipped versions.
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.