Swift JSON Parsing: Codable Guide

Apple has introduced a new way to decode and encode the JSON data using Codable since Swift 4.0 version.

In order to send and retrieve information in JSON format, most applications need to communicate with the server. A proper format for storing JSON data in models is needed. To store the JSON data, we encode and decode it according to the JSON data.

Many developers still rely on manual methods for parsing JSON, such as NSJSONSerialization or custom initializers, despite the Codable protocol. These approaches may work, but they introduce unnecessary complexity and increase the risk of errors when dealing with large datasets. Codable reduces boilerplate code and ensures type safety when parsing JSON.

By manually parsing JSON data, we can always store it in models. As a result, we must parse each object key by key. Would it be a good idea to write lots of code that may not be necessary? No, of course not.

This article will explain the following things:

Fundamental terminology about Codable
How to conform to the Codable?
How to decode and encode the JSON data?
How to parse the JSON key into different property names?
How to parse JSON with nested objects?
How to parse JSON with manual decoding?
How to parse JSON from non-root key?
Other factors…

Let’s start!

Decodable (or Deserialization): By conforming to the Decodable protocol, an object can be converted from JSON to a custom object format. For example:

{
   name: "Swiftable",
   id: 12345
}

To deserialize this we would just have to create a model with properties name matching the JSON fields like:

struct Community: Decodable {
    let id: Int
    let name: String
}

And using the JSONDecoder we would be able to deserialize this like below:

let community = try? JSONDecoder().decode(Community.self, from: jsonData)

Encodable (or Serialization): An object that conforms Encodable protocol can be converted to JSON. For example:

// Creating a sample Community object:
let swiftable = Community(id: 12345, name: "Swiftable")

// Encoding the custom object back into JSON data 
let jsonData = try? JSONEncoder().encode(swiftable)

Codable: A type alias for the Encodable and Decodable protocols. When you use Codable as a type or a generic constraint, it matches any type that conforms to both protocols. Here’s the predefined syntax:

typealias Codable = Decodable & Encodable

Codable is a protocol?

Codable is not a protocol, but it’s actually a type alias that combines two separate protocols: Encodable and Decodable. When you conform a type to Codable, you’re essentially conforming it to both. This makes it possible to handle both encoding and decoding of data with minimal code.

This question has been asked in many interviews. So, don’t be confuse.

Pro Tip: When you don’t need encoding a custom type, use Decodable protocol. In short, Codable is recommended for cases when both (decoding & encoding) are needed. If not, use a specific protocol.

How to conform to the Codable?

We are going to use below data to understand different Codable examples. Let’s take a look at a sample JSON data:

{
    "id": 16,
    "title": "iPhone 14",
    "description": "An apple mobile which is nothing like apple",
    "price": 749,
    "thumbnail": "https://i.dummyjson.com/data/products/1/thumbnail.jpg",
    "images": [
        "https://i.dummyjson.com/data/products/1/1.jpg",
        "https://i.dummyjson.com/data/products/1/2.jpg",
    ]
}

The Product structure should be as follows:

struct Product: Codable {
    let id: Int
    let title: String
    let shortDescription: String
    let price: Int
    let thumbnail: String
    let images: [String]
}

As a result of the JSON data above, we have created a structure called Product. This structure defines some properties with their data types matching corresponding fields in JSON.

The struct must conform to the Decodable (or Codable) protocol in order to convert JSON data into a Product instance.

How to decode & encode the JSON data?

Now we have to store the product information in the product model from the above JSON. For this, we have to use JSONDecoder class by passing the type and valid data object like below:

do {
    let product = try JSONDecoder().decode(Product.self, from: jsonData)
    print("Title: \(product.title) and Price: \(product.price)")
} catch let error {
    print("Error in decoding data: \(error)")
}

// Output:
// Title: iPhone 14 and Price: 749

The decode(from)is a throwable function and it throws an error when an invalid JSON is passed this error contains the exact information as to what keys or data types were expected and what were missing.

To encode the object (i.e. product), we use JSONEncoder().encode(). We can convert the returned JSON data into a JSON string with this method. For example:

do {
    let jsonData = try JSONEncoder().encode(product)
    if let jsonString = String(data: jsonData, encoding: .utf8) {
        print("JSON String: \(jsonString)")
    }
} catch let error {
    print("Error in encoding data: \(error)")
}

// Output:
// JSON String: {"images":["https:\/\/i.dummyjson.com\/data\/products\/1\/1.jpg","https:\/\/i.dummyjson.com\/data\/products\/1\/2.jpg"],"id":16,"title":"iPhone 14","description":"An apple mobile which is nothing like apple","price":749,"thumbnail":"https:\/\/i.dummyjson.com\/data\/products\/1\/thumbnail.jpg"}

To decode and encode the “product” instance, you must conforms both the protocols or Codable.

Is the output confusing to you? A large JSON string will be difficult to understand. What’s next? We can easily print JSON strings in the proper format by setting the output format as follows:

let encoder = JSONEncoder()
encoder.outputFormatting = .prettyPrinted
do {
    let jsonData = try encoder.encode(product)
    if let jsonString = String(data: jsonData, encoding: .utf8) {
        print("JSON String: \(jsonString)")
    }
} catch let error {
    print("Error in encoding data: \(error)")
}

Here is the JSON Output now:

JSON String: {
  "images" : [
    "https:\/\/i.dummyjson.com\/data\/products\/1\/1.jpg",
    "https:\/\/i.dummyjson.com\/data\/products\/1\/2.jpg"
  ],
  "id" : 16,
  "title" : "iPhone 14",
  "description" : "An apple mobile which is nothing like apple",
  "price" : 749,
  "thumbnail" : "https:\/\/i.dummyjson.com\/data\/products\/1\/thumbnail.jpg"
}

Now, it is easy to understand. Yay…!

How can we parse the JSON key into different property names?

There are some cases where our property names do not match the actual keys in the JSON data. Using the CodingKeys enumeration, we can provide alternative keys.

We have to parse some keys into different properties, for example. Using the below example, we need to parse name and shortDescription from different keys. As an example:

struct Product: Codable {
    let id: Int
    let name: String
    let shortDescription: String
    let price: Int
    let thumbnail: String
    let images: [String]

    enum CodingKeys: String, CodingKey {
        case id
        case name = "title"
        case shortDescription = "description"
        case price, thumbnail, images
    }
}

After making the above changes in the Product model, the rest of the process will not need to change to encode and decode the data.

By default, if we do not use the CodingKey enum explicitly, the compiler will auto generate the enum CodingKeys for us, which will map all the Keys of JSON directly to the Product struct without change (eg: ‘id’ from JSON to ‘id’ of Product struct).

If we are using CodingKeys enum for parsing, we have to specify all the property names of a class/struct. If any property name will be missing Compiler will generate a compile-time error.

How to parse JSON with nested objects?

When a JSON object is inside another JSON object, it’s called ‘nested’, and will look like the following JSON structure:

{
    "id": 16,
    "title": "iPhone 14",
    "description": "An apple mobile which is nothing like apple",
    "price": 749,
    "thumbnail": "https://i.dummyjson.com/data/products/1/thumbnail.jpg",
    "images": [
        "https://i.dummyjson.com/data/products/1/1.jpg",
        "https://i.dummyjson.com/data/products/1/2.jpg",
    ],
    "similarProducts": [
        {
            "title": "Apple Watch",
            "price": 599,
            "thumbnailImage": "watch-thumb.jpg",
            "fullImage": "watch-full.jpg",
            "discount": 10
        },
        {
            "title": "iPhone 6",
            "price": 1000,
            "thumbnailImage": "iphone-6-thumb.jpg",
            "fullImage": "iphone-6-full.jpg"
        }
    ]
}

In the above JSON, there is a nested JSON object called similarProducts which is an array of similar products. To store the information about similar products, we have to make some changes in Product model like the following:

struct Product: Codable {

    let id: Int
    let name: String
    let shortDescription: String
    let price: Int
    let thumbnail: String
    let images: [String]
    let similarProducts: [SimilarProduct]

    enum CodingKeys: String, CodingKey {
        case id
        case name = "title"
        case shortDescription = "description"
        case price, thumbnail, images, similarProducts
    }
}

struct SimilarProduct: Codable {
    let title: String
    let price: Int
    let detail: String
    let thumbnailImage: String
    let fullImage: String
    let discount: Int
}

After making the above changes in the Product model, the rest of the process will not need to change to encode and decode the data.

When we decode the above JSON data, we will see an error. The error will be handled in the catch block like this:

catch let error {
    print("Error in decoding data: \(error)")
}

// Error Message:
// Error in decoding data: keyNotFound(CodingKeys(stringValue: "discount", intValue: nil), Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "similarProducts", intValue: nil), _JSONKey(stringValue: "Index 1", intValue: 1)], debugDescription: "No value associated with key CodingKeys(stringValue: \"discount\", intValue: nil) (\"discount\").", underlyingError: nil))

By reading the error message, it clearly says that the discount key is not found in the JSON data while decoding.

We can notice that in the JSON example, the discount key is missing from the last similar product. This is a very common situation in the real world. Often, when we do JSON parsing, many keys are missing or different in the coming API responses.

How to handle this case?

We are not sure whether or not the discount key will be present in JSON data. In that case, we can make the discount property optional, as shown below:

let discount: Int?

Such properties need to be made optional since they might not appear in the JSON data.

When you’re sure about properties, you should always make them optional. Whenever there is a doubt that a value may be nil in any case, make it optional so the app works.

How to parse JSON with manual decoding?

If the structure of our Swift type differs from the structure of its encoded form, we can provide a custom implementation of Encodable and Decodable to define our own encoding and decoding logic.

In the below example, the images (small and large) are nested in JSON data. We need to decode them using custom decoding logic.

Here is an example of JSON:

{
    "id": 16,
    "title": "iPhone 14",
    "description": "An apple mobile which is nothing like apple",
    "price": 749,
    "images": {
        "small": "https://i.dummyjson.com/data/products/1/thumbnail.jpg",
        "large": "https://i.dummyjson.com/data/products/1/1.jpg"
    }
}

We can see the images are nested inside another object. To decode them using a custom implementation, we have to make changes to the Product struct like the below:

struct Product: Decodable {

    let id: Int
    let name: String
    let shortDescription: String
    let price: Int
    let smallImage: String
    let largeImage: String

    enum CodingKeys: String, CodingKey {
        case id
        case name = "title"
        case shortDescription = "description"
        case price, images
    }

    enum ProductImageKeys: String, CodingKey {
        case small
        case large
    }

    init(from decoder: Decoder) throws {

        let values = try decoder.container(keyedBy: CodingKeys.self)
        id = try values.decode(Int.self, forKey: .id)
        name = try values.decode(String.self, forKey: .name)
        shortDescription = try values.decode(String.self, forKey: .shortDescription)
        price = try values.decode(Int.self, forKey: .price)

        // Here, parsing the nested json object to store in properties. We used nestedContainer() method for nested parsing.
        let productImages = try values.nestedContainer(keyedBy: ProductImageKeys.self, forKey: .images)
        smallImage = try productImages.decode(String.self, forKey: .small)
        largeImage = try productImages.decode(String.self, forKey: .large)
    }
}

We required two enumerations here because JSON data has nested objects. The Product structs should conform to the Decodable protocol and implement its initializer init(from decoder: Decoder) to support custom decoding.

In the initializer, we used the nestedContainer() method to get the nested container and decode its values (small and large images).

How to parse JSON into an array of objects?

It’s common to work with APIs that return JSON data in the form of an array of objects. Each object in the array typically represents a specific entity like a user, product, or message. Parsing this JSON into a usable format is essential for displaying and working with this data in your app. Here is the sample JSON data:

[
    {
        "id": 1,
        "title": "iPhone 9",
        "description": "An apple mobile which is nothing like apple",
        "price": 549,
        "thumbnail": "https://i.dummyjson.com/data/products/1/thumbnail.jpg"
    },
    {
        "id": 2,
        "title": "iPhone 13",
        "description": "A superfast phone launched by Apple",
        "price": 949,
        "thumbnail": "https://i.dummyjson.com/data/products/2/thumbnail.jpg"
    }
]

In the above JSON, there is an array of objects that can be decoded like this:

let products = try JSONDecoder().decode([Product].self, from: jsonData)

How to parse JSON from non-root key?

JSON structures where the data you’re interested in is nested under a specific key, rather than at the root level. This can make parsing a bit more challenging, especially if you’re trying to extract an array of objects or a single value from within a more complex JSON structure.

Suppose we have a JSON data that does not have any root key like the below:

{
    "total": 2,
    "products": [
        {
            "id": 1,
            "title": "iPhone 9",
            "description": "An apple mobile which is nothing like apple",
            "price": 549,
            "thumbnail": "https://i.dummyjson.com/data/products/1/thumbnail.jpg"
        },
        {
            "id": 2,
            "title": "iPhone 13",
            "description": "A superfast phone launched by Apple",
            "price": 949,
            "thumbnail": "https://i.dummyjson.com/data/products/2/thumbnail.jpg"
        }
    ]
}

Here are the structs to decode them:

struct ProductList: Codable {
    let total: Int
    let products: [Product]
}

struct Product: Codable {
    let id: Int
    let title: String
    let description: String
    let price: Int
    let thumbnail: String
}

Here is main code to decode product list:

let productList = try JSONDecoder().decode(ProductList.self, from: jsonData)

How to decode non-nested JSON data into nested models?

Here is the sample JSON data:

{
    "id": 1,
    "title": "iPhone 12",
    "price": 649,
    "thumbnail": "https://i.dummyjson.com/data/products/1/thumbnail.jpg",
    "manufacturedBy": "Apple Inc.",
    "manufacturingYear": "2022",
    "firstReleasedDate": "October 2020"
}

struct Product: Decodable {

    let id: Int
    let title: String
    let price: Int
    let thumnail: String
    let manufactureDetail: ManufactureDetail // making separate struct

    enum CodingKeys: String, CodingKey {
        case id, title, price, thumbnail, manufacturedBy, manufacturingYear, firstReleasedDate
    }

    init(from decoder: Decoder) throws {
        let values = try decoder.container(keyedBy: CodingKeys.self)
        id = try values.decode(Int.self, forKey: .id)
        title = try values.decode(String.self, forKey: .title)
        price = try values.decode(Int.self, forKey: .price)
        thumnail = try values.decode(String.self, forKey: .thumbnail)
        manufactureDetail = try ManufactureDetail(from: decoder) // decoding manufacturing details
    }
}

struct ManufactureDetail: Codable {

    let name: String
    let year: String
    let releasedDate: String

    enum CodingKeys: String, CodingKey {
        case name = "manufacturedBy"
        case year = "manufacturingYear"
        case releasedDate = "firstReleasedDate"
    }
}

After making the above changes in the Product model, the rest of the process will not need to change to decode the data.

How to decode multi-nested JSON data?

Here is the sample JSON data:

{
    "id": 1,
    "title": "iPhone 12",
    "price": 649,
    "thumbnail": "https://i.dummyjson.com/data/products/1/thumbnail.jpg",
    "manufacturedDetail": {
        "company": {
            "manufacturedBy": "Apple Inc."
        }
    }
}

In the above JSON, we need to parse the value from the manufacturedBy key which is nested inside a nested object.

To decode this JSON data, we have two approaches. In the first approach, we can create multiple structs according to nested JSON. Nevertheless, it is not recommended to create multiple structs for single key parsing here.

Another approach is to parse the value using the nestedContainer() method like the below:

struct Product: Decodable {

    let id: Int
    let title: String
    let price: Int
    let thumnail: String
    let manufacturedBy: String

    enum RootKeys: String, CodingKey {
        case id, title, price, thumbnail, manufacturedDetail
    }

    enum ManufacturedKeys: String, CodingKey {
        case company
    }

    enum CompanyKeys: String, CodingKey {
        case manufacturedBy
    }

    init(from decoder: Decoder) throws {
        let values = try decoder.container(keyedBy: RootKeys.self)
        id = try values.decode(Int.self, forKey: .id)
        title = try values.decode(String.self, forKey: .title)
        price = try values.decode(Int.self, forKey: .price)
        thumnail = try values.decode(String.self, forKey: .thumbnail)

        // nested containers
        let manufacturedContainer = try values.nestedContainer(keyedBy: ManufacturedKeys.self, forKey: .manufacturedDetail)
        let companyContainer = try manufacturedContainer.nestedContainer(keyedBy: CompanyKeys.self, forKey: .company)
        self.manufacturedBy = try companyContainer.decode(String.self, forKey: .manufacturedBy)
    }
}

After making the above changes in the Product model, the rest of the process will not need to change to decode the data.

We should keep in mind some pros and cons when using the Codable:

These are some benefits of using Codable over manual parsing:

Using it reduces a lot of code because manual parsing is no longer necessary.
When parsing, remove multiple if-let and guard statements.
Ensures that the data you’re working with matches the expected types, reducing runtime errors.

These are some points you should consider while using Codable:

Complex JSON data may require us to write long code.
If we don’t handle it carefully, it won’t work.
If mismatched data types, it will fail without providing detailed error messages by default.
You need to handle errors explicitly to avoid crashes.

Thank you for taking the time to read this article! If you found it helpful, don’t forget to like, share, and leave a comment with your thoughts or feedback. Your support means a lot!

Keep reading,
— Swiftable

Ultimate Guide to JSON Parsing in Swift Using Codable