Integration patterns
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.
Country evidence mesh
Section titled “Country evidence mesh”At country scale, the same pattern can sit next to several domain platforms. Clinical health systems can expose bounded outputs through a reviewed FHIR integration, public-health program systems such as DHIS2 can use Relay’s product-neutral, reviewed Rhai script capability, and social protection, agriculture, education, and civil registration systems can keep their own authoritative stores. A Registry Stack project can deploy Relay only, Notary only, or both products. Relay-only projects expose governed source capabilities. Notary-only projects evaluate source-free or self-attested claims, but those claims are not issuable. In a combined project, Relay keeps source credentials and returns only reviewed typed consultation outputs for Notary to turn into configured claims. Consuming systems such as a social-protection management information system do not become raw-record readers.
The supported local first-run combined path extends the canonical spreadsheet sample in place with Notary and a private consultation Relay, then runs them as one local project. The snapshot starter is a separate offline authoring path. Its synthetic fixture results do not establish that Relay or Notary is running.
Evidence-to-action boundary
Section titled “Evidence-to-action boundary”Every combined integration follows the same ownership boundary. Registry Relay owns source-specific acquisition, source-access policy, and typed normalization. Registry Notary owns atomic evidence claims plus evidence authorization and disclosure policy. The evidence consumer determines how the evidence is used, and the decision owner remains accountable for requirements, decisions, workflow, and action.
The DHIS2 health-evidence starter makes that boundary visible. DHIS2 remains the system of record.
Relay uses its product-neutral script capability to perform bounded, same-origin acquisition and
normalize the existing health outputs plus bcg_birth_dose_recorded,
opv_birth_dose_recorded, and measles_dose_recorded. Notary exposes those facts as reusable
evidence claims. In this example, a public-health programme is both the evidence consumer and the
decision owner. It can compute outreach-required or follow-up-priority without moving either
decision into Relay or Notary.
The reviewed contract keeps true, false, null, no-match, ambiguity, and source failure
distinct. Missing evidence is not a negative fact. Offline synthetic fixtures are the deterministic
acceptance path; a governed live check against a reachable DHIS2 instance is optional compatibility
evidence.
Registry Notary may attest a decision that DHIS2 or another authoritative source already made only when the claim identifier and its review documentation identify it as a source-owned decision. This exception does not make Notary a general-purpose eligibility or workflow engine.
Domain registry platforms
Section titled “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, scoped read-only routes over source data, configured evidence responses, and hash-chained audit records. The connect your data guide starts from the supported public sample and points to the configuration reference for advanced source patterns.
One integration in a Registry Stack project can serve two different governed needs without
creating two source definitions.
A local materialization can back Relay’s records API, including configured filters, projection,
cursor pagination, relationships, aggregates, and enabled standards adapters.
snapshot consultations can use that same immutable published materialization for exact
evidence lookup.
The logical entity definition stays in the project workspace; provider paths, worksheets, tables,
and physical columns stay in the private environment binding.
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 evidence-shaped responses (predicate, redacted, selected value) rather than full records.
- A read path is needed for callers that must not be granted direct database access.
Exact subjects and batch envelopes
Section titled “Exact subjects and batch envelopes”A Relay consultation selects one subject with one to eight required typed selector components. The components form one fixed exact conjunction, not a general search or a subject batch. Each component is bounded and canonicalized under the compiled consultation contract. Up to sixteen total inputs may also include bounded parameters that are not selector components. Relay reports no match, one match, or ambiguity instead of choosing between duplicate records.
Registry Notary keeps batch evaluation as a separate outer API.
For registry-backed claims, a batch requires an Idempotency-Key, validates the complete batch
before the first Relay call, and fans items out as independently authorized single-subject
consultations under bounded concurrency.
Claims within one item may reuse an identical consultation result, but duplicate subjects in
different item positions remain separate children with separate identities.
Replay of the same caller-scoped outer request returns the stored result without repeating a
completed child consultation.
This split preserves ordered batch results without granting Relay a multi-subject request or an upstream bulk operation.
Closed source adaptation
Section titled “Closed source adaptation”Registry Relay compiles source access from a closed plan.
The public capabilities are http, script, and snapshot.
http performs one bounded request and projects the declared typed outputs.
Unknown response fields that no output selects are ignored and never cross the consultation
boundary. A second request, response-dependent request construction, pagination, branching, or
custom normalization uses script instead of a public operation graph.
Rhai is the first script runtime, not a DHIS2 feature.
The reviewed adapter runs once and asks Relay to perform calls through source.path, source.get,
source.post_json, and source.post_form. Relay validates every complete call against the authored
same-origin method and path authority before it resolves credentials or dispatches. Responses
contain bounded JSON or text plus only selected safe headers. Returned links remain usable for
pagination only after same-origin canonicalization and the ordinary authority and budget checks.
Scripts default to five source calls and cannot exceed sixteen.
snapshot performs an exact lookup against a Relay-local immutable entity generation.
The entity may also back a records service, but records publication is optional and carries a
separate access, purpose, projection, filter, and pagination policy.
OpenCRVS, DHIS2, OpenSPP, FHIR, and jurisdiction-specific systems remain authored integrations,
not runtime executor types. Product and version metadata record interoperability evidence and never
select a capability.
Fixed source credentials are compiled providers. Basic, bearer, OAuth 2.0 client credentials, API-key header, and API-key query placement do not give request callers a credential name or value. API-key values enter through environment-only secret references. Registry Stack-owned diagnostics, URLs, metrics, audit, and retained evidence must remain value-free. Query placement requires verified HTTPS outside loopback tests and an operator-security review because an upstream server, proxy, web application firewall, or network appliance may retain the URL outside Registry Stack’s control.
Workflow engines
Section titled “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 evidence fact (status, predicate, selected value) as an input to the workflow engine’s own decision.
- A workflow step needs an evidence artifact or credential rather than an internal service result.
- Generated workflow connectors must not depend on source schema details.
Exchange layers
Section titled “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. For the 1.0 single-node Compose deployment path, see Run single-node Compose behind your reverse proxy.
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: what entities exist, which fields are exposed, 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 route-level scopes, field projection, and source-specific access controls.
- An exchange-forwarded request needs a configured evidence response rather than a copied record.
Wallets
Section titled “Wallets”Examples: SD-JWT VC wallets, OID4VCI-compatible wallets.
Wallets own key management, credential storage, holder consent, and presentation to relying parties. Registry Stack adds the server-side issuance path: claim evaluation against registry data, plus the metadata describing what a registry-backed issuer offers.
Wire Registry Stack in alongside a wallet when:
- A registry-backed issuer needs to produce SD-JWT VC credentials or an OID4VCI issuance flow.
- An evidence offering needs to be discoverable before integration begins.
Public-service platforms
Section titled “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: entity routes, evidence responses, scoped 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
Section titled “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, ODRL, SKOS-shaped codelists |
| Scoped runtime metadata and protected data routes (Registry Relay) | OpenAPI, DCAT, BRegDCAT-AP, SHACL, JSON Schema, ODRL, OGC API Records, OGC API Features, OGC API EDR, SP-DCI, GovStack Digital Registries |
| Evidence and credentials (Registry Notary) | OpenAPI, CCCEV, SD-JWT VC, OID4VCI, W3C DID |