STAC API - SKOS Registry Extension

• Title: SKOS Registry
• Conformance Classes:
  • https://api.stacspec.org/v1.0.0-beta.1/skos-registry
• Scope: STAC API - Core
• Extension Maturity Classification: Proposal
• Dependencies:
  • STAC Extension - Themes (Required for metadata)
  • STAC API - Multi-Tenant Catalogs Endpoint (Optional but Recommended)
• Owner: @jonhealy1

Introduction

This extension defines a standard mechanism to expose SKOS (Simple Knowledge Organization System) hierarchies as navigable Virtual Catalogs.

It transforms static SKOS metadata (defined via the Themes Extension) into dynamic API resources. This allows users to browse the archive via controlled vocabularies (e.g., GEMET, AGROVOC, ISO Topic Categories) alongside the standard physical hierarchy.

This architecture draws directly from research such as A SKOS Taxonomy of the UN Global Geospatial Information Management Data Themes. As noted in that work, using SKOS to map disparate datasets enables the creation of "meaningful relations among data integrated from multiple organizations", a critical requirement for ensuring interoperability within national and global spatial infrastructures.

Motivation

The standard Themes Extension allows data providers to tag Items and Collections with controlled vocabularies (e.g., "Land Cover", "Disaster", "Optical").

However, without this API extension, these themes remain "dead metadata" - they are useful for advanced search filtering, but they do not appear in the API's browsing structure. Users cannot "click through" a concept to see what is inside.

This extension creates "Live Folders" (Virtual Catalogs) from these themes. It mandates that for every unique Theme/Concept found in the archive, the API MUST expose a corresponding Catalog resource containing links to the relevant Collections or Items.

URI Structure & Routing

This extension recommends a simplified ID generation strategy to ensure readable, predictable URLs.

Virtual Catalog ID Pattern: theme::{concept_id}

• concept_id: The id from the Concept Object (e.g., forest_management, land_cover).

Example:

• Concept: id: "forest_management" (from GEMET)
• Virtual Catalog ID: theme::forest_management
• API URL: GET /catalogs/theme::forest_management

Handling Collisions (Namespacing)

By default, this pattern merges identical IDs from different schemes into a single Virtual Catalog.

• Example: If GEMET has id="forest" and AGROVOC has id="forest", items from both will appear under /catalogs/theme::forest.

If strict separation of schemes is required, implementers MAY prefix the ID with a scheme alias:

• Pattern: theme::{scheme_alias}::{concept_id}
• Example: theme::gemet::forest vs theme::agrovoc::forest

Deep Hierarchies (Graph Flattening)

While SKOS hierarchies can be infinitely deep (Concept A -> Concept B -> Concept C), this extension recommends a Flat URL Structure for the API resources.

• Navigation: Depth is represented via rel="child" (Narrower) and rel="parent" (Broader) links between catalogs.
• Routing: Every Virtual Catalog, regardless of its semantic depth, is accessible directly at the top-level /catalogs/{concept_id} endpoint.

Example: To navigate from "Environment" to "Forestry":

1. User visits /catalogs/theme::environment.
2. Response includes a child link to /catalogs/theme::forestry.
3. User visits /catalogs/theme::forestry.

Behavior

1. Virtual Catalog Generation

The API exposes a STAC Catalog object for a Theme when requested via the API.

• id: Derived from the Theme Concept ID (e.g., theme::geonames::3017382).
• title: Derived from the Theme Concept Title (e.g., "France").
• description: "Virtual Catalog for concept 'France' (Source: geonames)".
• links: Includes rel="child" links pointing to all Collections (and optionally Items) tagged with this concept.

2. Poly-Hierarchy (Multi-Parenting)

This extension explicitly acknowledges that STAC Collections and Items may belong to multiple catalogs simultaneously (Poly-hierarchy).

Unlike a file system where an object resides in a single path, a Semantic Registry allows an object to appear in multiple logical contexts:

1. Physical Parent: The Data Provider (e.g., catalog-usgs).
2. Semantic Parent: The Topic (e.g., theme::forestry).
3. Project Parent: A Cross-cutting Group (e.g., project::global-change).

Implementation Note: While an Item MUST belong to exactly one collection (for metadata inheritance), it MAY be linked from multiple catalogs. When accessing a Collection via a Semantic Parent, the API SHOULD preserve the navigation context (e.g., the rel="parent" link in the response should point back to the Semantic Catalog used to discover it).

3. Taxonomy Navigation (Broader/Narrower)

To support full SKOS hierarchy traversal, a Virtual Catalog SHOULD include links to related concepts.

• Narrower Concepts: If the concept has skos:narrower children, include rel="child" links to those Virtual Catalogs.
• Broader Concepts: Include a rel="parent" link pointing to the Virtual Catalog of the skos:broader concept.

Example: Navigating from theme::environment -> theme::forestry -> theme::silviculture.

Example

1. The Source Data (Item/Collection)

An item tagged with concepts from GeoNames and Wikipedia using the Themes Extension.

{
  "id": "example-item",
  "type": "Feature",
  "stac_extensions": ["https://stac-extensions.github.io/themes/v1.0.0/schema.json"],
  "themes": [
    {
      "scheme": "https://www.geonames.org",
      "concepts": [
        {
          "id": "geonames::3017382",
          "name": "France"
        }
      ]
    },
    {
      "scheme": "https://en.wikipedia.org",
      "concepts": [
        {
          "id": "wiki::Summer",
          "name": "Summer"
        }
      ]
    }
  ]
}

2. The Virtual Catalog Response

The API returns these Catalog objects corresponding to the concept IDs.

Request: GET /catalogs/theme::geonames::11071625

{
  "type": "Catalog",
  "id": "theme::geonames::11071625",
  "title": "Auvergne-Rhône-Alpes",
  "description": "Virtual Catalog for concept 'Auvergne-Rhône-Alpes' (Source: geonames::11071625)",
  "links": [
    {
      "rel": "self",
      "href": "https://api.com/catalogs/theme::geonames::11071625",
      "type": "application/json"
    },
    {
      "rel": "root",
      "href": "https://api.com/",
      "type": "application/json"
    },
    {
      "rel": "parent",
      "href": "https://api.com/catalogs/theme::geonames::3017382",
      "title": "France (Broader Concept)",
      "type": "application/json"
    },
    {
      "rel": "child",
      "href": "https://api.com/catalogs/theme::geonames::2996944",
      "title": "Lyon (Narrower Concept)",
      "type": "application/json"
    },
    {
      "rel": "child",
      "href": "https://api.com/collections/example-collection",
      "title": "Collection containing items tagged 'Auvergne-Rhône-Alpes'",
      "type": "application/json"
    }
  ]
}

References

• Yaman, B., Thompson, K., & Brennan, R. (2021). A SKOS Taxonomy of the UN Global Geospatial Information Management Data Themes.