Schema Evolution

Fory supports schema evolution through compatible mode, which is enabled by default in Swift.

Compatible readers also tolerate selected scalar field type changes when the value is lossless. A matched field can read between Bool, String, numeric scalars, and Decimal when the converted value has the same logical value. For example, "true" and "false" can be read as booleans, "123" can be read as a numeric field that can hold 123, numbers and decimals can be read as canonical strings, and numeric widening or narrowing succeeds only when no precision or range is lost. Numeric strings use finite ASCII decimal syntax. Invalid strings and lossy conversions fail during deserialization.

Scalar conversion also composes with optional fields. A present optional value is converted by the same rules, while a missing optional value keeps Swift's normal compatible-mode default for the local field. Reference-tracked scalar type changes are incompatible.

Default Compatible Mode

let fory = Fory()

Example: Evolving a Struct

import Fory

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

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

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

let reader = Fory()
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
• Change a matched scalar field between Bool, String, numeric scalars, or Decimal when every value you write is lossless for the reader

What Is Not Safe

• Arbitrary type changes for an existing field, including scalar values that are out of range, rounded, non-finite, or not accepted by the compatible numeric string grammar
• Inconsistent registration mapping across peers

Same-Schema Optimization

Set compatible: false only when every reader and writer always uses the same schema and you want faster serialization and smaller size. For xlang payloads, set compatible: false only after verifying that every language uses the same schema, or when native types are generated from Fory schema IDL.