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 4b7c6f22c2 🔄 synced local 'docs/specification/' with remote
'docs/specification/'
4b7c6f22c2 is described below
commit 4b7c6f22c28328043f18eeea0522b4984c58b106
Author: chaokunyang <[email protected]>
AuthorDate: Wed May 6 05:45:02 2026 +0000
🔄 synced local 'docs/specification/' with remote 'docs/specification/'
---
docs/specification/java_serialization_spec.md | 35 +++++++++++---------
docs/specification/xlang_serialization_spec.md | 46 +++++++++++++++++---------
2 files changed, 51 insertions(+), 30 deletions(-)
diff --git a/docs/specification/java_serialization_spec.md
b/docs/specification/java_serialization_spec.md
index 2bac7bc0da..c52695f1cc 100644
--- a/docs/specification/java_serialization_spec.md
+++ b/docs/specification/java_serialization_spec.md
@@ -44,14 +44,14 @@ Java native serialization writes a one byte bitmap header.
The header layout mir
bitmap and uses the same flag bits.
```
-| 5 bits | 1 bit | 1 bit | 1 bit |
-+--------------+-------+-------+-------+
-| reserved | oob | xlang | null |
+| 6 bits | 1 bit | 1 bit |
++---------------+-------+-------+
+| reserved | oob | xlang |
```
-- null flag: 1 when object is null, 0 otherwise. If object is null, other bits
are not set.
-- xlang flag: 1 when serialization uses xlang format, 0 when serialization
uses Java native format.
-- oob flag: 1 when `BufferCallback` is not null, 0 otherwise.
+- xlang flag: bit 0, set when serialization uses xlang format and clear for
Java native format.
+- oob flag: bit 1, set when `BufferCallback` is not null.
+- reserved bits: bits 2-7, must be zero.
The header is always a single byte; no language ID is written.
@@ -202,32 +202,37 @@ when shared meta is enabled, or referenced by index when
already seen.
Header layout (lower bits on the right):
```
-| 50-bit hash | 4 bits reserved | 1 bit compress | 1 bit has_fields_meta |
8-bit size |
+| 52-bit hash | 3 bits reserved | 1 bit compress | 8-bit size |
```
- size: lower 8 bits. If size equals the mask (0xFF), write extra size as
varuint32 and add it.
-- compress: set when payload is compressed.
-- has_fields_meta: set when field metadata is present.
-- reserved: bits 10-13 are reserved for future use and must be zero.
-- hash: 50-bit hash of the payload and flags.
+- compress: bit 8, set when payload is compressed.
+- reserved: bits 9-11 are reserved for future use and must be zero.
+- hash: 52-bit hash of the payload.
### Class meta bytes
Class meta encodes a linearized class hierarchy (from parent to leaf) and
field metadata:
```
-| num_classes | class_layer_0 | class_layer_1 | ... |
+| root_kind_and_num_classes | class_layer_0 | class_layer_1 | ... |
class_layer:
| num_fields << 1 | registered_flag | [type_id if registered] |
| namespace | type_name | field_infos |
```
-- `num_classes` stores `(num_layers - 1)` in a single byte.
- - If it equals `0b1111`, read an extra varuint32 small7 and add it.
+- `root_kind_and_num_classes` stores the root TypeDef kind in the high four
bits and
+ `(num_layers - 1)` in the low four bits.
+ - Root kind codes are `STRUCT=0`, `COMPATIBLE_STRUCT=1`, `NAMED_STRUCT=2`,
+ `NAMED_COMPATIBLE_STRUCT=3`, `ENUM=4`, `NAMED_ENUM=5`, `EXT=6`,
`NAMED_EXT=7`,
+ `TYPED_UNION=8`, and `NAMED_UNION=9`.
+ - Kind codes `10-14` are reserved and `15` is an extended-kind escape
rejected until defined.
+ - If the low four bits equal `0b1111`, read an extra varuint32 small7 and
add it.
- The actual number of layers is `num_classes + 1`.
- `registered_flag` is 1 if the class is registered by numeric ID.
-- If registered by ID, the class type ID follows (varuint32 small7).
+- If registered by ID, the one-byte class type ID follows. For user-registered
ID kinds, the
+ user type ID follows as varuint32.
- If registered by name or unregistered, namespace and type name are written
as meta strings.
### Field info
diff --git a/docs/specification/xlang_serialization_spec.md
b/docs/specification/xlang_serialization_spec.md
index 24adbe3331..b1743918a9 100644
--- a/docs/specification/xlang_serialization_spec.md
+++ b/docs/specification/xlang_serialization_spec.md
@@ -323,15 +323,14 @@ Detailed byte layout:
```
Byte 0: Bitmap flags
- - Bit 0: null flag (0x01)
- - Bit 1: xlang flag (0x02)
- - Bit 2: oob flag (0x04)
- - Bits 3-7: reserved
+ - Bit 0: xlang flag (0x01)
+ - Bit 1: oob flag (0x02)
+ - Bits 2-7: reserved
```
-- **null flag** (bit 0): 1 when object is null, 0 otherwise. If an object is
null, only this flag is set.
-- **xlang flag** (bit 1): 1 when serialization uses Fory xlang format, 0 when
serialization uses Fory language-native format.
-- **oob flag** (bit 2): 1 when out-of-band serialization is enabled
(BufferCallback is not null), 0 otherwise.
+- **xlang flag** (bit 0): 1 when serialization uses Fory xlang format, 0 when
serialization uses Fory language-native format.
+- **oob flag** (bit 1): 1 when out-of-band serialization is enabled
(BufferCallback is not null), 0 otherwise.
+- **reserved bits** (bits 2-7): must be zero.
All data is encoded in little-endian format.
@@ -536,12 +535,11 @@ The 8-byte header is a little-endian uint64:
- Low 8 bits: meta size (number of bytes in the TypeDef body).
- If meta size >= 0xFF, the low 8 bits are set to 0xFF and an extra
`varuint32(meta_size - 0xFF)` follows immediately after the header.
-- Bit 8: `HAS_FIELDS_META` (1 = fields metadata present).
-- Bit 9: `COMPRESS_META` is reserved for a future xlang metadata-compression
extension.
+- Bit 8: `COMPRESS_META` is reserved for a future xlang metadata-compression
extension.
Current xlang writers MUST leave this bit unset and current xlang readers
MUST treat a set bit
as unsupported.
-- Bits 10-13: reserved for future extension (must be zero).
-- High 50 bits: hash of the TypeDef body.
+- Bits 9-11: reserved for future extension (must be zero).
+- High 52 bits: hash of the TypeDef body.
#### TypeDef body
@@ -551,12 +549,30 @@ TypeDef body has a single layer (fields are flattened in
class hierarchy order):
| meta header (1 byte) | type spec | field info ... |
```
-Meta header byte:
+Meta header byte for struct TypeDefs:
+- Bit 7: `IS_STRUCT` (1).
+- Bit 6: `COMPATIBLE`.
+- Bit 5: `REGISTER_BY_NAME` (1 = namespace + type name, 0 = numeric user type
ID).
- Bits 0-4: `num_fields` (0-30).
- If `num_fields == 31`, read an extra `varuint32` and add it.
-- Bit 5: `REGISTER_BY_NAME` (1 = namespace + type name, 0 = numeric type ID).
-- Bits 6-7: reserved.
+
+Meta header byte for non-struct TypeDefs:
+
+- Bit 7: `IS_STRUCT` (0).
+- Bits 4-6: reserved (must be zero).
+- Bits 0-3: kind code.
+
+Non-struct kind codes:
+
+- `0`: `ENUM`
+- `1`: `NAMED_ENUM`
+- `2`: `EXT`
+- `3`: `NAMED_EXT`
+- `4`: `TYPED_UNION`
+- `5`: `NAMED_UNION`
+- `6-14`: reserved
+- `15`: extended-kind escape, rejected until defined
Type spec:
@@ -564,7 +580,7 @@ Type spec:
- `namespace` meta string
- `type_name` meta string
- Otherwise:
- - `type_id` as `varuint32` (small7)
+ - user type ID as `varuint32`
Field info list:
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
