feat: add store-root spatial:bbox and tighten minispec requirements (EOPF-Explorer#164)

* feat: add store-root spatial:bbox and tighten minispec requirements

Introduces a GeoZarr "Store Root" layer in the minispec so clients can read
a summary footprint without walking into child groups, and tightens the
multiscale profile so `spatial:bbox` at the root and `spatial:transform` +
`spatial:shape` on every layout entry are mandatory.

Adds a new `geozarr.store` pydantic module (`GeoZarrStoreAttrs`,
`GeoZarrMultiscaleGroupAttrs`, `GeoZarr`) enforcing the tightened profile,
and updates the S2 converter to union child-group bboxes into an EPSG:4326
footprint written at the store root.

Closes EOPF-Explorer#156. Addresses the clear parts of EOPF-Explorer#163; the array-level and
non-multiscale-group parts of that issue need further clarification.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat: update GeoZarr store model and optimize S2 converter for improved bbox handling

* Addresses review feedback on EOPF-Explorer#164:

- Adds a "GeoZarr Hierarchy & Identification" subsection to the Store Root
  section of the minispec, codifying d-v-b's proposed rules: single root,
  root prefix ends with `.zarr`, suffix occurs at most once in the
  hierarchy, and explicit terminal-path conditions.
- Promotes the store-root CRS to mandatory: at least one of `proj:code`,
  `proj:wkt2`, `proj:projjson` MUST be set; there is no implicit EPSG:4326
  default. Per @vincentsarago's review.
- Promotes `zarr_conventions` declaration at the store root from
  RECOMMENDED to required.
- Converter now writes `proj:code: "EPSG:4326"` at the root alongside
  `spatial:bbox`.
- Pydantic `GeoZarrStoreAttrs` enforces the new CRS-required rule.

Cross-links the new hierarchy + spatial:extent follow-ups upstream:
zarr-developers/geozarr-spec#132 (hierarchy & root identification, also
addresses EOPF-Explorer#124 URL parsing) and EOPF-Explorer#133 (STAC-style spatial:extent).

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: emmanuelmathot

docs/geozarr-minispec.md

@@ -49,6 +49,107 @@ and their attributes before moving to higher-level structures like groups and th
 
 This specification targets **Zarr V3** exclusively. The geo-proj, spatial, and multiscales conventions are all Zarr V3.
 
+## Store Root
+
+A GeoZarr Store is the outermost Zarr group of a dataset — the group located at the root of the Zarr store (e.g. `my_dataset.zarr/zarr.json`). It sits above any [Dataset](#dataset) or [Multiscale Dataset](#multiscale-dataset) nodes in the hierarchy and is intended to give clients a single place to read a **summary spatial footprint** for the whole store without having to walk into child groups.
+
+> [!Note]
+> The hierarchy and identification rules below are local choices made for this implementation. They are subject to revision once the OGC GeoZarr Standards Working Group decides on canonical wording. A follow-up to surface these rules upstream is tracked in [zarr-developers/geozarr-spec#132](https://github.com/zarr-developers/geozarr-spec/issues/132). See also [GeoZarr Specification Contribution](geozarr-specification-contribution.md).
+
+### Hierarchy & Identification
+
+A GeoZarr hierarchy has these properties:
+
+- **Single root**: every GeoZarr store has exactly one root group.
+- **Root naming**: the root group is stored under a prefix ending with `.zarr` (e.g. `my_dataset.zarr/`). Clients given any sub-path inside a GeoZarr store MAY recover the root by walking up the path until they hit a segment ending in `.zarr`.
+- **No nested stores**: the `.zarr` suffix SHOULD occur exactly once in any path within the hierarchy. Nesting GeoZarr stores (e.g. `a.zarr/b/c.zarr/`) is strongly discouraged because it breaks the root-recovery rule above.
+- **Terminal paths**: a path `p` within the hierarchy is *terminal* (a leaf) when any of the following holds:
+  - an array node is reached at `p`,
+  - a group with no members is reached at `p`,
+  - `p` ends with a `zarr.json` file.
+
+### Attributes
+
+The store root carries a top-level spatial footprint. This is **informative**: it helps clients place the store spatially (STAC-style discovery) but is not authoritative — per-Dataset / per-Multiscale Dataset `spatial:` and `proj:` attributes remain the source of truth for reading individual variables.
+
+| key | type | required | notes |
+| --- | ---- | -------- | ----- |
+| `zarr_conventions` | array | yes | MUST declare the `spatial:` and `proj:` conventions used at the root |
+| `spatial:bbox` | number[4] | yes | Bounding box `[xmin, ymin, xmax, ymax]` covering the union of all spatial assets in the store, expressed in the CRS named by `proj:code` (or `proj:wkt2` / `proj:projjson`) |
+| `proj:code` | string | conditional* | Authority:code identifier of the bbox CRS, e.g. `"EPSG:4326"` |
+| `proj:wkt2` | string | conditional* | WKT2 representation of the bbox CRS |
+| `proj:projjson` | object | conditional* | PROJJSON representation of the bbox CRS |
+
+\* At least one of `proj:code`, `proj:wkt2`, `proj:projjson` MUST be provided. Use `"EPSG:4326"` (longitude/latitude, degrees) when no other CRS is meaningful — the store-root CRS is always declared explicitly; there is no implicit default.
+
+> [!Note]
+> The store-root `spatial:bbox` is **a summary** — e.g. the union of footprints from all nested Datasets / Multiscale Datasets. It is not a substitute for the per-group `spatial:bbox` defined by the [spatial convention](https://github.com/zarr-conventions/spatial).
+
+> [!Note]
+> A future extension may carry a list-of-bboxes at the root (one global + one per child group), STAC-style. This is tracked in [zarr-developers/geozarr-spec#133](https://github.com/zarr-developers/geozarr-spec/issues/133).
+
+### Example — store root in EPSG:4326
+
+```json
+{
+    "zarr.json": {
+        "node_type": "group",
+        "zarr_format": 3,
+        "attributes": {
+            "zarr_conventions": [
+                {
+                    "uuid": "f17cb550-5864-4468-aeb7-f3180cfb622f",
+                    "schema_url": "https://raw.githubusercontent.com/zarr-experimental/geo-proj/refs/tags/v1/schema.json",
+                    "spec_url": "https://github.com/zarr-experimental/geo-proj/blob/v1/README.md",
+                    "name": "proj:",
+                    "description": "Coordinate reference system information for geospatial data"
+                },
+                {
+                    "uuid": "689b58e2-cf7b-45e0-9fff-9cfc0883d6b4",
+                    "schema_url": "https://raw.githubusercontent.com/zarr-conventions/spatial/refs/tags/v1/schema.json",
+                    "spec_url": "https://github.com/zarr-conventions/spatial/blob/v1/README.md",
+                    "name": "spatial:",
+                    "description": "Spatial coordinate information"
+                }
+            ],
+            "proj:code": "EPSG:4326",
+            "spatial:bbox": [6.45686, 44.13800, 7.87192, 45.14807]
+        }
+    }
+}
+```
+
+### Example — store root in a non-4326 CRS
+
+```json
+{
+    "zarr.json": {
+        "node_type": "group",
+        "zarr_format": 3,
+        "attributes": {
+            "zarr_conventions": [
+                {
+                    "uuid": "f17cb550-5864-4468-aeb7-f3180cfb622f",
+                    "schema_url": "https://raw.githubusercontent.com/zarr-experimental/geo-proj/refs/tags/v1/schema.json",
+                    "spec_url": "https://github.com/zarr-experimental/geo-proj/blob/v1/README.md",
+                    "name": "proj:",
+                    "description": "Coordinate reference system information for geospatial data"
+                },
+                {
+                    "uuid": "689b58e2-cf7b-45e0-9fff-9cfc0883d6b4",
+                    "schema_url": "https://raw.githubusercontent.com/zarr-conventions/spatial/refs/tags/v1/schema.json",
+                    "spec_url": "https://github.com/zarr-conventions/spatial/blob/v1/README.md",
+                    "name": "spatial:",
+                    "description": "Spatial coordinate information"
+                }
+            ],
+            "proj:code": "EPSG:32632",
+            "spatial:bbox": [296577.1, 4887794.6, 413081.4, 5004299.4]
+        }
+    }
+}
+```
+
 ## DataArray
 
 A DataArray is a Zarr V3 array with named axes.
@@ -244,7 +345,7 @@ The `zarr_conventions` array at the Multiscale Dataset's root group MUST declare
 | `multiscales` | [MultiscalesMetadata](#multiscalesmetadata) | yes | Pyramid layout for this group |
 | `proj:code` | string | conditional* | CRS for all resolution levels (group-level inheritance) |
 | `spatial:dimensions` | string[] | yes | Names of spatial dimensions, e.g. `["Y", "X"]` |
-| `spatial:bbox` | number[] | no | Overall bounding box in the CRS coordinate space |
+| `spatial:bbox` | number[4] | yes | Overall bounding box `[xmin, ymin, xmax, ymax]` in the CRS coordinate space, covering every level in the pyramid |
 
 \* At least one of `proj:code`, `proj:wkt2`, or `proj:projjson` must be provided for geospatial datasets.
 
@@ -267,8 +368,8 @@ Each object in the `layout` array represents one resolution level:
 | `derived_from` | string | no | Path to the source level from which this level was generated. Required to define the transform |
 | `transform` | [TransformObject](#transformobject) | conditional | Required when `derived_from` is present. Describes the relative coordinate transformation from the source level |
 | `resampling_method` | string | no | Per-level override of the default resampling method |
-| `spatial:shape` | integer[] | no | Shape of the spatial dimensions at this level `[height, width]` |
-| `spatial:transform` | number[6] | no | Affine transform coefficients for this level, in Rasterio/Affine ordering `[a, b, c, d, e, f]` |
+| `spatial:shape` | integer[2] | yes | Shape of the spatial dimensions at this level `[height, width]` |
+| `spatial:transform` | number[6] | yes | Absolute affine transform coefficients for this level, in Rasterio/Affine ordering `[a, b, c, d, e, f]` |
 
 #### TransformObject
 
@@ -496,8 +597,8 @@ Key aspects:
 | `derived_from` | string | no | Relative path to the source level |
 | `transform` | TransformObject | conditional | Required when `derived_from` is present |
 | `resampling_method` | string | no | Per-level resampling override |
-| `spatial:shape` | integer[] | no | Spatial dimensions shape `[height, width]` at this level |
-| `spatial:transform` | number[6] | no | Absolute affine transform for this level (Rasterio/Affine ordering) |
+| `spatial:shape` | integer[2] | yes | Spatial dimensions shape `[height, width]` at this level |
+| `spatial:transform` | number[6] | yes | Absolute affine transform for this level (Rasterio/Affine ordering) |
 
 #### TransformObject
 

docs/geozarr-specification-contribution.md

@@ -48,7 +48,37 @@ def calculate_aligned_chunk_size(dimension_size: int, target_chunk_size: int) ->
 
 **Impact:** This approach prevents chunk overlap issues with Dask while optimizing for actual data dimensions rather than arbitrary tile sizes, significantly improving performance.
 
-### 3. Multiscale Hierarchy Structure Clarification
+### 3. GeoZarr Hierarchy Boundaries & Root Identification
+
+**Issue:** [zarr-developers/geozarr-spec#132](https://github.com/zarr-developers/geozarr-spec/issues/132)
+
+**Problem:** The current draft does not define how a GeoZarr store is bounded as a set of paths. The base Zarr spec treats the `.zarr` suffix as advisory only, so two implementations can disagree on whether nested stores (e.g. `a.zarr/b/c.zarr/`) are allowed, how a client given a deep URL recovers the root, and where a traversal should stop.
+
+**Our Solution:** We adopted an explicit set of rules in our [Store Root section](geozarr-minispec.md#hierarchy--identification): single root, root prefix ends with `.zarr`, the suffix occurs at most once in the hierarchy, and an enumerated list of terminal-path conditions.
+
+**Impact:** Clients reading a sub-path like `https://example.org/foo.zarr/measurements/reflectance/r10m` can now reliably recover the store root and read its summary `spatial:bbox` + `proj:code`. This also resolves a recurring URL-parsing question raised in [EOPF-Explorer/data-model#124](https://github.com/EOPF-Explorer/data-model/issues/124) without needing fragment-based URL workarounds.
+
+### 4. Store-root Summary Footprint (`spatial:bbox` + `proj:code`)
+
+**Issue:** [EOPF-Explorer/data-model#156](https://github.com/EOPF-Explorer/data-model/issues/156) — to be surfaced upstream once [#132](https://github.com/zarr-developers/geozarr-spec/issues/132) lands.
+
+**Problem:** Without a top-level summary footprint, clients have to walk into child groups to discover where a store sits geographically. That is expensive over network, and prevents STAC-style discovery patterns.
+
+**Our Solution:** A mandatory `spatial:bbox` plus an explicit CRS (one of `proj:code`, `proj:wkt2`, or `proj:projjson`) at the store root, defined in the [Store Root section](geozarr-minispec.md#store-root). The CRS is always declared explicitly — there is no implicit default.
+
+**Impact:** A single read of the root `zarr.json` is enough for catalogues and viewers to place a store on a map, without disturbing per-group `spatial:` attributes which remain authoritative for individual variables.
+
+### 5. STAC-style `spatial:extent` (multi-bbox at root)
+
+**Issue:** [zarr-developers/geozarr-spec#133](https://github.com/zarr-developers/geozarr-spec/issues/133)
+
+**Problem:** A single union `spatial:bbox` at the store root loses per-asset footprint information. Stores that mix several Datasets / Multiscale Datasets cannot expose individual extents without forcing clients to walk every child group.
+
+**Our Solution (proposed):** Mirror STAC's `extent.spatial.bbox` by introducing `spatial:extent` as a list of bboxes — first entry is the global union, subsequent entries are per-child extents. Suggested by @vincentsarago during review of #4 above; deferred until the upstream `spatial:` convention adopts it.
+
+**Impact:** Lets clients fetch all per-child footprints in one request, aligning Zarr discovery with STAC conventions.
+
+### 6. Multiscale Hierarchy Structure Clarification
 
 **Issue:** [zarr-developers/geozarr-spec#83](https://github.com/zarr-developers/geozarr-spec/issues/83)
 

pyproject.toml

@@ -180,6 +180,7 @@ module = [
     "eopf_geozarr.data_api.s1",
     "eopf_geozarr.data_api.s2",
     "eopf_geozarr.data_api.geozarr.v2",
+    "eopf_geozarr.data_api.geozarr.store",
 ]
 disable_error_code = ["valid-type"]
 

src/eopf_geozarr/data_api/geozarr/store.py

@@ -0,0 +1,129 @@
+"""GeoZarr store model.
+
+Enforces the store-level GeoZarr mini-spec profile: the store root carries a
+mandatory spatial footprint (`spatial:bbox` + a CRS via one of `proj:code`,
+`proj:wkt2`, `proj:projjson`), and nested multiscale groups carry mandatory
+`spatial:bbox` at the root plus `spatial:transform` + `spatial:shape` on every
+layout entry.
+
+Tightens the zarr convention-level models defined in `geozarr.multiscales`,
+`geozarr.spatial` and `geozarr.geoproj` without replacing them.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic.experimental.missing_sentinel import MISSING  # noqa: F401  (re-export for mypy)
+from pydantic_zarr.v3 import ArraySpec, GroupSpec
+
+from eopf_geozarr.data_api.geozarr.common import is_none
+from eopf_geozarr.data_api.geozarr.multiscales import MultiscaleMeta
+from eopf_geozarr.data_api.geozarr.multiscales.geozarr import MultiscaleGroupAttrs
+from eopf_geozarr.data_api.geozarr.multiscales.zcm import ScaleLevel
+from eopf_geozarr.data_api.geozarr.projjson import (
+    ProjJSON,  # noqa: TC001  (runtime use by pydantic)
+)
+
+
+class GeoZarrStoreAttrs(BaseModel):
+    """Attributes required at the store root (outermost Zarr group).
+
+    Both `spatial:bbox` and a CRS are mandatory. The CRS is encoded by exactly
+    one of `proj:code`, `proj:wkt2`, or `proj:projjson`; there is no implicit
+    default. Use `"EPSG:4326"` when no other CRS is meaningful.
+    """
+
+    bbox: list[float] = Field(alias="spatial:bbox", min_length=4, max_length=4)
+    code: str | None = Field(None, alias="proj:code", exclude_if=is_none, pattern="^[A-Z]+:[0-9]+$")
+    wkt2: str | None = Field(None, alias="proj:wkt2", exclude_if=is_none)
+    projjson: ProjJSON | None = Field(None, alias="proj:projjson", exclude_if=is_none)
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+        serialize_by_alias=True,
+    )
+
+    @model_validator(mode="after")
+    def validate_bbox_order(self) -> Self:
+        xmin, ymin, xmax, ymax = self.bbox
+        if xmin > xmax:
+            raise ValueError(
+                f"spatial:bbox: xmin ({xmin}) must be <= xmax ({xmax}); "
+                "expected [xmin, ymin, xmax, ymax]"
+            )
+        if ymin > ymax:
+            raise ValueError(
+                f"spatial:bbox: ymin ({ymin}) must be <= ymax ({ymax}); "
+                "expected [xmin, ymin, xmax, ymax]"
+            )
+        return self
+
+    @model_validator(mode="after")
+    def validate_crs(self) -> Self:
+        crs_fields_set = sum(1 for v in (self.code, self.wkt2, self.projjson) if v is not None)
+        if crs_fields_set == 0:
+            raise ValueError(
+                "Store root requires a CRS: set exactly one of proj:code, proj:wkt2, or proj:projjson"
+            )
+        if crs_fields_set > 1:
+            raise ValueError(
+                "At most one of proj:code, proj:wkt2, proj:projjson may be set at the store root"
+            )
+        return self
+
+
+class GeoZarrScaleLevel(ScaleLevel):
+    """Multiscale layout entry with mandatory `spatial:transform` + `spatial:shape`."""
+
+    spatial_shape: list[int] = Field(alias="spatial:shape", min_length=2, max_length=2)
+    spatial_transform: list[float] = Field(alias="spatial:transform", min_length=6, max_length=6)
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+        serialize_by_alias=True,
+    )
+
+
+class GeoZarrMultiscaleMeta(MultiscaleMeta):
+    """Multiscale metadata where every layout entry is a `GeoZarrScaleLevel`."""
+
+    layout: tuple[GeoZarrScaleLevel, ...]
+
+
+class GeoZarrMultiscaleGroupAttrs(MultiscaleGroupAttrs):
+    """Multiscale group attributes with a mandatory `spatial:bbox`."""
+
+    multiscales: GeoZarrMultiscaleMeta
+    spatial_bbox: list[float] = Field(alias="spatial:bbox", min_length=4, max_length=4)
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+        serialize_by_alias=True,
+    )
+
+    @model_validator(mode="after")
+    def validate_bbox_order(self) -> Self:
+        xmin, ymin, xmax, ymax = self.spatial_bbox
+        if xmin > xmax or ymin > ymax:
+            raise ValueError(
+                "spatial:bbox must be ordered as [xmin, ymin, xmax, ymax] with xmin<=xmax and ymin<=ymax"
+            )
+        return self
+
+
+GeoZarrMember = GroupSpec[Any, Any] | ArraySpec
+
+
+class GeoZarr(GroupSpec[GeoZarrStoreAttrs, GeoZarrMember]):
+    """A GeoZarr store.
+
+    Pairs the required store-root attributes with arbitrary Zarr children.
+    Intended as a reusable building block: downstream models can constrain the
+    `members` type further, e.g. require a nested `GeoZarrMultiscaleGroupAttrs`
+    group.
+    """

src/eopf_geozarr/s2_optimization/s2_converter.py

@@ -303,13 +303,63 @@ def simple_root_consolidation(output_path: str, datasets: dict[str, dict]) -> No
     )
     log.info("Root zarr group created")
 
+    # Write the store-root spatial footprint (geozarr minispec, Store Root section).
+    # Aggregates child-group `spatial:bbox` values, reprojects them to EPSG:4326
+    # and writes the union on the root `zarr.json`.
+    write_store_root_bbox(output_path)
+
     # consolidate reflectance group metadata
     zarr.consolidate_metadata(output_path + "/measurements/reflectance", zarr_format=3)
 
     # consolidate root group metadata
     zarr.consolidate_metadata(output_path, zarr_format=3)
 
 
+def write_store_root_bbox(output_path: str) -> None:
+    """Write `spatial:bbox` and `proj:code` at the store root.
+
+    Walks the zarr store, collects every child-group `spatial:bbox` along with
+    its `proj:code`, reprojects each to EPSG:4326 and writes the union plus
+    the CRS code on the root group. The CRS is always declared explicitly per
+    the Store Root section of the minispec — there is no implicit default.
+    """
+    from pyproj import Transformer
+
+    root = zarr.open_group(output_path, mode="r+")
+
+    bboxes_4326: list[tuple[float, float, float, float]] = []
+
+    def _walk(group: zarr.Group) -> None:
+        attrs = dict(group.attrs)
+        bbox = attrs.get("spatial:bbox")
+        code = attrs.get("proj:code")
+        if bbox is not None and len(bbox) == 4:
+            if code and code != "EPSG:4326":
+                transformer = Transformer.from_crs(code, "EPSG:4326", always_xy=True)
+                xmin, ymin = transformer.transform(bbox[0], bbox[1])
+                xmax, ymax = transformer.transform(bbox[2], bbox[3])
+                bboxes_4326.append((xmin, ymin, xmax, ymax))
+            else:
+                bboxes_4326.append(tuple(float(v) for v in bbox))  # type: ignore[arg-type]
+        for child in group.groups():
+            _walk(child[1])
+
+    for _, child_group in root.groups():
+        _walk(child_group)
+
+    if not bboxes_4326:
+        log.warning("No child-group spatial:bbox found; skipping store-root bbox")
+        return
+
+    xmin = min(b[0] for b in bboxes_4326)
+    ymin = min(b[1] for b in bboxes_4326)
+    xmax = max(b[2] for b in bboxes_4326)
+    ymax = max(b[3] for b in bboxes_4326)
+    root.attrs["spatial:bbox"] = [xmin, ymin, xmax, ymax]
+    root.attrs["proj:code"] = "EPSG:4326"
+    log.info("Wrote store-root spatial:bbox", bbox=[xmin, ymin, xmax, ymax])
+
+
 def optimization_summary(dt_input: xr.DataTree, dt_output: xr.DataTree, output_path: str) -> None:
     """Print optimization summary statistics."""
     # Count groups