Request a birth certificate SD-JWT VC from OpenCRVS

Extend the project created in Issue registered-parent evidence from OpenCRVS with a birth-record question and request the answer as a Selective Disclosure JWT Verifiable Credential (SD-JWT VC). The credential exposes givenName, familyName, dateOfBirth, and placeOfBirth as four independently disclosable fields.

Outcome: A verified SD-JWT VC containing a governed birth-record extract from synthetic data.
Time: About 25 minutes
Level: Institution source with synthetic data
Prerequisites: The completed OpenCRVS registered-parent tutorial projectA Record Search client for the public OpenCRVS demoThe Evidence Gateway toolsetcurl, python3, awk, and an editor

This tutorial uses the provider-published synthetic Josh Hoeger registration, selected by national ID 3617402568. Do not substitute a real person. The demo maintainers can reset its data, accounts, and integrations.

Understand the credential boundary

The example is informed by the European Union Once-Only Technical System birth-evidence sample, but this tutorial does not implement that exchange protocol. Evidence Gateway produces a governed extract from a registered birth:

{
  "birthCertificate": {
    "givenName": "...",
    "familyName": "...",
    "dateOfBirth": "...",
    "placeOfBirth": {
      "locationId": "..."
    }
  }
}

The deployment’s law and governance determine whether that extract is accepted as a birth certificate. Evidence Gateway proves which provider signed the configured assertion. It does not grant legal status to the document.

Each direct child of birthCertificate has its own SD-JWT disclosure. placeOfBirth is one atomic nested value, so its locationId is not disclosed separately from its container.

This response is a second serialization of one stateless assertion, not a credential lifecycle. There is no issuance session, status list, revocation, or presentation exchange.

Draft a birth-record source

Continue in the registered-parent directory created by Issue registered-parent evidence from OpenCRVS. The retained source.openapi.yaml includes the bounded birth fields used in this tutorial.

Draft a separate source so the certificate question cannot inherit the parent-identifier projection:

evidencectl source suggest \
  --project . \
  --source-id opencrvs-birth-certificate \
  --operation 'POST /events/search' \
  --select /total \
  --select '/results/*/type' \
  --select '/results/*/status' \
  --select '/results/*/dateOfEvent' \
  --select '/results/*/placeOfEvent' \
  --select '/results/*/declaration/child.nid' \
  --select '/results/*/declaration/child.name/firstname' \
  --select '/results/*/declaration/child.name/surname' \
  --select '/results/*/declaration/child.birthLocationId'

The command writes editable source artifacts. The selected operation remains a draft until you close the OpenCRVS-specific request and extraction decisions.

Configure the fixed search

Replace sources/opencrvs-birth-certificate.yaml with:

transport: http-json
baseUrl: https://events.farajaland-integration.opencrvs.dev
posture: record-transformed
authentication:
  kind: oauth2-client-credentials
  tokenEndpoint: https://auth.farajaland-integration.opencrvs.dev/token
  clientIdRef: secret:file/opencrvs-client-id
  clientSecretRef: secret:file/opencrvs-client-secret
  scope: recordsearch
  credentialPlacement: form-body
  maximumCacheSeconds: 300
  assumedLifetimeSeconds: 600
request:
  method: POST
  path: /events/search
  fixedHeaders:
    - name: Accept
      value: application/json
  selectorInputs:
    - role: child
      alternatives:
        - profile: opencrvs-national-id-v1
          fields: [national_id]
  prepareScript: adapters/opencrvs-birth-certificate-prepare.rhai
  adapterParameters:
    childSelectorRole: child
    eventType: birth
    registeredStatus: REGISTERED
    childNationalIdField: child.nid
    childNameField: child.name
    childBirthLocationField: child.birthLocationId
    resultLimit: 2
    resultOffset: 0
  adapterParametersSchema: schemas/opencrvs-birth-certificate-parameters.schema.yaml
  preparationLimits:
    query: forbidden
    jsonBody: required
    maximumJsonDepth: 12
    maximumCollectionItems: 32
    maximumStringBytes: 512
    maximumNormalizedBytes: 8192
  projection:
    - /total
    - /results/*/type
    - /results/*/status
    - /results/*/dateOfEvent
    - /results/*/placeOfEvent
    - /results/*/declaration/child.nid
    - /results/*/declaration/child.name/firstname
    - /results/*/declaration/child.name/surname
    - /results/*/declaration/child.birthLocationId
  redirects: deny
  timeoutMilliseconds: 10000
  maximumResponseBytes: 262144
  concurrencyLimit: 8
responseSchema: schemas/opencrvs-birth-certificate-response.schema.yaml
extractScript: adapters/opencrvs-birth-certificate-extract.rhai
factSchema: schemas/opencrvs-birth-certificate-facts.schema.yaml

The source can search only for one registered birth by the authorized child selector. The caller cannot change the event type, status, response projection, or result ceiling. It reuses the owner-only Record Search credentials from the registered-parent tutorial.

Replace schemas/opencrvs-birth-certificate-parameters.schema.yaml with:

type: object
additionalProperties: false
required:
  - childSelectorRole
  - eventType
  - registeredStatus
  - childNationalIdField
  - childNameField
  - childBirthLocationField
  - resultLimit
  - resultOffset
properties:
  childSelectorRole: {const: child}
  eventType: {const: birth}
  registeredStatus: {const: REGISTERED}
  childNationalIdField: {const: child.nid}
  childNameField: {const: child.name}
  childBirthLocationField: {const: child.birthLocationId}
  resultLimit: {const: 2}
  resultOffset: {const: 0}

Replace adapters/opencrvs-birth-certificate-prepare.rhai with:

fn prepare(selectors, context) {
    let parameters = context["parameters"];
    let child = selectors[parameters["childSelectorRole"]];
    let data = #{};
    data[parameters["childNationalIdField"]] = #{
        type: "exact",
        term: child["values"]["national_id"]
    };

    #{
        query: [],
        body: #{
            query: #{
                type: "and",
                clauses: [#{
                    eventType: parameters["eventType"],
                    status: #{
                        type: "exact",
                        term: parameters["registeredStatus"]
                    },
                    data: data
                }]
            },
            limit: parameters["resultLimit"],
            offset: parameters["resultOffset"]
        }
    }
}

Extract the birth facts

Replace adapters/opencrvs-birth-certificate-extract.rhai with:

fn extract(source_response, context) {
    let parameters = context["parameters"];
    let total = source_response["total"];
    let results = source_response["results"];
    if results.len > parameters["resultLimit"] {
        throw("source_protocol_error");
    }

    if total == 0 {
        if results.len != 0 { throw("source_protocol_error"); }
        return #{outcome: "no_match"};
    }
    if total > 1 {
        if results.len < 2 { throw("source_protocol_error"); }
        return #{outcome: "ambiguous"};
    }
    if results.len != 1 { throw("source_protocol_error"); }

    let result = results[0];
    if result["type"] != parameters["eventType"] ||
       result["status"] != parameters["registeredStatus"] ||
       !result.contains("declaration") {
        throw("source_protocol_error");
    }

    let declaration = result["declaration"];
    let child_id_field = parameters["childNationalIdField"];
    let child_name_field = parameters["childNameField"];
    let birth_location_field = parameters["childBirthLocationField"];
    if !declaration.contains(child_id_field) ||
       !declaration.contains(child_name_field) ||
       !declaration.contains(birth_location_field) ||
       result["placeOfEvent"] != declaration[birth_location_field] {
        throw("source_protocol_error");
    }

    let child_name = declaration[child_name_field];
    #{
        outcome: "match",
        facts: #{
            child_national_id: declaration[child_id_field],
            given_name: child_name["firstname"],
            family_name: child_name["surname"],
            date_of_birth: result["dateOfEvent"],
            place_of_birth_id: result["placeOfEvent"]
        }
    }
}

The extraction accepts exactly one registered birth. It also requires the top-level event place to match the declaration’s birth-location identifier before constructing facts.

Replace schemas/opencrvs-birth-certificate-facts.schema.yaml with:

type: object
additionalProperties: false
required:
  - child_national_id
  - given_name
  - family_name
  - date_of_birth
  - place_of_birth_id
properties:
  child_national_id: {type: string, minLength: 1, maxLength: 128}
  given_name: {type: string, minLength: 1, maxLength: 200}
  family_name: {type: string, minLength: 1, maxLength: 200}
  date_of_birth: {type: string, format: date}
  place_of_birth_id: {type: string, minLength: 1, maxLength: 128}

Define the governed certificate shape

Create schemas/birth-certificate.yaml:

$id: urn:registrystack:evidence:local:schema:birth-certificate:v1
type: object
additionalProperties: false
required: [givenName, familyName, dateOfBirth, placeOfBirth]
properties:
  givenName:
    type: string
    minLength: 1
    maxLength: 200
  familyName:
    type: string
    minLength: 1
    maxLength: 200
  dateOfBirth:
    type: string
    format: date
  placeOfBirth:
    type: object
    additionalProperties: false
    required: [locationId]
    properties:
      locationId:
        type: string
        minLength: 1
        maxLength: 128

The schema closes every returned field. The location is an OpenCRVS identifier because the public search response does not provide a reviewed human-readable place label.

Create questions/birth-certificate.yaml:

id: birth-certificate
question: What birth details are recorded for this person?
purpose: civil-registration-extract
subject:
  role: child
  selector: national_id
  profile: opencrvs-national-id-v1
  derivation: true
source:
  ref: opencrvs-birth-certificate
answers:
  - concept: birth_certificate
    type: reviewed-structured-value
    schema: schemas/birth-certificate.yaml
    maximumSerializedBytes: 2048
    sdJwtVc:
      claim: birthCertificate
      disclosure: top-level
responseFormats: [signed-jws, sd-jwt-vc]
derivation: derivations/birth-certificate.rhai
disclosure:
  allow: [birth_certificate]

birthCertificate is a configured JSON claim name. Evidence Gateway has no built-in birth-certificate type. The same mechanism can project any reviewed structured value under another non-reserved claim name. responseFormats explicitly permits the local bundle and this question’s local grant to return that projection as SD-JWT VC while retaining signed JWS.

Create derivations/birth-certificate.rhai:

fn answer(facts, selectors, context) {
    if facts.child_national_id != selectors.child.values.national_id {
        throw("derivation_input_error");
    }

    #{
        birth_certificate: #{
            form: "reviewed-structured-value",
            schema: "urn:registrystack:evidence:local:schema:birth-certificate:v1",
            fields: #{
                givenName: facts.given_name,
                familyName: facts.family_name,
                dateOfBirth: facts.date_of_birth,
                placeOfBirth: #{locationId: facts.place_of_birth_id}
            }
        }
    }
}

Evidence Gateway validates the complete value against the schema before mapping any field to an SD-JWT disclosure. A derivation cannot add undeclared certificate fields.

Start and prepare the SD-JWT request

Compile and start the updated local project:

evidencectl dev start .

Prepare the request and retain sd-jwt-vc as the expected response format before the source is called:

evidencectl request prepare birth-certificate \
  --purpose civil-registration-extract \
  --subject child:national_id=3617402568 \
  --response-format sd-jwt-vc \
  --name opencrvs-birth-certificate

Preparation obtains local authorization and records the expected issuer, audience, subject binding, requirement, value form, request nonce, and response format. It does not contact OpenCRVS.

Request the credential over HTTP

Send the retained request across the real Evidence Gateway boundary:

curl -fsS \
  --config .evidence/requests/opencrvs-birth-certificate/authorization.curl \
  --request POST \
  --url http://127.0.0.1:8080/v1/evidence \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/dc+sd-jwt' \
  --data-binary @.evidence/requests/opencrvs-birth-certificate/request.json \
  --output opencrvs-birth-certificate.sd-jwt

Evidence Gateway authenticates the caller, authorizes the exact question and purpose, obtains an OpenCRVS token, performs the fixed birth search, validates and derives the value, signs the SD-JWT VC, and durably records the disclosure release before returning the bytes.

Verify before reading

Verify the credential against the pre-response context:

evidencectl verify opencrvs-birth-certificate.sd-jwt \
  --context .evidence/requests/opencrvs-birth-certificate/verification.json \
  --output opencrvs-birth-certificate.verified.json

VERIFIED

Inspect the verified Evidence Gateway payload:

python3 -m json.tool opencrvs-birth-certificate.verified.json

The supported value retains the governed evidence form:

{
  "providesValueFor": "urn:registrystack:evidence:local:concept:birth-certificate:birth_certificate",
  "value": {
    "form": "reviewed-structured-value",
    "schema": "urn:registrystack:evidence:local:schema:birth-certificate:v1",
    "fields": {
      "givenName": "Josh",
      "familyName": "Hoeger",
      "dateOfBirth": "<synthetic-date>",
      "placeOfBirth": {
        "locationId": "<synthetic-location-id>"
      }
    }
  }
}

The angle brackets are this page’s, not the payload’s. Your output carries the date of birth and location identifier the demo instance holds; the names appear here because you already searched for them.

The signed credential carries an always-visible birthCertificate container and four nested disclosures, one for each top-level field in schemas/birth-certificate.yaml. Count the disclosure segments in the credential:

awk -F '~' '{print "disclosures:", NF - 2}' opencrvs-birth-certificate.sd-jwt

disclosures: 4

An SD-JWT VC serializes as the issuer JWT, one segment per disclosure, and a trailing tilde, which is why the count is the number of tilde-separated fields minus two.

Evidence Gateway’s V1 verifier checks the complete stored SD-JWT VC response. Wallet presentation, omission of selected disclosures, and key-binding JWT validation remain outside this profile.

Inspect the audit and clean up

Stop the services:

evidencectl dev stop

Inspect the last operation:

evidencectl audit show --last-operation

ACCESS AUTHORIZED birth-certificate civil-registration-extract requester=<pseudonym>
DISCLOSURE RELEASED birth_certificate

The requester value changes on each fresh project.

Read those two lines for what they leave out. They name the requester pseudonym, the question, the purpose it was authorized under, and the one concept released. Neither line carries a given name, a family name, a date of birth, or a location identifier, so the trail records that a birth certificate was released without becoming a second copy of it. Neither line carries the child’s national ID, the OpenCRVS token, or the search response. An operator reviewing this trail can establish who asked, why, and what was released, and cannot reconstruct the certificate from it.

Remove the sealed local generation:

evidencectl dev clean

Delete the Record Search client in OpenCRVS when you finish. Remove its two credential files when you no longer need the project.

Troubleshooting

Symptom	Cause	Resolution
The request returns no assertion for a subject that worked earlier	The demo was reset and the synthetic registration no longer exists under that national ID, so the fixed search matched nothing.	Sign in to the demo as the prerequisite tutorial describes and confirm the record is still there. Leave the extractor’s `no_match` path alone; a missing registration is an answer.
Evidence Gateway reports an ambiguous source result	More than one registered birth now carries that national ID in the demo data.	Keep `resultLimit: 2` and the `ambiguous` outcome. An ambiguous civil-registration match is a fact about the record set.
The OpenCRVS token request fails with 401	The Record Search client was deleted, its secret was rotated, or the demo reset its integrations.	Create a new Record Search client and rewrite `secrets/opencrvs-client-id` and `secrets/opencrvs-client-secret`. Keep both values out of shell history and tracked files.
Requests start failing after several runs	OpenCRVS audits its searches and applies a daily request limit on the integration demo.	Wait for the limit to reset before running the tutorial again. Do not add retries around the source.
Evidence Gateway reports a source dependency failure	The demo host was unreachable or slow, or the response exceeded `timeoutMilliseconds` or `maximumResponseBytes`.	Retry later. Treat the bounds as reviewed source policy, and raise one only after deciding it is right for the deployment.
The token request or the search fails with a certificate error	An intercepting proxy or an out-of-date trust store on your machine.	Repair the trust store, or exempt the demo hosts from interception. Do not reach for `--insecure`: the source denies redirects and reaches OpenCRVS over HTTPS only.