Data Persistence and Local State

Introduction

An iOS application rarely exists only for the duration of one screen. Users expect preferences to remain selected, drafts to survive termination, credentials to remain protected, and substantial records to be searchable and updated efficiently. Data persistence is the practice of storing information so that it remains available beyond the lifetime of a particular view, process, or application launch. Local state is the information an application maintains on the device to represent its current and remembered condition.

Choosing a persistence mechanism is a design decision rather than merely an implementation detail. The appropriate choice depends on the data’s sensitivity, size, structure, lifetime, query requirements, migration needs, and whether it must be synchronized with a server. This chapter examines UserDefaults, files, Codable, SwiftData, Core Data, and Keychain, and develops a practical selection framework.

Learning Objectives

By the end of this chapter, you should be able to:

• distinguish transient state from persisted local data;
• store simple preferences using UserDefaults;
• encode and decode structured data with Codable;
• read and write files safely within an app’s sandbox;
• explain the roles of SwiftData and Core Data;
• protect secrets with Keychain rather than ordinary files or preferences;
• select a storage technology according to security, scale, structure, and lifecycle;
• design persistence code that supports errors, migration, privacy, and testing.

1. Understanding State and Persistence

State can be classified by lifetime and ownership. A local variable usually lasts only while a function executes. A view model may last while a screen or feature is active. Scene state can preserve navigation or restoration information. Persistent state survives application termination. Remote state is held by a server and may be shared across devices or users.

Persistence does not mean that data is permanent in an absolute sense. The operating system may remove caches, the user may delete the app, storage may become unavailable, or a migration may change the data model. A sound design therefore defines the intended lifecycle explicitly.

Typical questions include:

1. Can the data be recreated from another source?
2. Is it confidential or a security credential?
3. Is it a single value, a document, or a collection of related records?
4. Must the application search, sort, filter, or update individual records?
5. How large can it become?
6. Must it survive app updates and model changes?
7. Does it need synchronization with a backend?

A useful principle is: store each kind of data in the least complex mechanism that satisfies its requirements, but no less secure or reliable than necessary.

2. UserDefaults: Preferences, Not a Database

UserDefaults stores small key–value preferences. It is appropriate for settings such as a selected appearance mode, whether onboarding has been completed, a preferred unit system, or a last-used tab. It supports property-list-compatible values including strings, numbers, Boolean values, dates, arrays, dictionaries, and data values.

let defaults = UserDefaults.standard

defaults.set(true, forKey: "hasCompletedOnboarding")
let completed = defaults.bool(forKey: "hasCompletedOnboarding")

For maintainability, centralize keys and avoid scattering string literals throughout the application:

enum PreferenceKey {
    static let hasCompletedOnboarding = "hasCompletedOnboarding"
    static let selectedTheme = "selectedTheme"
}

UserDefaults is not suitable for passwords, authentication tokens, large datasets, frequently changing records, or information requiring complex queries. Its contents should be regarded as user preferences, not as a secure vault. Although the system provides protection mechanisms, application code should not use preferences as a substitute for Keychain.

A registration dictionary can provide defaults without writing values immediately:

UserDefaults.standard.register(defaults: [
    "selectedTheme": "system",
    "hasCompletedOnboarding": false
])

When a setting is removed or renamed, consider migration. For example, an application can read an old key once, transform its value, write the new key, and remove the old key. Preference changes should also be tested across fresh installation, upgrade, and restoration scenarios.

3. Files and the Application Sandbox

Every iOS application operates within a sandbox. The application should obtain directory URLs through FileManager rather than constructing arbitrary paths. Common locations include:

For internal structured data, Application Support is often more appropriate than Documents. A cache must be safe to delete and reconstruct. Files that represent user documents may require different backup and visibility decisions.

let fileManager = FileManager.default
let supportURL = try fileManager.url(
    for: .applicationSupportDirectory,
    in: .userDomainMask,
    appropriateFor: nil,
    create: true
)

let fileURL = supportURL.appendingPathComponent("profile.json")

File operations can fail because of missing directories, insufficient space, permissions, corruption, or interruption. Production code should use throws, handle errors meaningfully, and avoid replacing a valid file with partially written data. For important files, write to a temporary location and replace the original after successful completion. File protection options can restrict access while the device is locked.

4. Codable for Structured Local Data

Codable combines Encodable and Decodable. It allows Swift values to be converted to and from formats such as JSON or property lists. Codable is a serialization mechanism; it is not itself a database or storage location.

struct StudySession: Codable, Identifiable {
    let id: UUID
    var course: String
    var minutes: Int
    var completedAt: Date
}

Encoding and decoding a file can be implemented as follows:

struct SessionStore {
    let url: URL
    private let encoder = JSONEncoder()
    private let decoder = JSONDecoder()

    func save(_ sessions: [StudySession]) throws {
        encoder.dateEncodingStrategy = .iso8601
        let data = try encoder.encode(sessions)
        try data.write(to: url, options: [.atomic])
    }

    func load() throws -> [StudySession] {
        let data = try Data(contentsOf: url)
        decoder.dateDecodingStrategy = .iso8601
        return try decoder.decode([StudySession].self, from: data)
    }
}

The .atomic option helps prevent readers from observing an incomplete replacement. It does not eliminate every failure mode, so applications should still consider backups, validation, and recovery.

Codable works well for small and moderate document-like data. Its limitations become apparent when a file contains thousands of records and the application repeatedly rewrites the entire collection. It also does not automatically provide query indexes, relationships, conflict resolution, or schema migration. A model change can make older data undecodable unless compatibility is designed deliberately.

A robust model can use explicit versioning:

struct StoredDataV1: Codable {
    var name: String
}

struct StoredDataV2: Codable {
    var displayName: String
}

A migration layer can detect an older representation and convert it to the current model. Do not assume that a successful decode proves that the data is semantically valid; validate ranges, required fields, and business rules after decoding.

5. SwiftData and Core Data

When an application maintains many related records, persistence frameworks provide capabilities beyond a single JSON file. These include object modeling, change tracking, fetching, sorting, relationships, validation, and migration.

SwiftData

SwiftData is Apple’s modern, Swift-oriented persistence framework, introduced with iOS 17. A model type can be annotated with @Model:

import SwiftData

@Model
final class Book {
    var title: String
    var author: String
    var isRead: Bool

    init(title: String, author: String, isRead: Bool = false) {
        self.title = title
        self.author = author
        self.isRead = isRead
    }
}

A model container manages persistent storage, while a model context tracks objects and saves changes. SwiftUI integration can use @Query to fetch model objects, but views should not become the sole location of persistence policy. A separate store or repository can make testing and migration clearer.

SwiftData is attractive for new applications targeting current operating systems because it uses modern Swift syntax and integrates with SwiftUI. Its deployment availability must nevertheless be checked. If an application supports older iOS versions or already uses a mature Core Data model, Core Data may remain the practical choice.

Core Data

Core Data is a mature object graph and persistence framework. It supports managed object contexts, persistent stores, fetched results, relationships, validation, and several store configurations. Core Data is not simply a database wrapper: it manages an object graph and coordinates changes between in-memory objects and persistent storage.

Core Data is often selected when an application requires broad OS-version support, mature migration facilities, extensive tooling, or an existing model. It requires careful context management. Objects belong to contexts, and managed objects should not be freely passed across threads. Background work should use an appropriate background context and merge changes deliberately.

Comparison

6. Keychain and Sensitive Information

The Keychain is intended for sensitive small items such as passwords, private keys, access tokens, and cryptographic material. It provides protected storage managed by the operating system and supports access-control policies. A token should not be placed in UserDefaults, a JSON file, application logs, or analytics events.

A production application should decide whether an item must be available when the device is unlocked, only after the user has authenticated, or under another access policy. Keychain accessibility affects both security and usability. The least permissive policy that still supports the feature is generally preferable.

Keychain APIs are lower-level than ordinary preferences. Many teams encapsulate them in a type such as KeychainStore so that the rest of the application uses a clear interface:

protocol SecretStore {
    func save(_ value: Data, account: String) throws
    func read(account: String) throws -> Data?
    func delete(account: String) throws
}

A Keychain wrapper should handle status codes, distinguish “not found” from an actual error, avoid logging secret values, and test behavior after reinstall, device backup restoration, and account changes. Keychain persistence may have lifecycle behavior different from ordinary app files, so the application must define whether credentials should survive an app reinstall or be invalidated during logout.

Encryption and access control are related but different concerns. Encryption protects data from unauthorized reading; access control determines who or what may use it and under which conditions. Sensitive files may require both file protection and application-level encryption, while credentials generally belong in Keychain.

7. A Decision Framework

Storage selection can be organized around five dimensions:

• Sensitivity: Is disclosure harmful? If yes, use Keychain or an appropriately protected store.
• Cardinality and size: Is the data a few values, one document, or a large collection?
• Query complexity: Are filtering, sorting, joins, and relationships required?
• Lifecycle: Must it survive launches, upgrades, device backup, logout, or reinstall?
• Availability: Must the application work offline, and must data synchronize later?

A practical decision sequence is:

1. For a small non-secret setting, choose UserDefaults.
2. For a document or exportable structured object, choose Codable and a file.
3. For a secret, choose Keychain.
4. For many related records and queries, choose SwiftData or Core Data.
5. For data owned by a server or shared across devices, use a server-side system as the source of truth and treat local persistence as a cache or offline store.

This framework is not mechanical. For example, a large encrypted document may require a file-based design, while a modest collection with many relationships may justify SwiftData. The data model and lifecycle are more important than the raw number of bytes.

8. Applied Case: An Offline Study Planner

This is an illustrative case. A study-planner application allows a learner to define subjects, record study sessions, continue working without connectivity, and sign in to synchronize progress.

Background and problem

The application needs a theme preference, a session history, an authentication token, and downloadable course notes. The team initially stores all values in UserDefaults. As usage grows, startup becomes slower, the preference file contains sensitive material, and updating one study session requires rewriting a large encoded array.

Analysis

The theme is a small non-sensitive preference. The token is a credential. Session history consists of many records that must be filtered by subject and date. Course notes are document-like files that can be downloaded again and may be large.

Approach

The redesigned architecture uses:

• UserDefaults for theme and onboarding state;
• Keychain for the access and refresh tokens;
• SwiftData for subjects and study-session records;
• Codable files in Application Support for downloaded note documents;
• a cache directory for thumbnails that can be regenerated;
• a synchronization service that treats the server as authoritative when conflicts occur.

Each persistence operation is placed behind a repository or store interface. View models request operations rather than directly constructing file paths or Keychain queries. A migration converts the old preference representation and removes the token from UserDefaults. The app displays an offline status and queues permitted changes for later synchronization.

Outcome

Preferences remain simple, credentials receive stronger protection, records can be queried without rewriting one large file, and downloadable documents have an explicit cache and backup policy. The separation also improves testing: repositories can be replaced with in-memory implementations during unit tests.

Learning points

The important improvement was not selecting the newest framework everywhere. It was matching each data category to its security, scale, and lifecycle requirements. Persistence boundaries also clarified ownership, error handling, and synchronization responsibilities.

9. Reliability, Privacy, and Professional Practice

Persistence code must be designed for failure. Applications should handle missing files, malformed data, failed saves, storage exhaustion, model migration errors, and interrupted synchronization. A useful strategy is to preserve the last known good data and report recovery options rather than silently deleting it.

Testing should include:

• first launch with no existing data;
• normal read and write operations;
• corrupted or partial files;
• application upgrade and schema migration;
• device lock and unlock behavior;
• logout and account switching;
• low-storage conditions where practical;
• concurrent or background operations;
• backup and restore assumptions;
• accessibility and privacy expectations.

Privacy design begins with data minimization: do not collect or retain information that the feature does not need. Avoid placing personal data in logs, crash reports, URLs, or analytics. Explain collection and retention in the privacy policy, and ensure that deletion mechanisms actually remove local copies, caches, credentials, and queued synchronization data where required.

Offline data also creates governance questions. A user may expect a record deleted on one device to disappear from all devices. A local delete queue, conflict policy, and server retention policy must be consistent. For regulated or sensitive applications, consult applicable organizational and legal requirements rather than assuming that device storage alone satisfies compliance.

10. Contemporary Considerations

Modern iOS applications increasingly combine local persistence with asynchronous networking, background tasks, cloud synchronization, and Swift concurrency. Persistence APIs must be used with their threading and actor-isolation rules in mind. A background import should not block the main actor, and UI updates should be delivered in a controlled manner.

Cloud synchronization can improve continuity but introduces conflicts, identity management, retry logic, and data-consistency decisions. Local persistence should not be described as synchronization merely because it survives an app launch. Synchronization is a distributed-systems problem involving multiple copies of data.

AI features may generate summaries, classifications, or recommendations that are stored locally. Such outputs should be labeled appropriately, validated where consequential, and protected if they contain personal information. A generated result is not automatically authoritative, and retaining prompts or inferred attributes can create additional privacy obligations.

Best-Practice Checklist

• Use UserDefaults only for small, non-sensitive preferences.
• Use Keychain for credentials and other secrets.
• Use Codable files for manageable document-like structures.
• Use SwiftData or Core Data for rich, queryable object collections.
• Obtain paths from FileManager and choose directories according to lifecycle.
• Perform atomic writes where appropriate and handle errors explicitly.
• Version persisted formats and plan migrations before shipping changes.
• Keep persistence policy outside views when the feature is non-trivial.
• Never log secrets or assume local storage is automatically private.
• Test fresh installation, upgrades, deletion, offline use, and failure recovery.
• Define backup, cache, logout, reinstall, and synchronization behavior.

Chapter Summary

Data persistence allows application information to survive beyond a view or process, but different data categories require different solutions. UserDefaults is suited to small preferences; Codable provides a convenient representation for structured documents; files provide direct control over local documents and caches; SwiftData and Core Data support queryable records, relationships, change tracking, and migration; and Keychain protects credentials and other secrets. The correct choice depends on sensitivity, size, structure, query needs, lifecycle, and synchronization requirements. Reliable persistence also requires atomicity, validation, migration, error recovery, privacy protection, testing, and explicit policies for backup, deletion, logout, and offline behavior.

Key Terms

Persistence: Storing data so it survives a limited execution scope, such as an app launch.

Local state: Information maintained on the device to represent application condition.

UserDefaults: A key–value store intended primarily for small application preferences.

Application sandbox: The protected file and resource area assigned to an application.

Codable: Swift protocol composition supporting encoding and decoding of values.

Serialization: Converting in-memory values into a storable or transferable representation.

Schema: The structure and rules describing stored data.

Migration: Converting data from an older schema to a newer schema.

Atomic write: A write strategy intended to replace a file without exposing a partial result.

Cache: Re-creatable data stored to improve performance.

Keychain: An operating-system-managed store for protected credentials and secrets.

Access control: Rules determining which operations or identities may use protected data.

SwiftData: Apple’s modern Swift-oriented persistence framework, available from iOS 17.

Core Data: Apple’s mature object graph and persistence framework.

Model context: An environment that tracks and coordinates changes to persisted objects.

Repository: An abstraction that provides data operations while hiding storage details.

Offline-first: A design in which core functionality can operate with limited or no network access.

Synchronization: Coordinating multiple copies of data across devices or services.

Data minimization: Collecting and retaining only information necessary for a stated purpose.

Review Questions

Short Answer Questions

1. What type of information is UserDefaults designed to store?
2. Why should an authentication token not be stored in UserDefaults?
3. What is the purpose of Codable?
4. Name two reasons an application might choose SwiftData or Core Data instead of a JSON file.
5. What is the difference between a cache and durable application data?

Long Answer Questions

1. Explain how sensitivity, scale, query requirements, and lifecycle influence persistence selection.
2. Compare UserDefaults, Codable files, SwiftData, Core Data, and Keychain in terms of appropriate use.
3. Describe a migration strategy for an application whose persisted model has changed.
4. Explain the reliability and privacy practices required for production persistence code.
5. Discuss why synchronization is more complex than merely saving data locally.

Analytical / Application Questions

1. Design a persistence architecture for a health journal containing preferences, daily entries, photos, and an account token. Justify every storage choice.
2. An application stores 20,000 records as one Codable array and rewrites the file after every edit. Analyze the weaknesses of this design and propose an alternative.
3. A user logs out while the device is offline. Determine which local data should be deleted, retained, or queued, and explain the security and synchronization assumptions behind your decision.

Multiple Choice Questions with Answers

Question 1

Which data is the most appropriate candidate for UserDefaults?

A. A refresh token

B. A 50,000-record transaction history

C. The user’s selected theme

D. A private encryption key

Correct Answer: C. The user’s selected theme

Question 2

What is Codable primarily used for?

A. Providing biometric authentication

B. Encoding and decoding Swift values

C. Creating database indexes

D. Managing network connections

Correct Answer: B. Encoding and decoding Swift values

Question 3

Which storage mechanism is intended for passwords and access tokens?

A. Keychain

B. UserDefaults

C. The Caches directory

D. A plain JSON file

Correct Answer: A. Keychain

Question 4

Which directory is generally appropriate for re-creatable downloaded thumbnails?

A. Documents

B. Library/Caches

C. Keychain

D. The application bundle

Correct Answer: B. Library/Caches

Question 5

A collection contains many related records that must be filtered and sorted frequently. Which option is generally most suitable?

A. UserDefaults

B. A single Boolean preference

C. SwiftData or Core Data

D. A temporary directory

Correct Answer: C. SwiftData or Core Data

Question 6

What does an atomic file write primarily help prevent?

A. All unauthorized access to the device

B. Readers observing a partially replaced file

C. The need for schema migration

D. Network synchronization conflicts

Correct Answer: B. Readers observing a partially replaced file

Question 7

SwiftData was introduced for which minimum major iOS release in the chapter’s discussion?

A. iOS 13

B. iOS 15

C. iOS 16

D. iOS 17

Correct Answer: D. iOS 17

Question 8

Which statement best describes synchronization?

A. Keeping data in a local variable

B. Coordinating multiple copies across devices or services

C. Encoding a structure as JSON

D. Registering default preferences

Correct Answer: B. Coordinating multiple copies across devices or services

Question 9

Why should a persisted data format often be versioned?

A. To make passwords shorter

B. To support conversion when the model changes

C. To avoid using FileManager

D. To guarantee unlimited storage

Correct Answer: B. To support conversion when the model changes

Question 10

Which is an example of data minimization?

A. Retaining every generated log indefinitely

B. Collecting only information required by the feature

C. Copying credentials into analytics events

D. Storing all records in UserDefaults

Correct Answer: B. Collecting only information required by the feature