Integration patterns

View as Markdown

Registry Stack is the registry-facing surface that sits behind systems already in a delivery stack. This page describes the technical wiring for each neighbor: what the neighbor owns, what Registry Stack adds, and the conditions under which a Registry Stack surface belongs in the path. For how the registry family relates to the wider ecosystem, see the ecosystem page.

Two runtime surfaces can appear in an integration path. Registry Relay publishes a governed read-only HTTP API over SQLite sources an institution already holds: the operations, the readable columns, and the shape of every response are fixed by a contract reviewed before the service starts, not by a query the caller writes. Evidence Gateway answers one predefined requirement about one set of subjects with a signed assertion carrying the answer rather than the record. Registry Mint is a supporting service that issues the short-lived access tokens either surface verifies when a deployment has no identity provider. The patterns below describe Relay and Evidence Gateway.

Country evidence mesh

At country scale, the same two surfaces can sit next to several domain platforms. Each authority keeps custody of its own data and exposes a bounded output; consuming systems such as a social-protection management information system receive answers and do not become raw-record readers.

Which surface fits depends on what the authority holds and how it holds it:

Where the authoritative data already sits in a SQLite database, or the authority can produce a SQLite extract from it, Registry Relay serves it as a governed read-only API. Relay opens that file in place, read-only, and holds no upstream credential because it makes no upstream call.
Where the authoritative data lives inside a domain platform with its own API, such as a FHIR server or a DHIS2 instance, Evidence Gateway reaches it through its own fixed HTTP source contract and returns only the values a reviewed requirement declares.

Civil registration, social protection, agriculture, and education systems each keep their own authoritative store either way; neither surface copies the record into a central store.

The two products are authored by two separate tools, relayctl and evidencectl, and neither compiles a description of the other. A country mesh is therefore a deployment arrangement that an architecture review holds together, not an artifact any tool in this stack emits or validates.

Evidence Gateway to action boundary

Every combined integration follows the same ownership boundary. Registry Relay owns one reviewed contract over the read-only SQLite sources it declares, and the governed read surface compiled from it. Evidence Gateway owns the predefined requirement, evidence authorization, acquisition against its own fixed sources, and the declared disclosure that requirement carries. The evidence consumer determines how the evidence is used, and the decision owner remains accountable for requirements, decisions, workflow, and action.

The maintained DHIS2 health-evidence reference project makes that boundary visible. DHIS2 remains the system of record. Evidence Gateway reaches it through its own fixed HTTP source contract, using bounded reviewed Rhai for request preparation and extraction, and exposes bounded facts as reusable requirements: that project reads two Tracker programmes for two independent requirements, adult status and professional licence status, and a caller authorized for one learns nothing about the other. Relay is not in that path at all, and could not be: it makes no outbound source request. In this example, a public-health programme is both the evidence consumer and the decision owner. It can compute an outreach or follow-up priority without moving either decision into Relay or Evidence Gateway.

The reviewed contract keeps a positive fact, its negative, an absent value, no match, ambiguity, and source failure distinct. Missing evidence is not a negative fact. Offline synthetic fixtures are the deterministic acceptance path for both products: relayctl test runs a Relay project’s fixture cases through the same kernel the server uses, offline, and neither tool provides a live-test mode or an external deployed-system compatibility runner. An operator can exercise a deployed API with a standard HTTP client and owner-maintained credentials as separate interoperability evidence.

Evidence Gateway has no general policy engine and no eligibility or workflow engine. A requirement whose answer restates a decision an authoritative source already made must say so in its review documentation, and Evidence Gateway does not recompute that decision.

Domain registry platforms

Examples: OpenCRVS (civil registration), OpenSPP (social-protection household and programme management), DHIS2 (health management information), OpenIMIS (health insurance information).

These platforms own storage, business rules, correction workflows, user interfaces, and a runtime API for their domain. Registry Stack adds standardized metadata description, governed read-only operations over source data, minimum-disclosure evidence responses, and audit records. The connect your data guide is the entry point; Configure Relay is the reference for a Relay deployment’s own files.

One SQLite database can serve more than one governed operation without being copied. The contract names the views and columns each operation may read, and every operation reads through the same read-only connection. Relay opens that database under one of two declared source profiles: snapshot, for an immutable extract that must not change underneath the service, or live-read-only, for a database the authority keeps writing to through its own application. Either way Relay opens it read-only and binds to the exact file it validated at startup.

The reviewed contract carries the meaning: registry identity, resources, operations, access profiles, and disclosure. Deployment-local facts, including where the database file actually is, stay in runtime.yaml and never enter the reviewed contract, so the same contract can be reviewed once and deployed in staging and production without editing it.

Wire Registry Stack in alongside a domain platform when:

The platform does not yet publish standards-shaped catalog, service, schema, policy, or evidence-offering metadata.
Callers need an answer in a declared form (a boolean, a reviewed code, a bucket) rather than full records.
A read path is needed for callers that must not be granted direct database access.

Exact subjects, one question at a time

A Relay named lookup resolves one record from one exact conjunction. The contract declares that lookup’s selectors by name, each bound to one exact source column with a declared type and optional byte bounds and codelist, and bounds the request body in bytes. A request must supply exactly the declared set: an extra selector or a missing one is refused before any source access rather than silently ignored, so a caller cannot widen or narrow the conjunction to probe. Relay returns one resolved record or a single indistinguishable unresolved outcome. It returns no candidates, no scores, no rankings, and no matching explanation, so an exact lookup is not record matching and cannot be used as one. The compiler also reports a contextual review finding when a lookup’s selectors are classified more restrictively than the properties its access profile discloses, because such a lookup would let a caller confirm a value it is not permitted to read.

Evidence Gateway keeps the same exact-subject discipline for each evaluation. A singular request names one requirement and carries one selector per declared subject role, at most eight roles. Its closed acquisition is either one fixed source request or one fixed search followed, only after a unique schema-valid match, by one fixed fetch. The latter has a hard two-request ceiling and does not allow response-led routing or general multi-source fulfillment.

POST /v1/evidence/batch groups between one and sixteen ordered audience-scoped evaluations that share one requirement and purpose. Each item carries its own complete subject-role set and request nonce. Evidence Gateway validates and authorizes every item before source access, then returns one ordered evidence or evidence_not_available result per item. Each available result contains its own signed flattened JSON Web Signature (JWS). Any failure other than an ordinary unavailable outcome aborts the complete request without releasing a partial response.

The request-batch route is distinct from holder-bound issuance batching on POST /v1/evidence. Request batching evaluates several subject sets. Holder-bound issuance batching performs one subject evaluation and emits one credential per presented holder key. A lookup still resolves to exactly one match, no match, or ambiguity, and Evidence Gateway never surfaces or chooses between candidates.

Sources read where they live

Registry Relay’s source model is deliberately the narrowest thing that can still serve a registry: local SQLite databases, each opened read-only and read in place. A contract may declare more than one, and each resource binds to exactly one of them.

There is no source adaptation layer to configure, because there is nothing to adapt. Relay does not fetch from an HTTP source, read a spreadsheet, connect to PostgreSQL, run a scripting runtime, or hold a credential for any upstream system. Its only outbound traffic is OpenID Connect discovery and JWKS retrieval for verifying the tokens its own callers present. A source is one of two declared profiles, snapshot or live-read-only, and both are SQLite.

That closes an entire class of integration question, and it moves the corresponding work upstream: if the authoritative data is not in SQLite, producing an extract is the institution’s job, done with its own tooling under its own change control, before Relay is involved. The cost is real and worth naming. The benefit is that the reviewable surface is a file and a contract, with no request-time acquisition path to audit.

Earlier Relay releases did compile source access from a plan with HTTP, scripted, and snapshot capabilities, with compiled credential providers behind it. None of that survives in V2. If you are reading an integration guide that describes source scripts, same-origin call budgets, or API-key placement for Relay, it describes the retired runtime. See Known limitations for the full list of what went with it.

Evidence Gateway keeps its own source model, and it is a different one: fixed HTTP sources with compiled credentials and bounded reviewed Rhai. The two products do not share that machinery, and Evidence does not inherit Relay’s authorization model. When an institution’s authoritative data is not in SQLite and cannot reasonably be extracted into it, Evidence Gateway is the surface that can reach it.

Evidence Gateway with a fixed authoritative source

Use this pattern when an institution wants a minimum-disclosure answer over data in an authoritative system. Evidence Gateway calls that system through its own fixed HTTP source contract. The reviewed bundle fixes the origin, path authority, method, authentication, projection, schemas, and bounded scripts. The caller cannot select or redirect the source.

Request batches use the same closed sources. Sequential item evaluation is available without extra source configuration. An operator can enable the optional source-batch capability in both the governed bundle and runtime for an eligible fixed-path HTTP source with reviewed prepare_batch and extract_batch scripts. That option changes the number of physical source calls, not the request, authorization, disclosure, signing, or audit contract. Once an optimized call begins, a failure does not retry through sequential fanout.

The caller’s access token and the source credential serve different boundaries:

The caller holds a short-lived access token for Evidence Gateway, from the deployment’s identity provider or from Registry Mint when there is none. See the Registry Mint reference.
Evidence Gateway holds its own compiled credential for the authoritative source. The caller never sees it and cannot influence which credential is resolved.

Registry Relay is not part of this request path. If the institution also operates Relay, it is a separate protected-read product with its own source, callers, authorization, and audit trail.

There is one composition where they do meet, and it runs one way only. A Relay-served API is an ordinary protected HTTP endpoint, so Evidence Gateway can consume it through the same fixed HTTP source contract it uses for any other authoritative system. That is a deployment choice made in an Evidence bundle, not a feature either product declares: Relay does not know it is being read by Evidence, and Evidence does not inherit Relay’s authorization decisions. The maintained protected-read reference project is written to be product-neutral for exactly that reason: it targets any protected read that projects fields, filters to an exact reference, and signals whether a page is complete, and Relay is only the worked example.

Workflow engines

Examples: Camunda, Flowable, and other casework or process orchestration engines.

Workflow engines own process state, task assignment, timers, branching, retries, escalation, and history. Registry Stack adds a stable registry contract that workflow steps can call, without learning source tables, raw SQL, or full records.

Wire Registry Stack in alongside a workflow engine when:

A workflow step needs an authoritative fact (a status, a boolean, a reviewed code) as an input to the workflow engine’s own decision.
A workflow step needs a signed, independently verifiable assertion rather than an internal service result.
Generated workflow connectors must not depend on source schema details.

Exchange layers

Examples: X-Road, GovStack-style reference exchanges, and country-specific interoperability layers.

X-Road and Registry Stack solve complementary parts of a secure data-exchange architecture. See Operate Registry Relay for what sits between the exchange layer and a Relay process, including the fact that Relay serves plain HTTP and expects transport security to be terminated in front of it.

Exchange layers own participant onboarding, message transport, mutual trust, routing, addressing, and cross-institution policy. Registry Stack adds the registry-facing surface that sits behind the exchange layer: which records exist, which properties are readable under which access profile, and what evidence can be requested.

Wire Registry Stack in behind an exchange layer when:

The exchange layer handles network trust but the registry endpoint still needs its own scope and purpose checks, per-response disclosure limits, and an audit record of what was released.
An exchange-forwarded request needs a minimized evidence response rather than a copied record.

Public-service platforms

Examples: citizen portals, casework systems, service catalogue platforms.

These platforms own the user journey: forms, case queues, notifications, payments, channels. Registry Stack adds the narrow registry-facing surface those journeys can call: governed read operations, evidence responses, published metadata, and audit records.

Wire Registry Stack in alongside a service platform when:

A service platform needs a registry answer during delivery but must not pull the full record.
A service catalogue needs to discover an evidence offering before integration.

Standards each surface speaks

Each integration surface involves a different set of standards. The claim level differs per standard (some surfaces emit a standard, others map to or compare against it); the standards register is the authoritative list of claim levels and per-project evidence.

Integration surface	Relevant standards
Static catalog and service discovery (Registry Manifest)	DCAT, BRegDCAT-AP, CPSV-AP, OGC API Records, SHACL, JSON Schema, JSON-LD, ODRL, SKOS-shaped codelists
Governed read API (Registry Relay)	OpenAPI, JSON Schema, SHACL, JSON-LD, GeoJSON, JSON-FG, SDMX (a profiled read subset), GovStack Digital Registries
Minimum-disclosure assertions (Evidence Gateway)	OpenAPI, CCCEV, SD-JWT VC, JSON Schema

Relay’s row is a list of what it emits or serves, not a conformance claim. It is explicitly not conformant to OGC API Features, OGC API Records, or OGC API EDR: it serves RFC 7946 GeoJSON and the bounded JSON-FG profile as response serializations of its own governed records, with no OGC API route, collection, or conformance class. Its SDMX binding is a narrow aligned read subset of SDMX REST 2.2.2, not full SDMX conformance or certification.