Merge branch 'main' of https://github.com/eopf-explorer/data-model into feat/scale-offset-codecs

d-v-b · d-v-b · commit 3a6e73dd83d3 · 2026-05-02T11:17:13.000-04:00
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.8.0"
+  ".": "0.9.0"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.9.0 (2026-04-02)
+
+## What's Changed
+* Add site_url to the mkdocs config by @maxrjones in https://github.com/EOPF-Explorer/data-model/pull/121
+* Update GeoZarr mini-spec to EOPF V1 by @emmanuelmathot in https://github.com/EOPF-Explorer/data-model/pull/129
+* use zarr-cm for defining zarr conventions metadata by @d-v-b in https://github.com/EOPF-Explorer/data-model/pull/131
+* chore/fill value consistency by @d-v-b in https://github.com/EOPF-Explorer/data-model/pull/135
+* Set the minimum supported python version to 3.12 by @d-v-b in https://github.com/EOPF-Explorer/data-model/pull/141
+* add titiler integration test by @d-v-b in https://github.com/EOPF-Explorer/data-model/pull/137
+* Pin GitHub Actions to commit SHAs (coordination#239) by @lhoupert in https://github.com/EOPF-Explorer/data-model/pull/143
+* ci: add permissions block and make security checks blocking by @lhoupert in https://github.com/EOPF-Explorer/data-model/pull/145
+* enh: clarify CF metadata scope in GeoZarr mini-spec and update attribute definitions by @emmanuelmathot in https://github.com/EOPF-Explorer/data-model/pull/133
+* feat: include b08 in resolution groups by @d-v-b in https://github.com/EOPF-Explorer/data-model/pull/152
+
+## New Contributors
+* @maxrjones made their first contribution in https://github.com/EOPF-Explorer/data-model/pull/121
+* @lhoupert made their first contribution in https://github.com/EOPF-Explorer/data-model/pull/143
+
+**Full Changelog**: https://github.com/EOPF-Explorer/data-model/compare/v0.8.0...v0.9.0
+
 ## 0.8.0 (2026-01-21)
 
 ## What's Changed
diff --git a/docs/geozarr-minispec.md b/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
 
diff --git a/docs/geozarr-specification-contribution.md b/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)
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "eopf-geozarr"
-version = "0.8.0"
+version = "0.9.0"
 description = "GeoZarr compliant data model for EOPF datasets"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -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"]
 
diff --git a/src/eopf_geozarr/data_api/geozarr/store.py b/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.
+    """
diff --git a/src/eopf_geozarr/s2_optimization/s2_converter.py b/src/eopf_geozarr/s2_optimization/s2_converter.py
diff --git a/tests/test_s2_converter_simplified.py b/tests/test_s2_converter_simplified.py
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`{`
`2`		`- ".": "0.8.0"`
	`2`	`+ ".": "0.9.0"`
`3`	`3`	`}`