SwiftData Expert Skill

Overview

Agent Behavior Contract (Follow These Rules)

1. Identify the minimum deployment target before recommending APIs (notably

   #Index

   ,

   #Unique

   ,

   HistoryDescriptor

   ,

   DataStore

   , inheritance examples).
2. Confirm the app has real

   ModelContainer

   wiring before debugging data issues; without it, inserts fail and fetches are empty.
3. Distinguish main-actor UI operations from background persistence operations; never assume one context fits both.
4. Treat schema changes as migration changes: evaluate lightweight migration first, then

   SchemaMigrationPlan

   when needed.
5. For CloudKit-enabled apps, verify schema compatibility constraints before proposing model changes.
6. Prefer deterministic query definitions (shared predicates, explicit sort order, bounded fetches) over ad hoc filtering in views.
7. Use persistent history tokens when reading cross-process changes; delete stale history to avoid storage growth.
8. In code reviews, prioritize data loss risk, accidental mass deletion, sync divergence, and context-isolation bugs over style changes.

Analysis Commands (Use Early)

• Search container setup:

  • rg "modelContainer\\(|ModelContainer\\(" -n

• Search model definitions:

  • rg "^@Model|#Unique|#Index|@Relationship|@Attribute|@Transient" -n

• Search context usage:

  • rg "modelContext|mainContext|ModelContext\\(" -n

• Search migrations and history:

  • rg "SchemaMigrationPlan|VersionedSchema|MigrationStage|fetchHistory|deleteHistory|historyToken" -n

• Search CloudKit and app groups:

  • rg "cloudKitDatabase|iCloud|CloudKit|groupContainer|AppGroup|NSPersistentCloudKitContainer" -n

Project Intake (Before Advising)

• Determine deployment targets: iOS, iPadOS, macOS, watchOS, and visionOS.
• Locate container setup:

  .modelContainer(...)

  modifier or manual

  ModelContainer(...)

  .
• Verify whether autosave is expected and whether explicit

  save()

  is required.
• Check if undo is enabled (

  isUndoEnabled

  ) and whether operations occur on

  mainContext

  or custom contexts.
• Check CloudKit capabilities and chosen container strategy (

  automatic

  ,

  .private(...)

  ,

  .none

  ).
• Check if app group storage is required.
• Check if Core Data coexistence is in scope.
• Check if schema changes must be backward-compatible with existing user data.

Workflow Decision Tree

1. Need a new model or schema shape:
   • Read

     references/modeling-and-schema.md

     .
2. Need create, update, delete behavior or context correctness:
   • Read

     references/model-context-and-lifecycle.md

     .
3. Need filtering, sorting, or dynamic list behavior:
   • Read

     references/querying-and-fetching.md

     .
4. Need relationship modeling or inheritance:
   • Read

     references/relationships-and-inheritance.md

     .
5. Need migration planning, release upgrades, or change tracking:
   • Read

     references/migrations-and-history.md

     .
6. Need iCloud sync or CloudKit compatibility:
   • Read

     references/cloudkit-sync.md

     .
7. Need incremental migration from Core Data:
   • Read

     references/core-data-adoption.md

     .
8. Need background isolation or actor-based persistence:
   • Read

     references/concurrency-and-actors.md

     .
9. Need quick diagnostics or API availability checks:
   • Read

     references/troubleshooting-and-updates.md

     .
10. Need end-to-end execution playbook for a concrete task:

• Read

  references/implementation-playbooks.md

  .

Triage-First Playbook (Common Problems -> Next Move)

• Insert fails or fetch is always empty:
  • Confirm

    .modelContainer(...)

    is attached at app or window root and the model type is included.
• Duplicate rows appear after network refresh:
  • Add

    @Attribute(.unique)

    or

    #Unique

    constraints and rely on insert-upsert behavior.
• Unexpected data loss during delete:
  • Audit delete rules (

    .cascade

    vs

    .nullify

    ) and check for unbounded

    delete(model:where:)

    .
• Undo or redo does nothing:
  • Ensure

    isUndoEnabled: true

    and that changes are saved via

    mainContext

    (not only background context).
• CloudKit sync not behaving:
  • Check capabilities, remote notifications, and CloudKit schema compatibility; explicitly set

    cloudKitDatabase

    if multiple containers exist.
• Widget or App Intent changes are not reflected:
  • Use persistent history (

    fetchHistory

    ) with token + author filtering.

• historyTokenExpired

  appears:
  • Reset local token strategy and rebootstrap change consumption from a safe point.
• Query results are expensive or unstable:
  • Use shared predicate builders, explicit sorting, and bounded

    FetchDescriptor

    settings.

Anti-Patterns (Reject by Default)

• Building persistence logic before validating container wiring.
• Performing broad deletes without predicate review and confirmation.
• Mixing UI-driven editing and background write pipelines without isolation boundaries.
• Relying on ad hoc in-memory filtering instead of store-backed predicates.
• Enabling CloudKit sync without capability setup and schema compatibility checks.
• Shipping schema changes without migration rehearsal on existing user data.
• Consuming history without token persistence and cleanup policy.

Core Patterns

App-level container wiring (SwiftUI)

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            RootView()
        }
        .modelContainer(for: [Trip.self, Accommodation.self])
    }
}

Manual container configuration

let config = ModelConfiguration(isStoredInMemoryOnly: false)
let container = try ModelContainer(
    for: Trip.self,
    Accommodation.self,
    configurations: config
)

Dynamic query setup in a view initializer

struct TripListView: View {
    @Query private var trips: [Trip]

    init(searchText: String) {
        let predicate = #Predicate<Trip> {
            searchText.isEmpty || $0.name.localizedStandardContains(searchText)
        }
        _trips = Query(filter: predicate, sort: \.startDate, order: .forward)
    }

    var body: some View { List(trips) { Text($0.name) } }
}

Safe batch delete pattern

do {
    try modelContext.delete(
        model: Trip.self,
        where: #Predicate { $0.endDate < .now },
        includeSubclasses: true
    )
    try modelContext.save()
} catch {
    // Handle delete and save failures.
}

Reference Files

• references/modeling-and-schema.md

• references/model-context-and-lifecycle.md

• references/querying-and-fetching.md

• references/relationships-and-inheritance.md

• references/migrations-and-history.md

• references/cloudkit-sync.md

• references/core-data-adoption.md

• references/concurrency-and-actors.md

• references/troubleshooting-and-updates.md

• references/implementation-playbooks.md

Best Practices Summary

1. Keep model code as the source of truth; avoid hidden schema assumptions.
2. Apply explicit uniqueness and indexing strategy for large or frequently queried datasets.
3. Insert root models and let SwiftData traverse relationship graphs automatically.
4. Keep query behavior deterministic with explicit predicates and sort descriptors.
5. Bound fetches (

   fetchLimit

   , offsets, identifier-only fetches) for scalability.
6. Treat delete rules as business rules; review them during schema changes.
7. Use

   ModelConfiguration

   for environment-specific behavior (in-memory tests, CloudKit, app groups, read-only stores).
8. Handle history as an operational system: token persistence, filtering, and cleanup.
9. Use model actors or isolated contexts for non-UI persistence work.
10. Gate recommendations by API availability and deployment target.

Verification Checklist (After Changes)

• Build succeeds for target platforms and minimum deployment versions.
• CRUD tests pass with real store and in-memory store.
• Relationship deletes behave as intended (

  cascade

  ,

  nullify

  , and others).
• Query behavior is stable with realistic datasets and sort or filter combinations.
• Migration path is validated on pre-existing data (not only clean installs).
• CloudKit behavior is validated in a development container before release.
• Cross-process changes (widgets, intents, extensions) are observed correctly.
• Error paths and rollback behavior are covered for destructive operations.

Response Contract

• For review tasks, report findings first by severity and include exact file paths and lines.
• For implementation tasks, describe:
  • container or context changes,
  • schema or migration changes,
  • query or performance changes,
  • verification steps run and any gaps.
• If deployment target blocks a recommended API, provide the best fallback compatible with the current target.