Swift Codable Patterns

Comprehensive guide to Codable protocol conformance for JSON and PropertyList encoding/decoding in Swift 6.x.

Quick Reference

Decision Tree: When to Use Each Approach

Has your type...
├─ All properties Codable? → Automatic synthesis (just add `: Codable`)
├─ Property names differ from JSON keys? → CodingKeys customization
├─ Needs to exclude properties? → CodingKeys customization
├─ Enum with associated values? → Check enum synthesis patterns
├─ Needs structural transformation? → Manual implementation + bridge types
├─ Needs data not in JSON? → DecodableWithConfiguration (iOS 15+)
└─ Complex nested JSON? → Manual implementation + nested containers

Common Triggers

Error	Solution
"Type 'X' does not conform to protocol 'Decodable'"	Ensure all stored properties are Codable
"No value associated with key X"	Check CodingKeys match JSON keys
"Expected to decode X but found Y instead"	Type mismatch; check JSON structure or use bridge type
"keyNotFound"	JSON missing expected key; make property optional or provide default
"Date parsing failed"	Configure dateDecodingStrategy on decoder

---

Part 1: Automatic Synthesis

Swift automatically synthesizes Codable conformance when all stored properties are Codable.

Struct Synthesis

// ✅ Automatic synthesis
struct User: Codable {
    let id: UUID              // Codable
    var name: String          // Codable
    var membershipPoints: Int // Codable
}

// JSON: {"id":"...", "name":"Alice", "membershipPoints":100}

Requirements:

• All stored properties must conform to Codable
• Properties use standard Swift types or other Codable types
• No custom initialization logic needed

Enum Synthesis Patterns

Pattern 1: Raw Value Enums

enum Direction: String, Codable {
    case north, south, east, west
}

// Encodes as: "north"

The raw value itself becomes the JSON representation.

Pattern 2: Enums Without Associated Values

enum Status: Codable {
    case success
    case failure
    case pending
}

// Encodes as: {"success":{}}

Each case becomes an object with the case name as the key and empty dictionary as value.

Pattern 3: Enums With Associated Values

enum APIResult: Codable {
    case success(data: String, count: Int)
    case error(code: Int, message: String)
}

// success case encodes as:
// {"success":{"data":"example","count":5}}

Gotcha: Unlabeled associated values generate _0, _1 keys:

enum Command: Codable {
    case store(String, Int)  // ❌ Unlabeled
}

// Encodes as: {"store":{"_0":"value","_1":42}}

Fix: Always label associated values for predictable JSON:

enum Command: Codable {
    case store(key: String, value: Int)  // ✅ Labeled
}

// Encodes as: {"store":{"key":"value","value":42}}

When Synthesis Breaks

Automatic synthesis fails when:

1. Computed properties - Only stored properties are encoded
2. Non-Codable properties - Custom types without Codable conformance
3. Property wrappers - @Published, @State (except @AppStorage with Codable types)
4. Class inheritance - Subclasses must implement init(from:) manually

---

Part 2: CodingKeys Customization

Use CodingKeys enum to customize encoding/decoding without full manual implementation.

Renaming Keys

struct Article: Codable {
    let url: URL
    let title: String
    let body: String

    enum CodingKeys: String, CodingKey {
        case url = "source_link"      // JSON uses "source_link"
        case title = "content_name"   // JSON uses "content_name"
        case body                     // Matches JSON key
    }
}

// JSON: {"source_link":"...", "content_name":"...", "body":"..."}

Excluding Properties

Omit properties from CodingKeys to exclude them from encoding/decoding:

struct NoteCollection: Codable {
    let name: String
    let notes: [Note]
    var localDrafts: [Note] = []  // ✅ Must have default value

    enum CodingKeys: CodingKey {
        case name
        case notes
        // localDrafts omitted - not encoded/decoded
    }
}

Rule: Excluded properties require default values or you must implement init(from:) manually.

Snake Case Conversion

For consistent snake_case → camelCase conversion:

let decoder = JSONDecoder()
decoder.keyDecodingStrategy = .convertFromSnakeCase

// JSON: {"first_name":"Alice", "last_name":"Smith"}
// Decodes to: User(firstName: "Alice", lastName: "Smith")

Enum Associated Value Keys

Customize keys for enum associated values using {CaseName}CodingKeys:

enum Command: Codable {
    case store(key: String, value: Int)
    case delete(key: String)

    enum StoreCodingKeys: String, CodingKey {
        case key = "identifier"  // Renames "key" to "identifier"
        case value = "data"      // Renames "value" to "data"
    }

    enum DeleteCodingKeys: String, CodingKey {
        case key = "identifier"
    }
}

// store case encodes as: {"store":{"identifier":"x","data":42}}

Pattern: {CaseName}CodingKeys with capitalized case name.

---

Part 3: Manual Implementation

For structural differences between JSON and Swift models, implement init(from:) and encode(to:).

Container Types

Container	When to Use
Keyed	Dictionary-like data with string keys
Unkeyed	Array-like sequential data
Single-value	Wrapper types that encode as a single value
Nested	Hierarchical JSON structures

Nested Containers Example

Flatten hierarchical JSON:

// JSON:
// {
//   "latitude": 37.7749,
//   "longitude": -122.4194,
//   "additionalInfo": {
//     "elevation": 52
//   }
// }

struct Coordinate {
    var latitude: Double
    var longitude: Double
    var elevation: Double  // Nested in JSON, flat in Swift

    enum CodingKeys: String, CodingKey {
        case latitude, longitude, additionalInfo
    }

    enum AdditionalInfoKeys: String, CodingKey {
        case elevation
    }
}

extension Coordinate: Decodable {
    init(from decoder: Decoder) throws {
        let values = try decoder.container(keyedBy: CodingKeys.self)
        latitude = try values.decode(Double.self, forKey: .latitude)
        longitude = try values.decode(Double.self, forKey: .longitude)

        let additionalInfo = try values.