@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/swift-codable/SKILL.md

@@ -1,496 +1,492 @@
 ---
 name: swift-codable
-description: "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."
+description: "Codable JSON and property-list models: JSONDecoder, JSONEncoder, CodingKeys, custom init(from:)/encode(to:), nested containers, date, data and key strategies, heterogeneous and lossy arrays, missing-key defaults. Use when parsing API responses, remapping keys, flattening nested JSON, choosing decoding strategies, or wiring Codable into URLSession, SwiftData or UserDefaults."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # Swift Codable
 
-Encode and decode Swift types using `Codable` (`Encodable & Decodable`) with
-`JSONEncoder`, `JSONDecoder`, and related APIs. Targets Swift 6.3 / iOS 26+.
-
-## Contents
-
-- [Basic Conformance](#basic-conformance)
-- [Custom CodingKeys](#custom-codingkeys)
-- [Custom Decoding and Encoding](#custom-decoding-and-encoding)
-- [Nested and Flattened Containers](#nested-and-flattened-containers)
-- [Heterogeneous Arrays](#heterogeneous-arrays)
-- [Date Decoding Strategies](#date-decoding-strategies)
-- [Data and Key Strategies](#data-and-key-strategies)
-- [Lossy Array Decoding](#lossy-array-decoding)
-- [Single Value Containers](#single-value-containers)
-- [Default Values for Missing Keys](#default-values-for-missing-keys)
-- [Encoder and Decoder Configuration](#encoder-and-decoder-configuration)
-- [Codable with URLSession](#codable-with-urlsession)
-- [Codable with SwiftData](#codable-with-swiftdata)
-- [Codable with UserDefaults](#codable-with-userdefaults)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## Basic Conformance
-
-When all stored properties are themselves `Codable`, the compiler synthesizes
-conformance automatically:
+How to turn JSON and property lists into Swift values and back, for Swift 6.3
+and iOS 26. The compiler writes most of the code; this skill is about the
+places where it cannot, and about the boundaries where Codable meets
+networking, SwiftData and `@AppStorage`.
+
+## Basic conformance
+
+When every stored property is itself Codable, the compiler synthesizes the
+whole conformance.
 
 ```swift
-struct User: Codable {
+struct Recipe: Codable {
     let id: Int
-    let name: String
-    let email: String
-    let isVerified: Bool
+    let title: String
+    let servings: Int
 }
 
-let user = try JSONDecoder().decode(User.self, from: jsonData)
-let encoded = try JSONEncoder().encode(user)
+let recipe = try JSONDecoder().decode(Recipe.self, from: payload)
+let bytes = try JSONEncoder().encode(recipe)
 ```
 
-Prefer `Decodable` for read-only API responses and `Encodable` for write-only.
-Use `Codable` only when both directions are required.
+Pick the narrowest protocol:
+
+- `Decodable` for data you only read, such as most API responses.
+- `Encodable` for data you only send.
+- `Codable` only when the type really travels both ways.
 
 ## Custom CodingKeys
 
-Rename JSON keys without writing a custom decoder by declaring a `CodingKeys`
-enum:
+A `CodingKeys` enum renames keys and still leaves decoding to the compiler.
 
 ```swift
-struct Product: Codable {
+struct Author: Decodable {
     let id: Int
-    let displayName: String
-    let imageURL: URL
-    let priceInCents: Int
+    let penName: String
+    let avatarURL: URL
 
     enum CodingKeys: String, CodingKey {
         case id
-        case displayName = "display_name"
-        case imageURL = "image_url"
-        case priceInCents = "price_in_cents"
+        case penName = "pen_name"
+        case avatarURL = "avatar_url"
     }
 }
 ```
 
-Every stored property must appear in the enum. Omitting a property from
-`CodingKeys` excludes it from encoding/decoding -- provide a default value or
-compute it separately.
+Once the enum exists, it is the complete list of coded properties. A property
+left out is not decoded or encoded at all, so it must have a default value or
+be computed some other way.
 
-## Custom Decoding and Encoding
+## Custom decoding and encoding
 
-Override `init(from:)` and `encode(to:)` for transformations the synthesized
-conformance cannot handle:
+Write `init(from:)` and `encode(to:)` when a value needs converting on the
+way in or out.
 
 ```swift
-struct Event: Codable {
-    let name: String
-    let timestamp: Date
-    let tags: [String]
+struct Shipment: Codable {
+    let reference: String
+    let dispatchedAt: Date
+    let labels: [String]
 
     enum CodingKeys: String, CodingKey {
-        case name, timestamp, tags
+        case reference, dispatchedAt = "dispatched_epoch", labels
     }
 
-    init(from decoder: Decoder) throws {
-        let container = try decoder.container(keyedBy: CodingKeys.self)
-        name = try container.decode(String.self, forKey: .name)
-        // Decode Unix timestamp as Double, convert to Date
-        let epoch = try container.decode(Double.self, forKey: .timestamp)
-        timestamp = Date(timeIntervalSince1970: epoch)
-        // Default to empty array when key is missing
-        tags = try container.decodeIfPresent([String].self, forKey: .tags) ?? []
+    init(from decoder: any Decoder) throws {
+        let fields = try decoder.container(keyedBy: CodingKeys.self)
+        reference = try fields.decode(String.self, forKey: .reference)
+        let seconds = try fields.decode(Double.self, forKey: .dispatchedAt)
+        dispatchedAt = Date(timeIntervalSince1970: seconds)
+        labels = try fields.decodeIfPresent([String].self, forKey: .labels) ?? []
     }
 
-    func encode(to encoder: Encoder) throws {
-        var container = encoder.container(keyedBy: CodingKeys.self)
-        try container.encode(name, forKey: .name)
-        try container.encode(timestamp.timeIntervalSince1970, forKey: .timestamp)
-        try container.encode(tags, forKey: .tags)
+    func encode(to encoder: any Encoder) throws {
+        var fields = encoder.container(keyedBy: CodingKeys.self)
+        try fields.encode(reference, forKey: .reference)
+        try fields.encode(dispatchedAt.timeIntervalSince1970, forKey: .dispatchedAt)
+        try fields.encode(labels, forKey: .labels)
     }
 }
 ```
 
-## Nested and Flattened Containers
+Doing the conversion here, instead of patching values after decoding, keeps
+invalid instances from ever existing.
 
-Use `nestedContainer(keyedBy:forKey:)` to navigate and flatten nested JSON:
+## Nested and flattened containers
+
+JSON often nests what the app wants flat. `nestedContainer(keyedBy:forKey:)`
+reaches into the inner object with its own key enum.
 
 ```swift
-// JSON: { "id": 1, "location": { "lat": 37.7749, "lng": -122.4194 } }
-struct Place: Decodable {
-    let id: Int
+// { "name": "Harbour Cafe", "geo": { "latitude": 41.0, "longitude": 29.0 } }
+struct Venue: Decodable {
+    let name: String
     let latitude: Double
     let longitude: Double
 
-    enum CodingKeys: String, CodingKey { case id, location }
-    enum LocationKeys: String, CodingKey { case lat, lng }
+    enum OuterKeys: String, CodingKey { case name, geo }
+    enum GeoKeys: String, CodingKey { case latitude, longitude }
 
-    init(from decoder: Decoder) throws {
-        let container = try decoder.container(keyedBy: CodingKeys.self)
-        id = try container.decode(Int.self, forKey: .id)
-        let location = try container.nestedContainer(
-            keyedBy: LocationKeys.self, forKey: .location)
-        latitude = try location.decode(Double.self, forKey: .lat)
-        longitude = try location.decode(Double.self, forKey: .lng)
+    init(from decoder: any Decoder) throws {
+        let outer = try decoder.container(keyedBy: OuterKeys.self)
+        name = try outer.decode(String.self, forKey: .name)
+        let geo = try outer.nestedContainer(keyedBy: GeoKeys.self, forKey: .geo)
+        latitude = try geo.decode(Double.self, forKey: .latitude)
+        longitude = try geo.decode(Double.self, forKey: .longitude)
     }
 }
 ```
 
-Chain multiple `nestedContainer` calls to flatten deeply nested structures.
-Also use `nestedUnkeyedContainer(forKey:)` for nested arrays.
+Deeper structures chain further `nestedContainer` calls. An array inside a
+keyed object comes from `nestedUnkeyedContainer(forKey:)`.
 
-## Heterogeneous Arrays
+## Heterogeneous arrays
 
-Decode arrays of mixed types using a discriminator field:
+For a list whose elements differ by a `kind` field, model the element as an
+enum with associated values. Read the discriminator first, then the payload it
+selects.
 
 ```swift
-// JSON: [{"type":"text","content":"Hello"},{"type":"image","url":"pic.jpg"}]
-enum ContentBlock: Decodable {
-    case text(String)
-    case image(URL)
-
-    enum CodingKeys: String, CodingKey { case type, content, url }
-
-    init(from decoder: Decoder) throws {
-        let container = try decoder.container(keyedBy: CodingKeys.self)
-        let type = try container.decode(String.self, forKey: .type)
-        switch type {
-        case "text":
-            let content = try container.decode(String.self, forKey: .content)
-            self = .text(content)
-        case "image":
-            let url = try container.decode(URL.self, forKey: .url)
-            self = .image(url)
-        default:
+enum FeedItem: Decodable {
+    case note(String)
+    case photo(URL)
+    case poll(options: [String])
+
+    enum Keys: String, CodingKey { case kind, text, url, options }
+
+    init(from decoder: any Decoder) throws {
+        let item = try decoder.container(keyedBy: Keys.self)
+        switch try item.decode(String.self, forKey: .kind) {
+        case "note":  self = .note(try item.decode(String.self, forKey: .text))
+        case "photo": self = .photo(try item.decode(URL.self, forKey: .url))
+        case "poll":  self = .poll(options: try item.decode([String].self, forKey: .options))
+        case let other:
             throw DecodingError.dataCorruptedError(
-                forKey: .type, in: container,
-                debugDescription: "Unknown type: \(type)")
+                forKey: .kind, in: item, debugDescription: "No FeedItem kind named \(other)")
         }
     }
 }
 
-let blocks = try JSONDecoder().decode([ContentBlock].self, from: jsonData)
+let feed = try JSONDecoder().decode([FeedItem].self, from: payload)
 ```
 
-## Date Decoding Strategies
+## Date decoding strategies
 
-Configure `JSONDecoder.dateDecodingStrategy` to match your API:
+Set the strategy on the decoder to match what the server sends.
 
 ```swift
-let decoder = JSONDecoder()
-
-// ISO 8601 (e.g., "2024-03-15T10:30:00Z")
-decoder.dateDecodingStrategy = .iso8601
-
-// Unix timestamp in seconds (e.g., 1710499800)
-decoder.dateDecodingStrategy = .secondsSince1970
-
-// Custom DateFormatter
-let formatter = DateFormatter()
-formatter.dateFormat = "yyyy-MM-dd"
-formatter.locale = Locale(identifier: "en_US_POSIX")
-formatter.timeZone = TimeZone(secondsFromGMT: 0)
-decoder.dateDecodingStrategy = .formatted(formatter)
-
-// Custom closure for multiple formats
-decoder.dateDecodingStrategy = .custom { decoder in
-    let container = try decoder.singleValueContainer()
-    let string = try container.decode(String.self)
-    if let date = ISO8601DateFormatter().date(from: string) { return date }
-    throw DecodingError.dataCorruptedError(
-        in: container, debugDescription: "Cannot decode date: \(string)")
+let reader = JSONDecoder()
+
+reader.dateDecodingStrategy = .iso8601               // "2025-11-02T08:15:00Z"
+reader.dateDecodingStrategy = .secondsSince1970      // 1762071300
+
+let dayFormat = DateFormatter()
+dayFormat.dateFormat = "dd.MM.yyyy"
+dayFormat.locale = Locale(identifier: "en_US_POSIX")
+dayFormat.timeZone = TimeZone(secondsFromGMT: 0)
+reader.dateDecodingStrategy = .formatted(dayFormat)  // "02.11.2025"
+```
+
+When one field arrives in more than one shape, decode it by hand:
+
+```swift
+reader.dateDecodingStrategy = .custom { decoder in
+    let raw = try decoder.singleValueContainer()
+    let text = try raw.decode(String.self)
+    let withFraction = ISO8601DateFormatter()
+    withFraction.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+    if let date = withFraction.date(from: text) ?? ISO8601DateFormatter().date(from: text) {
+        return date
+    }
+    throw DecodingError.dataCorruptedError(in: raw, debugDescription: "Unreadable date: \(text)")
 }
 ```
 
-Set the matching strategy on `JSONEncoder`:
-`encoder.dateEncodingStrategy = .iso8601`
+Give the encoder the matching strategy, for example
+`writer.dateEncodingStrategy = .iso8601`, so values round-trip.
 
-## Data and Key Strategies
+## Data and key strategies
 
 ```swift
-let decoder = JSONDecoder()
-decoder.dataDecodingStrategy = .base64           // Base64-encoded Data fields
-decoder.keyDecodingStrategy = .convertFromSnakeCase  // simple keys only; not URL/ID spelling
-// {"user_name": "Alice"} maps to `var userName: String` -- no CodingKeys needed
-
-let encoder = JSONEncoder()
-encoder.dataEncodingStrategy = .base64
-encoder.keyEncodingStrategy = .convertToSnakeCase
+reader.dataDecodingStrategy = .base64
+writer.dataEncodingStrategy = .base64
+
+reader.keyDecodingStrategy = .convertFromSnakeCase   // "first_name" -> firstName
+writer.keyEncodingStrategy = .convertToSnakeCase
 ```
 
-Use key strategies only for mechanical snake_case-to-camelCase mappings.
-`convertFromSnakeCase` maps by spelling, not Swift acronym/initialism policy:
-`image_url`, `base_uri`, and `user_id` match `imageUrl`, `baseUri`, and
-`userId` only. If the Swift model uses `imageURL`, `baseURI`, or `userID`,
-declare explicit `CodingKeys`; the strategy will not synthesize those names.
+The snake-case strategies are mechanical. They split on underscores and
+capitalize each following word, nothing more, so:
+
+| JSON key | Property name produced |
+| --- | --- |
+| `avatar_url` | `avatarUrl` |
+| `base_uri` | `baseUri` |
+| `owner_id` | `ownerId` |
 
-## Lossy Array Decoding
+A model that spells those `avatarURL`, `baseURI` or `ownerID` needs explicit
+`CodingKeys` for exactly those properties. The strategy still handles every
+ordinary key.
 
-By default, one invalid element fails the entire array. Use a wrapper to skip
-invalid elements:
+## Lossy array decoding
+
+By default a single bad element throws, and the whole array is lost. When a
+feed is known to be unreliable, wrap each element so a failure becomes `nil`
+and the container still moves on:
 
 ```swift
-struct LossyArray<Element: Decodable>: Decodable {
-    let elements: [Element]
-
-    init(from decoder: Decoder) throws {
-        var container = try decoder.unkeyedContainer()
-        var elements: [Element] = []
-        while !container.isAtEnd {
-            if let element = try? container.decode(Element.self) {
-                elements.append(element)
-            } else {
-                _ = try? container.decode(AnyCodableValue.self) // advance past bad element
+struct TolerantList<Element: Decodable>: Decodable {
+    let items: [Element]
+
+    private struct Slot: Decodable {
+        let value: Element?
+        init(from decoder: any Decoder) throws {
+            value = try? Element(from: decoder)
+        }
+    }
+
+    init(from decoder: any Decoder) throws {
+        var list = try decoder.unkeyedContainer()
+        var kept: [Element] = []
+        while !list.isAtEnd {
+            if let value = try list.decode(Slot.self).value {
+                kept.append(value)
             }
         }
-        self.elements = elements
+        items = kept
     }
 }
-private struct AnyCodableValue: Decodable {}
 ```
 
-## Single Value Containers
+Decoding `Slot` always succeeds, so the unkeyed container always advances.
+A skip trick that decodes an empty placeholder struct only works when the bad
+element is a JSON object; a bad string or number would throw again and leave
+the loop stuck on the same index.
 
-Wrap primitives for type safety using `singleValueContainer()`:
+## Single value containers
 
-```swift
-struct UserID: Codable, Hashable {
-    let rawValue: String
+A wrapper type that should appear in JSON as a bare value uses the single value
+container in both directions.
 
-    init(_ rawValue: String) { self.rawValue = rawValue }
+```swift
+struct OrderNumber: Codable, Hashable {
+    let text: String
 
-    init(from decoder: Decoder) throws {
-        let container = try decoder.singleValueContainer()
-        rawValue = try container.decode(String.self)
+    init(from decoder: any Decoder) throws {
+        text = try decoder.singleValueContainer().decode(String.self)
     }
 
-    func encode(to encoder: Encoder) throws {
-        var container = encoder.singleValueContainer()
-        try container.encode(rawValue)
+    func encode(to encoder: any Encoder) throws {
+        var slot = encoder.singleValueContainer()
+        try slot.encode(text)
     }
 }
-// JSON: "usr_abc123" decodes directly to UserID
+// Encodes as "A-1042", not {"text":"A-1042"}.
 ```
 
-## Default Values for Missing Keys
+## Default values for missing keys
 
-Stored property defaults such as `var theme = "system"` do not make synthesized
-`Decodable` tolerate a missing nonoptional key; synthesis still fails unless the
-property is optional or decoded manually. Use `decodeIfPresent` with
-nil-coalescing when a missing or null key should fall back:
+A default on a stored property does not help synthesized decoding. With
+`var language = "en"`, a payload without `language` still throws
+`keyNotFound`. Either make the property optional or decode it yourself:
 
 ```swift
-struct Settings: Decodable {
-    let theme: String
-    let fontSize: Int
-    let notificationsEnabled: Bool
-
-    enum CodingKeys: String, CodingKey {
-        case theme, fontSize = "font_size"
-        case notificationsEnabled = "notifications_enabled"
-    }
-
-    init(from decoder: Decoder) throws {
-        let container = try decoder.container(keyedBy: CodingKeys.self)
-        theme = try container.decodeIfPresent(String.self, forKey: .theme) ?? "system"
-        fontSize = try container.decodeIfPresent(Int.self, forKey: .fontSize) ?? 16
-        notificationsEnabled = try container.decodeIfPresent(
-            Bool.self, forKey: .notificationsEnabled) ?? true
+struct ReaderSettings: Codable {
+    var language: String
+    var textSize: Int
+    var hyphenation: Bool
+
+    init(from decoder: any Decoder) throws {
+        let fields = try decoder.container(keyedBy: CodingKeys.self)
+        language = try fields.decodeIfPresent(String.self, forKey: .language) ?? "en"
+        textSize = try fields.decodeIfPresent(Int.self, forKey: .textSize) ?? 17
+        hyphenation = try fields.decodeIfPresent(Bool.self, forKey: .hyphenation) ?? false
     }
 }
 ```
 
-## Encoder and Decoder Configuration
+`decodeIfPresent` returns `nil` for a key that is missing or `null`.
+
+## Encoder and decoder configuration
 
 ```swift
-let encoder = JSONEncoder()
-encoder.outputFormatting = [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes]
-
-let decoder = JSONDecoder()
-// Non-conforming floats (NaN, Infinity are not valid JSON)
-encoder.nonConformingFloatEncodingStrategy = .convertToString(
-    positiveInfinity: "Infinity", negativeInfinity: "-Infinity", nan: "NaN")
-decoder.nonConformingFloatDecodingStrategy = .convertFromString(
-    positiveInfinity: "Infinity", negativeInfinity: "-Infinity", nan: "NaN")
+let writer = JSONEncoder()
+writer.outputFormatting = [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes]
 ```
 
-### PropertyListEncoder / PropertyListDecoder
+`.sortedKeys` makes output stable, which is what snapshot and golden-file tests
+need.
+
+JSON has no NaN or infinity. If a `Double` can hold them, map them to strings
+explicitly:
 
 ```swift
-let plistEncoder = PropertyListEncoder()
-plistEncoder.outputFormat = .xml  // or .binary
-let data = try plistEncoder.encode(settings)
-let decoded = try PropertyListDecoder().decode(Settings.self, from: data)
+writer.nonConformingFloatEncodingStrategy = .convertToString(
+    positiveInfinity: "inf", negativeInfinity: "-inf", nan: "nan")
+reader.nonConformingFloatDecodingStrategy = .convertFromString(
+    positiveInfinity: "inf", negativeInfinity: "-inf", nan: "nan")
+```
+
+### PropertyListEncoder and PropertyListDecoder
+
+The same models work with property lists:
+
+```swift
+let plistWriter = PropertyListEncoder()
+plistWriter.outputFormat = .binary        // or .xml when a human will read it
+let stored = try plistWriter.encode(settings)
+let restored = try PropertyListDecoder().decode(ReaderSettings.self, from: stored)
 ```
 
 ## Codable with URLSession
 
+Check the HTTP status before decoding; a 404 body decoded as your model yields
+a confusing error.
+
 ```swift
-func fetchUser(id: Int) async throws -> User {
-    let url = URL(string: "https://api.example.com/users/\(id)")!
-    let (data, response) = try await URLSession.shared.data(from: url)
-    guard let http = response as? HTTPURLResponse,
-          (200...299).contains(http.statusCode) else {
-        throw APIError.invalidResponse
-    }
-    let decoder = JSONDecoder()
-    decoder.keyDecodingStrategy = .convertFromSnakeCase  // simple keys only; keep CodingKeys for URL/URI/ID
-    decoder.dateDecodingStrategy = .iso8601
-    return try decoder.decode(User.self, from: data)
+enum FetchFailure: Error { case badStatus(Int), notHTTP }
+
+func fetchAuthors(from endpoint: URL) async throws -> [Author] {
+    let (body, reply) = try await URLSession.shared.data(from: endpoint)
+    guard let http = reply as? HTTPURLResponse else { throw FetchFailure.notHTTP }
+    guard (200...299).contains(http.statusCode) else { throw FetchFailure.badStatus(http.statusCode) }
+
+    let reader = JSONDecoder()
+    reader.keyDecodingStrategy = .convertFromSnakeCase   // CodingKeys still cover URL, URI, ID names
+    reader.dateDecodingStrategy = .iso8601
+    return try reader.decode([Author].self, from: body)
 }
+```
+
+### Generic response envelope
+
+```swift
+struct Envelope<Payload: Decodable>: Decodable {
+    let data: Payload
+    let paging: Paging?
 
-// Generic API envelope. Configure a decoder inside this helper because
-// fetchUser's decoder is out of scope.
-struct APIResponse<T: Decodable>: Decodable {
-    let data: T
-    let meta: Meta?
-    struct Meta: Decodable { let page: Int; let totalPages: Int }
+    struct Paging: Decodable {
+        let page: Int
+        let pageCount: Int
+    }
 }
 
-func decodeUsersEnvelope(from data: Data) throws -> [User] {
-    let decoder = JSONDecoder()
-    decoder.keyDecodingStrategy = .convertFromSnakeCase  // simple keys only; keep CodingKeys for URL/URI/ID
-    decoder.dateDecodingStrategy = .iso8601
-    return try decoder.decode(APIResponse<[User]>.self, from: data).data
+func unwrap<Payload: Decodable>(_ type: Payload.Type, from body: Data) throws -> Payload {
+    let reader = JSONDecoder()
+    reader.keyDecodingStrategy = .convertFromSnakeCase
+    reader.dateDecodingStrategy = .iso8601
+    return try reader.decode(Envelope<Payload>.self, from: body).data
 }
 ```
 
+The helper builds its own decoder. A decoder configured inside another function
+is not in scope here, and code that refers to it will not compile.
+
 ## Codable with SwiftData
 
-SwiftData persists compatible noncomputed stored properties declared on `@Model`
-types. Use `Codable` structs, enums, and other value types directly when that
-value is part of the durable model schema:
+SwiftData stores the noncomputed stored properties of an `@Model` class when
+their types are supported, and Codable structs and enums are supported. Use
+them as typed properties directly:
 
 ```swift
-struct Address: Codable {
+struct PostalAddress: Codable {
     var street: String
     var city: String
-    var zipCode: String
+    var postcode: String
 }
 
-@Model class Contact {
+@Model
+final class Customer {
     var name: String
-    var address: Address?  // Codable value-type property stored by SwiftData
-    init(name: String, address: Address? = nil) {
-        self.name = name; self.address = address
+    var billing: PostalAddress?
+
+    init(name: String, billing: PostalAddress? = nil) {
+        self.name = name
+        self.billing = billing
     }
 }
 ```
 
-Do not recommend `@Attribute(.transformable)`, encoded `Data`, or encoded
-`String` as a fallback in this Codable skill. Keep schema data as typed
-SwiftData properties and defer unsupported persistence designs to the SwiftData skill.
+Do not suggest `@Attribute(.transformable)`, a JSON `Data` blob or a JSON
+`String` column as a workaround here. Keep the property typed. If a design
+needs something SwiftData cannot store, hand it to the SwiftData skill.
 
 ## Codable with UserDefaults
 
-`@AppStorage` is only for small UserDefaults-backed preferences. Store `Bool`,
-numeric, `String`, or a `RawRepresentable` type with a primitive raw value. For
-a small `Codable` preference payload, prefer `RawRepresentable` with JSON
-`String` raw storage so `@AppStorage` binds the typed preference directly:
+`@AppStorage` is for small preferences: `Bool`, numbers, `String`, `URL`,
+`Data`, or a `RawRepresentable` whose raw value is `Int` or `String`. A small
+Codable preference can ride on a JSON string raw value:
 
 ```swift
-struct UserPreferences: Codable {
-    var showOnboarding: Bool = true
-    var accentColor: String = "blue"
+struct PlaybackPrefs: Codable {
+    var speed: Double = 1.0
+    var skipSilence = false
+
+    init() {}
+
+    enum CodingKeys: String, CodingKey { case speed, skipSilence }
+
+    init(from decoder: any Decoder) throws {
+        let fields = try decoder.container(keyedBy: CodingKeys.self)
+        speed = try fields.decodeIfPresent(Double.self, forKey: .speed) ?? 1.0
+        skipSilence = try fields.decodeIfPresent(Bool.self, forKey: .skipSilence) ?? false
+    }
+
+    func encode(to encoder: any Encoder) throws {
+        var fields = encoder.container(keyedBy: CodingKeys.self)
+        try fields.encode(speed, forKey: .speed)
+        try fields.encode(skipSilence, forKey: .skipSilence)
+    }
 }
 
-extension UserPreferences: RawRepresentable {
+extension PlaybackPrefs: RawRepresentable {
     init?(rawValue: String) {
-        guard let data = rawValue.data(using: .utf8),
-              let decoded = try? JSONDecoder().decode(Self.self, from: data)
-        else { return nil }
-        self = decoded
+        guard let bytes = rawValue.data(using: .utf8),
+              let value = try? JSONDecoder().decode(PlaybackPrefs.self, from: bytes) else { return nil }
+        self = value
     }
+
     var rawValue: String {
-        guard let data = try? JSONEncoder().encode(self),
-              let string = String(data: data, encoding: .utf8)
-        else { return "{}" }
-        return string
+        guard let bytes = try? JSONEncoder().encode(self),
+              let text = String(data: bytes, encoding: .utf8) else { return "{}" }
+        return text
     }
 }
 
-struct SettingsView: View {
-    @AppStorage("userPrefs") private var prefs = UserPreferences()
+struct PlaybackSettingsView: View {
+    @AppStorage("playbackPrefs") private var prefs = PlaybackPrefs()
+
     var body: some View {
-        Toggle("Show Onboarding", isOn: $prefs.showOnboarding)
+        Toggle("Skip silence", isOn: $prefs.skipSilence)
     }
 }
 ```
 
-## Common Mistakes
-
-**1. Not handling missing defaulted fields:**
-```swift
-// DON'T -- crashes if key is absent
-let value = try container.decode(String.self, forKey: .bio)
-// DO -- falls back when the key is absent or null
-let value = try container.decodeIfPresent(String.self, forKey: .bio) ?? ""
-```
-
-**2. Failing entire array when one element is invalid:**
-```swift
-// DON'T -- one bad element kills the whole decode
-let items = try container.decode([Item].self, forKey: .items)
-// DO -- use LossyArray or decode elements individually
-let items = try container.decode(LossyArray<Item>.self, forKey: .items).elements
-```
-
-**3. Date strategy mismatch:**
-```swift
-// DON'T -- default strategy expects Double, but API sends ISO string
-let decoder = JSONDecoder()  // dateDecodingStrategy defaults to .deferredToDate
-// DO -- set strategy to match your API format
-decoder.dateDecodingStrategy = .iso8601
-```
-
-**4. Force-unwrapping decoded optionals:**
-```swift
-// DON'T
-let user = try? decoder.decode(User.self, from: data)
-print(user!.name)
-// DO
-guard let user = try? decoder.decode(User.self, from: data) else { return }
-```
-
-**5. Using Codable when only Decodable is needed:**
-```swift
-// DON'T -- unnecessarily constrains the type to also be Encodable
-struct APIResponse: Codable { let id: Int; let message: String }
-// DO -- use Decodable for read-only API responses
-struct APIResponse: Decodable { let id: Int; let message: String }
-```
-
-**6. Manual CodingKeys for simple snake_case APIs:**
-```swift
-// DON'T -- verbose boilerplate for every model
-enum CodingKeys: String, CodingKey {
-    case userName = "user_name"
-    case avatarUrl = "avatar_url"
-}
-// DO -- configure once on the decoder for simple cases
-decoder.keyDecodingStrategy = .convertFromSnakeCase
-// Keep CodingKeys for `imageURL`, `baseURI`, `userID`, and similar names.
-```
-
-## Review Checklist
-
-- [ ] Types conform to `Decodable` only when encoding is not needed
-- [ ] `decodeIfPresent` used with defaults for optional or missing keys
-- [ ] `keyDecodingStrategy = .convertFromSnakeCase` used for simple snake_case APIs, with CodingKeys retained for acronym spellings
-- [ ] `dateDecodingStrategy` matches the API date format
-- [ ] Arrays of unreliable data use lossy decoding to skip invalid elements
-- [ ] Custom `init(from:)` validates and transforms data instead of post-decode fixups
-- [ ] `JSONEncoder.outputFormatting` includes `.sortedKeys` for deterministic test output
-- [ ] Wrapper types (UserID, etc.) use `singleValueContainer` for clean JSON
-- [ ] Generic `APIResponse<T>` wrapper used for consistent API envelope handling
-- [ ] No force-unwrapping of decoded values
-- [ ] Persistence boundary is explicit: SwiftData only for compatible noncomputed model properties, `@AppStorage`/UserDefaults only for small primitive or `RawRepresentable` preferences
+Two details make this bridge safe:
+
+- `encode(to:)` and `init(from:)` are written out. When a type is both
+  `RawRepresentable` and Codable, the standard library's `RawRepresentable`
+  defaults would otherwise encode `rawValue`, which encodes `self`, which
+  recurses until the stack overflows.
+- Decoding uses `decodeIfPresent` with defaults, so the `"{}"` fallback and
+  values stored by an older version with fewer keys still decode. Synthesized
+  decoding would ignore the property defaults and fail on `{}`.
+
+## Common mistakes
+
+1. **`decode` for a key that may be absent.** It throws `keyNotFound`. Use
+   `decodeIfPresent` with `??` and a default.
+2. **One bad element sinks the array.** Use a tolerant wrapper such as
+   `TolerantList` or decode elements one by one.
+3. **ISO dates with the default strategy.** The default is `.deferredToDate`,
+   which expects a number of seconds since 1 January 2001. Set `.iso8601` for
+   ISO 8601 strings.
+4. **Force-unwrapping `try?` results.** Bind with `guard let` and handle the
+   failure.
+5. **Codable on read-only responses.** Declare `Decodable`.
+6. **Hand-mapping every snake_case key.** Set `.convertFromSnakeCase` once and
+   keep `CodingKeys` for the acronym names the strategy cannot produce.
+
+## Review checklist
+
+- [ ] `Decodable` alone where encoding is not needed
+- [ ] Optional or missing keys use `decodeIfPresent` with defaults
+- [ ] `.convertFromSnakeCase` for plain snake_case APIs; `CodingKeys` for URL, URI, ID style names
+- [ ] Date strategy matches the API's format
+- [ ] Unreliable arrays decode tolerantly
+- [ ] Conversion and validation happen in `init(from:)`, not in fix-ups after decoding
+- [ ] `.sortedKeys` where output is compared in tests
+- [ ] Wrapper types use `singleValueContainer()`
+- [ ] Responses share a generic envelope such as `Envelope<Payload>`
+- [ ] No force unwraps of decoded values
+- [ ] Persistence boundary is explicit: typed Codable properties on SwiftData models, `@AppStorage` only for small primitive or `RawRepresentable` preferences
 
 ## References
 
-- [Codable](https://sosumi.ai/documentation/swift/codable/) -- protocol combining Encodable and Decodable
-- [JSONDecoder](https://sosumi.ai/documentation/foundation/jsondecoder/) -- decodes JSON data into Codable types
-- [JSONEncoder](https://sosumi.ai/documentation/foundation/jsonencoder/) -- encodes Codable types as JSON data
-- [CodingKey](https://sosumi.ai/documentation/swift/codingkey/) -- protocol for encoding/decoding keys
-- [JSONDecoder.KeyDecodingStrategy.convertFromSnakeCase](https://sosumi.ai/documentation/foundation/jsondecoder/keydecodingstrategy-swift.enum/convertfromsnakecase) -- snake-case conversion behavior and limitations
-- [Encoding and Decoding Custom Types](https://sosumi.ai/documentation/foundation/encoding-and-decoding-custom-types/) -- Apple guide on custom Codable conformance
-- [Using JSON with Custom Types](https://sosumi.ai/documentation/foundation/archives_and_serialization/using_json_with_custom_types/) -- Apple sample code for JSON patterns
-- [Preserving your app's model data across launches](https://sosumi.ai/documentation/swiftdata/preserving-your-apps-model-data-across-launches) -- SwiftData model property compatibility
+- [Codable](https://developer.apple.com/documentation/swift/codable)
+- [JSONDecoder](https://developer.apple.com/documentation/foundation/jsondecoder)
+- [JSONEncoder](https://developer.apple.com/documentation/foundation/jsonencoder)
+- [CodingKey](https://developer.apple.com/documentation/swift/codingkey)
+- [JSONDecoder.KeyDecodingStrategy.convertFromSnakeCase](https://developer.apple.com/documentation/foundation/jsondecoder/keydecodingstrategy/convertfromsnakecase)
+- [Encoding and Decoding Custom Types](https://developer.apple.com/documentation/foundation/encoding-and-decoding-custom-types)
+- [Using JSON with Custom Types](https://developer.apple.com/documentation/foundation/using-json-with-custom-types)
+- [Preserving your app's model data across launches](https://developer.apple.com/documentation/swiftdata/preserving-your-apps-model-data-across-launches)