deploy: 2e91641de2

features/binary_formats/bjdata.md

@@ -116,18 +116,22 @@ The library uses the following mapping from JSON values types to BJData types ac
     ```
 
     Likewise, when a JSON object in the above form is serialized using
-    [`to_bjdata`](../../api/basic_json/to_bjdata.md), it is automatically converted into a compact BJData ND-array. When
-    the 1-dimensional vector stored in `"_ArraySize_"` contains a single integer or two integers with one being 1, a
-    regular 1-D optimized array is generated instead.
+    [`to_bjdata`](../../api/basic_json/to_bjdata.md), it is automatically converted into a compact BJData ND-array.
 
-    An object is only converted if the annotation actually describes a packed array; otherwise it is serialized as a
-    regular JSON object. This requires all of the following:
+    When parsing, an ND-array whose dimension vector is empty, contains a single integer, contains two integers with the
+    first being 1, or contains a 0 is returned as a regular (possibly empty) array rather than an annotated object.
+
+    An object is only converted if the annotation describes a packed array that is parsed back into the same annotated
+    object; otherwise it is serialized as a regular JSON object, so the annotation is never lost in a round trip. This requires
+    all of the following:
 
     - `"_ArrayType_"` is one of `uint8`, `int8`, `uint16`, `int16`, `uint32`, `int32`, `uint64`, `int64`, `single`,
       `double`, `char`, or `byte`,
     - `"_ArraySize_"` is an array, since the dimensions are written as the ND-array header's length,
-    - every entry of `"_ArraySize_"` is a non-negative integer, and their product is representable as a `std::size_t`,
-    - `"_ArrayData_"` holds exactly that many elements, and
+    - `"_ArraySize_"` has at least two entries and is not a 1×N row vector (first entry 1), since other shapes are
+      parsed back as a regular array,
+    - every entry of `"_ArraySize_"` is a positive integer, and their product is representable as a `std::size_t`,
+    - `"_ArrayData_"` is an array holding exactly that many elements, and
     - every element of `"_ArrayData_"` is a number of the kind named by `"_ArrayType_"` (a floating-point number for
       `single` and `double`, an integer otherwise).
 

features/binary_formats/bjdata/index.md

@@ -92,14 +92,17 @@ To maintain type and size information, ND-arrays are converted to JSON objects f
 }
 ```
 
-Likewise, when a JSON object in the above form is serialized using [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md), it is automatically converted into a compact BJData ND-array. When the 1-dimensional vector stored in `"_ArraySize_"` contains a single integer or two integers with one being 1, a regular 1-D optimized array is generated instead.
+Likewise, when a JSON object in the above form is serialized using [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md), it is automatically converted into a compact BJData ND-array.
 
-An object is only converted if the annotation actually describes a packed array; otherwise it is serialized as a regular JSON object. This requires all of the following:
+When parsing, an ND-array whose dimension vector is empty, contains a single integer, contains two integers with the first being 1, or contains a 0 is returned as a regular (possibly empty) array rather than an annotated object.
+
+An object is only converted if the annotation describes a packed array that is parsed back into the same annotated object; otherwise it is serialized as a regular JSON object, so the annotation is never lost in a round trip. This requires all of the following:
 
 - `"_ArrayType_"` is one of `uint8`, `int8`, `uint16`, `int16`, `uint32`, `int32`, `uint64`, `int64`, `single`, `double`, `char`, or `byte`,
 - `"_ArraySize_"` is an array, since the dimensions are written as the ND-array header's length,
-- every entry of `"_ArraySize_"` is a non-negative integer, and their product is representable as a `std::size_t`,
-- `"_ArrayData_"` holds exactly that many elements, and
+- `"_ArraySize_"` has at least two entries and is not a 1×N row vector (first entry 1), since other shapes are parsed back as a regular array,
+- every entry of `"_ArraySize_"` is a positive integer, and their product is representable as a `std::size_t`,
+- `"_ArrayData_"` is an array holding exactly that many elements, and
 - every element of `"_ArrayData_"` is a number of the kind named by `"_ArrayType_"` (a floating-point number for `single` and `double`, an integer otherwise).
 
 The current version of this library does not yet support automatic detection of and conversion from a nested JSON array input to a BJData ND-array.