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 c40a093febdf598122f27311e11e5f860ce51a2b Author: chaokunyang <[email protected]> AuthorDate: Thu May 7 07:04:42 2026 +0000 🔄 synced local 'docs/specification/' with remote 'docs/specification/' --- docs/specification/xlang_serialization_spec.md | 22 +++++++++++++++++++++- docs/specification/xlang_type_mapping.md | 15 ++++++++++++--- 2 files changed, 33 insertions(+), 4 deletions(-) diff --git a/docs/specification/xlang_serialization_spec.md b/docs/specification/xlang_serialization_spec.md index b1743918a9..851791edbc 100644 --- a/docs/specification/xlang_serialization_spec.md +++ b/docs/specification/xlang_serialization_spec.md @@ -182,6 +182,24 @@ canonical dynamic tags for `array<T>`: `ARRAY (42)` is reserved for a future generic or shaped-array descriptor and is not emitted for dense primitive arrays. +In schema-compatible mode only, a matched struct/class field may read between +direct top-level `list<T>` and direct top-level `array<T>` schemas when `T` +belongs to the valid dense array element domains above. Integer list element +encodings in the same signedness and width domain match the corresponding dense +array element domain. This is a read adaptation, not a schema-kind merge: +writers keep emitting their local canonical `list<T>` or `array<T>` payload, and +TypeDef/ClassDef encodings, fingerprints, dynamic root serialization, +schema-consistent mode, and unknown-field skipping continue to treat `list<T>` +and `array<T>` as distinct kinds. + +The adaptation is limited to the immediate schema of the matched compatible +field. It does not apply when `list<T>` or `array<T>` appears inside another +field type, including collection elements, map keys or values, array elements, +union alternatives, or other generic/container positions. When a peer `list<T>` +payload declares nullable or ref-tracked elements, a local matched `array<T>` +field must raise a compatible-read error. Null list elements must not be coerced +to dense-array default values. + 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. @@ -1219,7 +1237,9 @@ can be taken as an example. #### primitive array Primitive array are taken as a binary buffer, serialization will just write the length of array size as an unsigned int, -then copy the whole buffer into the stream. +then copy the whole buffer into the stream. Multi-byte element arrays are always encoded in little-endian element order; +runtimes whose native typed-array storage uses another byte order must swap or write elements explicitly instead of +copying native storage bytes unchanged. Such serialization won't compress the array. If users want to compress primitive array, users need to register custom serializers for such types or mark it as list type. diff --git a/docs/specification/xlang_type_mapping.md b/docs/specification/xlang_type_mapping.md index acd8743ca1..a05a045bb3 100644 --- a/docs/specification/xlang_type_mapping.md +++ b/docs/specification/xlang_type_mapping.md @@ -93,7 +93,7 @@ FDL spells them as an encoding modifier plus a semantic integer type. | 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<bool>` (bool_array) | 43 | bool[] | BoolArray / ndarray(np.bool\_) | BoolArray / 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>` | @@ -103,8 +103,8 @@ FDL spells them as an encoding modifier plus a semantic integer type. | `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<float16>` (float16_array) | 53 | `Float16Array` / `@Float16Type short[]` | Float16Array / ndarray(float16) | Float16Array / 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) | BFloat16Array / 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>` | @@ -112,6 +112,7 @@ Notes: - 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. +- JavaScript `BoolArray`, fallback `Float16Array`, and `BFloat16Array` are public dense-array wrappers backed by `Uint8Array` or `Uint16Array`. A JavaScript runtime with native `Float16Array` may return that native carrier for `array<float16>`. - 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 @@ -123,6 +124,14 @@ Notes: of the current xlang type-mapping surface. - Current xlang uses `*_ARRAY` for one-dimensional primitive arrays and nested `list` for multi-dimensional arrays. +- `list<T>` and `array<T>` remain distinct schema kinds. In schema-compatible struct/class field + matching only, a direct top-level `list<T>` field may be read as a direct top-level `array<T>` + field, and a direct top-level `array<T>` field may be read as a direct top-level `list<T>` field, + when `T` is one of the dense bool/numeric array domains. Integer list element encodings in the + same signedness and width domain match the corresponding dense array element domain. The rule does + not apply inside nested collection, map, array, union, or generic positions. A peer `list<T>` + payload that declares nullable or ref-tracked elements must raise a compatible-read error when the + local matched field is `array<T>`. ## Type info --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
