SwiftData Expert

Fast, production-oriented guidance for building correct, performant SwiftData apps and fixing common crashes. Based on comprehensive SwiftData reference material (iOS 17+).

Agent behavior contract (follow these rules)

1. SwiftData requires iOS 17+ / macOS Sonoma / tvOS 17 / watchOS 10 / visionOS 1.0 minimum — confirm deployment target before advising.
2. All SwiftData models must be classes with the @Model macro — never structs.
3. Never pass model objects across actors — use PersistentIdentifier (the .id property) and ModelContainer (both are Sendable). ModelContext and model objects are not Sendable.
4. Prefer explicit relationships with @Relationship over inferred ones — explicit relationships are never regretted.
5. For many-to-many relationships, @Relationship(inverse:) is required — SwiftData will not infer them.
6. When CloudKit is enabled: no @Attribute(.unique), all properties need defaults or optionality, all relationships must be optional.
7. Always remind: deleteAllData() on ModelContainer does not actually delete data as of iOS 17 — use modelContext.delete(model:) for each model type instead.
8. Reference this skill’s references/ files for detailed code examples and patterns.

First 60 seconds (triage template)

• Clarify the goal: model definition, querying, relationships, migration, SwiftUI integration, iCloud sync, performance, testing, or error fix?
• Collect minimal facts:
  • platform + deployment target (iOS 17+?)
  • CloudKit enabled or local-only?
  • using SwiftUI directly or MVVM pattern?
  • exact error message + crash log if applicable
• Branch immediately:
  • crash / error → references/common-errors.md
  • model definition → references/model-definition.md
  • relationships → references/relationships.md
  • querying / filtering / sorting → references/querying.md
  • migration → references/migration.md
  • SwiftUI integration → references/swiftui-integration.md
  • concurrency / background work → references/concurrency.md
  • iCloud / CloudKit → references/cloudkit-sync.md
  • performance → references/performance.md
  • testing → references/testing.md

Routing map (pick the right reference fast)

• @Model, properties, attributes, Codable support → references/model-definition.md
• ModelContainer / ModelContext / ModelConfiguration → references/containers-context.md
• Relationships (1:1, 1:many, many:many, cascade deletes) → references/relationships.md
• @Query, #Predicate, FetchDescriptor, sorting → references/querying.md
• Lightweight & complex migrations, VersionedSchema → references/migration.md
• SwiftUI integration (@Query, @Bindable, previews, dynamic sort/filter) → references/swiftui-integration.md
• Background contexts, Swift Concurrency, batch inserts → references/concurrency.md
• iCloud / CloudKit sync, stopping sync → references/cloudkit-sync.md
• MVVM, singletons, pre-populating, discarding changes → references/architecture.md
• Performance optimization → references/performance.md
• Unit tests, UI tests → references/testing.md
• UIKit integration, widgets, document-based apps → references/platform-integration.md
• Common errors and solutions → references/common-errors.md
• Core Data migration / coexistence → references/core-data-coexistence.md

Core Data → SwiftData mapping (quick reference)

Common errors → next best move

• “Circular reference resolving attached macro ‘Relationship'” → remove @Relationship(inverse:) from one side
• “NSFetchRequest could not locate an NSEntityDescription” → model type missing from modelContainer(for:)
• “Set a .modelContext in view’s environment to use Query” → missing modelContainer() modifier on WindowGroup
• “A stored property cannot be named ‘description'” → rename property (reserved by Core Data internally)
• “Illegal attempt to establish a relationship between objects in different contexts” → don’t insert related objects separately; insert only the parent
• EXC_BAD_ACCESS near #Predicate → unsupported predicate operation (e.g., .contains() on [String] array)
• “Fatal error: Duplicate registration attempt” → inserting both sides of a relationship; remove one insert
• “validation recovery attempt FAILED … Code=1570 … is a required value” → non-optional relationship being set to nil; use .cascade delete rule or make property optional
• Autosave silently failing → check @Relationship min/max constraints; call save() manually to see error
• “I’m confused, how am I not moored…” → subclassing a model; mark classes final and don’t subclass

Verification checklist (when changing SwiftData code)

• All @Model types are classes (not structs).
• Model container includes all model types (or they’re reachable via relationships).
• Relationships with non-optional inverse use .cascade delete rule or explicit @Relationship(inverse:).
• Many-to-many relationships have explicit @Relationship(inverse:) on one side only.
• No model objects or ModelContext passed across actors — only PersistentIdentifier and ModelContainer.
• If CloudKit: no .unique, all defaults/optionals, all relationships optional.
• Predicates don’t use unsupported operations (e.g., contains() on [String], == false on .isEmpty).

Reference files

• references/model-definition.md
• references/containers-context.md
• references/relationships.md
• references/querying.md
• references/migration.md
• references/swiftui-integration.md
• references/concurrency.md
• references/cloudkit-sync.md
• references/architecture.md
• references/performance.md
• references/testing.md
• references/platform-integration.md
• references/common-errors.md
• references/core-data-coexistence.md