This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory-site.git
The following commit(s) were added to refs/heads/main by this push:
new ac2958617c 🔄 synced local 'docs/guide/' with remote 'docs/guide/'
ac2958617c is described below
commit ac2958617cd548edf8b6ba81eac8954d3dd2bbc9
Author: chaokunyang <[email protected]>
AuthorDate: Fri Feb 20 03:44:43 2026 +0000
🔄 synced local 'docs/guide/' with remote 'docs/guide/'
---
docs/guide/swift/basic-serialization.md | 114 ++++++++++++++++++++++++++++++++
docs/guide/swift/configuration.md | 95 ++++++++++++++++++++++++++
docs/guide/swift/cross-language.md | 63 ++++++++++++++++++
docs/guide/swift/custom-serializers.md | 84 +++++++++++++++++++++++
docs/guide/swift/field-configuration.md | 92 ++++++++++++++++++++++++++
docs/guide/swift/index.md | 66 ++++++++++++++++++
docs/guide/swift/polymorphism.md | 80 ++++++++++++++++++++++
docs/guide/swift/references.md | 111 +++++++++++++++++++++++++++++++
docs/guide/swift/row-format.md | 38 +++++++++++
docs/guide/swift/schema-evolution.md | 77 +++++++++++++++++++++
docs/guide/swift/troubleshooting.md | 92 ++++++++++++++++++++++++++
docs/guide/swift/type-registration.md | 76 +++++++++++++++++++++
12 files changed, 988 insertions(+)
diff --git a/docs/guide/swift/basic-serialization.md
b/docs/guide/swift/basic-serialization.md
new file mode 100644
index 0000000000..a7690d262d
--- /dev/null
+++ b/docs/guide/swift/basic-serialization.md
@@ -0,0 +1,114 @@
+---
+title: Basic Serialization
+sidebar_position: 2
+id: basic_serialization
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+This page covers object graph serialization and core API usage in Swift.
+
+## Object Graph Serialization
+
+Use `@ForyObject` on structs/classes/enums, register types, then serialize and
deserialize.
+
+```swift
+import Foundation
+import Fory
+
+@ForyObject
+struct Address: Equatable {
+ var street: String = ""
+ var zip: Int32 = 0
+}
+
+@ForyObject
+struct Person: Equatable {
+ var id: Int64 = 0
+ var name: String = ""
+ var nickname: String? = nil
+ var tags: Set<String> = []
+ var scores: [Int32] = []
+ var addresses: [Address] = []
+ var metadata: [Int8: Int32?] = [:]
+}
+
+let fory = Fory()
+fory.register(Address.self, id: 100)
+fory.register(Person.self, id: 101)
+
+let person = Person(
+ id: 42,
+ name: "Alice",
+ nickname: nil,
+ tags: ["swift", "xlang"],
+ scores: [10, 20, 30],
+ addresses: [Address(street: "Main", zip: 94107)],
+ metadata: [1: 100, 2: nil]
+)
+
+let data = try fory.serialize(person)
+let decoded: Person = try fory.deserialize(data)
+assert(decoded == person)
+```
+
+## Working with Existing Buffers
+
+Append serialized bytes to an existing `Data` and deserialize from
`ByteBuffer`.
+
+```swift
+var output = Data()
+try fory.serialize(person, to: &output)
+
+let inputBuffer = ByteBuffer(data: output)
+let fromBuffer: Person = try fory.deserialize(from: inputBuffer)
+assert(fromBuffer == person)
+```
+
+## Built-in Supported Types
+
+### Primitive and scalar
+
+- `Bool`
+- `Int8`, `Int16`, `Int32`, `Int64`, `Int`
+- `UInt8`, `UInt16`, `UInt32`, `UInt64`, `UInt`
+- `Float`, `Double`
+- `String`
+- `Data`
+
+### Date and time
+
+- `Date`
+- `ForyDate`
+- `ForyTimestamp`
+
+### Collections
+
+- `[T]` where `T: Serializer`
+- `Set<T>` where `T: Serializer & Hashable`
+- `[K: V]` where `K: Serializer & Hashable`, `V: Serializer`
+- Optional variants (`T?`)
+
+### Dynamic
+
+- `Any`
+- `AnyObject`
+- `any Serializer`
+- `AnyHashable`
+- `[Any]`
+- `[String: Any]`
+- `[Int32: Any]`
+- `[AnyHashable: Any]`
diff --git a/docs/guide/swift/configuration.md
b/docs/guide/swift/configuration.md
new file mode 100644
index 0000000000..3ff8f03d38
--- /dev/null
+++ b/docs/guide/swift/configuration.md
@@ -0,0 +1,95 @@
+---
+title: Configuration
+sidebar_position: 1
+id: configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+This page covers `ForyConfig` and recommended runtime presets.
+
+## ForyConfig
+
+`Fory` is configured with:
+
+```swift
+public struct ForyConfig {
+ public var xlang: Bool
+ public var trackRef: Bool
+ public var compatible: Bool
+}
+```
+
+Default configuration:
+
+```swift
+let fory = Fory() // xlang=true, trackRef=false, compatible=false
+```
+
+## Options
+
+### `xlang`
+
+Controls cross-language protocol mode.
+
+- `true`: Use xlang wire format (default)
+- `false`: Use Swift-native mode
+
+```swift
+let fory = Fory(config: .init(xlang: true))
+```
+
+### `trackRef`
+
+Enables shared/circular reference tracking for reference-trackable types.
+
+- `false`: No reference table (smaller/faster for acyclic or value-only graphs)
+- `true`: Preserve object identity for class/reference graphs
+
+```swift
+let fory = Fory(config: .init(xlang: true, trackRef: true))
+```
+
+### `compatible`
+
+Enables compatible schema mode for evolution across versions.
+
+- `false`: Schema-consistent mode (stricter, lower metadata overhead)
+- `true`: Compatible mode (supports add/remove/reorder fields)
+
+```swift
+let fory = Fory(config: .init(xlang: true, trackRef: false, compatible: true))
+```
+
+## Recommended Presets
+
+### Local, strict schema
+
+```swift
+let fory = Fory(config: .init(xlang: false, trackRef: false, compatible:
false))
+```
+
+### Cross-language service payloads
+
+```swift
+let fory = Fory(config: .init(xlang: true, trackRef: false, compatible: true))
+```
+
+### Graph/object identity workloads
+
+```swift
+let fory = Fory(config: .init(xlang: true, trackRef: true, compatible: true))
+```
diff --git a/docs/guide/swift/cross-language.md
b/docs/guide/swift/cross-language.md
new file mode 100644
index 0000000000..896141f3f2
--- /dev/null
+++ b/docs/guide/swift/cross-language.md
@@ -0,0 +1,63 @@
+---
+title: Cross-Language Serialization
+sidebar_position: 9
+id: cross_language
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Fory Swift can exchange payloads with other Fory runtimes using the xlang
protocol.
+
+## Recommended Cross-language Configuration
+
+```swift
+let fory = Fory(config: .init(xlang: true, trackRef: false, compatible: true))
+```
+
+## Register Types with Shared Identity
+
+### ID-based registration
+
+```swift
+@ForyObject
+struct Order {
+ var id: Int64 = 0
+ var amount: Double = 0
+}
+
+let fory = Fory(config: .init(xlang: true, compatible: true))
+fory.register(Order.self, id: 100)
+```
+
+### Name-based registration
+
+```swift
+try fory.register(Order.self, namespace: "com.example", name: "Order")
+```
+
+## Cross-language Rules
+
+- Keep type registration mapping consistent across languages
+- Use compatible mode when independently evolving schemas
+- Register all user-defined concrete types used by dynamic fields (`Any`, `any
Serializer`)
+
+## Debugging Cross-language Tests
+
+Enable debug output when running xlang tests:
+
+```bash
+ENABLE_FORY_DEBUG_OUTPUT=1 FORY_SWIFT_JAVA_CI=1 mvn -T16 test
-Dtest=org.apache.fory.xlang.SwiftXlangTest
+```
diff --git a/docs/guide/swift/custom-serializers.md
b/docs/guide/swift/custom-serializers.md
new file mode 100644
index 0000000000..dfe184a2b9
--- /dev/null
+++ b/docs/guide/swift/custom-serializers.md
@@ -0,0 +1,84 @@
+---
+title: Custom Serializers
+sidebar_position: 4
+id: custom_serializers
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+For types that cannot or should not use `@ForyObject`, implement `Serializer`
manually.
+
+## When to Use Custom Serializers
+
+- External types with strict wire compatibility requirements
+- Specialized compact encodings
+- Legacy payload migration paths
+- Highly tuned hot-path serialization
+
+## Implementing `Serializer`
+
+```swift
+import Foundation
+import Fory
+
+struct UUIDBox: Serializer, Equatable {
+ var value: UUID = UUID(uuidString: "00000000-0000-0000-0000-000000000000")!
+
+ static func foryDefault() -> UUIDBox {
+ UUIDBox()
+ }
+
+ static var staticTypeId: ForyTypeId {
+ .ext
+ }
+
+ func foryWriteData(_ context: WriteContext, hasGenerics: Bool) throws {
+ _ = hasGenerics
+ try value.uuidString.foryWriteData(context, hasGenerics: false)
+ }
+
+ static func foryReadData(_ context: ReadContext) throws -> UUIDBox {
+ let raw = try String.foryReadData(context)
+ guard let uuid = UUID(uuidString: raw) else {
+ throw ForyError.invalidData("invalid UUID string: \(raw)")
+ }
+ return UUIDBox(value: uuid)
+ }
+}
+```
+
+## Register and Use
+
+```swift
+let fory = Fory()
+fory.register(UUIDBox.self, id: 300)
+
+let input = UUIDBox(value: UUID())
+let data = try fory.serialize(input)
+let output: UUIDBox = try fory.deserialize(data)
+
+assert(input == output)
+```
+
+## Choosing `staticTypeId`
+
+For manually implemented custom types, use `staticTypeId` that matches the
wire kind you are implementing.
+
+Typical choices:
+
+- `.structType`: regular structured object
+- `.enumType` / `.typedUnion`: enum-like values
+- `.ext`: extension/custom kind
diff --git a/docs/guide/swift/field-configuration.md
b/docs/guide/swift/field-configuration.md
new file mode 100644
index 0000000000..a44869dfde
--- /dev/null
+++ b/docs/guide/swift/field-configuration.md
@@ -0,0 +1,92 @@
+---
+title: Field Configuration
+sidebar_position: 5
+id: field_configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+This page covers macro-level field configuration in Swift.
+
+## Available Macro Attributes
+
+- `@ForyObject` on struct/class/enum
+- `@ForyField(encoding: ...)` on numeric fields
+
+## `@ForyField(encoding:)`
+
+Use `@ForyField` to override integer encoding strategy.
+
+```swift
+@ForyObject
+struct Metrics: Equatable {
+ @ForyField(encoding: .fixed)
+ var u32Fixed: UInt32 = 0
+
+ @ForyField(encoding: .tagged)
+ var u64Tagged: UInt64 = 0
+}
+```
+
+### Supported combinations
+
+| Swift type | Supported encoding values | Default encoding |
+| ---------- | ------------------------------ | ---------------- |
+| `Int32` | `.varint`, `.fixed` | `.varint` |
+| `UInt32` | `.varint`, `.fixed` | `.varint` |
+| `Int64` | `.varint`, `.fixed`, `.tagged` | `.varint` |
+| `UInt64` | `.varint`, `.fixed`, `.tagged` | `.varint` |
+| `Int` | `.varint`, `.fixed`, `.tagged` | `.varint` |
+| `UInt` | `.varint`, `.fixed`, `.tagged` | `.varint` |
+
+Compile-time validation rejects unsupported combinations (for example, `Int32`
with `.tagged`).
+
+## `@ForyObject` Requirements
+
+### Struct and class fields
+
+- Stored properties must declare explicit types
+- Computed properties are ignored
+- Static/class properties are ignored
+
+### Class requirement
+
+Classes annotated with `@ForyObject` must provide a `required init()` for
default construction.
+
+```swift
+@ForyObject
+final class Node {
+ var value: Int32 = 0
+ var next: Node? = nil
+
+ required init() {}
+}
+```
+
+## Dynamic Any Fields in Macro Types
+
+`@ForyObject` supports dynamic fields and nested containers:
+
+- `Any`, `AnyObject`, `any Serializer`
+- `AnyHashable`
+- `[Any]`
+- `[String: Any]`
+- `[Int32: Any]`
+- `[AnyHashable: Any]`
+
+Current limitations:
+
+- `Dictionary<K, Any>` is only supported when `K` is `String`, `Int32`, or
`AnyHashable`
diff --git a/docs/guide/swift/index.md b/docs/guide/swift/index.md
new file mode 100644
index 0000000000..a7f0373c70
--- /dev/null
+++ b/docs/guide/swift/index.md
@@ -0,0 +1,66 @@
+---
+title: Swift Serialization Guide
+sidebar_position: 0
+id: serialization_index
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory Swift provides high-performance object graph serialization with
strong type safety, macro-based code generation, schema evolution, and
cross-language compatibility.
+
+## Why Fory Swift?
+
+- Fast binary serialization for Swift value and reference types
+- `@ForyObject` macro for zero-boilerplate model serialization
+- Cross-language protocol compatibility (`xlang`) with Java, Rust, Go, Python,
and more
+- Compatible mode for schema evolution across versions
+- Built-in support for dynamic values (`Any`, `AnyObject`, `any Serializer`,
`AnyHashable`)
+- Reference tracking for shared/circular graphs, including weak references on
classes
+
+## Guide Contents
+
+- [Configuration](configuration.md)
+- [Basic Serialization](basic-serialization.md)
+- [Type Registration](type-registration.md)
+- [Custom Serializers](custom-serializers.md)
+- [Field Configuration](field-configuration.md)
+- [Shared and Circular References](references.md)
+- [Polymorphism and Dynamic Types](polymorphism.md)
+- [Schema Evolution](schema-evolution.md)
+- [Cross-Language Serialization](cross-language.md)
+- [Row Format Status](row-format.md)
+- [Troubleshooting](troubleshooting.md)
+
+## Quick Example
+
+```swift
+import Fory
+
+@ForyObject
+struct User: Equatable {
+ var name: String = ""
+ var age: Int32 = 0
+}
+
+let fory = Fory()
+fory.register(User.self, id: 1)
+
+let input = User(name: "alice", age: 30)
+let data = try fory.serialize(input)
+let output: User = try fory.deserialize(data)
+
+assert(input == output)
+```
diff --git a/docs/guide/swift/polymorphism.md b/docs/guide/swift/polymorphism.md
new file mode 100644
index 0000000000..f03d677c01
--- /dev/null
+++ b/docs/guide/swift/polymorphism.md
@@ -0,0 +1,80 @@
+---
+title: Polymorphism and Dynamic Types
+sidebar_position: 7
+id: polymorphism
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Fory Swift supports dynamic serialization for `Any`, `AnyObject`, and `any
Serializer`.
+
+## Top-level Dynamic APIs
+
+```swift
+let fory = Fory()
+
+let dynamic: Any = Int32(7)
+let data = try fory.serialize(dynamic)
+let decoded: Any = try fory.deserialize(data)
+```
+
+Equivalent overloads exist for:
+
+- `AnyObject`
+- `any Serializer`
+- `AnyHashable`
+- `[Any]`
+- `[String: Any]`
+- `[Int32: Any]`
+- `[AnyHashable: Any]`
+
+## Dynamic Fields in `@ForyObject` Types
+
+```swift
+@ForyObject
+struct DynamicHolder {
+ var value: Any = ForyAnyNullValue()
+ var list: [Any] = []
+ var byName: [String: Any] = [:]
+ var byId: [Int32: Any] = [:]
+ var byDynamicKey: [AnyHashable: Any] = [:]
+}
+```
+
+## Concrete Type Registration Still Applies
+
+If dynamic values contain user-defined runtime types, register those concrete
types.
+
+```swift
+@ForyObject
+struct Address {
+ var street: String = ""
+ var zip: Int32 = 0
+}
+
+let fory = Fory()
+fory.register(Address.self, id: 100)
+```
+
+## Null Semantics
+
+- `Any` null representation: `ForyAnyNullValue`
+- `AnyObject` null representation: `NSNull`
+- Optional dynamic values map to the corresponding null representation on
decode
+
+## Current Limitations
+
+- `AnyHashable` keys must wrap runtime values that are both `Hashable` and
supported by Fory dynamic serialization
diff --git a/docs/guide/swift/references.md b/docs/guide/swift/references.md
new file mode 100644
index 0000000000..36f97e4902
--- /dev/null
+++ b/docs/guide/swift/references.md
@@ -0,0 +1,111 @@
+---
+title: Shared and Circular References
+sidebar_position: 6
+id: references
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Swift reference tracking is controlled by `ForyConfig.trackRef`.
+
+## Enable Reference Tracking
+
+```swift
+let fory = Fory(config: .init(xlang: true, trackRef: true, compatible: false))
+```
+
+When enabled, reference-trackable types preserve identity and cycles.
+
+## Shared Reference Example
+
+```swift
+import Fory
+
+@ForyObject
+final class Animal {
+ var name: String = ""
+
+ required init() {}
+
+ init(name: String) {
+ self.name = name
+ }
+}
+
+@ForyObject
+final class AnimalPair {
+ var first: Animal? = nil
+ var second: Animal? = nil
+
+ required init() {}
+
+ init(first: Animal? = nil, second: Animal? = nil) {
+ self.first = first
+ self.second = second
+ }
+}
+
+let fory = Fory(config: .init(xlang: true, trackRef: true))
+fory.register(Animal.self, id: 200)
+fory.register(AnimalPair.self, id: 201)
+
+let shared = Animal(name: "cat")
+let input = AnimalPair(first: shared, second: shared)
+
+let data = try fory.serialize(input)
+let decoded: AnimalPair = try fory.deserialize(data)
+
+assert(decoded.first === decoded.second)
+```
+
+## Circular Reference Example (Use `weak`)
+
+`trackRef` preserves the reference graph, but it does not change ARC ownership.
+Use `weak` on at least one edge in a cycle to avoid leaks.
+
+```swift
+import Fory
+
+@ForyObject
+final class Node {
+ var value: Int32 = 0
+ weak var next: Node? = nil
+
+ required init() {}
+
+ init(value: Int32, next: Node? = nil) {
+ self.value = value
+ self.next = next
+ }
+}
+
+let fory = Fory(config: .init(xlang: true, trackRef: true))
+fory.register(Node.self, id: 300)
+
+let node = Node(value: 7)
+node.next = node
+
+let data = try fory.serialize(node)
+let decoded: Node = try fory.deserialize(data)
+
+assert(decoded.next === decoded)
+```
+
+## Notes
+
+- Value types (`struct`, primitive values) do not carry identity semantics
+- `trackRef` controls serialization graph identity, not ARC memory ownership
+- Use `trackRef=false` for purely value-based payloads to reduce overhead
diff --git a/docs/guide/swift/row-format.md b/docs/guide/swift/row-format.md
new file mode 100644
index 0000000000..4143b68c80
--- /dev/null
+++ b/docs/guide/swift/row-format.md
@@ -0,0 +1,38 @@
+---
+title: Row Format
+sidebar_position: 10
+id: row_format
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Swift currently focuses on object-graph serialization (`Fory.serialize` /
`Fory.deserialize`).
+
+## Current Status
+
+- Object graph serialization: supported
+- Cross-language xlang object protocol: supported
+- Swift row-format APIs: not exposed yet
+
+## Recommended Approach Today
+
+- Use object serialization for application payloads
+- Use compatible mode for schema evolution across service versions
+- Use xlang mode for interoperability with other Fory runtimes
+
+## Future Direction
+
+Row-format support in Swift can be added without changing existing object
serialization APIs. Until then, treat row-format features as unavailable in
Swift runtime code.
diff --git a/docs/guide/swift/schema-evolution.md
b/docs/guide/swift/schema-evolution.md
new file mode 100644
index 0000000000..958c0da4fe
--- /dev/null
+++ b/docs/guide/swift/schema-evolution.md
@@ -0,0 +1,77 @@
+---
+title: Schema Evolution
+sidebar_position: 8
+id: schema_evolution
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Fory supports schema evolution through compatible mode.
+
+## Enable Compatible Mode
+
+```swift
+let fory = Fory(config: .init(xlang: true, trackRef: false, compatible: true))
+```
+
+## Example: Evolving a Struct
+
+```swift
+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(config: .init(xlang: true, compatible: true))
+writer.register(PersonV1.self, id: 1)
+
+let reader = Fory(config: .init(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.
diff --git a/docs/guide/swift/troubleshooting.md
b/docs/guide/swift/troubleshooting.md
new file mode 100644
index 0000000000..f94b0d1ea0
--- /dev/null
+++ b/docs/guide/swift/troubleshooting.md
@@ -0,0 +1,92 @@
+---
+title: Troubleshooting
+sidebar_position: 11
+id: troubleshooting
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+This page covers common Swift issues and how to debug them.
+
+## Common Runtime Errors
+
+### `Type not registered: ...`
+
+Cause: user type was not registered on the current `Fory` instance.
+
+Fix:
+
+```swift
+fory.register(MyType.self, id: 100)
+```
+
+### `Type mismatch: expected ..., got ...`
+
+Cause: registration mapping or field type info differs across peers.
+
+Fix:
+
+- Ensure both sides register the same type ID/name mapping
+- Verify field type compatibility
+
+### `Invalid data: xlang bitmap mismatch`
+
+Cause: serializer and deserializer use different `xlang` settings.
+
+Fix: configure both sides with matching `xlang` mode.
+
+### `Invalid data: class version hash mismatch`
+
+Cause: schema changed while `compatible=false`.
+
+Fix:
+
+- Enable compatible mode for evolving schemas
+- Or keep strict schema parity with schema-consistent mode
+
+## Common Macro-time Errors
+
+### `@ForyObject requires explicit types for stored properties`
+
+Add explicit type annotations to stored properties.
+
+### `@ForyObject enum associated values cannot have default values`
+
+Remove default values from enum case associated values.
+
+### `Set<...> with Any elements is not supported by @ForyObject yet`
+
+Use `[Any]` or a typed set instead.
+
+### `Dictionary<..., ...> with Any values is only supported for String, Int32,
or AnyHashable keys`
+
+Switch key type to `String`, `Int32`, or `AnyHashable`, or avoid dynamic `Any`
map values.
+
+## Debugging Commands
+
+Run Swift tests:
+
+```bash
+cd swift
+ENABLE_FORY_DEBUG_OUTPUT=1 swift test
+```
+
+Run Java-driven Swift xlang tests:
+
+```bash
+cd java/fory-core
+ENABLE_FORY_DEBUG_OUTPUT=1 FORY_SWIFT_JAVA_CI=1 mvn -T16 test
-Dtest=org.apache.fory.xlang.SwiftXlangTest
+```
diff --git a/docs/guide/swift/type-registration.md
b/docs/guide/swift/type-registration.md
new file mode 100644
index 0000000000..0e5228ce4f
--- /dev/null
+++ b/docs/guide/swift/type-registration.md
@@ -0,0 +1,76 @@
+---
+title: Type Registration
+sidebar_position: 3
+id: type_registration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+This page covers registration APIs for user-defined types.
+
+## Why Registration Is Required
+
+User types (`struct`, `class`, enum/union, ext types) must be registered
before serialization/deserialization.
+
+If a type is missing, deserialization fails with:
+
+- `Type not registered: ...`
+
+## Register by Numeric ID
+
+Use a stable ID shared by serializer and deserializer peers.
+
+```swift
+@ForyObject
+struct User {
+ var name: String = ""
+ var age: Int32 = 0
+}
+
+let fory = Fory()
+fory.register(User.self, id: 1)
+```
+
+## Register by Name
+
+### Fully-qualified name
+
+```swift
+try fory.register(User.self, name: "com.example.User")
+```
+
+`name` is split by `.`:
+
+- namespace: `com.example`
+- type name: `User`
+
+### Explicit namespace + name
+
+```swift
+try fory.register(User.self, namespace: "com.example", name: "User")
+```
+
+## Consistency Rules
+
+Keep registration mapping consistent across peers:
+
+- ID mode: same type uses same numeric ID on all peers
+- Name mode: same type uses same namespace and type name on all peers
+- Do not mix ID and name mapping for the same logical type across services
+
+## Dynamic Types and Registration
+
+When serializing dynamic values (`Any`, `AnyObject`, `any Serializer`) that
contain user-defined types, the concrete runtime types must still be registered.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
