孫昊

Posted on May 7

How I rebuilt the Codable migration pattern across 4 iOS apps in 2 hours

#swift #ios #codable #architecture

I was adding a single new feature to DaysUntil: yearly-recurring events. Twenty lines of product code. But underneath, the data layer needed a pattern fix that turned out to apply to four apps, not one.

Here's how I systematized it, and why this pattern compounds across every future app I ship.

The trigger

I added this one line to the Event struct in DaysUntil:

var isRecurring: Bool = false

Innocent, right? It has a default value. Existing JSON from older app versions don't have this key, so the decoder should... just use the default?

No.

Swift's synthesized Codable decoder ignores property defaults. When it hits JSON without isRecurring, it throws keyNotFound. The app crashes on launch. Users with saved data see a blank list because the try? swallowed the error.

This is the trap I see indie iOS devs hit every 2–3 months. It's invisible in dev (you only have new schema) and lights up day-1 of rollout.

The fix (one custom decoder)

I wrote a custom init(from:) that uses decodeIfPresent for all fields with defaults:

struct Event: Identifiable, Codable, Hashable {
    var id: UUID = UUID()
    var title: String
    var date: Date
    var emoji: String = "🎯"
    var colorID: String = "default"
    var createdAt: Date = .now
    var isRecurring: Bool = false

    enum CodingKeys: String, CodingKey {
        case id, title, date, emoji, colorID, createdAt, isRecurring
    }

    init(from decoder: Decoder) throws {
        let c = try decoder.container(keyedBy: CodingKeys.self)
        self.id          = try c.decode(UUID.self, forKey: .id)
        self.title       = try c.decode(String.self, forKey: .title)
        self.date        = try c.decode(Date.self, forKey: .date)
        self.emoji       = try c.decodeIfPresent(String.self, forKey: .emoji) ?? "🎯"
        self.colorID     = try c.decodeIfPresent(String.self, forKey: .colorID) ?? "default"
        self.createdAt   = try c.decodeIfPresent(Date.self, forKey: .createdAt) ?? .now
        self.isRecurring = try c.decodeIfPresent(Bool.self, forKey: .isRecurring) ?? false
    }
}

The synthesized encode(to:) stays as-is. Encoding always writes current fields; decoding tolerates missing ones from older clients.

One key: I applied decodeIfPresent to all fields with defaults, not just the new one. This future-proofs the decoder — every schema v1.0.1+ migration is now precedented.

Why I applied this to three apps that don't currently need it

DaysUntil got the fix immediately (it needed it). But here's what happened next:

I checked AltitudeNow. Same pattern: persisted Location struct, four default-valued fields.

I checked PromptVault. Same: persisted Prompt struct, five defaults.

I checked AutoChoice. Same: persisted Choice struct, three defaults.

None of these apps have added a field yet. But all of them will, eventually. The moment they ship v1.0.1 with a new feature, the migration trap appears.

So I applied the same decoder pattern to all four. Same pattern, same tests, same future-proofing. Total time: 2 hours for all four repos. Cost of not doing it now: debugging the crash on day-1 of each future release.

The test I added to each repo

func testDecodingOldEventSchemaWithoutIsRecurring() throws {
    let oldJSON = #"""
    {
        "id": "00000000-0000-0000-0000-000000000001",
        "title": "Old Event",
        "date": 777600000,
        "emoji": "🎯",
        "colorID": "default",
        "createdAt": 777600000
    }
    """#.data(using: .utf8)!

    let decoded = try JSONDecoder().decode(Event.self, from: oldJSON)
    XCTAssertEqual(decoded.title, "Old Event")
    XCTAssertFalse(decoded.isRecurring)
}

This test passes the v1.0.0 schema through the v1.0.1 decoder. If you forget the custom init(from:), it fails with keyNotFound. Better to catch in CI than in App Review.

The leverage pattern

This is the kind of work that doesn't show up in a "what I shipped" list. No visible feature. No new button. No marketing copy.

But it saves:

Zero crash reports on day-1 of four future releases
Zero "the app deleted my data" support messages
Zero debugging the same trap four times across four code bases

The pattern I'm applying now:

Every persisted struct gets a custom init(from:) the moment it ships, not after it breaks.
Use decodeIfPresent for all fields with defaults, not just the new ones.
One backwards-compat test per struct that encodes the v1.0.0 schema, decodes it, asserts no throw.

Boring boilerplate on day-1. But day-60, when I'm shipping v1.0.1 across four apps, I don't have four migration bugs to debug.

What scales and what doesn't

If you're building multiple iOS apps:

Scales: Custom decoder pattern. Applied to four apps, caught zero regressions in CI, cost 20 minutes per app.

Doesn't scale: Manual testing. Each app's persisted structs are unique; you can't test one migration and assume the others are fine.

Scales: Shared test template. I copied the test structure across all four repos. CI caught any typos.

The meta-lesson: schema migration is the invisible foundation of persisted data. Systematize it early, apply it everywhere, then you can stop thinking about it.

The Event struct and tests are in my open-source iOS apps on GitHub.

If you're shipping v1.0.1 of an iOS app with new persistent fields, drop a comment — happy to share other migration patterns I've seen scale.

Sources:

DEV Community