Apple Developer SwiftData Best Practices

Comprehensive data modeling, persistence, and state management guide for Swift and SwiftUI applications using SwiftData, sourced from official Apple Developer tutorials and WWDC sessions. Contains 48 rules across 8 categories (after merging duplicates and adding concurrency coverage), prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Defining @Model classes and their properties
• Setting up ModelContainer and ModelContext for persistence
• Writing @Query declarations and predicates
• Implementing create, update, and delete operations
• Configuring model relationships (one-to-many, inverse)
• Coordinating SwiftUI state with SwiftData (@Bindable, @State, @Environment)
• 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. Model design: define @Model classes, defaults, and transient/computed state (see model-*)
2. Container wiring: configure ModelContainer once at the app boundary; choose default vs custom configuration; decide App Group sharing (see persist-container-setup, schema-configuration, persist-app-group)
3. Queries: prefer @Query in views; use FetchDescriptor in services/background work (see query-property-wrapper, query-fetch-descriptor, query-fetch-tuning)
4. CRUD flows: insert/delete via the environment context; choose creation UI patterns; handle cancel/undo appropriately (see crud-*)
5. Relationships: model to-many relationships as arrays; define delete rules for ownership (see rel-*)
6. Previews: create in-memory containers and sample data for fast iteration (see preview-*)
7. Schema evolution: plan migrations and validate uniqueness/indexing choices before shipping (see schema-*)

Troubleshooting

• Data not persisting -> persist-model-macro, persist-container-setup, persist-autosave, schema-configuration
• List not updating -> query-property-wrapper, state-wrapper-views
• Duplicates -> schema-unique-attributes, schema-unique-macro
• Widget/extension can’t see data -> persist-app-group, schema-configuration

Rule Categories by Priority

Quick Reference

1. Data Modeling (CRITICAL)

• model-custom-types – Use custom types over parallel arrays
• model-class-for-persistence – Use classes for SwiftData persistent models
• model-identifiable – Conform models to Identifiable with UUID
• model-initializer – Provide custom initializers for model classes
• model-computed-properties – Use computed properties for derived data
• model-defaults – Provide sensible default values for model properties
• model-transient – Mark non-persistent properties with @Transient
• model-external-storage – Use external storage for large binary data

2. Persistence Setup (CRITICAL)

• persist-model-macro – Apply @Model macro to all persistent types
• persist-container-setup – Configure ModelContainer at the App level
• persist-context-environment – Access ModelContext via @Environment
• 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
• 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 ModelContext
• crud-delete-indexset – Delete using IndexSet with onDelete modifier
• crud-sheet-creation – Use sheets for focused data creation
• crud-cancel-delete – Delete unsaved models on cancel
• crud-undo-cancel – Enable undo and use it to cancel edits
• crud-edit-button – Provide EditButton for list management
• crud-dismiss-save – Use Environment dismiss for modal save flow

5. 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

6. SwiftUI State Flow (MEDIUM)

• 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

7. 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

8. Schema & Migration (LOW-MEDIUM)

• 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-configuration – Customize storage with ModelConfiguration

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