Skip to content

dpearson2699/swift-ios-skills / skills/swift-codable

swift-codable

Verified

Implement Swift Codable models for JSON and property-list encoding and decoding with JSONDecoder, JSONEncoder, CodingKeys, and custom init(from:) or encode(to:). Use when parsing API responses, remapping keys, flattening nested JSON, handling date or data decoding strategies, decoding heterogeneous arrays, or integrating Codable with URLSession, SwiftData, or UserDefaults.

FileKindSize
SKILL.mdskill md13.5 KB
evals/evals.jsonconfig4.8 KB
references/codable-advanced-patterns.mdmarkdown3.3 KB

references/codable-advanced-patterns.md

View on GitHub
# Advanced Codable Patterns

Use these patterns after the model's core keys, nested containers, and decoding
strategies are established.

## Contents

- [Heterogeneous Arrays](#heterogeneous-arrays)
- [Lossy Arrays](#lossy-arrays)
- [Single-Value Wrappers](#single-value-wrappers)
- [Missing-Key Defaults](#missing-key-defaults)
- [Encoder Configuration](#encoder-configuration)
- [Persistence Boundaries](#persistence-boundaries)

## Heterogeneous Arrays

Decode a discriminator first, then decode only fields owned by that case:

```swift
enum ContentBlock: Decodable {
    case text(String)
    case image(URL)

    enum CodingKeys: String, CodingKey { case type, content, url }

    init(from decoder: Decoder) throws {
        let values = try decoder.container(keyedBy: CodingKeys.self)
        switch try values.decode(String.self, forKey: .type) {
        case "text": self = .text(try values.decode(String.self, forKey: .content))
        case "image": self = .image(try values.decode(URL.self, forKey: .url))
        default:
            throw DecodingError.dataCorruptedError(
                forKey: .type, in: values,
                debugDescription: "Unknown content type"
            )
        }
    }
}
```

## Lossy Arrays

Default array decoding fails when any element is invalid. Use lossy decoding
only when the product contract permits partial data, and report skipped items.

```swift
struct LossyArray<Element: Decodable>: Decodable {
    let elements: [Element]

    init(from decoder: Decoder) throws {
        var values = try decoder.unkeyedContainer()
        var decoded: [Element] = []
        while !values.isAtEnd {
            if let value = try? values.decode(Element.self) {
                decoded.append(value)
            } else {
                _ = try? values.decode(DiscardedValue.self)
            }
        }
        elements = decoded
    }
}

private struct DiscardedValue: Decodable {}
```

## Single-Value Wrappers

```swift
struct UserID: Codable, Hashable {
    let rawValue: String

    init(from decoder: Decoder) throws {
        rawValue = try decoder.singleValueContainer().decode(String.self)
    }

    func encode(to encoder: Encoder) throws {
        var value = encoder.singleValueContainer()
        try value.encode(rawValue)
    }
}
```

## Missing-Key Defaults

A stored property default does not make synthesized decoding tolerate a missing
nonoptional key. Decode manually when missing or null has an explicit fallback:

```swift
let values = try decoder.container(keyedBy: CodingKeys.self)
theme = try values.decodeIfPresent(String.self, forKey: .theme) ?? "system"
```

Preserve the distinction between a missing key, explicit null, and malformed
data when the API contract assigns them different meanings.

## Encoder Configuration

Configure matching date, data, float, and key strategies once per transport or
file format. Use `PropertyListEncoder`/`PropertyListDecoder` for property lists;
do not send plist configuration through JSON helpers.

## Persistence Boundaries

- SwiftData: persist supported Codable value types as typed model properties;
  route schema and unsupported-storage decisions to `swiftdata`.
- UserDefaults: store primitive preferences directly. For a small Codable
  preference, a `RawRepresentable` wrapper with JSON-string storage can support
  `@AppStorage`; route larger or durable data to a real persistence layer.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall