Schema Evolution

Fory supports schema evolution through compatible mode.

Enable Compatible Mode

let fory = Fory(xlang: true, trackRef: false, compatible: true)

Example: Evolving a Struct

import Fory

@ForyObject
struct PersonV1 {
    var name: String = ""
    var age: Int32 = 0
    var address: String = ""
}

@ForyObject
struct PersonV2 {
    var name: String = ""
    var age: Int32 = 0
    var phone: String? = nil // added field
}

let writer = Fory(xlang: true, compatible: true)
writer.register(PersonV1.self, id: 1)

let reader = Fory(xlang: true, compatible: true)
reader.register(PersonV2.self, id: 1)

let v1 = PersonV1(name: "alice", age: 30, address: "main st")
let bytes = try writer.serialize(v1)
let v2: PersonV2 = try reader.deserialize(bytes)

assert(v2.name == "alice")
assert(v2.age == 30)
assert(v2.phone == nil)

What Is Safe in Compatible Mode

• Add new fields
• Remove old fields
• Reorder fields

What Is Not Safe

• Arbitrary type changes for an existing field (for example Int32 to String)
• Inconsistent registration mapping across peers

Schema-consistent Mode Behavior

With compatible=false, Fory validates schema hash and fails fast on mismatch.