Refactor documentation for mappings in HDF5 and Zarr formats to improve clarity and consistency

Author: Claptar

docs/ELEMENTS_h5ad.md

@@ -18,7 +18,8 @@ It is intended to be GitHub-renderable Markdown (no Sphinx/MyST directives).
   - [DataFrame v0.2.0](#dataframe-v020)
   - [DataFrame v0.1.0 (legacy: anndata 0.7.x)](#dataframe-v010-legacy-anndata-07x)
   - [Legacy categorical columns (Series-level)](#legacy-categorical-columns-series-level)
-- [Mappings / dict](#mappings--dict)
+- [Mappings](#mappings)
+  - [Legacy mapping encoding (`dict` v0.1.0)](#legacy-mapping-encoding-dict-v010)
 - [Scalars](#scalars)
 - [Categorical arrays](#categorical-arrays)
 - [String arrays](#string-arrays)
@@ -152,26 +153,37 @@ In v0.1.0 DataFrames, a categorical column dataset (e.g. `obs/cell_type`) can be
 
 - `categories`: an **HDF5 object reference** pointing to the corresponding `__categories/<colname>` dataset.
 
-## Mappings / dict
+## Mappings
 
-### `encoding-type: dict`, `encoding-version: 0.1.0`
+Mappings are stored as HDF5 **groups** on disk.
 
-- A mapping **MUST** be stored as an HDF5 **group**.
-- Group attributes:
-  - `encoding-type: "dict"`
-  - `encoding-version: "0.1.0"`
-- Each entry in the group is another element (recursively).
+- This includes standard AnnData mappings such as `layers`, `obsm`, `varm`, `obsp`, `varp`, and `uns`.
+- Mappings are distinct from DataFrames and sparse arrays and do not require special mapping-specific attributes.
+- Mapping semantics are recursive: entries in `uns` can themselves be groups containing additional encoded elements.
 
-> **Legacy note**
+> **Legacy compatibility note**
 >
-> In anndata 0.7.x, groups used as mappings often had **no special attributes**.
+> In earlier conventions (commonly seen in older docs and some files), mappings could carry
+> `encoding-type: "dict"` and `encoding-version: "0.1.0"`.
+> Readers should still accept this legacy metadata when encountered.
+
+### Legacy mapping encoding (`dict` v0.1.0)
+
+For backward compatibility, older files may encode mappings with explicit mapping metadata:
+
+- `encoding-type: "dict"`
+- `encoding-version: "0.1.0"`
+
+This historical convention existed in earlier AnnData docs and files and should still be accepted by readers.
 
 ## Scalars
 
 ### `encoding-version: 0.2.0`
 
 Scalars are stored as **0-dimensional datasets**.
 
+These should typically only occur inside `uns` and are commonly used for saved parameters.
+
 - Numeric scalars:
   - `encoding-type: "numeric-scalar"`
   - `encoding-version: "0.2.0"`

docs/ELEMENTS_zarr.md

@@ -18,7 +18,8 @@ It is intended to be GitHub-renderable Markdown (no Sphinx/MyST directives).
   - [DataFrame v0.2.0](#dataframe-v020)
   - [DataFrame v0.1.0 (legacy: anndata 0.7.x)](#dataframe-v010-legacy-anndata-07x)
   - [Legacy categorical columns (Series-level)](#legacy-categorical-columns-series-level)
-- [Mappings / dict](#mappings--dict)
+- [Mappings](#mappings)
+  - [Legacy mapping encoding (`dict` v0.1.0)](#legacy-mapping-encoding-dict-v010)
 - [Scalars](#scalars)
 - [Categorical arrays](#categorical-arrays)
 - [String arrays](#string-arrays)
@@ -154,26 +155,37 @@ In v0.1.0 DataFrames, a categorical column array (e.g. `obs/cell_type`) can be i
 
 (This differs from HDF5, which can store an object reference.)
 
-## Mappings / dict
+## Mappings
 
-### `encoding-type: dict`, `encoding-version: 0.1.0`
+Mappings are stored as Zarr **groups** on disk.
 
-- A mapping **MUST** be stored as a Zarr **group**.
-- Group attributes:
-  - `encoding-type: "dict"`
-  - `encoding-version: "0.1.0"`
-- Each entry in the group is another element (recursively).
+- This includes standard AnnData mappings such as `layers`, `obsm`, `varm`, `obsp`, `varp`, and `uns`.
+- Mappings are distinct from DataFrames and sparse arrays and do not require special mapping-specific attributes.
+- Mapping semantics are recursive: entries in `uns` can themselves be groups containing additional encoded elements.
 
-> **Legacy note**
+> **Legacy compatibility note**
 >
-> In anndata 0.7.x, groups used as mappings often had **no special attributes**.
+> In earlier conventions (commonly seen in older docs and some files), mappings could carry
+> `encoding-type: "dict"` and `encoding-version: "0.1.0"`.
+> Readers should still accept this legacy metadata when encountered.
+
+### Legacy mapping encoding (`dict` v0.1.0)
+
+For backward compatibility, older files may encode mappings with explicit mapping metadata:
+
+- `encoding-type: "dict"`
+- `encoding-version: "0.1.0"`
+
+This historical convention existed in earlier AnnData docs and files and should still be accepted by readers.
 
 ## Scalars
 
 ### `encoding-version: 0.2.0`
 
 Scalars are stored as **0-dimensional Zarr arrays**.
 
+These should typically only occur inside `uns` and are commonly used for saved parameters.
+
 - Numeric scalars:
   - `encoding-type: "numeric-scalar"`
   - `encoding-version: "0.2.0"`