How to use custom names for Swift properties when decoding JSON data

Swift's Codable protocol makes it straightforward to convert JSON data into native Swift types and vice versa. In some cases, however, we may want to customize how JSON keys map to Swift properties.

For example, the JSON returned by an API might use different naming conventions than our Swift models, or it might contain keys that we want to ignore.

Let's look at how to customize this behavior.

Architecture & Design Patterns for iOS

This book is a practical guide to essential architectural principles and design patterns for iOS development. It covers strategies for building maintainable apps with Swift and SwiftUI, including dependency injection, navigation, common patterns, and modularization.

LEARN MORE

Types conforming to Codable can declare a nested enumeration called CodingKeys that conforms to the CodingKey protocol. The cases of this enumeration define which properties participate in encoding and decoding.

By default, Swift expects the case names to match the property names.

Assume we receive the following JSON response from a server:

{
  "username": "user123",
  "validated": true
}

And we want to map it to the following Swift type:

struct User: Codable {

    let username: String
    let isValidated: Bool
}

In this example, the JSON key validated does not match our Swift property name isValidated.

To map the JSON key to our property, we can define a custom CodingKeys enum:

struct User: Codable {

    let username: String
    let isValidated: Bool

    enum CodingKeys: String, CodingKey {
        case username
        case isValidated = "validated"
  }
}

By assigning a raw value to a case, we explicitly tell Swift which JSON key corresponds to the property.

During decoding, the value of the JSON key validated will now be assigned to the isValidated property of the User struct.