To keep a Swift Codable model compatible with older in-memory representations, make genuinely absent values optional and implement decoding fallbacks explicitly. Adding a declaration default alone does not make a missing encoded field decode successfully.

This guide is for a Mac developer updating a simple desktop layout model. The concrete task is to let the revised model accept older synthetic representations while preserving supplied values and reporting incompatible types. Every example creates and consumes values in memory.

What changes when a field becomes optional or gains a default?

Codable combines encoding and decoding. Swift can synthesize those implementations when the stored properties support the necessary protocols. That removes routine code, but a change that still compiles can alter which representations the model accepts. Apple documents both automatic conformance and custom implementations in Encoding and Decoding Custom Types.

Consider a layout tile with a required title and subtitle. You now want the subtitle to be optional and want a new column count to default to three. These are two separate decisions: the subtitle may have no value, while the column count must always have a usable value after decoding.

For ordinary mutable properties included in synthesized decoding, Swift treats an optional property as permitting a missing key or a null value. A declaration initializer is not a decoding fallback: an optional property initialized to a non-nil value can still decode as nil, and a nonoptional property with a declaration default can still fail when its key is absent. The Swift team's explanation of Codable synthesis describes this deliberate behavior.

The following decision table translates those rules into a field policy. It assumes an integer field and a present value that is convertible to Int. The final two rows require custom decoding.

Field policy Key absent Explicit null Valid integer Incompatible type
Synthesized var columns: Int Error Error Use value Error
Synthesized var columns: Int = 3 Error Error Use value Error
Synthesized var columns: Int? nil nil Use value Error
Custom fallback for absence and null 3 3 Use value Error
Custom fallback for absence only 3 Error Use value Error

The distinction comes from the container methods. decode(_:forKey:) requires an entry and a non-null convertible value. decodeIfPresent(_:forKey:) returns nil for either absence or null, but still throws for an incompatible type. Applying ?? 3 to the latter result supplies the fallback.

Implement and check the compatibility policy in memory

Use this example in a Swift execution context on your Mac with Foundation available and support for top-level statements, such as an existing playground. Run the entire block together. Foundation's JSONEncoder produces a Data representation, and JSONDecoder creates a new typed value from it. The example uses no literal encoded document or external input.

The chosen policy is explicit: title remains required; an absent or null subtitle becomes nil; an absent or null columns becomes three. A present, incompatible column value remains an error. The custom initializer handles decoding, while encoding remains synthesized under the model's CodingKeys. Apple documents this customization approach in Encoding and Decoding Custom Types.

This is a complete program, including synthetic fixtures and checks. Swift was unavailable in the research environment, so the example was inspected against the documented APIs but was not executed.

import Foundation

struct LegacyTile: Codable {
    var title: String
    var subtitle: String
}

struct Tile: Codable, Equatable {
    static let defaultColumns = 3

    var title: String
    var subtitle: String?
    var columns: Int = Tile.defaultColumns

    enum CodingKeys: String, CodingKey {
        case title, subtitle, columns
    }
}

extension Tile {
    init(from decoder: Decoder) throws {
        let values = try decoder.container(keyedBy: CodingKeys.self)
        title = try values.decode(String.self, forKey: .title)
        subtitle = try values.decodeIfPresent(String.self, forKey: .subtitle)
        columns = try values.decodeIfPresent(Int.self, forKey: .columns)
            ?? Self.defaultColumns
    }
}

struct MinimalTile: Encodable {
    var title: String
}

struct NullTile: Encodable {
    enum CodingKeys: String, CodingKey {
        case title, subtitle, columns
    }

    func encode(to encoder: Encoder) throws {
        var values = encoder.container(keyedBy: CodingKeys.self)
        try values.encode("Circle", forKey: .title)
        try values.encodeNil(forKey: .subtitle)
        try values.encodeNil(forKey: .columns)
    }
}

struct WrongColumnsTile: Encodable {
    var title: String
    var columns: String
}

let encoder = JSONEncoder()
let decoder = JSONDecoder()

// An older representation keeps its subtitle and gains the fallback.
let legacyBytes = try encoder.encode(
    LegacyTile(title: "Circle", subtitle: "Blue")
)
let upgraded = try decoder.decode(Tile.self, from: legacyBytes)
precondition(upgraded.title == "Circle")
precondition(upgraded.subtitle == "Blue")
precondition(upgraded.columns == 3)

// Missing keys and explicit nulls follow the chosen policy.
let minimalBytes = try encoder.encode(MinimalTile(title: "Circle"))
let minimal = try decoder.decode(Tile.self, from: minimalBytes)
precondition(minimal.subtitle == nil)
precondition(minimal.columns == 3)

let nullBytes = try encoder.encode(NullTile())
let explicitNull = try decoder.decode(Tile.self, from: nullBytes)
precondition(explicitNull == minimal)

// A supplied nondefault value survives an encode/decode cycle.
let supplied = Tile(title: "Square", subtitle: "Green", columns: 5)
let suppliedBytes = try encoder.encode(supplied)
let restored = try decoder.decode(Tile.self, from: suppliedBytes)
precondition(restored == supplied)

// Incompatible types must remain visible as decoding failures.
let wrongBytes = try encoder.encode(
    WrongColumnsTile(title: "Circle", columns: "wide")
)
do {
    _ = try decoder.decode(Tile.self, from: wrongBytes)
    preconditionFailure("Expected a type mismatch")
} catch DecodingError.typeMismatch(_, let context) {
    precondition(context.codingPath.last?.stringValue == "columns")
}

// A newer representation may no longer satisfy an older reader.
let currentBytes = try encoder.encode(minimal)
do {
    _ = try decoder.decode(LegacyTile.self, from: currentBytes)
    preconditionFailure("Expected the required subtitle to be missing")
} catch DecodingError.keyNotFound(let key, _) {
    precondition(key.stringValue == "subtitle")
}

print("All in-memory compatibility checks passed.")

The expected final output is All in-memory compatibility checks passed. Unexpected errors propagate instead of being converted into success. The fixtures deliberately cover different representations: MinimalTile omits fields, while NullTile uses encodeNil(forKey:) to create explicit null entries.

Keeping init(from:) in an extension also leaves the structure's memberwise initializer available, allowing the example to construct Tile(title:subtitle:columns:). The custom decoding initializer assigns every stored instance property, so the result is fully initialized before it returns.

Should null use the default, or remain an error?

Choose according to the meaning of the field. For this illustrative layout, treating both absence and null as the standard column count is a reasonable policy. It is still an application decision: decodeIfPresent deliberately combines those two states, and the fallback then gives them the same result. Its documented return behavior makes that consequence explicit.

If absence means “use the standard layout,” but a supplied null should fail, replace only the columns assignment inside the program's init(from:) with this fragment. All other prerequisites and definitions remain the same.

// Replacement fragment inside Tile.init(from:).
if values.contains(.columns) {
    columns = try values.decode(Int.self, forKey: .columns)
} else {
    columns = Self.defaultColumns
}

contains(_:) reports whether an entry exists, including a null entry. Consequently, explicit null takes the decode branch and produces valueNotFound; only absence receives the default. Under this revised policy, the original program's null-fixture check must change to expect that error rather than equality with minimal.

Avoid turning the assignment into (try? values.decode(Int.self, forKey: .columns)) ?? 3 unless discarding every decoding failure is the intended behavior. That expression also substitutes three for an incompatible supplied value. Using try decodeIfPresent preserves the distinction between an accepted omission and a representation the field cannot interpret, as specified by the decoding method's error contract.

Does compatibility work in both directions?

Check each reader separately. The program demonstrates that the revised reader accepts the older representation. It also demonstrates a boundary: the older reader still requires subtitle, so it rejects a newer representation in which that field is omitted. Changing the new Swift property to optional does not change the old type's requirements.

Synthesized optional encoding omits nil values through conditional encoding. Swift's encodeIfPresent(_:forKey:) documents that it encodes only non-nil values. Encoding an explicit null instead is possible with encodeNil, but that still cannot satisfy an older nonoptional String property that requires a value.

When an older reader must remain usable, define an explicit representation that meets its requirements. In this synthetic example, an adapter could construct a LegacyTile with a chosen subtitle before encoding it. Whether an absent subtitle should become a particular string is a separate product decision; do not silently invent that meaning inside a general fallback.

Also distinguish value preservation from representation preservation. In the example, an omitted subtitle and an explicit null both become the same Swift value, nil. The model therefore cannot reproduce which of those two inputs it received. Similarly, decoding a missing column count as three and re-encoding the model supplies a concrete column count. These are direct consequences of the chosen model and decoding policy.

What should you verify before changing the model?

Use a small compatibility matrix whenever a field changes. Start with an older representation, then vary one field at a time. This keeps a successful round trip from hiding a failure that occurs only when a key is missing.

  • Older input: Confirm the revised reader accepts it and preserves existing values.
  • Missing field: Confirm the result is the intended optional value, fallback, or error.
  • Explicit null: Test it independently from omission.
  • Supplied value: Use a nondefault value to prove decoding does not overwrite it.
  • Incompatible type: Confirm it still throws when no conversion policy exists.
  • Older reader: Check whether the revised encoded representation still meets its requirements.

Do not remove a field from CodingKeys merely to obtain a fallback. Apple explains that omitted properties are excluded from the encoded and decoded representation, and need defaults for automatic decoding conformance. That is suitable when a property intentionally stays outside the representation; it also means a supplied value for that property will not be read. See Apple's coding-key guidance.

Keep the compatibility rule beside the field's decoding logic: optional for meaningful absence, an explicit fallback for an accepted omission, and ordinary throwing decoding for required values. The in-memory fixtures then make the intended behavior reviewable each time the model changes.

Sources