improve STAC OpenAPI and service metadata

Author: fmigneault

CHANGES.md

@@ -15,7 +15,15 @@
 [Unreleased](https://github.com/bird-house/birdhouse-deploy/tree/master) (latest)
 ------------------------------------------------------------------------------------------------------------------
 
-[//]: # (list changes here, using '-' for each new entry, remove this when items are added)
+## Changes
+
+- STAC API: Improve reported service links.
+
+  - Add `STAC_LICENSE_URL` to define the relevant license metadata location of the selected implementation.
+  - Add `STAC_OPENAPI_SPEC_PATH` and `STAC_OPENAPI_DOCS_PATH` to define endpoints of OpenAPI specification.
+  - Update the `/services/stac` response to provide more metadata links, including license details and better
+    API metadata references. Notably, replace the *generic* STAC API Core OpenAPI definition by the 
+    implementation-specific definition self-served by the selected docker image to document API extensions.
 
 [2.20.1](https://github.com/bird-house/birdhouse-deploy/tree/2.20.1) (2025-12-16)
 ------------------------------------------------------------------------------------------------------------------

birdhouse/components/stac/default.env

@@ -20,6 +20,10 @@ export STAC_PGPASSWORD='${BIRDHOUSE_POSTGRES_PASSWORD}'
 export STAC_VERSION=6.0.0-crim-2.1.0
 export STAC_IMAGE='ghcr.io/crim-ca/stac-app:2.1.0'
 export STAC_IMAGE_URI='${STAC_IMAGE}'
+export STAC_LICENSE_URL='https://raw.githubusercontent.com/crim-ca/stac-app/refs/heads/main/LICENSE'
+export STAC_OPENAPI_SPEC_PATH='/api'
+export STAC_OPENAPI_DOCS_PATH='/api.html'
+
 # database SQL schemas must be aligned with STAC_VERSION
 # there versions are not "equal", check compatibilities on https://github.com/stac-utils/stac-fastapi-pgstac
 export STAC_DB_VERSION=0.9.8
@@ -92,6 +96,9 @@ OPTIONAL_VARS="
   \$STAC_VERSION
   \$STAC_IMAGE
   \$STAC_IMAGE_URI
+  \$STAC_LICENSE_URL
+  \$STAC_OPENAPI_SPEC_PATH
+  \$STAC_OPENAPI_DOCS_PATH
   \$STAC_DB_VERSION
   \$STAC_DB_TAGGED
   \$STAC_DB_DOCKER

birdhouse/components/stac/docker-compose-extra.yml

@@ -21,8 +21,8 @@ services:
       - POSTGRES_HOST_WRITER=stac-db
       - POSTGRES_PORT=5432
       - ROUTER_PREFIX=/stac
-      - OPENAPI_URL=/stac/api
-      - DOCS_URL=/stac/api.html
+      - OPENAPI_URL=/stac${STAC_OPENAPI_SPEC_PATH}
+      - DOCS_URL=/stac${STAC_OPENAPI_DOCS_PATH}
     logging: *default-logging
     restart: always
     healthcheck:

birdhouse/components/stac/service-config.json.template

@@ -19,22 +19,43 @@
     {
       "rel": "service-doc",
       "type": "text/html",
-      "href": "https://github.com/radiantearth/stac-api-spec/tree/v1.0.0"
+      "href": "${BIRDHOUSE_PROXY_SCHEME}://${BIRDHOUSE_FQDN_PUBLIC}/stac${STAC_OPENAPI_DOCS_PATH}"
     },
     {
       "rel": "service-desc",
-      "type": "application/yaml",
-      "href": "https://raw.githubusercontent.com/radiantearth/stac-api-spec/main/core/openapi.yaml"
+      "type": "application/vnd.oai.openapi+json;version=3.0",
+      "href": "${BIRDHOUSE_PROXY_SCHEME}://${BIRDHOUSE_FQDN_PUBLIC}/stac${STAC_OPENAPI_SPEC_PATH}"
     },
     {
-      "rel": "alternate",
+      "title": "OpenAPI specification",
+      "rel": "openapi",
+      "type": "application/vnd.oai.openapi+json;version=3.0",
+      "href": "${BIRDHOUSE_PROXY_SCHEME}://${BIRDHOUSE_FQDN_PUBLIC}/stac${STAC_OPENAPI_SPEC_PATH}"
+    },
+    {
+      "rel": "conformance",
+      "type": "application/json",
+      "href": "${BIRDHOUSE_PROXY_SCHEME}://${BIRDHOUSE_FQDN_PUBLIC}/stac/conformance"
+    },
+    {
+      "rel": "describedby",
       "type": "text/html",
-      "href": "${BIRDHOUSE_PROXY_SCHEME}://${BIRDHOUSE_FQDN_PUBLIC}/stac-browser/"
+      "href": "https://github.com/radiantearth/stac-api-spec/tree/v1.0.0"
     },
     {
       "rel": "service-meta",
       "type": "application/vnd.oci.image.index.v1+json",
       "href": "${STAC_IMAGE_URI}"
+    },
+    {
+      "rel": "alternate",
+      "type": "text/html",
+      "href": "${BIRDHOUSE_PROXY_SCHEME}://${BIRDHOUSE_FQDN_PUBLIC}/stac-browser/"
+    },
+    {
+      "rel": "license",
+      "type": "text/plain",
+      "href": "${STAC_LICENSE_URL}"
     }
   ]
 }