Walkthrough 5 — Collections¶
Wrap the hosted Items in a Collection — one call suggests it from the Items
and exports a complete, self-contained Collection folder: collection.json
plus one copy of each Item, links wired, ready to open and validate on its
own. No separate builder step, no assemble later.
Before running: make your workspace folder public (EDITO datalab → Storage → the folder's eyeball icon) — the remaining walkthroughs read Items, Collections and the final catalog by their public URLs (viewers, validate, publish). World-readable while on: demo only, toggle it back off after the session.
Works with the EPT frontend or curl/python — both shown. Requires the
hosted Items, ARCO-ified in the previous step.
1. Create and export in one call¶
In the frontend: Make STAC → Create Collection Tree —
paste these two hosted Item URLs into item_links (a JSON array of
strings):
[
"https://minio.dive.edito.eu/<bucket>/<workspace>/items/mangrove/<projectid>-mangrove.json",
"https://minio.dive.edito.eu/<bucket>/<workspace>/items/heritage-shipwrecks/<projectid>-heritage-shipwrecks.json"
]
Then set id = <projectid>-habitats-and-heritage, title =
<projectid> Habitats and Heritage Collection, description = Demo
bucket = your bucket,
target = <workspace>/collections/<projectid>-habitats-and-heritage, and
tick overwrite. 🎬 Screencast
These are the two mangrove/heritage Items — the DIN Item stays out: it belongs to the other Collection, built in the your turn section at the bottom of this page.
POST /v1/stac/collections/tree fetches the Items and derives everything:
the extent is the union of their bboxes and datetimes, a shared license
becomes the Collection license (distinct licenses become a licenses list),
keywords are unioned, and the id/title are suggested too. Nothing here is
hand-written — you only pick the destination, the id and the title.
The id is yours to pick — flat, no /, prefixed with your project's short
name (<projectid>-…), which must be unique: every id in the session
derives from it. End collection titles in Collection and mark the
description as a demo for the EPT tutorial — when someone looks the object
up in the STAC browser or the EDITO API later, the name says what it is. Leave the id
out and EPT proposes one itself — namespaced
with your username, not the project — so in a shared project session pass
the explicit <projectid>-… id, as below. Nothing needs to match
beforehand: the export in the same call stamps the id onto the item copies
(collection property plus root/parent/collection links), so
collection.json plus one subfolder per item (<item-id>/<item-id>.json)
lands complete and self-rooted. The response says status: "completed" and
exported: true, with collection_uri and item_uris pointing at what
landed.
curl -X POST $EPT_URL/v1/stac/collections/tree \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"item_links": [
"https://minio.dive.edito.eu/'$BUCKET'/'$WORKSPACE'/items/mangrove/'$PROJECTID'-mangrove.json",
"https://minio.dive.edito.eu/'$BUCKET'/'$WORKSPACE'/items/heritage-shipwrecks/'$PROJECTID'-heritage-shipwrecks.json"
],
"id": "'$PROJECTID'-habitats-and-heritage",
"title": "'$PROJECTID' Habitats and Heritage Collection",
"description": "Demo '$PROJECTID' Habitats and Heritage Collection for EPT tutorial.",
"bucket": "'$BUCKET'",
"target": "'$WORKSPACE'/collections/'$PROJECTID'-habitats-and-heritage",
"overwrite": true,
"endpoint_url": "https://minio.dive.edito.eu",
"access_key_id": "'$S3_KEY'", "secret_access_key": "'$S3_SECRET'",
"session_token": "'$S3_SESSION'"
}' | tee collection-suggested.json \
| jq '{status, exported, collection_uri, item_uris, warnings}'
my_id = f"{PROJECTID}-habitats-and-heritage" # or omit id: EPT proposes
# <username>-<slug>
collection = post("/v1/stac/collections/tree",
item_links=[
f"{MINIO}/{BUCKET}/{WORKSPACE}/items/mangrove/{PROJECTID}-mangrove.json",
f"{MINIO}/{BUCKET}/{WORKSPACE}/items/heritage-shipwrecks/{PROJECTID}-heritage-shipwrecks.json",
],
id=my_id,
title=f"{PROJECTID} Habitats and Heritage Collection",
description=f"Demo {PROJECTID} Habitats and Heritage Collection for EPT tutorial.",
bucket=BUCKET, target=f"{WORKSPACE}/collections/{my_id}",
overwrite=True, **S3)
print(collection["status"], collection["exported"], collection["collection_uri"])
print("\n".join(collection["warnings"]))
Check .warnings for anything EPT had to guess — extent, license and
keywords are derived, and the export writes them unchanged.
2. Read it back and validate it alone¶
The response's collection_uri is the public URL of collection.json —
open it in a browser and the item links are there: the folder is complete
on its own. Check what landed with STAC Fetch: the id is yours,
extent covers both Items, license matches. Or paste the
collection_uri into the
STAC browser and browse the Collection
with its Items from there.
MY_ID=$PROJECTID-habitats-and-heritage
curl -s "$EPT_URL/v1/stac/objects?url=https://minio.dive.edito.eu/$BUCKET/$WORKSPACE/collections/$MY_ID/collection.json" \
-H "Authorization: Bearer $TOKEN" | jq '.stac_object | .id, .extent, .license'
Then validate the folder where it stands — validate_children checks the
Collection and its item copies:
In the frontend: STAC Tools → Validate STAC — stac_url =
https://minio.dive.edito.eu/<bucket>/<workspace>/collections/<projectid>-habitats-and-heritage/collection.json,
validate_children on. 🎬 Screencast
curl -s -X POST $EPT_URL/v1/stac/validations \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"stac_url": "https://minio.dive.edito.eu/'$BUCKET'/'$WORKSPACE'/collections/'$MY_ID'/collection.json",
"validate_children": true}' \
| jq '{stac_is_valid, summary}'
out = post("/v1/stac/validations",
stac_url=f"{MINIO}/{BUCKET}/{WORKSPACE}/collections/{my_id}/collection.json",
validate_children=True)
pprint(out)
✅ Check: stac_is_valid: true and invalid_objects: 0. This is the
partway check the old flow never had — the bare collection.json from the
builder had dangling links until the catalog step ran; here the exported folder is
complete and every object inside it passes schema validation.
3. Make it yours¶
Read what was suggested and change what you don't like — title and
description are yours to call. Rebuilding at the same target with
overwrite is a one-call update at the same URL; the id stays fixed —
it's what the exported item copies carry and what the catalog links under.
In the frontend: STAC Collection Builder — open the
collection.json URL above in a browser, copy the JSON, paste it as
stac_json, edit title and description in the JSON (keep the title's
Collection ending), keep bucket +
target = <workspace>/collections/<projectid>-habitats-and-heritage,
overwrite on, export.
curl -s "$EPT_URL/v1/stac/objects?url=https://minio.dive.edito.eu/$BUCKET/$WORKSPACE/collections/$MY_ID/collection.json" \
-H "Authorization: Bearer $TOKEN" \
| jq '.stac_object | .title = "Your title" | .description = "Your description"' > my-collection.json
curl -X POST $EPT_URL/v1/stac/objects/collection \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d "$(jq -n --slurpfile c my-collection.json \
--arg bucket "$BUCKET" --arg target "$WORKSPACE/collections/$MY_ID" \
--arg endpoint "https://minio.dive.edito.eu" \
--arg key "$S3_KEY" --arg secret "$S3_SECRET" --arg token "$S3_SESSION" \
'{stac_json: $c[0], bucket: $bucket, target: $target,
endpoint_url: $endpoint, access_key_id: $key,
secret_access_key: $secret, session_token: $token, overwrite: true}')" \
| jq .target_uri
mine = requests.get(
f"{MINIO}/{BUCKET}/{WORKSPACE}/collections/{my_id}/collection.json"
).json()
mine["title"] = "Your title"
mine["description"] = "Your description"
out = post("/v1/stac/objects/collection", stac_json=mine,
bucket=BUCKET, target=f"{WORKSPACE}/collections/{my_id}",
overwrite=True, **S3)
pprint(out)
The builder writes only collection.json — the item copies from step 1
stay put, still linked.
Your turn — a Collection for the DIN item¶
Same flow, one Item, in the frontend too: Make STAC → Create Collection Tree — item_links = this single URL:
id = <projectid>-ocean-chemistry, title = <projectid> Ocean
Chemistry Collection, description = Demo bucket = your
bucket, target =
<workspace>/collections/<projectid>-ocean-chemistry, overwrite on —
then read it back and validate exactly as in steps 1–2 above.
Keep that id — the catalog step links the Collection under it, so a descriptive name pays off.
my_id = f"{PROJECTID}-ocean-chemistry" # or omit id: EPT proposes
# <username>-<slug>
collection = post("/v1/stac/collections/tree",
item_links=[
f"{MINIO}/{BUCKET}/{WORKSPACE}/items/din/{PROJECTID}-din.json",
],
id=my_id,
title=f"{PROJECTID} Ocean Chemistry Collection",
description=f"Demo {PROJECTID} Ocean Chemistry Collection for EPT tutorial.",
bucket=BUCKET, target=f"{WORKSPACE}/collections/{my_id}",
overwrite=True, **S3)
print(collection["status"], collection["exported"], collection["collection_uri"])
print("\n".join(collection["warnings"]))
Next: Walkthrough 6 — Catalog