Configuration Reference

All runtime configuration is via environment variables. No config files are required. See .env.example for a ready-to-copy template.

Registry

Catalog source selection

Exactly one of the following should be set:

• REGISTRY_CATALOG_JSON
• REGISTRY_CATALOG_FILE
• REGISTRY_CATALOG_URL

If none is set, startup fails.

Catalog format

Accepted JSON shapes:

[
  {
    "model": "re-indicators-specification",
    "version": "0.0.3",
    "route_url": "https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v0.0.3/generated/route.json",
    "schema_url": "https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v0.0.3/generated/schema.json",
    "shacl_url": "https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v0.0.3/generated/shacl.ttl"
  }
]

or

{
  "models": [
    {
      "model": "re-indicators-specification",
      "version": "0.0.3",
      "route_url": "https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v0.0.3/generated/route.json",
      "schema_url": "https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v0.0.3/generated/schema.json"
    }
  ]
}

Rules:

• Multiple versions for the same model are allowed.
• Duplicate (model, version) entries are rejected.
• Catalog entries must declare explicit per-artifact URLs using route_url, schema_url, shacl_url, owl_url, and openapi_url as needed.
• At least one artifact reference must be declared in each entry.
• Artifact references must be directly fetchable runtime URLs to the artifact file itself, not repository HTML pages.
• route_url is only required for routable model operations; validation-only entries may publish only schema_url, shacl_url, or owl_url.
• If model or version is omitted, the registry attempts to infer them from declared artifact URLs when they match known CE-RISE Codeberg patterns.
• Every artifact URL is validated against REGISTRY_ALLOWED_HOSTS.
• Every artifact URL must satisfy REGISTRY_REQUIRE_HTTPS when enabled.

For SHACL behavior and artifact expectations (shacl.ttl), see SHACL Validation.

Refresh behavior

POST /admin/registry/refresh re-loads the catalog source each time:

• REGISTRY_CATALOG_URL: re-downloads latest JSON from that URL.
• REGISTRY_CATALOG_FILE: re-reads the file from disk.
• REGISTRY_CATALOG_JSON: reuses in-memory inline catalog unless changed by process restart or runtime replacement API.

The in-memory index swap is atomic. If the catalog cannot be loaded/parsed, refresh returns an error and the previous index remains active. If individual model entries fail artifact resolution, refresh succeeds with per-entry errors and loads only successful entries.

IO Adapter

Notes:

• IO_ADAPTER_ID=memory: in-process memory store (dev/test).
• IO_ADAPTER_ID=http: enables crates/io-http; requires IO_ADAPTER_BASE_URL.

Auth

Notes:

• jwt_jwks is for direct bearer JWT validation in this service.
• forward_auth is for deployments where an upstream proxy/gateway already authenticated the caller and injects identity headers.
• none is only for isolated dry runs and requires AUTH_ALLOW_INSECURE_NONE=true.
• Detailed integration guidance: Authentication.

Server

Observability

OWL Validation Mode

OWL validation is enabled through the hex-validator-owl adapter in API wiring.

• Runtime mode: embedded profile checks (no external OWL subprocess required).
• Activation condition: validator executes when owl.ttl is present in resolved artifacts.
• Missing owl.ttl: validator skips gracefully and returns passed=true with no violations.
• Invalid owl.ttl: mapped to validator initialization error.
• Runtime execution fault: mapped to validator execution error.

Operationally this keeps deployment simple (no extra binaries), but the current path is profile-oriented and not a full generic OWL reasoner.