Skip to content

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 Habitats and Heritage Collection for EPT tutorial, 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:

[
  "https://minio.dive.edito.eu/<bucket>/<workspace>/items/din/<projectid>-din.json"
]

id = <projectid>-ocean-chemistry, title = <projectid> Ocean Chemistry Collection, description = Demo Ocean Chemistry Collection for EPT tutorial, 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"]))

🎬 Screencast — python

Next: Walkthrough 6 — Catalog