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:

1. Domain design: define domain structs (Trip, Friend) with validation/computed rules (see model-domain-mapping, state-business-logic-placement)
2. Entity design: define @Model entity classes with mapping methods (see model-*, model-domain-mapping)
3. Repository protocol: define in Domain layer, implement with SwiftData in Data layer (see persist-repository-wrapper)
4. Container wiring: configure ModelContainer once at the app boundary with error recovery (see persist-container-setup, persist-container-error-recovery)
5. Dependency injection: inject repository protocols via @Environment (see state-dependency-injection)
6. ViewModel: create @Observable ViewModel that delegates directly to repository protocols (see state-query-vs-viewmodel)
7. CRUD flows: route all insert/delete/update through ViewModel -> Repository (see crud-*)
8. Sync architecture: queue writes, execute via sync coordinator with retry policy (see sync-*)
9. Relationships: model to-many relationships as arrays; define delete rules (see rel-*)
10. Previews: create in-memory containers and sample data for fast iteration (see preview-*)
11. 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