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
commit 6c5d0707d997008aded25f2dd1bdefca39ab26a2 Author: chaokunyang <[email protected]> AuthorDate: Wed Aug 26 04:33:07 2026 +0000 🔄 synced local 'docs/object-serialization/' with remote 'docs/object-serialization/' --- docs/object-serialization/cpp/schema-metadata.md | 5 +++-- docs/object-serialization/csharp/schema-metadata.md | 3 ++- docs/object-serialization/dart/schema-metadata.md | 1 + docs/object-serialization/go/schema-metadata.md | 4 ++++ docs/object-serialization/go/troubleshooting.md | 10 ++++++++-- docs/object-serialization/java/schema-metadata.md | 15 ++++++++------- .../object-serialization/javascript/schema-metadata.md | 18 ++++++++++++++++++ docs/object-serialization/kotlin/schema-metadata.md | 4 ++++ docs/object-serialization/python/schema-metadata.md | 7 ++++--- docs/object-serialization/rust/schema-metadata.md | 3 ++- docs/object-serialization/scala/schema-metadata.md | 4 ++++ docs/object-serialization/swift/schema-metadata.md | 18 ++++++++++++++++++ 12 files changed, 76 insertions(+), 16 deletions(-) diff --git a/docs/object-serialization/cpp/schema-metadata.md b/docs/object-serialization/cpp/schema-metadata.md index c60f3866e50..5c05de1c0e9 100644 --- a/docs/object-serialization/cpp/schema-metadata.md +++ b/docs/object-serialization/cpp/schema-metadata.md @@ -59,8 +59,9 @@ FORY_STRUCT(DataV2, id, (timestamp, fory::F().tagged()), version); FORY_STRUCT(Counter, FORY_PROPERTY(value, fory::F().varint())); ``` -`fory::F(id)` uses explicit id-based field identity. IDs must be -non-negative: +`fory::F(id)` uses explicit id-based field identity. Configured IDs must be +unique within the complete struct schema and satisfy `0 <= id < 2^29` (`0` +through `536870911`): ```cpp FORY_STRUCT(DataV2, (id, fory::F(0)), (timestamp, fory::F(1).tagged()), diff --git a/docs/object-serialization/csharp/schema-metadata.md b/docs/object-serialization/csharp/schema-metadata.md index d9858982e5c..c555671441b 100644 --- a/docs/object-serialization/csharp/schema-metadata.md +++ b/docs/object-serialization/csharp/schema-metadata.md @@ -23,7 +23,7 @@ This page covers schema metadata for C# generated serializers. ## `[ForyStruct]` and `[ForyField]` -Use `[ForyStruct]` to enable source-generated serializers. Use `[ForyField]` to assign an optional stable non-negative field id or to override the Fory schema type used for a field. +Use `[ForyStruct]` to enable source-generated serializers. Use `[ForyField]` to assign an optional stable field ID or to override the Fory schema type used for a field. Configured IDs must be unique within the complete struct schema and satisfy `0 <= id < 2^29` (`0` through `536870911`). External-type serialization puts `Target` on a local abstract serializer declaration. Its properties own the field names, IDs, schema descriptors, @@ -77,6 +77,7 @@ public sealed class Metrics ``` `Id` is optional. When it is omitted, compatible mode still matches the field by name. +Once assigned, keep an ID stable and do not reuse it for a different field. ```csharp using Apache.Fory; diff --git a/docs/object-serialization/dart/schema-metadata.md b/docs/object-serialization/dart/schema-metadata.md index 3073cf6bb83..ed4a957cc59 100644 --- a/docs/object-serialization/dart/schema-metadata.md +++ b/docs/object-serialization/dart/schema-metadata.md @@ -69,6 +69,7 @@ String name = ''; ``` Once a payload is shared across services, never reuse an `id` for a different field. +Configured IDs must satisfy `0 <= id < 2^29` (`0` through `536870911`). An ordinary child has one flattened field namespace. IDs must therefore be unique across all fields included from its child, superclass, and diff --git a/docs/object-serialization/go/schema-metadata.md b/docs/object-serialization/go/schema-metadata.md index 878661dabbf..7073e1e2439 100644 --- a/docs/object-serialization/go/schema-metadata.md +++ b/docs/object-serialization/go/schema-metadata.md @@ -47,6 +47,10 @@ type User struct { } ``` +Configured IDs must be unique within the struct schema and satisfy +`0 <= id < 2^29` (`0` through `536870911`). Keep assigned IDs stable and do +not reuse them for different fields. + **Benefits**: - Smaller serialized size (numeric IDs vs field names) diff --git a/docs/object-serialization/go/troubleshooting.md b/docs/object-serialization/go/troubleshooting.md index 9c51ba6be01..be7fa1e9bb8 100644 --- a/docs/object-serialization/go/troubleshooting.md +++ b/docs/object-serialization/go/troubleshooting.md @@ -206,7 +206,8 @@ f2 := fory.New(fory.WithTrackRef(true)) // Must match! **Common causes**: -1. **Invalid tag ID**: ID must be non-negative +1. **Invalid tag ID**: ID must satisfy `0 <= id < 2^29` (`0` through + `536870911`) ```go // Wrong: negative ID @@ -218,6 +219,11 @@ type Bad struct { type Good struct { Field int `fory:"id=0"` } + +// Wrong: ID reaches the exclusive upper bound +type TooLarge struct { + Field int `fory:"id=536870912"` +} ``` 2. **Duplicate tag IDs**: Each field must have a unique ID within the struct @@ -256,7 +262,7 @@ type User struct { } ``` -2. **Use field IDs for consistent ordering**: Field IDs (non-negative integers) act as aliases for field names, used for both sorting and field matching during deserialization: +2. **Use field IDs for consistent ordering**: Field IDs in the protocol range act as aliases for field names, used for both sorting and field matching during deserialization: ```go type User struct { diff --git a/docs/object-serialization/java/schema-metadata.md b/docs/object-serialization/java/schema-metadata.md index 981e47184a2..8a1265d84b2 100644 --- a/docs/object-serialization/java/schema-metadata.md +++ b/docs/object-serialization/java/schema-metadata.md @@ -87,10 +87,10 @@ public class User { ### Parameters -| Parameter | Type | Default | Description | -| --------- | --------- | ------- | -------------------------------------- | -| `id` | `int` | `-1` | Non-negative field tag ID, or no ID | -| `dynamic` | `Dynamic` | `AUTO` | Control polymorphism for struct fields | +| Parameter | Type | Default | Description | +| --------- | --------- | ------- | -------------------------------------------- | +| `id` | `int` | `-1` | Field tag ID, or the internal no-ID sentinel | +| `dynamic` | `Dynamic` | `AUTO` | Control polymorphism for struct fields | Use `@Nullable` on the field type or nested type position for nullable schema metadata and `@Ref` for reference tracking. `@ForyField` does not carry either @@ -123,10 +123,11 @@ public class User { **Notes**: -- IDs must be unique within a class -- IDs must be >= 0 when configured -- If not specified, the annotation default `-1` is ignored and field name is used in metadata +- Configured IDs must satisfy `0 <= id < 2^29` (`0` through `536870911`) +- IDs must be unique within the complete struct schema, including inherited fields +- If not specified, the annotation default `-1` is the internal no-ID sentinel and the field name is used in metadata (larger overhead) +- Once assigned, keep an ID stable and do not reuse it for a different field **Without field IDs** (field names used in metadata): diff --git a/docs/object-serialization/javascript/schema-metadata.md b/docs/object-serialization/javascript/schema-metadata.md index c891701b614..6884795978e 100644 --- a/docs/object-serialization/javascript/schema-metadata.md +++ b/docs/object-serialization/javascript/schema-metadata.md @@ -50,6 +50,24 @@ const byName = Type.struct( Use `.` inside `typeName` to add a namespace prefix. +## Field IDs + +Call `setId(id)` on a field type to assign a stable numeric field identity: + +```ts +const userType = Type.struct( + { typeId: 1001 }, + { + id: Type.int64().setId(0), + name: Type.string().setId(1), + }, +); +``` + +Configured IDs must be unique within the struct schema and satisfy +`0 <= id < 2^29` (`0` through `536870911`). Keep assigned IDs stable and do +not reuse them for different fields. Fields without an ID use their names. + ## Decorator Metadata Decorators keep the schema next to a TypeScript class declaration: diff --git a/docs/object-serialization/kotlin/schema-metadata.md b/docs/object-serialization/kotlin/schema-metadata.md index b46bd14f9f8..a7fb57abd96 100644 --- a/docs/object-serialization/kotlin/schema-metadata.md +++ b/docs/object-serialization/kotlin/schema-metadata.md @@ -51,6 +51,10 @@ Use `@ForyField(id = 1)` on constructor properties. `@field:ForyField(id = 1)` i for field-backed properties. Do not use `@get:ForyField` or `@set:ForyField`; accessors are not schema fields and the processor rejects them. +Configured field IDs must be unique within the struct schema and satisfy +`0 <= id < 2^29` (`0` through `536870911`). Keep assigned IDs stable and do +not reuse them for different fields. If `id` is omitted, the field name is used. + ## Nullability Use Kotlin `?` to describe nullable schema positions. Nullability is preserved inside collections diff --git a/docs/object-serialization/python/schema-metadata.md b/docs/object-serialization/python/schema-metadata.md index e7359c96a92..cd8517dba59 100644 --- a/docs/object-serialization/python/schema-metadata.md +++ b/docs/object-serialization/python/schema-metadata.md @@ -72,7 +72,7 @@ class User: | Parameter | Type | Default | Description | | ----------------- | -------- | --------- | ------------------------------------ | -| `id` | `int` | omitted | Non-negative field tag ID | +| `id` | `int` | omitted | Field tag ID in `0 <= id < 2^29` | | `nullable` | `bool` | `False` | Whether the field can be null | | `ref` | `bool` | `False` | Enable reference tracking | | `ignore` | `bool` | `False` | Exclude field from serialization | @@ -102,9 +102,10 @@ class User: **Notes**: -- IDs must be unique within a class -- IDs must be >= 0 +- IDs must be unique within the struct schema +- IDs must satisfy `0 <= id < 2^29` (`0` through `536870911`) - If not specified, field name is used in metadata (larger overhead) +- Once assigned, keep an ID stable and do not reuse it for a different field **Without field IDs** (field names used in metadata): diff --git a/docs/object-serialization/rust/schema-metadata.md b/docs/object-serialization/rust/schema-metadata.md index 249f9a906a9..4b18c04d7a6 100644 --- a/docs/object-serialization/rust/schema-metadata.md +++ b/docs/object-serialization/rust/schema-metadata.md @@ -83,8 +83,9 @@ struct User { **Notes**: - IDs must be unique within a struct -- IDs must be non-negative +- IDs must satisfy `0 <= id < 2^29` (`0` through `536870911`) - If not specified, field name is used in metadata (larger overhead) +- Once assigned, keep an ID stable and do not reuse it for a different field ### Skipping Fields (`skip`) diff --git a/docs/object-serialization/scala/schema-metadata.md b/docs/object-serialization/scala/schema-metadata.md index d630690824c..151c8cdb616 100644 --- a/docs/object-serialization/scala/schema-metadata.md +++ b/docs/object-serialization/scala/schema-metadata.md @@ -38,6 +38,10 @@ final case class Person( ) derives ForySerializer ``` +Configured field IDs must be unique within the struct schema and satisfy +`0 <= id < 2^29` (`0` through `536870911`). Keep assigned IDs stable and do +not reuse them for different fields. If `id` is omitted, the field name is used. + Schema `optional T` fields are represented as `Option[T]`. ## Reference Tracking diff --git a/docs/object-serialization/swift/schema-metadata.md b/docs/object-serialization/swift/schema-metadata.md index e805210003c..2a216e4f7b6 100644 --- a/docs/object-serialization/swift/schema-metadata.md +++ b/docs/object-serialization/swift/schema-metadata.md @@ -26,6 +26,7 @@ This page covers macro-level schema metadata in Swift. - `@ForyStruct` on struct/class models and external structural serializers - `@ForyEnum` on C-style enum models and external enum serializers - `@ForyUnion` and `@ForyCase` on associated-value enum models and external union serializers +- `@ForyField(id: ...)` for stable numeric field identity - `@ForyField(encoding: ...)` on numeric fields - `@ForyField(with: ...)` for exact serializer selection - `@ListField`, `@ArrayField`, `@SetField`, and `@MapField` for collection field metadata @@ -47,6 +48,23 @@ Equivalent target arguments are available on `@ForyEnum` and `@ForyUnion`. See [External-Type Serialization](external-types.md) for target access and construction requirements. +## `@ForyField(id:)` + +Assign an ID when field identity must remain stable across renames or schema +evolution: + +```swift +@ForyStruct +struct User { + @ForyField(id: 1) + var name: String +} +``` + +Configured IDs must be unique within the struct schema and satisfy +`0 <= id < 2^29` (`0` through `536870911`). Keep assigned IDs stable and do +not reuse them for different fields. Fields without an ID use their names. + ## `@ForyField(with:)` An unannotated field implicitly selects its declared type when that type --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
