Make your data types encodable and decodable for compatibility with external representations such as JSON.
- Swift Standard Library
Many programming tasks involve sending data over a network connection, saving data to disk, or submitting data to APIs and services. These tasks often require data to be encoded and decoded to and from an intermediate format while the data is being transferred.
The Swift standard library defines a standardized approach to data encoding and decoding. You adopt this approach by implementing the
Decodable protocols on your custom types. Adopting these protocols lets implementations of the
Decoder protocols take your data and encode or decode it to and from an external representation such as JSON or property list. To support both encoding and decoding, declare conformance to
Codable, which combines the
Decodable protocols. This process is known as making your types codable.
Encode and Decode Automatically
The simplest way to make a type codable is to declare its properties using types that are already
Codable. These types include standard library types like
Double; and Foundation types like
URL. Any type whose properties are codable automatically conforms to
Codable just by declaring that conformance.
Landmark structure that stores the name and founding year of a landmark:
Codable to the inheritance list for
Landmark triggers an automatic conformance that satisfies all of the protocol requirements from
Codable on your own types enables you to serialize them to and from any of the built-in data formats, and any formats provided by custom encoders and decoders. For example, the
Landmark structure can be encoded using both the
JSONEncoder classes, even though
Landmark itself contains no code to specifically handle property lists or JSON.
The same principle applies to custom types made up of other custom types that are codable. As long as all of its properties are
Codable, any custom type can also be
The example below shows how automatic
Codable conformance applies when a
location property is added to the
Built-in collections such as
Dictionary also conform to
Codable whenever they contain codable types. You can add an array of
Coordinate instances to
Landmark, and the entire structure will still satisfy
Encoding or Decoding Exclusively
In some cases, you may not need
Codable's support for bidirectional encoding and decoding. For example, some apps only need to make calls to a remote network API and do not need to decode a response containing the same type. Declare conformance to
Encodable if you only need to support the encoding of data. Conversely, declare conformance to
Decodable if you only need to read data of a given type.
The examples below show alternative declarations of the
Landmark structure that only encode or decode data:
Rename Properties Using Coding Keys
If the keys used in your serialized data format don't match the property names from your data type, provide alternate keys by adding a nested enumeration named
Coding that conforms to the
Coding protocol. This lets you name your data structures according to the Swift API Design Guidelines rather than having to match the names, punctuation, and capitalization of the serialization format you're modeling.
The example below uses alternate keys for the
founding properties of the
Landmark structure when encoding and decoding:
Encode and Decode Manually
If the structure of your Swift type differs from the structure of its encoded form, you can provide a custom implementation of
Decodable to define your own encoding and decoding logic.
In the examples below, the
Coordinate structure is expanded to support an
elevation property that's nested inside of an
Because the encoded form of the
Coordinate type contains a second level of nested information, the type's adoption of the
Decodable protocols uses two enumerations that each list the complete set of coding keys used on a particular level.
In the example below, the
Coordinate structure is extended to conform to the
Decodable protocol by implementing its required initializer,
The initializer populates a
Coordinate instance by using methods on the
Decoder instance it receives as a parameter. The
Coordinate instance's two properties are initialized using the keyed container APIs provided by the Swift standard library.
The example below shows how the
Coordinate structure can be extended to conform to the
Encodable protocol by implementing its required method,
This implementation of the
encode(to:) method reverses the decoding operation from the previous example.