SwiftData provides model-based persistence integrated with Swift and SwiftUI. A model declaration describes stored information, a container owns the schema and storage configuration, and a context tracks operations on model instances. These roles are distinct from JSON encoding and from a view's temporary State values.
Review the classes lesson and Codable lesson. This guide requires an Apple platform with SwiftData support, such as iOS 17 or macOS 14 and later, and a suitable Swift 5.9+ toolchain. It is not a portable Windows or Linux command-line persistence API.
Models describe persistent state
Apply the Model macro to a supported class declaration and define stored properties that fit SwiftData's supported schema types. An initializer establishes the model's valid starting state. The macro generates persistence-related behavior; it does not automatically decide every business validation or permission rule.
Relationships connect models and need a deliberate ownership and deletion policy. Deleting a parent can affect related data according to configured rules, so do not accept defaults blindly for valuable user records. Attribute options such as uniqueness also need conflict semantics; a duplicate identity should not be treated as a universally simple validation error.
Keep the model focused on persistent information. UI-only draft text and an in-flight loading indicator often belong outside the stored schema. A persistence model is a reference object managed through a context, which differs from an independent immutable DTO transferred between concurrency domains.
Container and context have different ownership
The container defines the schema and underlying configuration. A context tracks inserted, changed and deleted model instances against that container. Create these at a meaningful application boundary rather than recreate the production container inside every view body or button action.
SwiftUI can receive a model container through its environment integration, and Query can expose fetched models to a view under its supported contract. Those conveniences do not eliminate the need to understand context ownership or save failures. A view should not accidentally switch stores because it constructs a new container during an update.
Keep managed models and contexts within their appropriate isolation and concurrency design. Do not send a context or arbitrary model reference into a detached task as if it were an independent Sendable value. Use supported model-actor patterns or transfer stable identifiers and snapshots when work crosses ownership boundaries.
Save policy, errors and migrations matter
Context changes and a completed save are not the same event. An explicit save provides a clear failure boundary for operations that need confirmation. Framework autosave behavior can be useful in its intended context, but a product should not tell users that critical data is safely committed solely because an in-memory property changed.
Handle store creation and saving errors meaningfully. Do not erase a user's database automatically when opening fails, and do not replace every failed save with a silent success status. Preserve a recovery path and avoid logging personal model contents unnecessarily.
Persistent schemas outlive one app release. Adding, removing or changing stored fields can need a supported migration plan, versioned schemas and compatibility tests. An in-memory test proves current behavior but not migration from an older on-disk store. Keep representative old stores or fixtures and validate upgrades before shipping a schema change.
Query and identity rules should be explicit
FetchDescriptor combines the requested model type with predicates, sorting and limits where appropriate. A predicate expresses which models are needed; fetching everything and filtering in memory can waste work for large stores. Only use supported predicate expressions and test them on the actual deployment environment.
An application code such as PEN can be a domain identifier, but decide whether uniqueness is guaranteed and how conflicts are handled. This guide's small exercise inserts one known code and does not claim to implement distributed inventory consistency. A remote service can remain authoritative even when the app caches persistent local models.
Test empty results, updates, deletes, save failures and old-schema upgrades separately. Fresh in-memory containers help isolate tests from one another and from real user data. A deterministic sorted fetch is useful evidence; a successful screenshot of a view is not enough to establish persistence and migration correctness.
Official references
Apple's Meet SwiftData session explains the model-based approach. Read ModelContainer and ModelContext for ownership and operations. Review schema evolution, save confirmation, query ordering and concurrency separately before moving from an isolated example to a user's persistent database.
SwiftData Models and Persistence Boundaries Examples
Each example shows the code, the output it produces and what each part does.
Insert, save and fetch in memory
Run this as a macOS 14+ command-line target with SwiftData available. The in-memory configuration makes the example self-contained and avoids modifying an existing persistent store. MainActor makes the demonstration's context ownership explicit.
Sorting makes the expected order explicit. The program does not rely on an unspecified fetch order. Compile a standalone entry point with the appropriate macOS deployment target and parse-as-library handling if needed; a Windows Swift installation cannot supply Apple's SwiftData framework.
import Foundation
import SwiftData
@Model final class StockItem {
var code: String
var quantity: Int
init(code: String, quantity: Int) {
self.code = code
self.quantity = quantity
}
}
@main struct Demo {
@MainActor static func main() throws {
let configuration = ModelConfiguration(isStoredInMemoryOnly: true)
let container = try ModelContainer(for: StockItem.self, configurations: configuration)
let context = ModelContext(container)
context.insert(StockItem(code: "PEN", quantity: 3))
context.insert(StockItem(code: "BOOK", quantity: 2))
try context.save()
let request = FetchDescriptor<StockItem>(sortBy: [SortDescriptor(\StockItem.code)])
for item in try context.fetch(request) {
print("\(item.code):\(item.quantity)")
}
}
}BOOK:2
PEN:3SwiftData Models and Persistence Boundaries in Real Projects
Worked exercise: Update one known stock item
Create a fresh in-memory store, fetch the item by its code, validate a new nonnegative quantity, save and refetch. The operation is local persistence, not a transaction across remote clients.
import Foundation
import SwiftData
@Model final class Item {
var code: String
var quantity: Int
init(code: String, quantity: Int) { self.code = code; self.quantity = quantity }
}
enum UpdateError: Error { case missingItem, invalidQuantity }
@main struct Demo {
@MainActor static func main() throws {
let container = try ModelContainer(for: Item.self,
configurations: ModelConfiguration(isStoredInMemoryOnly: true))
let context = ModelContext(container)
context.insert(Item(code: "PEN", quantity: 3))
try context.save()
let request = FetchDescriptor<Item>(predicate: #Predicate { $0.code == "PEN" })
guard let item = try context.fetch(request).first else { throw UpdateError.missingItem }
let newQuantity = 5
guard newQuantity >= 0 else { throw UpdateError.invalidQuantity }
item.quantity = newQuantity
try context.save()
print(try context.fetch(request).first?.quantity ?? -1)
}
}5The fixture contains one matching record. A production operation must define what duplicates mean instead of arbitrarily choosing first. If saving fails, present a failure state and follow the context's supported recovery policy. Validate important invariants at the operation boundary even when the editable UI also checks them.
SwiftData Models and Persistence Boundaries FAQ
Is SwiftData the same as Codable JSON storage?
No. Codable describes conversion to and from representations, while SwiftData manages persistent models, contexts, querying and storage configuration. They can coexist for different boundaries: a network DTO can decode with Codable and map into local persistent models. Do not assume every managed model is an independent transport value or that JSON round-trip tests establish database behavior. Choose each tool from the representation, query and lifetime requirements it actually serves.
Why use an in-memory container for examples and tests?
It isolates the demonstration from real user files and gives each test a fresh store with controlled input. That makes insertion, fetch and update assertions reproducible. It does not prove on-disk durability or migration behavior, so add separate tests for those requirements. Keep the configuration explicit so a preview or test cannot accidentally open the production store, and avoid sharing one mutable test context among unrelated concurrent cases.
Can I pass ModelContext into any detached task?
Do not treat a managed context as an unrestricted Sendable value. Context and model ownership must follow SwiftData's supported concurrency patterns, including appropriate actor-based designs. Transfer stable identifiers or immutable snapshots when another domain only needs information. A detached task does not inherit the same isolation as ordinary actor-owned work, so moving a reference there can violate the intended ownership boundary. Review the actual framework contract before attempting concurrent persistence access.
Does changing a model property prove the data was saved?
No. A context can track an in-memory change before a successful persistence boundary. Autosave behavior can help in supported environments, but critical operations need an intentional save and error policy. Do not display an unconditional committed-success message before handling possible save failure. Tests should verify the needed persistence behavior through the appropriate store lifecycle, and migration tests must include older stored schemas rather than only fresh in-memory models.
SwiftData Models and Persistence Boundaries Exercises
Answer each one and check it instantly. If you get stuck, open the hint before the answer.
What additional evidence is needed after an in-memory current-schema test passes?
SwiftData Models and Persistence Boundaries Quiz
2 questions to check what you learned.
Which object establishes schema and storage configuration?
- A temporary TextField binding.
- ModelContainer.
- A formatted JSON string alone.
Why sort the main example's fetch?
- Every database returns insertion order permanently.
- Sorting encrypts the models.
- To make the result order an explicit contract for expected output.