Zarr metadata to STAC Item¶
Build a STAC Item from the metadata of a Zarr store and write it to S3 (default) or a local directory.
EPT opens the Zarr store (local directory, s3:// prefix, or HTTP(S) URL), reads dimensions, coordinates, data variables, and global/variable attributes, derives the spatial extent (from CF latitude/longitude coordinates or geospatial_* attributes) and the temporal extent (from the time coordinate or time_coverage_* attributes), then builds and validates a STAC 1.1 Item whose single data asset points at the store.
Endpoint¶
Authentication: Authorization: Bearer <access_token>.
Collection: optional, with a suggestion¶
Pass collection_id to attach the item explicitly (collection_source: "provided"), or leave it out: the item is built standalone (collection_source: "standalone", collection_id: null) and the response carries a suggested_collection_id — a kebab-case slug of the first data-variable CF standard_name from the CF standard name table. EPT suggests but never auto-attaches a matched collection.
Usage¶
Zarr store in your personal bucket, item written to stac/items (the bucket defaults to your personal oidc-<your-username> bucket, so the item lands at s3://oidc-<your-username>/stac/items/observations.json):
curl --fail-with-body \
-X POST "${EPT_API_URL}/v1/conversions/zarr/stac-item" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"source_uri": "s3://oidc-<your-username>/stores/observations.zarr",
"target": "stac/items",
"endpoint_url": "https://minio.dive.edito.eu",
"access_key_id": "<s3_credentials.access_key_id from /v1/auth>",
"secret_access_key": "<s3_credentials.secret_access_key from /v1/auth>",
"session_token": "<s3_credentials.session_token from /v1/auth>"
}'
Request¶
| Field | Meaning |
|---|---|
source_uri |
Zarr store source: local directory, s3://bucket/prefix, or HTTP(S) URL. |
target |
S3 destination prefix relative to bucket (no s3:// scheme): the item JSON is written to s3://<bucket>/<target>/<item_id>.json. Ending the value in .json overrides the file name. Required unless local_output is set. |
bucket |
Destination S3 bucket. Defaults to your personal EDITO bucket oidc-<username> derived from your bearer token; project buckets are equally valid. Ignored when local_output is set. |
local_output |
Directory on the EPT service filesystem instead of S3 (<local_output>/<item_id>.json, or a .json path to set the file name yourself). Takes precedence over target/bucket. |
collection_id |
Optional. Collection id attached to the item as-is — it does not have to exist in the EDITO STAC API. When omitted (and nothing matches), the item is standalone and suggested_collection_id carries a vocabulary-based suggestion. |
item_id |
Optional STAC Item id. When omitted, one is proposed: the dataset's own id, identifier, or title attribute (else the store directory name without the .zarr suffix), namespaced with your username — <username>-<identifier>. Also names the output file (<item_id>.json). |
overwrite |
Default false; an existing item at the resolved target fails the request with 409. |
decode_cf |
Default true; applies CF decoding (mask/scale, datetimes) when reading. |
consolidated |
Optional; whether to require consolidated Zarr metadata. By default xarray auto-detects. |
bbox, start_datetime, end_datetime |
Optional spatial/temporal overrides for stores without CF coordinates or attributes; start_datetime and end_datetime must be provided together. |
extra_properties |
Additional top-level properties merged into the item. |
endpoint_url, access_key_id, secret_access_key, session_token |
S3 connection parameters from POST /v1/auth; required for s3:// sources, optional otherwise (service-level S3_* environment fallback). Request-scoped, never installed into the EPT environment. |
Response¶
Same shape as the NetCDF variant: the validated stac_item, the target_uri it was written to, the resolved collection_id with collection_source (provided or standalone), a suggested_collection_id, and the full dataset metadata extraction the item was built from.
Good to know¶
- The item's
dataasset is typedapplication/x-zarr. - Items declare
datetime(single instant from date attributes such asdate_created) ordatetime: nullwithstart_datetime/end_datetimecarrying the temporal range. - Standalone items declare no
collectionproperty — valid STAC, attachable later. Items with acollectionalso carry arel="collection"link (required by the STAC 1.1 schema). - Zarr v2 and v3 stores are both auto-detected by zarr-python.