Registry Atlas reference
Look up capability discovery terms, asset schema, proxy settings, token handling rules,
fixture paths, build commands, and CLI entry points for Registry Atlas v0.1.
This reference is hand-maintained against the registry-atlas source; check the repository
README if a detail looks stale.
Capability discovery accepted match inputs
Section titled “Capability discovery accepted match inputs”The strict matcher accepts the following Term kinds in a CapabilityQuery.
Evidence for these semantics is in
crates/system-capability-discovery/src/matcher.rs
and the test fixture
crates/system-capability-discovery/tests/strict_matcher.rs.
| Term kind | Matched against | Canonicalization applied | Notes |
|---|---|---|---|
Term::Label(s) | Asset label text, dcterms:title, skos:prefLabel, field label properties | Whitespace trim, Unicode normalization, case fold | Matches label text in discovered metadata assets |
Term::Iri(s) | @type, conformsTo, property IRIs, schema $id | Compact IRI expansion from known prefix map | Must match a known prefix or full absolute IRI |
Term::Field(s) | SchemaProperty.property_name, SchemaProperty.property_path, ShaclProperty.path, equivalent property evidence | Whitespace trim only | Must not match arbitrary description text |
Term::ReviewedMapping { mapping_set_id, mapping_id } | Explicit reviewed mapping set entry | None; mapping is pre-resolved | Every match using a reviewed mapping exposes the mapping set id and version in its evidence |
The engine never applies stemming, fuzzy edit distance, semantic similarity, or unreviewed
synonym expansion.
See SYSTEM_CAPABILITY_DISCOVERY_SPEC.md
for the full normative contract.
Need field roles
Section titled “Need field roles”| Field | Role in matching |
|---|---|
requires_any | Required information terms. At least one term must match for the need to produce a CapabilityMatch. |
requires_all | Conjunctive terms. Every term must match the same candidate asset or route. Use when a field name alone is too generic. |
about_any | Subject or population context. Improves ordering and evidence explanation. Cannot produce a match by itself. |
purpose | Program or use context. Can match policy or purpose evidence. Cannot produce a match by itself. |
question | Human-facing wording only. The strict matcher never searches this field. |
Asset envelope schema
Section titled “Asset envelope schema”This is the JSON you get when you export from the Evidence tab or run the CLI harvest command.
A DiscoveryRunEnvelope wraps a DiscoveryReport with host-side fetch state.
Key fields at the envelope top level, sourced from
fixtures/system-capability/registry-relay-all-standards.envelope.json:
| Field | Type | Description |
|---|---|---|
report | DiscoveryReport | The portable evidence contract. Contains summary, assets, and artifacts. |
report.summary.artifact_count | integer | Total artifacts fetched (including failed). |
report.summary.asset_count | integer | Total semantic assets extracted from all artifacts. |
report.summary.failed_artifact_count | integer | Artifacts that could not be fetched or parsed. |
report.summary.unsupported_artifact_count | integer | Artifacts fetched but not recognized as a supported kind. |
report.summary.parse_error_count | integer | Artifacts that parsed partially with errors. |
report.assets | array | Array of SemanticAsset objects. Each has kind, id, label, and links. |
report.artifacts | array | Array of FetchedArtifact objects. Each has url, status, media_type, body_bytes, hash. |
A DiscoveryReport without an envelope is the portable evidence contract.
Pass it to the capability query CLI or to semantic-asset-discovery-cli validate-report.
Recognized semantic asset kinds
Section titled “Recognized semantic asset kinds”| Kind | Source format | Notes |
|---|---|---|
catalog | Generic catalog container | n/a |
dcat_catalog | DCAT Catalogue JSON-LD | dcat:Catalog class |
dataset | DCAT Dataset | dcat:Dataset class |
distribution | DCAT Distribution | dcat:Distribution class |
data_service | DCAT DataService | dcat:DataService class |
json_schema | JSON Schema Draft 2020-12 | application/schema+json |
shacl | SHACL shapes graph | RDF Turtle or JSON-LD |
policy | ODRL policy document | odrl:hasPolicy, application/ld+json |
open_api | OpenAPI 3.x specification | application/vnd.oai.openapi+json |
api_description | OGC API Records or other API description | Landing page JSON |
class | RDF class definitions (RDFS, OWL, SKOS) | n/a |
metadata_index | OGC API Records metadata landing page | n/a |
Proxy allowed-host model
Section titled “Proxy allowed-host model”The proxy’s host-blocking behavior is documented in
server/index.mjs.
| Rule | Default | Override |
|---|---|---|
| Private IPv4 ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) | Blocked in production | ATLAS_PROXY_ALLOW_LOCAL=1 |
| Loopback (127.0.0.0/8) | Blocked in production | ATLAS_PROXY_ALLOW_LOCAL=1 |
| Link-local (169.254.0.0/16) | Blocked in production | ATLAS_PROXY_ALLOW_LOCAL=1 |
| IPv6 ULA (fc00::/7) | Blocked in production | ATLAS_PROXY_ALLOW_LOCAL=1 |
| IPv6 link-local (fe80::/10) | Blocked in production | ATLAS_PROXY_ALLOW_LOCAL=1 |
data:, file:, ftp: schemes | Always blocked | None |
| Embedded credentials in URL | Stripped before upstream request | None |
“Production mode” means NODE_ENV=production AND ATLAS_PROXY_ALLOW_LOCAL is not "1".
pnpm dev does not set NODE_ENV=production, so local targets are reachable by default.
Proxy environment variables
Section titled “Proxy environment variables”| Variable | Default | Description |
|---|---|---|
PORT | 3717 | Proxy listen port |
NODE_ENV | Unset (treated as non-production) | When production, private-network targets are blocked unless ATLAS_PROXY_ALLOW_LOCAL=1 |
ATLAS_PROXY_ALLOW_LOCAL | Unset | Set to "1" to allow private-network targets in production mode |
ATLAS_PROXY_MAX_BYTES | 2097152 (2 MB) | Maximum upstream response size in bytes |
ATLAS_PROXY_TIMEOUT_MS | 8000 | Upstream request timeout in milliseconds |
ATLAS_PROXY_REDIRECT_LIMIT | 3 | Maximum HTTP redirect chain length |
Proxy error codes
Section titled “Proxy error codes”Error responses use Content-Type: application/problem+json.
| Code | Meaning |
|---|---|
invalid_url | Target URL failed parsing or uses a non-HTTP/S scheme |
dns_lookup_failed | DNS resolution failed for target host |
private_network_blocked | Target resolved to a private or loopback address in production mode |
upstream_timeout | Upstream request exceeded ATLAS_PROXY_TIMEOUT_MS |
response_too_large | Response exceeded ATLAS_PROXY_MAX_BYTES |
content_type_blocked | Response content type is not in the allowed set |
Session token handling rules
Section titled “Session token handling rules”These rules apply to bearer tokens entered in the Atlas UI.
They are stated explicitly in
README.md
and confirmed by reviewing server/index.mjs.
- Tokens are accepted only in the session URL entry field.
- The token is forwarded to the proxy as an
Authorization: Bearer <token>header. - The proxy forwards the token in upstream requests only on same-origin redirects.
- The token is held in React component state for the duration of the browser session only.
- The token is never written to
localStorage,sessionStorage, or IndexedDB. - The proxy does not log the
Authorizationheader. - The token is discarded when the browser tab closes or the page is refreshed.
- No mechanism for token refresh, credential expiry, or persistence across browser restarts is implemented in v0.1.
Fixture file layout
Section titled “Fixture file layout”| Path | Kind | Description |
|---|---|---|
src/fixtures/registry-relay-dcat-ap.jsonld | DCAT catalog JSON-LD | Bundled offline demo catalog; loaded by the curated demo fixtures selector in the UI |
src/fixtures/registry-relay-system-capability.envelope.json | DiscoveryRunEnvelope | Full envelope with fetch summary, rejected fetches, and the nested DiscoveryReport for the Registry Relay all-standards demo |
fixtures/system-capability/registry-relay-all-standards.report.json | DiscoveryReport | Extracted report with all asset kinds represented; used by Rust tests |
fixtures/system-capability/registry-relay-all-standards.envelope.json | DiscoveryRunEnvelope | Full envelope for the all-standards demo; used by CLI and Rust tests |
fixtures/reports/dcat-ap-report.json | DiscoveryReport | DCAT-AP profile fixture report |
fixtures/reports/semantic-package-report.json | DiscoveryReport | Semantic package profile fixture report |
fixtures/semantic-asset-discovery/ | Per-standard fixture directories | Subdirectories for breg-dcat-ap, dcat-ap, json-schema, ogc-features, ogc-records, openapi, prof, publicschema-package, registry-relay-standards, semic-shacl-turtle |
CLI quick reference
Section titled “CLI quick reference”The workspace ships two CLI entry points you can run with cargo.
Harvest a registry and produce a DiscoveryRunEnvelope:
cargo run -p semantic-asset-discovery-cliRun a capability query against an existing envelope:
cargo run -p system-capability-discovery --bin system-capability-query -- \ --envelope fixtures/system-capability/registry-relay-all-standards.envelope.json \ --need-all disability_status label "Disabled Person" \ --need-all disability_status field disability_status \ --prettyBoth commands accept --help for the full option list.
Full worked examples are in
HOW_TO_TEST_V0_1.md.
Build and dev commands
Section titled “Build and dev commands”Sourced from
package.json.
| Command | Description |
|---|---|
pnpm install | Install Node dependencies |
pnpm dev | Build WASM, start Vite dev server (http://127.0.0.1:5177) and Express proxy (http://127.0.0.1:3717) concurrently |
pnpm server | Start Express proxy only |
pnpm build | TypeScript type-check, Vite production build, WASM compile |
pnpm test | Run Vitest tests |
pnpm lint | Run ESLint |
pnpm check | Run lint, tests, and production build (use before review) |
pnpm check:release | Run Rust tests, lint, tests, build, and semantic checks (full release gate) |
pnpm check:rust | Run Rust tests via cargo test |
pnpm check:semantic | Run semantic discovery validation checks |
pnpm build:wasm | Compile semantic-asset-discovery-wasm from Rust via wasm-pack |
pnpm canonicalize:system-fixtures | Normalize capability discovery fixture files |