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

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

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.