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 48b8747d0668e8882e7870602f7fec5955d26bd3
Author: chaokunyang <[email protected]>
AuthorDate: Mon May 4 13:02:28 2026 +0000

    🔄 synced local 'docs/specification/' with remote 'docs/specification/'
---
 docs/specification/xlang_serialization_spec.md | 103 +++++++++++++-----
 docs/specification/xlang_type_mapping.md       | 138 +++++++++++++------------
 2 files changed, 150 insertions(+), 91 deletions(-)

diff --git a/docs/specification/xlang_serialization_spec.md 
b/docs/specification/xlang_serialization_spec.md
index c109a6d288..37a1968012 100644
--- a/docs/specification/xlang_serialization_spec.md
+++ b/docs/specification/xlang_serialization_spec.md
@@ -39,18 +39,12 @@ This specification defines the Fory xlang binary format. 
The format is dynamic r
 - bool: a boolean value (true or false).
 - int8: a 8-bit signed integer.
 - int16: a 16-bit signed integer.
-- int32: a 32-bit signed integer.
-- varint32: a 32-bit signed integer which use fory variable-length encoding.
-- int64: a 64-bit signed integer.
-- varint64: a 64-bit signed integer which use fory PVL encoding.
-- tagged_int64: a 64-bit signed integer which use fory Hybrid encoding.
+- int32: a 32-bit signed integer. Scalar type expressions may use fixed or 
varint encoding.
+- int64: a 64-bit signed integer. Scalar type expressions may use fixed, 
varint/PVL, or tagged encoding.
 - uint8: an 8-bit unsigned integer.
 - uint16: a 16-bit unsigned integer.
-- uint32: a 32-bit unsigned integer.
-- var_uint32: a 32-bit unsigned integer which use fory variable-length 
encoding.
-- uint64: a 64-bit unsigned integer.
-- var_uint64: a 64-bit unsigned integer which use fory PVL encoding.
-- tagged_uint64: a 64-bit unsigned integer which use fory Hybrid encoding.
+- uint32: a 32-bit unsigned integer. Scalar type expressions may use fixed or 
varint encoding.
+- uint64: a 64-bit unsigned integer. Scalar type expressions may use fixed, 
varint/PVL, or tagged encoding.
 - float8: an 8-bit floating point number.
 - float16: a 16-bit floating point number.
 - bfloat16: a 16-bit brain floating point number.
@@ -76,20 +70,23 @@ This specification defines the Fory xlang binary format. 
The format is dynamic r
 - date: a naive date without timezone, encoded as a signed varint64 count of 
days since the Unix epoch.
 - decimal: an exact decimal value encoded as a signed `scale` and an exact 
`unscaled` integer.
 - binary: an variable-length array of bytes.
-- array: in current xlang, only one-dimensional primitive/numeric arrays have 
dedicated wire types. Other arrays are
-  taken as `list`, and implementations should support interoperability between 
array and list carriers. Internal type
-  ID `ARRAY (42)` is reserved for a future dedicated multi-dimensional array 
encoding and is not emitted by the current
-  xlang format.
-  - bool_array: one dimensional bool array.
-  - int8_array: one dimensional int8 array.
-  - int16_array: one dimensional int16 array.
-  - int32_array: one dimensional int32 array.
-  - int64_array: one dimensional int64 array.
-  - float8_array: one dimensional float8 array.
-  - float16_array: one dimensional half_float_16 array.
-  - bfloat16_array: one dimensional bfloat16 array.
-  - float32_array: one dimensional float32 array.
-  - float64_array: one dimensional float64 array.
+- array: `array<T>` is dense one-dimensional bool or numeric data. Current 
xlang emits the canonical specialized
+  `*_ARRAY` type IDs for each supported element domain. `ARRAY (42)` is 
reserved for a future generic array encoding and
+  is not emitted by the current xlang format. `list<T>` remains a separate 
schema kind.
+  - bool_array: canonical wire tag for `array<bool>`.
+  - int8_array: canonical wire tag for `array<int8>`.
+  - int16_array: canonical wire tag for `array<int16>`.
+  - int32_array: canonical wire tag for `array<int32>`.
+  - int64_array: canonical wire tag for `array<int64>`.
+  - uint8_array: canonical wire tag for `array<uint8>`.
+  - uint16_array: canonical wire tag for `array<uint16>`.
+  - uint32_array: canonical wire tag for `array<uint32>`.
+  - uint64_array: canonical wire tag for `array<uint64>`.
+  - float8_array: reserved canonical wire tag for `array<float8>`.
+  - float16_array: canonical wire tag for `array<float16>`.
+  - bfloat16_array: canonical wire tag for `array<bfloat16>`.
+  - float32_array: canonical wire tag for `array<float32>`.
+  - float64_array: canonical wire tag for `array<float64>`.
 - union: a tagged union type that can hold one of several alternative types. 
The active alternative is identified by an index.
 - typed_union: a union value with registered numeric union type ID.
 - named_union: a union value with embedded union type name or shared TypeDef.
@@ -128,9 +125,61 @@ class Foo2 {
 }
 ```
 
-`intArray` has an `int32_array` type. But both `objects` and `objectList` 
fields in the serialize data have `list` data
-type. When deserializing, the implementation will create an `Object` array for 
`objects`, but create a `ArrayList`
-for `objectList` to populate its elements. And the serialized data of `Foo` 
can be deserialized into `Foo2` too.
+`intArray` has `array<int32>` schema and uses the `int32_array` wire tag. Both 
`objects` and `objectList` have `list`
+schema. These schema kinds are distinct; implementations must not treat 
general object arrays as dense numeric arrays.
+
+### List and Array Semantics
+
+`list<T>` and `array<T>` are different schema kinds.
+
+Use `list<T>` for ordinary ordered collections whose elements may need 
collection
+semantics, nullable element handling, reference handling, or 
object/string/bytes
+payloads. A primitive `list<T>` may still use an optimized homogeneous element
+segment internally, but the payload is owned by the list protocol and carries
+list metadata.
+
+Use `array<T>` for dynamic-length dense one-dimensional bool or numeric data.
+`array<T>` elements are always non-null, non-reference-tracked, and fixed-width
+by the array contract. `array<bool>` uses one byte per value. Integer arrays 
use
+fixed-width little-endian element payloads even when the scalar `int32`,
+`int64`, `uint32`, or `uint64` default encoding is varint/PVL in scalar or list
+positions.
+
+Valid `array<T>` element domains are:
+
+```text
+bool
+int8, int16, int32, int64
+uint8, uint16, uint32, uint64
+float16, bfloat16, float32, float64
+```
+
+Invalid array schemas include `array<fixed int32>`,
+`array<optional int32>`, `array<ref T>`, `array<string>`, `array<bytes>`,
+`array<map<...>>`, and arrays of structs, unions, enums, temporal values,
+decimals, or dynamic `any` values.
+
+The current wire format keeps specialized primitive-array type IDs as the
+canonical dynamic tags for `array<T>`:
+
+| Schema            | Dynamic wire tag |
+| ----------------- | ---------------- |
+| `array<bool>`     | `BOOL_ARRAY`     |
+| `array<int8>`     | `INT8_ARRAY`     |
+| `array<int16>`    | `INT16_ARRAY`    |
+| `array<int32>`    | `INT32_ARRAY`    |
+| `array<int64>`    | `INT64_ARRAY`    |
+| `array<uint8>`    | `UINT8_ARRAY`    |
+| `array<uint16>`   | `UINT16_ARRAY`   |
+| `array<uint32>`   | `UINT32_ARRAY`   |
+| `array<uint64>`   | `UINT64_ARRAY`   |
+| `array<float16>`  | `FLOAT16_ARRAY`  |
+| `array<bfloat16>` | `BFLOAT16_ARRAY` |
+| `array<float32>`  | `FLOAT32_ARRAY`  |
+| `array<float64>`  | `FLOAT64_ARRAY`  |
+
+`ARRAY (42)` is reserved for a future generic or shaped-array descriptor and is
+not emitted for dense primitive arrays.
 
 Users can also provide meta hints for fields of a type, or the type whole. 
Here is an example in java which use
 annotation to provide such information.
diff --git a/docs/specification/xlang_type_mapping.md 
b/docs/specification/xlang_type_mapping.md
index a96688d0bc..acd8743ca1 100644
--- a/docs/specification/xlang_type_mapping.md
+++ b/docs/specification/xlang_type_mapping.md
@@ -48,65 +48,76 @@ When reading type IDs:
 
 ## Type Mapping
 
-| Fory Type               | Fory Type ID | Java            | Python            
       | Javascript                     | C++                                   
              | Golang                                         | Rust           
                   |
-| ----------------------- | ------------ | --------------- | 
------------------------ | ------------------------------ | 
--------------------------------------------------- | 
---------------------------------------------- | 
--------------------------------- |
-| bool                    | 1            | bool/Boolean    | bool              
       | Boolean                        | bool                                  
              | bool                                           | bool           
                   |
-| int8                    | 2            | byte/Byte       | int/pyfory.int8   
       | Type.int8()                    | int8_t                                
              | int8                                           | i8             
                   |
-| int16                   | 3            | short/Short     | int/pyfory.int16  
       | Type.int16()                   | int16_t                               
              | int16                                          | i16            
                   |
-| int32                   | 4            | int/Integer     | 
int/pyfory.fixed_int32   | Type.int32()                   | int32_t             
                                | int32                                         
 | i32                               |
-| varint32                | 5            | int/Integer     | int/pyfory.int32  
       | Type.varint32()                | int32_t                               
              | int32                                          | i32            
                   |
-| int64                   | 6            | long/Long       | 
int/pyfory.fixed_int64   | Type.int64()                   | int64_t             
                                | int64                                         
 | i64                               |
-| varint64                | 7            | long/Long       | int/pyfory.int64  
       | Type.varint64()                | int64_t                               
              | int64                                          | i64            
                   |
-| tagged_int64            | 8            | long/Long       | 
int/pyfory.tagged_int64  | Type.tagged_int64()            | int64_t             
                                | int64                                         
 | i64                               |
-| uint8                   | 9            | short/Short     | int/pyfory.uint8  
       | Type.uint8()                   | uint8_t                               
              | uint8                                          | u8             
                   |
-| uint16                  | 10           | int/Integer     | int/pyfory.uint16 
       | Type.uint16()                  | uint16_t                              
              | uint16                                         | u16            
                   |
-| uint32                  | 11           | long/Long       | 
int/pyfory.fixed_uint32  | Type.uint32()                  | uint32_t            
                                | uint32                                        
 | u32                               |
-| var_uint32              | 12           | long/Long       | int/pyfory.uint32 
       | Type.varUInt32()               | uint32_t                              
              | uint32                                         | u32            
                   |
-| uint64                  | 13           | long/Long       | 
int/pyfory.fixed_uint64  | Type.uint64()                  | uint64_t            
                                | uint64                                        
 | u64                               |
-| var_uint64              | 14           | long/Long       | int/pyfory.uint64 
       | Type.varUInt64()               | uint64_t                              
              | uint64                                         | u64            
                   |
-| tagged_uint64           | 15           | long/Long       | 
int/pyfory.tagged_uint64 | Type.taggedUInt64()            | uint64_t            
                                | uint64                                        
 | u64                               |
-| float8                  | 16           | /               | /                 
       | /                              | /                                     
              | /                                              | /              
                   |
-| float16                 | 17           | Float16         | 
float/pyfory.float16     | `number`                       | `fory::float16_t`   
                                | `float16.Float16`                             
 | `fory::f16`                       |
-| bfloat16                | 18           | BFloat16        | pyfory.bfloat16   
       | `BFloat16` / `number`          | `fory::bfloat16_t`                    
              | `bfloat16.BFloat16`                            | `BFloat16`     
                   |
-| float32                 | 19           | float/Float     | 
float/pyfory.float32     | Type.float32()                 | float               
                                | float32                                       
 | f32                               |
-| float64                 | 20           | double/Double   | 
float/pyfory.float64     | Type.float64()                 | double              
                                | float64                                       
 | f64                               |
-| string                  | 21           | String          | str               
       | String                         | string                                
              | string                                         | String/str     
                   |
-| list                    | 22           | List/Collection | list/tuple        
       | array                          | vector                                
              | slice                                          | Vec            
                   |
-| set                     | 23           | Set             | set               
       | /                              | set                                   
              | fory.Set                                       | Set            
                   |
-| map                     | 24           | Map             | dict              
       | Map                            | unordered_map                         
              | map                                            | HashMap        
                   |
-| enum                    | 25           | Enum subclasses | enum subclasses   
       | /                              | enum                                  
              | /                                              | enum           
                   |
-| named_enum              | 26           | Enum subclasses | enum subclasses   
       | /                              | enum                                  
              | /                                              | enum           
                   |
-| struct                  | 27           | pojo/record     | data class        
       | object                         | struct/class                          
              | struct                                         | struct         
                   |
-| compatible_struct       | 28           | pojo/record     | data class        
       | object                         | struct/class                          
              | struct                                         | struct         
                   |
-| named_struct            | 29           | pojo/record     | data class        
       | object                         | struct/class                          
              | struct                                         | struct         
                   |
-| named_compatible_struct | 30           | pojo/record     | data class        
       | object                         | struct/class                          
              | struct                                         | struct         
                   |
-| ext                     | 31           | pojo/record     | data class        
       | object                         | struct/class                          
              | struct                                         | struct         
                   |
-| named_ext               | 32           | pojo/record     | data class        
       | object                         | struct/class                          
              | struct                                         | struct         
                   |
-| union                   | 33           | Union           | typing.Union      
       | /                              | `std::variant<Ts...>`                 
              | /                                              | tagged union 
enum                 |
-| none                    | 36           | null            | None              
       | null                           | `std::monostate`                      
              | nil                                            | `()`           
                   |
-| duration                | 37           | Duration        | timedelta         
       | Number                         | duration                              
              | Duration                                       | Duration       
                   |
-| timestamp               | 38           | Instant         | datetime          
       | Number                         | std::chrono::nanoseconds              
              | Time                                           | DateTime       
                   |
-| date                    | 39           | LocalDate       | datetime.date     
       | Date                           | fory::serialization::Date             
              | fory.Date                                      | 
chrono::NaiveDate                 |
-| decimal                 | 40           | BigDecimal      | Decimal           
       | Decimal                        | /                                     
              | fory.Decimal                                   | fory::Decimal  
                   |
-| binary                  | 41           | byte[]          | bytes             
       | /                              | `uint8_t[n]/vector<T>`                
              | `[n]uint8/[]T`                                 | `Vec<uint8_t>` 
                   |
-| bool_array              | 43           | bool[]          | 
ndarray(np.bool\_)       | /                              | `bool[n]`           
                                | `[n]bool/[]T`                                 
 | `Vec<bool>`                       |
-| int8_array              | 44           | byte[]          | ndarray(int8)     
       | /                              | `int8_t[n]/vector<T>`                 
              | `[n]int8/[]T`                                  | `Vec<i8>`      
                   |
-| int16_array             | 45           | short[]         | ndarray(int16)    
       | /                              | `int16_t[n]/vector<T>`                
              | `[n]int16/[]T`                                 | `Vec<i16>`     
                   |
-| int32_array             | 46           | int[]           | ndarray(int32)    
       | /                              | `int32_t[n]/vector<T>`                
              | `[n]int32/[]T`                                 | `Vec<i32>`     
                   |
-| int64_array             | 47           | long[]          | ndarray(int64)    
       | /                              | `int64_t[n]/vector<T>`                
              | `[n]int64/[]T`                                 | `Vec<i64>`     
                   |
-| uint8_array             | 48           | short[]         | ndarray(uint8)    
       | /                              | `uint8_t[n]/vector<T>`                
              | `[n]uint8/[]T`                                 | `Vec<u8>`      
                   |
-| uint16_array            | 49           | int[]           | ndarray(uint16)   
       | /                              | `uint16_t[n]/vector<T>`               
              | `[n]uint16/[]T`                                | `Vec<u16>`     
                   |
-| uint32_array            | 50           | long[]          | ndarray(uint32)   
       | /                              | `uint32_t[n]/vector<T>`               
              | `[n]uint32/[]T`                                | `Vec<u32>`     
                   |
-| uint64_array            | 51           | long[]          | ndarray(uint64)   
       | /                              | `uint64_t[n]/vector<T>`               
              | `[n]uint64/[]T`                                | `Vec<u64>`     
                   |
-| float8_array            | 52           | /               | /                 
       | /                              | /                                     
              | /                                              | /              
                   |
-| float16_array           | 53           | Float16List     | ndarray(float16)  
       | `number[]`                     | 
`fory::float16_t[n]/std::vector<fory::float16_t>`   | `[N]float16.Float16` / 
`[]float16.Float16`     | `Vec<fory::f16>` / `[Float16; N]` |
-| bfloat16_array          | 54           | BFloat16List    | 
pyfory.bfloat16array     | `BFloat16Array` / `BFloat16[]` | 
`fory::bfloat16_t[n]/std::vector<fory::bfloat16_t>` | `[N]bfloat16.BFloat16` / 
`[]bfloat16.BFloat16` | `Vec<BFloat16>` / `[BFloat16; N]` |
-| float32_array           | 55           | float[]         | ndarray(float32)  
       | /                              | `float[n]/vector<T>`                  
              | `[n]float32/[]T`                               | `Vec<f32>`     
                   |
-| float64_array           | 56           | double[]        | ndarray(float64)  
       | /                              | `double[n]/vector<T>`                 
              | `[n]float64/[]T`                               | `Vec<f64>`     
                   |
+The first column names the Fory schema expression or canonical wire tag. Scalar
+encoding rows such as `fixed int32` and `tagged int64` are not FDL type names;
+FDL spells them as an encoding modifier plus a semantic integer type.
+
+| Fory schema / wire tag             | Fory Type ID | Java                     
                 | Python                                    | Javascript       
                     | C++                                                 | 
Golang                                         | Rust                           
   |
+| ---------------------------------- | ------------ | 
----------------------------------------- | 
----------------------------------------- | 
------------------------------------- | 
--------------------------------------------------- | 
---------------------------------------------- | 
--------------------------------- |
+| bool                               | 1            | bool/Boolean             
                 | bool                                      | Boolean          
                     | bool                                                | 
bool                                           | bool                           
   |
+| int8                               | 2            | byte/Byte                
                 | int/pyfory.Int8                           | Type.int8()      
                     | int8_t                                              | 
int8                                           | i8                             
   |
+| int16                              | 3            | short/Short              
                 | int/pyfory.Int16                          | Type.int16()     
                     | int16_t                                             | 
int16                                          | i16                            
   |
+| fixed int32                        | 4            | int/Integer              
                 | int/pyfory.FixedInt32                     | `Type.int32({ 
encoding: "fixed" })`   | int32_t                                             | 
int32                                          | i32                            
   |
+| int32                              | 5            | int/Integer              
                 | int/pyfory.Int32                          | Type.int32()     
                     | int32_t                                             | 
int32                                          | i32                            
   |
+| fixed int64                        | 6            | long/Long                
                 | int/pyfory.FixedInt64                     | `Type.int64({ 
encoding: "fixed" })`   | int64_t                                             | 
int64                                          | i64                            
   |
+| int64                              | 7            | long/Long                
                 | int/pyfory.Int64                          | Type.int64()     
                     | int64_t                                             | 
int64                                          | i64                            
   |
+| tagged int64                       | 8            | long/Long                
                 | int/pyfory.TaggedInt64                    | `Type.int64({ 
encoding: "tagged" })`  | int64_t                                             | 
int64                                          | i64                            
   |
+| uint8                              | 9            | short/Short              
                 | int/pyfory.UInt8                          | Type.uint8()     
                     | uint8_t                                             | 
uint8                                          | u8                             
   |
+| uint16                             | 10           | int/Integer              
                 | int/pyfory.UInt16                         | Type.uint16()    
                     | uint16_t                                            | 
uint16                                         | u16                            
   |
+| fixed uint32                       | 11           | long/Long                
                 | int/pyfory.FixedUInt32                    | `Type.uint32({ 
encoding: "fixed" })`  | uint32_t                                            | 
uint32                                         | u32                            
   |
+| uint32                             | 12           | long/Long                
                 | int/pyfory.UInt32                         | Type.uint32()    
                     | uint32_t                                            | 
uint32                                         | u32                            
   |
+| fixed uint64                       | 13           | long/Long                
                 | int/pyfory.FixedUInt64                    | `Type.uint64({ 
encoding: "fixed" })`  | uint64_t                                            | 
uint64                                         | u64                            
   |
+| uint64                             | 14           | long/Long                
                 | int/pyfory.UInt64                         | Type.uint64()    
                     | uint64_t                                            | 
uint64                                         | u64                            
   |
+| tagged uint64                      | 15           | long/Long                
                 | int/pyfory.TaggedUInt64                   | `Type.uint64({ 
encoding: "tagged" })` | uint64_t                                            | 
uint64                                         | u64                            
   |
+| float8                             | 16           | /                        
                 | /                                         | /                
                     | /                                                   | /  
                                            | /                                 
|
+| float16                            | 17           | Float16                  
                 | native float / pyfory.Float16 annotation  | `number`         
                     | `fory::float16_t`                                   | 
`float16.Float16`                              | `Float16`                      
   |
+| bfloat16                           | 18           | BFloat16                 
                 | native float / pyfory.BFloat16 annotation | `BFloat16` / 
`number`                 | `fory::bfloat16_t`                                  
| `bfloat16.BFloat16`                            | `BFloat16`                   
     |
+| float32                            | 19           | float/Float              
                 | float/pyfory.Float32                      | Type.float32()   
                     | float                                               | 
float32                                        | f32                            
   |
+| float64                            | 20           | double/Double            
                 | float/pyfory.Float64                      | Type.float64()   
                     | double                                              | 
float64                                        | f64                            
   |
+| string                             | 21           | String                   
                 | str                                       | String           
                     | string                                              | 
string                                         | String/str                     
   |
+| list                               | 22           | List/Collection          
                 | list/tuple                                | array            
                     | vector                                              | 
slice                                          | Vec                            
   |
+| set                                | 23           | Set                      
                 | set                                       | /                
                     | set                                                 | 
fory.Set                                       | Set                            
   |
+| map                                | 24           | Map                      
                 | dict                                      | Map              
                     | unordered_map                                       | 
map                                            | HashMap                        
   |
+| enum                               | 25           | Enum subclasses          
                 | enum subclasses                           | /                
                     | enum                                                | /  
                                            | enum                              
|
+| named_enum                         | 26           | Enum subclasses          
                 | enum subclasses                           | /                
                     | enum                                                | /  
                                            | enum                              
|
+| struct                             | 27           | pojo/record              
                 | data class                                | object           
                     | struct/class                                        | 
struct                                         | struct                         
   |
+| compatible_struct                  | 28           | pojo/record              
                 | data class                                | object           
                     | struct/class                                        | 
struct                                         | struct                         
   |
+| named_struct                       | 29           | pojo/record              
                 | data class                                | object           
                     | struct/class                                        | 
struct                                         | struct                         
   |
+| named_compatible_struct            | 30           | pojo/record              
                 | data class                                | object           
                     | struct/class                                        | 
struct                                         | struct                         
   |
+| ext                                | 31           | pojo/record              
                 | data class                                | object           
                     | struct/class                                        | 
struct                                         | struct                         
   |
+| named_ext                          | 32           | pojo/record              
                 | data class                                | object           
                     | struct/class                                        | 
struct                                         | struct                         
   |
+| union                              | 33           | Union                    
                 | typing.Union                              | /                
                     | `std::variant<Ts...>`                               | /  
                                            | tagged union enum                 
|
+| none                               | 36           | null                     
                 | None                                      | null             
                     | `std::monostate`                                    | 
nil                                            | `()`                           
   |
+| duration                           | 37           | Duration                 
                 | timedelta                                 | Number           
                     | duration                                            | 
Duration                                       | Duration                       
   |
+| timestamp                          | 38           | Instant                  
                 | datetime                                  | Number           
                     | std::chrono::nanoseconds                            | 
Time                                           | DateTime                       
   |
+| date                               | 39           | LocalDate                
                 | datetime.date                             | Date             
                     | fory::serialization::Date                           | 
fory.Date                                      | chrono::NaiveDate              
   |
+| decimal                            | 40           | BigDecimal               
                 | Decimal                                   | Decimal          
                     | /                                                   | 
fory.Decimal                                   | fory::Decimal                  
   |
+| binary                             | 41           | byte[]                   
                 | bytes                                     | /                
                     | `uint8_t[n]/vector<T>`                              | 
`[n]uint8/[]T`                                 | `Vec<u8>`                      
   |
+| `array<bool>` (bool_array)         | 43           | bool[]                   
                 | BoolArray / ndarray(np.bool\_)            | Type.boolArray() 
                     | `bool[n]`                                           | 
`[n]bool/[]T`                                  | `Vec<bool>`                    
   |
+| `array<int8>` (int8_array)         | 44           | `@Int8Type byte[]`       
                 | Int8Array / ndarray(int8)                 | Type.int8Array() 
                     | `int8_t[n]/vector<T>`                               | 
`[n]int8/[]T`                                  | `Vec<i8>`                      
   |
+| `array<int16>` (int16_array)       | 45           | short[]                  
                 | Int16Array / ndarray(int16)               | 
Type.int16Array()                     | `int16_t[n]/vector<T>`                  
            | `[n]int16/[]T`                                 | `Vec<i16>`       
                 |
+| `array<int32>` (int32_array)       | 46           | int[]                    
                 | Int32Array / ndarray(int32)               | 
Type.int32Array()                     | `int32_t[n]/vector<T>`                  
            | `[n]int32/[]T`                                 | `Vec<i32>`       
                 |
+| `array<int64>` (int64_array)       | 47           | long[]                   
                 | Int64Array / ndarray(int64)               | 
Type.int64Array()                     | `int64_t[n]/vector<T>`                  
            | `[n]int64/[]T`                                 | `Vec<i64>`       
                 |
+| `array<uint8>` (uint8_array)       | 48           | `@UInt8Type byte[]`      
                 | UInt8Array / ndarray(uint8)               | 
Type.uint8Array()                     | `uint8_t[n]/vector<T>`                  
            | `[n]uint8/[]T`                                 | `Vec<u8>`        
                 |
+| `array<uint16>` (uint16_array)     | 49           | `@UInt16Type short[]`    
                 | UInt16Array / ndarray(uint16)             | 
Type.uint16Array()                    | `uint16_t[n]/vector<T>`                 
            | `[n]uint16/[]T`                                | `Vec<u16>`       
                 |
+| `array<uint32>` (uint32_array)     | 50           | `@UInt32Type int[]`      
                 | UInt32Array / ndarray(uint32)             | 
Type.uint32Array()                    | `uint32_t[n]/vector<T>`                 
            | `[n]uint32/[]T`                                | `Vec<u32>`       
                 |
+| `array<uint64>` (uint64_array)     | 51           | `@UInt64Type long[]`     
                 | UInt64Array / ndarray(uint64)             | 
Type.uint64Array()                    | `uint64_t[n]/vector<T>`                 
            | `[n]uint64/[]T`                                | `Vec<u64>`       
                 |
+| `array<float8>` (float8_array)     | 52           | /                        
                 | /                                         | /                
                     | /                                                   | /  
                                            | /                                 
|
+| `array<float16>` (float16_array)   | 53           | `Float16Array` / 
`@Float16Type short[]`   | Float16Array / ndarray(float16)           | 
Type.float16Array()                   | 
`fory::float16_t[n]/std::vector<fory::float16_t>`   | `[N]float16.Float16` / 
`[]float16.Float16`     | `Vec<Float16>` / `[Float16; N]`   |
+| `array<bfloat16>` (bfloat16_array) | 54           | `BFloat16Array` / 
`@BFloat16Type short[]` | BFloat16Array / ndarray(bfloat16)         | 
Type.bfloat16Array()                  | 
`fory::bfloat16_t[n]/std::vector<fory::bfloat16_t>` | `[N]bfloat16.BFloat16` / 
`[]bfloat16.BFloat16` | `Vec<BFloat16>` / `[BFloat16; N]` |
+| `array<float32>` (float32_array)   | 55           | float[]                  
                 | Float32Array / ndarray(float32)           | 
Type.float32Array()                   | `float[n]/vector<T>`                    
            | `[n]float32/[]T`                               | `Vec<f32>`       
                 |
+| `array<float64>` (float64_array)   | 56           | double[]                 
                 | Float64Array / ndarray(float64)           | 
Type.float64Array()                   | `double[n]/vector<T>`                   
            | `[n]float64/[]T`                               | `Vec<f64>`       
                 |
 
 Notes:
 
-- `Float16List` and `BFloat16List` are the xlang `float16_array` and 
`bfloat16_array` carriers.
+- Python `pyfory.Float16` and `pyfory.BFloat16` are reserved annotation 
markers; scalar values deserialize as native Python `float`.
+- Python `BoolArray`, `Int8Array`, `Int16Array`, `Int32Array`, `Int64Array`, 
`UInt8Array`, `UInt16Array`, `UInt32Array`, `UInt64Array`, `Float16Array`, 
`BFloat16Array`, `Float32Array`, and `Float64Array` are public dense-array 
wrappers with list-like sequence behavior.
+- Java plain `byte[]` maps to `binary`. Numeric byte arrays use type-use 
annotations:
+  `@Int8Type byte[]` for `array<int8>` and `@UInt8Type byte[]` for 
`array<uint8>`.
+- Dart uses `BoolList` for `array<bool>`, typed-data lists for 
integer/float32/float64 arrays, and
+  `Float16List` / `BFloat16List` for `array<float16>` / `array<bfloat16>`. 
Plain Dart `List<bool>`
+  maps to `list<bool>` unless a field uses `@ArrayField(element: BoolType())` 
or
+  `@ForyField(type: ArrayType(element: BoolType()))` with a `BoolList` carrier.
 - `Float16[]` and `BFloat16[]` remain object arrays in xlang mode and 
serialize with the `list` wire type.
 - `ARRAY (42)` is reserved for a future dedicated multi-dimensional array 
encoding and is not part
   of the current xlang type-mapping surface.
@@ -117,9 +128,9 @@ Notes:
 
 Due to differences between type systems of languages, those types can't be 
mapped one-to-one between languages.
 
-If the user notices that one type on a language corresponds to multiple types 
in Fory type systems, for example, `long`
-in java has type `int64/varint64/h64`, it means the language lacks some types, 
and the user must provide extra type
-info when using Fory.
+If one host-language type corresponds to multiple Fory scalar encodings, for
+example Java `long` can represent fixed, varint, or tagged `int64`, the user
+must provide encoding metadata when the default is not the intended schema.
 
 ## Type annotation
 
@@ -138,9 +149,8 @@ Here is en example:
 
   ```java
   class Foo {
-    @Int32Type(encoding = Int32Encoding.FIXED)
-    int f1;
-    List<@Int32Type(encoding = Int32Encoding.FIXED) Integer> f2;
+    private @Int32Type int f1;
+    private List<@Int32Type Integer> f2;
   }
   ```
 
@@ -148,6 +158,6 @@ Here is en example:
 
   ```python
   class Foo:
-      f1: pyfory.fixed_int32
-      f2: List[pyfory.int32]
+      f1: pyfory.Int32
+      f2: List[pyfory.Int32]
   ```


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]


Reply via email to