Skip to content

improve STAC OpenAPI and service metadata #621

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fmigneault wants to merge 1 commit into
base: master
Choose a base branch
from
Open

improve STAC OpenAPI and service metadata #621

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion CHANGES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
------------------------------------------------------------------------------------------------------------------
Expand Down
7 changes: 7 additions & 0 deletions birdhouse/components/stac/default.env
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -92,6 +96,9 @@ OPTIONAL_VARS="
\$STAC_VERSION
\$STAC_IMAGE
\$STAC_IMAGE_URI
\$STAC_LICENSE_URL
Copy link
Collaborator

@mishaschwartz mishaschwartz Dec 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These should go in "VARS" since they'll break things if they're not set

(service-config.json will contain invalid URLs and the OPENAPI_URL and DOCS_URL paths will just be /stac which may confuse the stac-app)

Copy link
Member Author

@fmigneault fmigneault Dec 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I though VARS is for "you must provide them" and OPTIONAL_VARS for "some default exists", and not overriding them will use the defaults. If overridden with inadequate values, it can break, and it is up to the dev not to provide garbage in.

If that's not the case, then there are many actually breaking OPTIONAL_VARS all over the repository, such as all _DOCKER, _VERSION and _IMAGE (and many more) that create invalid docker compose if explicitly set empty.

I think in this specific case, setting them to empty explicitly (for whatever reason) would still startup correctly, though indeed would lead to weird URLs.

Should the VARS/OPTIONAL_VARS be better defined, with review of existing definitions? It is not the first time this confusion occurred. The current descriptions leave them up to personal interpretation, notably because both can use defaults, "they do not have to be defined in 'env.local' if values are adequate", and empty is technically a defined variable, just not "set".

birdhouse-deploy/birdhouse/default.env

Lines 48 to 51 in 2ef86b1

# list of all variables to be substituted in templates
# some of these variables *could* employ provided values in 'default.env',
# but they must ultimately be defined one way or another for the server to work
VARS='

birdhouse-deploy/birdhouse/default.env

Lines 70 to 74 in 2ef86b1

# list of vars to be substituted in template but they do not have to be set in env.local
# their default values are from 'default.env', so they do not have to be defined in 'env.local' if values are adequate
# they usually are intended to provide additional features or extended customization of their behavior
# when the value provided explicitly, it will be used instead of guessing it by inferred values from other variables
OPTIONAL_VARS='

Copy link
Collaborator

@mishaschwartz mishaschwartz Dec 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The error message when a VARS variable is empty is: "Required variable ${v#$} is not set" and then the process exits. This is checked with the -z test which checks for empty or unset strings.

To me this has always implied that these variables must be set to a non-empty value in order for the stack to work properly.

I though VARS is for "you must provide them" and OPTIONAL_VARS for "some default exists",

I think that this is almost right but also it means that you cannot override the default VARS variables and make the value empty.

If that's not the case, then there are many actually breaking OPTIONAL_VARS all over the repository,

This is true as well

Should the VARS/OPTIONAL_VARS be better defined, with review of existing definitions?

Yes please

\$STAC_OPENAPI_SPEC_PATH
\$STAC_OPENAPI_DOCS_PATH
\$STAC_DB_VERSION
\$STAC_DB_TAGGED
\$STAC_DB_DOCKER
Expand Down
4 changes: 2 additions & 2 deletions birdhouse/components/stac/docker-compose-extra.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
31 changes: 26 additions & 5 deletions birdhouse/components/stac/service-config.json.template
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}"
}
]
}
Loading