swift-codable

intent

encode and decode swift types using codable (encodable & decodable) with jsondecoder, jsonencoder, and related apis. use this skill when you need to transform json or plist payloads into strongly-typed swift objects, handle mismatched key names between your api and model layer, apply custom transformations (date formats, nested flattening, lossy arrays), and round-trip data bidirectionally. targets swift 6.3+, ios 18+.

inputs

• json or plist data: raw bytes from api response, file system, or userdefaults
• swift type conforming to codable: struct or class with codable conformance (synthesized or custom)
• decoder configuration (optional): datedecodingstrategy, keydecodingstrategy, datadecodingstrategy
• encoder configuration (optional): dateencodingstrategy, keyencodingstrategy, outputformatting
• urlsession (when fetching): initialized session with auth headers or credentials if needed
• external api (when applicable): endpoint url, expected response envelope, error codes

procedure

1. declare the model with basic conformance

inputs: struct/class definition, list of properties

outputs: type that conforms to codable (auto-synthesized)

when all stored properties are themselves codable, the compiler synthesizes conformance automatically:

struct User: Codable {
    let id: Int
    let name: String
    let email: String
    let isVerified: Bool
}

prefer decodable for read-only api responses and encodable for write-only. use codable only when both directions are required by the contract.

2. handle key name mismatches with codingkeys

inputs: json key names from api, property names in swift model

outputs: codingkeys enum mapping swift names to json keys

when json uses snake_case but swift uses camelCase, declare a codingkeys enum:

struct Product: Codable {
    let id: Int
    let displayName: String
    let imageURL: URL
    let priceInCents: Int

    enum CodingKeys: String, CodingKey {
        case id
        case displayName = "display_name"
        case imageURL = "image_url"
        case priceInCents = "price_in_cents"
    }
}

every stored property must appear in the enum. omitting a property from codingkeys excludes it from encoding/decoding.

alternatively, configure the decoder with keydecoding strategy:

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

use keydecoding strategy only for mechanical snake_case-to-camelCase mappings. if the swift model uses acronyms (imageURL, baseURI, userID), keep explicit codingkeys because the strategy maps by spelling, not acronym policy.

3. configure decoder for date format and data encoding

inputs: api date format string or strategy enum, data encoding (e.g., base64)

outputs: configured jsondecoder ready to handle dates and binary data

match the decoder strategy to the api format:

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)")
}

// base64-encoded data fields
decoder.dataDecodingStrategy = .base64

4. implement custom init(from:) for transformations

inputs: decoder, codingkeys enum, logic to transform raw values

outputs: fully initialized instance with computed or transformed properties

override init(from:) when synthesized conformance cannot handle your transformation:

struct Event: Codable {
    let name: String
    let timestamp: Date
    let tags: [String]

    enum CodingKeys: String, CodingKey {
        case name, timestamp, tags
    }

    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) ?? []
    }

    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)
    }
}

use decodeIfPresent instead of decode for optional or missing keys. validate and transform data inside init(from:), not in post-decode fixups.

5. flatten nested json with nested containers

inputs: decoder, nested codingkeys enum, path to nested object

outputs: flattened properties extracted from nested structure

use nestedcontainer(keyedby:forkey:) to navigate and flatten nested json:

// json: { "id": 1, "location": { "lat": 37.7749, "lng": -122.4194 } }
struct Place: Decodable {
    let id: Int
    let latitude: Double
    let longitude: Double

    enum CodingKeys: String, CodingKey { case id, location }
    enum LocationKeys: String, CodingKey { case lat, lng }

    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)
    }
}

chain multiple nestedcontainer calls to flatten deeply nested structures. use nestedunkeyedcontainer(forkey:) for nested arrays.

6. use single value containers for wrapper types

inputs: decoder, primitive value to wrap

outputs: type-safe wrapper (e.g., userID, articleslug)

use singlevaluecontainer() for wrapper types to keep json clean:

struct UserID: Codable {
    let value: Int
    
    init(from decoder: Decoder) throws {
        let container = try decoder.singleValueContainer()
        value = try container.decode(Int.self)
    }
    
    func encode(to encoder: Encoder) throws {
        var container = encoder.singleValueContainer()
        try container.encode(value)
    }
}

// json: 42 decodes to UserID(value: 42)

7. handle lossy array decoding when partial success is allowed

inputs: array of items, some of which may be malformed

outputs: array containing only valid elements (invalid ones skipped)

decode array elements individually only when partial success is allowed by the contract:

struct APIResponse: Decodable {
    let items: [Item]
    
    enum CodingKeys: String, CodingKey { case items }
    
    init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        var itemsArray: [Item] = []
        if var unkeyedContainer = try? container.nestedUnkeyedContainer(forKey: .items) {
            while !unkeyedContainer.isAtEnd {
                if let item = try? unkeyedContainer.decode(Item.self) {
                    itemsArray.append(item)
                } else {
                    _ = try unkeyedContainer.decode(AnyCodable.self)  // skip invalid
                }
            }
        }
        items = itemsArray
    }
}

use lossy arrays only when the product contract explicitly allows partial success. do not hide contract failures with lossy decoding.

8. decode from urlsession with envelope

inputs: url, decoder configuration, expected response envelope type

outputs: decoded model extracted from api response

fetch and decode from an api endpoint:

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
    decoder.dateDecodingStrategy = .iso8601
    return try decoder.decode(User.self, from: data)
}

// generic api envelope
struct APIResponse<T: Decodable>: Decodable {
    let data: T
    let meta: Meta?
    struct Meta: Decodable { let page: Int; let totalPages: Int }
}

func decodeUsersEnvelope(from data: Data) throws -> [User] {
    let decoder = JSONDecoder()
    decoder.keyDecodingStrategy = .convertFromSnakeCase
    decoder.dateDecodingStrategy = .iso8601
    return try decoder.decode(APIResponse<[User]>.self, from: data).data
}

9. encode with matching strategies and deterministic output

inputs: codable instance, encoder configuration

outputs: json or plist data ready for transport

match encoder strategies to the decoder:

let encoder = JSONEncoder()
encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
encoder.dateEncodingStrategy = .iso8601
encoder.dataEncodingStrategy = .base64
encoder.keyEncodingStrategy = .convertToSnakeCase

let encoded = try encoder.encode(user)

include .sortedkeys for deterministic test output. set the matching strategy on both encoder and decoder to ensure round-trip fidelity.

10. test with representative fixtures and verify round trips

inputs: json fixtures covering success, missing, null, malformed, acronym-key, and date formats

outputs: confirmed model instances or handled decodingerror

decode representative success, missing, null, malformed, acronym-key, and date fixtures:

func testDecodeUser() throws {
    let json = """
    {"id": 1, "name": "alice", "email": "alice@example.com", "is_verified": true}
    """.data(using: .utf8)!
    
    let decoder = JSONDecoder()
    decoder.keyDecodingStrategy = .convertFromSnakeCase
    let user = try decoder.decode(User.self, from: json)
    XCTAssertEqual(user.id, 1)
}

func testRoundTrip() throws {
    let original = User(id: 1, name: "alice", email: "alice@example.com", isVerified: true)
    let encoded = try JSONEncoder().encode(original)
    let decoded = try JSONDecoder().decode(User.self, from: encoded)
    XCTAssertEqual(original.id, decoded.id)
    XCTAssertEqual(original.name, decoded.name)
}

on failure, inspect decodingerror, its codingpath, and the raw payload. correct only the mismatched model, key, container, or strategy. do not hide contract failures with lossy decoding. rerun fixtures and encode/decode round trips where both directions are part of the contract.

decision points

if the json uses simple snake_case consistently: configure keydecoding strategy on the decoder. omit explicit codingkeys to reduce boilerplate.

if the json uses acronyms (imageurl, baseuri, userid) or mixed conventions: declare explicit codingkeys instead, because keydecoding strategy maps by spelling and will not synthesize acronym names.

if the api returns dates as iso 8601 strings: set decoder.datedecodingstrategy = .iso8601.

if the api returns dates as unix timestamps: set decoder.datedecodingstrategy = .secondssince1970 or .millisecondssince1970.

if the api returns dates in a custom format: create a dateformatter with the exact format string and configure decoder.datedecodingstrategy = .formatted(formatter). test with explicit locale and timezone.

if the api returns custom date formats and you need to try multiple parsers: use decoder.datedecodingstrategy = .custom { decoder in ... } to attempt each format and throw a clear decodingerror if all fail.

if a required key is missing and you have a sensible default: use decodeifpresent with ?? fallback. do not rely on stored property defaults; synthesized decoding does not tolerate missing nonoptional keys.

if a json field is optional or may be null: decode it with decodeifpresent and provide a fallback (nil, empty array, zero, etc.). do not use decode on optional keys.

if the api response wraps your data in an envelope (e.g., { "data": [...], "meta": {...} }): create a generic wrapper struct apiresonse<t: decodable> and decode the envelope first, then extract the inner type.

if an array may contain malformed elements and partial success is acceptable: decode array elements individually in init(from:) with lossy skipping. only use this when the contract explicitly allows data loss.

if an array element is guaranteed to fail if one element is invalid: decode the whole array with decode([item].self, forkey:); let the error propagate to the caller.

if you need both encoding and decoding: use codable. if only decoding is needed for api responses, use decodable. if only encoding is needed for requests, use encodable.

if you are persisting to swiftdata: keep only codable properties that swiftdata supports (no computed properties, no lazy properties, no transient fields). do not encode the entire swiftdata model; map codable properties explicitly.

if you are persisting to userdefaults: use primitives or rawrepresentable types with @appstorage. do not encode large codable objects to userdefaults; use swiftdata or a real persistence layer.

if the api returns non-conforming floats (nan, infinity): configure encoder/decoder with the nonconformingfloatstrategy.

output contract

• decoded instance: strongly-typed swift model matching the api response structure, all required fields populated, optional fields either nil or populated with fallback values.
• encoded data: json or plist bytes in the format matching the decoder's expected input (sorted keys if .sortedkeys was set, snake_case keys if keygencostrategy was applied, dates in the configured format).
• error on failure: decodingerror or encodingerror with codingpath pointing to the mismatched field, type information, and human-readable debug description. do not suppress or silently default on decode failure unless lossy array skipping is part of the contract.
• file location (if persisted): userdefaults key, swiftdata store url, or document directory path where the encoded data was written.

outcome signal

• decoded model prints without force-unwrapping or post-decode fixups; all properties are directly accessible.
• encode/decode round trip produces a byte-identical payload (byte-for-byte if .sortedkeys was applied, logically equivalent if date precision differs).
• test suite passes on representative fixtures: valid payloads decode successfully, invalid payloads throw decodingerror with clear codingpath, and date/key mismatches are caught early.
• urlsession integration fetches and decodes in a single chain with no manual json parsing.
• swiftdata models persist and round-trip without losing type information or violating schema constraints.