swift-data

SwiftData Best Practices — Modular MVVM-C Data Layer Comprehensive data modeling, persistence, sync architecture, and error handling guide for SwiftData aligned with the clinic modular MVVM-C stack. Architecture Alignment This skill enforces the same modular architecture mandated by swift-ui-architect : ┌───────────────────────────────────────────────────────────────┐ │ Feature modules: View + ViewModel, no SwiftData imports │ ├───────────────────────────────────────────────────────────────┤ │ Domain: models + repository/coordinator/error protocols │ ├───────────────────────────────────────────────────────────────┤ │ Data: @Model entities, SwiftData stores, repository impls, │ │ remote clients, retry executor, sync queue, conflict handling │ └───────────────────────────────────────────────────────────────┘ Key principle: SwiftData types ( @Model , ModelContext , @Query , FetchDescriptor ) live in Data-only implementation code. Feature Views/ViewModels work with Domain types and protocol dependencies. Clinic Architecture Contract (iOS 26 / Swift 6.2) All guidance in this skill assumes the clinic modular MVVM-C architecture: Feature modules import Domain + DesignSystem only (never Data , never sibling features) App target is the convergence point and owns DependencyContainer , concrete coordinators, and Route Shell wiring Domain stays pure Swift and defines models plus repository, Coordinating , ErrorRouting , and AppError contracts Data owns SwiftData/network/sync/retry/background I/O and implements Domain protocols Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes ViewModels call repository protocols directly (no default use-case/interactor layer) When to Apply Reference these guidelines when: Defining @Model entity classes and mapping them to domain structs Setting up ModelContainer and ModelContext in the Data layer Implementing repository protocols backed by SwiftData Writing stale-while-revalidate repository reads ( AsyncStream ) Implementing optimistic writes plus queued sync operations Configuring entity relationships (one-to-many, inverse) Fetching from APIs and persisting to SwiftData via sync coordinators Handling save failures, corrupt stores, and migration errors Routing AppError traits to centralized error UI infrastructure Building preview infrastructure with sample data Planning schema migrations for app updates Workflow Use this workflow when designing or refactoring a SwiftData-backed feature: Domain design: define domain structs ( Trip , Friend ) with validation/computed rules (see model-domain-mapping , state-business-logic-placement ) Entity design: define @Model entity classes with mapping methods (see model- , model-domain-mapping ) Repository protocol: define in Domain layer, implement with SwiftData in Data layer (see persist-repository-wrapper ) Container wiring: configure ModelContainer once at the app boundary with error recovery (see persist-container-setup , persist-container-error-recovery ) Dependency injection: inject repository protocols via @Environment (see state-dependency-injection ) ViewModel: create @Observable ViewModel that delegates directly to repository protocols (see state-query-vs-viewmodel ) CRUD flows: route all insert/delete/update through ViewModel -> Repository (see crud- ) Sync architecture: queue writes, execute via sync coordinator with retry policy (see sync- ) Relationships: model to-many relationships as arrays; define delete rules (see rel- ) Previews: create in-memory containers and sample data for fast iteration (see preview- ) Schema evolution: plan migrations with versioned schemas (see schema-* ) Troubleshooting Data not persisting -> persist-model-macro , persist-container-setup , persist-autosave , schema-configuration List not updating after background import -> query-background-refresh , persist-model-actor List not updating (same-context) -> query-property-wrapper , state-wrapper-views Duplicates from API sync -> schema-unique-attributes , sync-conflict-resolution App crashes on launch after model change -> schema-migration-recovery , persist-container-error-recovery Save failures silently losing data -> crud-save-error-handling Stale data from network -> sync-offline-first , sync-fetch-persist Widget/extension can't see data -> persist-app-group , schema-configuration Choosing architecture pattern for data views -> state-query-vs-viewmodel , persist-repository-wrapper Rule Categories by Priority Priority Category Impact Prefix 1 Data Modeling CRITICAL model- 2 Persistence Setup CRITICAL persist- 3 Querying & Filtering HIGH query- 4 CRUD Operations HIGH crud- 5 Sync & Networking HIGH sync- 6 Relationships MEDIUM-HIGH rel- 7 SwiftUI State Flow MEDIUM-HIGH state- 8 Schema & Migration MEDIUM-HIGH schema- 9 Sample Data & Previews MEDIUM preview- Quick Reference 1. Data Modeling (CRITICAL) model-domain-mapping - Map @Model entities to domain structs across Domain/Data boundaries model-custom-types - Use custom types over parallel arrays model-class-for-persistence - Use classes for SwiftData entity types model-identifiable - Conform entities to Identifiable with UUID model-initializer - Provide custom initializers for entity classes model-computed-properties - Use computed properties for derived data model-defaults - Provide sensible default values for entity properties model-transient - Mark non-persistent properties with @Transient model-external-storage - Use external storage for large binary data 2. Persistence Setup (CRITICAL) persist-repository-wrapper - Wrap SwiftData behind Domain repository protocols persist-model-macro - Apply @Model macro to all persistent types persist-container-setup - Configure ModelContainer at the App level persist-container-error-recovery - Handle ModelContainer creation failure with store recovery persist-context-environment - Access ModelContext via @Environment (Data layer) persist-autosave - Enable autosave for manually created contexts persist-enumerate-batch - Use ModelContext.enumerate for large traversals persist-in-memory-config - Use in-memory configuration for tests and previews persist-app-group - Use App Groups for shared data storage persist-model-actor - Use @ModelActor for background SwiftData work persist-identifier-transfer - Pass PersistentIdentifier across actors 3. Querying & Filtering (HIGH) query-property-wrapper - Use @Query for declarative data fetching (Data layer) query-background-refresh - Force view refresh after background context inserts query-sort-descriptors - Apply sort descriptors to @Query query-predicates - Use #Predicate for type-safe filtering query-dynamic-init - Use custom view initializers for dynamic queries query-fetch-descriptor - Use FetchDescriptor outside SwiftUI views query-fetch-tuning - Tune FetchDescriptor paging and pending-change behavior query-localized-search - Use localizedStandardContains for search query-expression - Use #Expression for reusable predicate components (iOS 18+) 4. CRUD Operations (HIGH) crud-insert-context - Insert models via repository implementations crud-delete-indexset - Delete via repository with IndexSet from onDelete crud-sheet-creation - Use sheets for focused data creation via ViewModel crud-cancel-delete - Avoid orphaned records by persisting only on save crud-undo-cancel - Enable undo and use it to cancel edits crud-edit-button - Provide EditButton for list management crud-dismiss-save - Dismiss modal after ViewModel save completes crud-save-error-handling - Handle repository save failures with user feedback 5. Sync & Networking (HIGH) sync-fetch-persist - Use injected sync services to fetch and persist API data sync-offline-first - Design offline-first architecture with repository reads and background sync sync-conflict-resolution - Implement conflict resolution for bidirectional sync 6. Relationships (MEDIUM-HIGH) rel-optional-single - Use optionals for optional relationships rel-array-many - Use arrays for one-to-many relationships rel-inverse-auto - Rely on SwiftData automatic inverse maintenance rel-delete-rules - Configure cascade delete rules for owned relationships rel-explicit-sort - Sort relationship arrays explicitly 7. SwiftUI State Flow (MEDIUM-HIGH) state-query-vs-viewmodel - Route all data access through @Observable ViewModels state-business-logic-placement - Place business logic in domain value types and repository-backed ViewModels state-dependency-injection - Inject repository protocols via @Environment state-bindable - Use @Bindable for two-way model binding state-local-state - Use @State for view-local transient data state-wrapper-views - Extract wrapper views for dynamic query state 8. Schema & Migration (MEDIUM-HIGH) schema-define-all-types - Define schema with all model types schema-unique-attributes - Use @Attribute(.unique) for natural keys schema-unique-macro - Use #Unique for compound uniqueness (iOS 18+) schema-index - Use #Index for hot predicates and sorts (iOS 18+) schema-migration-plan - Plan migrations before changing models schema-migration-recovery - Plan migration recovery for schema changes schema-configuration - Customize storage with ModelConfiguration 9. Sample Data & Previews (MEDIUM) preview-sample-singleton - Create a SampleData singleton for previews preview-in-memory - Use in-memory containers for preview isolation preview-static-data - Define static sample data on model types preview-main-actor - Annotate SampleData with @MainActor How to Use Read individual reference files for detailed explanations and code examples: Section definitions - Category structure and impact levels Rule template - Template for adding new rules Reference Files File Description references/_sections.md Category definitions and ordering assets/templates/_template.md Template for new rules metadata.json Version and reference information