Ios Data Persistence

---
name: ios-data-persistence
description: Use when designing iOS persistence, SwiftData migrations, Keychain storage, files, offline sync, or searchable app entities; use ios-architecture for broader module design.
metadata:
  portable: true
  compatible_with:
  - claude-code
  - codex
---

# iOS Data Persistence
Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

<!-- dual-compat-start -->
## Use When

- Designing, implementing, or reviewing iOS persistence with SwiftData, Core Data migration, UserDefaults, Keychain, file storage, offline sync, Core Spotlight semantic indexing, App Entity exposure, AI local context, or privacy-sensitive caches.
- The task mentions local storage, migrations, offline-first sync, search/indexing, Siri/App Entity data exposure, or AI cache retention.

## Do Not Use When

- The task is general iOS implementation with no local data or cache concerns; use `ios-development`.
- The task is only platform capability routing; use `ios-platform-capabilities`.
- The task is security policy rather than persistence mechanics; use `ios-security-and-rbac` alongside this skill.

## Required Inputs

- Data model, sensitivity classification, deployment target, sync/backend contract, offline requirements, account/tenant model, deletion rules, and whether data is exposed to Spotlight, Siri, widgets, or AI context.

## Workflow

1. Load `ios-development` for Swift and project standards.
2. Choose storage: UserDefaults, Keychain, SwiftData/Core Data, FileManager, URLCache/NSCache, Core Spotlight, or an AI local-context cache.
3. Load `references/ios-swiftdata.md` for SwiftData details.
4. Load `references/semantic-indexing-and-ai-caches-wwdc26.md` when data is exposed to Siri, Spotlight, App Entities, widgets, or AI.
5. Produce a model spec, migration plan, cache policy, deletion policy, and test plan.

## Quality Standards

- Persistence models must separate stored data, domain entities, DTOs, and search/intent projections when privacy or API shape differs.
- Secrets belong in Keychain or stronger platform storage, not UserDefaults, SwiftData, Spotlight, or logs.
- Offline data must have conflict, sync, stale-state, and deletion behavior.
- Indexed or AI-context data must have retention, invalidation, and user/account cleanup rules.

## Anti-Patterns

- Exposing stored models directly as App Entities without reviewing fields.
- Keeping stale Spotlight entries after logout, role change, tenant switch, or deletion.
- Using local AI context as a hidden long-term memory without retention and deletion controls.
- Treating SwiftData migrations as a compile-time concern only.

## Outputs

- Persistence model spec, storage decision, SwiftData migration plan, offline sync plan, search/index projection, AI cache policy, or review findings.

## Evidence Produced

| Category | Artifact | Format | Example |
|----------|----------|--------|---------|
| Data safety | Persistence model spec | Markdown doc per `skill-composition-standards/references/entity-model-template.md` covering entities, projections, retention, and deletion | `docs/ios/persistence-model-orders.md` |
| Correctness | Persistence test plan | Markdown doc listing CRUD, migration, sync, index, and deletion test cases | `docs/ios/persistence-tests-orders.md` |

## References

- `references/ios-swiftdata.md` for SwiftData `@Model`, relationships, model actors, migrations, CloudKit, and testing.
- `references/semantic-indexing-and-ai-caches-wwdc26.md` for Core Spotlight, App Entities, Siri semantic index privacy, local AI context, and cache invalidation rules.
- `references/skill-deep-dive.md` for UserDefaults, Keychain, repository pattern, file storage, URLCache/NSCache, offline-first architecture, and cross-skill references.
<!-- dual-compat-end -->

## Storage Decision Guide

## Inputs

| Artefact | Produced by | Required? | Why |
|---|---|---|---|
| Entity and retention model | Product and backend owners | required | Defines durable records and deletion duties |
| API conflict contract | `api-design-first` | conditional | Governs offline reconciliation |
| Data classification | `ios-security-and-rbac` | required | Selects Keychain, file protection, or database storage |

## Decision Rules

| Data | Storage |
|---|---|
| Credential or private key | Keychain or Secure Enclave reference |
| Queryable application records | SwiftData with an explicit migration plan |
| Large media or export | Protected file with metadata in SwiftData |
| Financial offline conflict | Server-authoritative merge with idempotency |

## Degraded Mode

Without a runnable schema, provide the model delta, migration stages, backup/rollback path, and fixtures required for validation. Do not assert migration safety without testing old stores.
If execution is unavailable, report migration safety as unverified.

## Domain Anti-Patterns

- Storing tokens in UserDefaults. Fix: use an access-group-scoped Keychain item.
- Changing a persistent model without old-store fixtures. Fix: test each supported migration path.
- Caching private AI input indefinitely. Fix: define purpose-bound retention and deletion.
- Treating Spotlight as authoritative storage. Fix: rebuild the index from the source database.
- Resolving ledger conflicts by last-write-wins. Fix: reconcile against server versions.

| Data Type | Storage | Example |
|---|---|---|
| User preferences | UserDefaults | Theme, language, sort order |
| Tokens / credentials | Keychain Services | JWT tokens, API keys, passwords |
| Structured app data | SwiftData or Core Data | Products, orders, customers |
| Searchable safe projections | Core Spotlight / App Entity projection | Title, display date, safe summary |
| Large files / images | FileManager | Photos, PDFs, exports |
| Temporary cache | URLCache / NSCache | API response caching |
| AI local context | App-owned encrypted cache or SwiftData projection | Prompt-safe summaries, never raw secrets |

Rule of thumb: simple flag/scalar = UserDefaults. Secret = Keychain. Relationships/querying = SwiftData. Binary blob = FileManager. Search/Siri/AI exposure = separate projection with explicit privacy review.