Configure OpenCRVS claims

Use this guide when a Registry Stack project needs birth-record claims from an OpenCRVS deployment. Registry Relay owns the Digital Convergence Initiative (DCI) source interaction and returns only the typed outputs in the compiled consultation. Registry Notary evaluates and discloses the configured claims from that Relay result.

When to use this

Use the starter as a reviewed starting point for an OpenCRVS DCI search journey. The built-in fixtures are synthetic. They prove the canonical token, key, and search requests, signed response verification, exact identifier matching, ambiguity handling, output minimization, and claim evaluation without contacting OpenCRVS, Relay, or Notary.

The starter does not prove compatibility with a particular OpenCRVS deployment. Record that evidence separately before marking a source version verified.

Before you start

You need:

• A registryctl build with Registry Stack project authoring commands
• A shell and a text editor
• The reviewed OpenCRVS DCI endpoint, sender and receiver identifiers, registry profile, and signing-key policy for the target deployment

Keep OAuth credentials and signing keys out of authored files, fixtures, commands, and test output.

Copy the OpenCRVS starter

Create the project workspace:

registryctl init --from opencrvs-dci --project-dir opencrvs-project

The result confirms the initialized project and next command:

Initialized Registry Stack project "fictional-civil-registry".
  Directory: opencrvs-project
  Starter: opencrvs-dci (Registry Stack 0.13.0)
  Starter content: matches bundled digest
  Editor support: VS Code and Zed (opencrvs-project/.registry-stack-editor/manifest.json)

Next:
  cd opencrvs-project
  registryctl test --project-dir .

The project contains one combined topology. Relay owns the OpenCRVS integration and consultation. Notary owns the evidence service, claims, disclosure policy, and optional credential profiles.

Run the canonical starter sequence

Use the focused trace and watch smoke before adapting the OpenCRVS profile. The complete fixture test remains offline and uses only synthetic token, key, and DCI search interactions.

Run these commands in order. Initialization creates the editor files, and the next idempotent command verifies them against the running registryctl. The focused test prints a safe synthetic trace. The following command starts the same fixture as a watch smoke; pressCtrl+C after its initial passing report. The final three commands test every fixture, explain the redacted plan, and build the unsigned product inputs.

opencrvs-dci: OpenCRVS DCI

A product-neutral script adapter with the signed DCI search verification profile.

registryctl init --from opencrvs-dci --project-dir opencrvs-project
registryctl authoring editor --project-dir opencrvs-project
registryctl test --project-dir opencrvs-project --integration birth-record --fixture birth-record-match --trace
registryctl test --project-dir opencrvs-project --integration birth-record --fixture birth-record-match --watch
registryctl test --project-dir opencrvs-project
registryctl check --project-dir opencrvs-project --environment local --explain
registryctl build --project-dir opencrvs-project --environment local

Generated from the five starter workspaces compiled into registryctl.

Prove the synthetic journey

Run every fixture without a network connection:

registryctl test --project-dir opencrvs-project

The human-readable report starts with:

PASS: <passed>/<total> fixtures passed

The match fixture proves the exact identifier and minimized birth-record outputs. The no-match and ambiguity fixtures prove that Relay does not choose a record when the source result is absent or non-unique. Derived checks reject malformed signatures, unexpected response shapes, excessive data, and source work before authorization.

Adapt the project contract

Review and update these surfaces:

1. In registry-stack.yaml, set the registry id, service purpose, caller scopes, consultation input mapping, claims, disclosure modes, and credential profiles.
2. In integrations/birth-record/integration.yaml, set the OpenCRVS product evidence, allowed source version, DCI endpoint path, sender and receiver identifiers, registry and record types, selector mapping, outputs, and limits.
3. In integrations/birth-record/adapter.rhai, keep the source calls and response handling within the declared method, path, origin, output, and limit authority.
4. In integrations/birth-record/fixtures/, replace the fictional observations with wholly synthetic examples of the reviewed request and response contract.
5. In environments/<environment>.yaml, bind the private source, OAuth, trust, Relay workload, caller, issuance, and deployment settings through secret references.

source.product and source.versions are interoperability evidence. They do not enable DCI, Rhai, or another executor. The script capability remains available for any source product whose reviewed integration needs bounded multi-request adaptation.

Check and build the combined topology

Validate the adapted project and inspect its redacted plan:

registryctl check \
  --project-dir opencrvs-project \
  --environment local \
  --explain

The human-readable report marks the project valid. Review the fixed source authority, required caller scopes, consultation input mapping, output projection, claims, disclosure modes, and required review classes. Add --format json only for machine processing.

Generate deterministic unsigned inputs for both products:

registryctl build \
  --project-dir opencrvs-project \
  --environment local

The human-readable report starts with Built Registry Stack project and identifies the output directory. The output has separate Relay and Notary Config Bundle input directories under .registry-stack/build/local/private/. It contains secret references, not secret values. Package, sign, verify, and activate each product input through that product’s Config Bundle workflow.

Verify the boundary

Before deployment approval, confirm:

• Only Relay has source origin, credential, token, and source-trust bindings.
• Notary has a Relay workload binding for registry-backed claims and no direct OpenCRVS connector.
• The source product and version do not select the script capability.
• Each fixture proves the canonical source request and a minimized typed result.
• The generated review record identifies every semantic and operator-security review required by the adapted project.

Troubleshooting

Symptom	Cause	Fix
A fixture request differs from the trace	The expected DCI interaction does not match the compiled integration.	Correct the integration or update the wholly synthetic interaction proof.
Signature verification fails	The synthetic response, key set, algorithm, or configured key policy is inconsistent.	Regenerate only synthetic fixture evidence from the reviewed contract.
A source response is ambiguous	More than one record matches the exact identifier.	Correct the source data or strengthen the reviewed selector contract.
Notary contains an OpenCRVS source credential	Source authority crossed the Relay boundary.	Remove the Notary binding and bind the credential only to the Relay integration environment.
A product or version change enables script execution	Runtime dispatch is coupled to interoperability metadata.	Keep capability.script explicit and treat product and version only as evidence.

Next

• Return to Author an HTTP Registry Stack project for the complete fixture, review, and unsigned-build workflow.
• Use Configure a script source adapter to review the product-neutral Rhai host boundary.
• Read Integration patterns for the Relay and Notary topology around a domain system.