SwiftData Expert Skill

Version: 1.0.0
Target: iOS 17+, macOS 14+, SwiftUI + SwiftData projects

Agent Behavior Contract

1. Triage first: Use 60-second assessment before diving into code
2. Route correctly: Match problem to appropriate section
3. Verify assumptions: Check model definitions, relationships, query syntax
4. Test incrementally: Validate each change with diagnostics
5. Document decisions: Explain why specific patterns were chosen
6. Handle errors gracefully: SwiftData fails silently - always verify saves
7. Respect constraints: CloudKit, relationships, and migrations have strict rules

First 60 Seconds Triage

When user reports SwiftData issue:

1. IDENTIFY SYMPTOM
   - Data not saving? → Check autosave, context, container setup
   - Crash on launch? → Model definition, relationship, migration issue
   - Query returns empty? → Predicate syntax, model registration
   - UI not updating? → @Query usage, observation, context
   - CloudKit sync failing? → Optional properties, unique constraints

2. LOCATE PROBLEM AREA
   - Models (01) → @Model, properties, initializers
   - Relationships (02) → @Relationship, delete rules, inverse
   - Queries (03) → @Query, #Predicate, FetchDescriptor
   - Context/Container (04) → ModelContext, ModelContainer, saves
   - SwiftUI Integration (05) → @Query, @Bindable, environment
   - Performance (06) → Batch operations, faulting, indexes
   - CloudKit (07) → Configuration, optional properties, sync

3. VERIFY BASICS
   - Is @Model applied to class?
   - Is modelContainer() in App struct?
   - Are relationships properly defined?
   - Is context being used correctly?
   - Are saves happening (autosave vs manual)?

Routing Map

Common Errors → Next Best Move

// ERROR: "Circular reference resolving attached macro 'Relationship'"
// FIX: Only define @Relationship on ONE side of relationship

// ERROR: "illegal attempt to establish a relationship"
// FIX: Insert objects BEFORE manipulating relationship arrays

// ERROR: "Too many items in %{PROPERTY}@"
// FIX: Check maximumModelCount constraint, reduce array size

// ERROR: "validation recovery attempt FAILED"
// FIX: Non-optional property set to nil via relationship - make optional

// ERROR: Silent save failure
// FIX: Check CloudKit requirements (optional properties, no unique)

// ERROR: Network data not inserting
// FIX: Use MainActor.run for modelContext.insert after URLSession

Quick Reference

Model Definition

import SwiftData

@Model
class User {
    var name: String
    var age: Int
    var email: String?
    
    init(name: String, age: Int, email: String? = nil) {
        self.name = name
        self.age = age
        self.email = email
    }
}

App Setup

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .modelContainer(for: User.self)
    }
}

Query in SwiftUI

struct ContentView: View {
    @Query(sort: \User.name) var users: [User]
    @Environment(\.modelContext) var modelContext
    
    var body: some View {
        List(users) { user in
            Text(user.name)
        }
    }
}

CRUD Operations

// Create
let user = User(name: "Alice", age: 30)
modelContext.insert(user)

// Update
user.name = "Alice Smith"

// Delete
modelContext.delete(user)

// Save (if autosave disabled)
try modelContext.save()

Detailed Guides

• 01-models-attributes.md - Model definitions, attributes, transformers
• 02-relationships.md - One-to-one, one-to-many, many-to-many, delete rules
• 03-queries-predicates.md - @Query, #Predicate, FetchDescriptor, sorting, filtering
• 04-context-saves.md - ModelContext, ModelContainer, autosave, manual saves, undo/redo
• 05-swiftui-integration.md - @Query, @Bindable, Observable objects, dynamic sorting/filtering
• 06-performance.md - Batch operations, concurrency, faulting, prefetching, indexes
• 07-cloudkit-sync.md - iCloud setup, requirements, troubleshooting
• 08-migrations.md - Schema changes, migration plans, versioning
• 09-testing-previews.md - In-memory containers, preview data, testing strategies
• 10-network-integration.md - URLSession, Codable, fetch/save, image handling, sync patterns

Critical Rules

1. Models must be classes - Structs not supported
2. @Model required - Apply to all persistent classes
3. Relationships need care - Use @Relationship for explicit control
4. CloudKit has strict rules - Optional properties, no unique constraints
5. Silent failures common - Always verify saves, check constraints
6. One container per app - Usually sufficient, shared via environment
7. Context = main actor - Default context is @MainActor safe
8. Migrations automatic - For simple changes, complex needs MigrationPlan

When to Use Each Pattern

Verification Checklist

Before marking task complete:

• Models have @Model macro
• App has modelContainer() modifier
• Relationships have proper delete rules
• Queries use correct predicate syntax
• Context is accessed via @Environment
• CloudKit requirements met (if syncing)
• Migrations defined (if schema changed)
• Previews use in-memory containers
• No silent save failures
• UI updates when data changes

Resources

• Apple SwiftData Documentation
• WWDC23 Session 10187: Meet SwiftData
• WWDC23 Session 10195: Build an app with SwiftData
• SwiftData by Example (Paul Hudson)
• Community articles (see individual section files)