DCI API Compliance: reg_type field usage, predicate query support, and envelope structure

[jeremi]

Summary

While integrating OpenSPP with OpenCRVS via the DCI (Digital Convergence Initiative) API, we identified several differences between the OpenCRVS implementation and the SPDCI API specification v1.0.0. This ticket documents these findings to help improve interoperability.

Environment

• DCI API spec version: v1.0.0
• Testing via: OpenSPP DCI Client

Findings

1. reg_type Field Semantic Mismatch (High Priority)

Spec expectation:
Per the SearchRequest schema, reg_type should contain the registry type:

reg_type:
  type: string
  description: |
    @context:https://schema.spdci.org/common/v1/api-schemas/RegistryType.jsonld
    example: "ns:org:RegistryType:Civil"

OpenCRVS behavior:
OpenCRVS expects reg_type to contain a lowercase event type (e.g., "birth", "death").

Impact:
This breaks semantic interoperability. Clients following the spec would send reg_type: "ns:org:RegistryType:Civil" and use reg_event_type for event filtering, but OpenCRVS rejects or misinterprets this.

Suggested fix:

• Use reg_type for registry type identification
• Use reg_event_type for event type filtering (BIRTH, DEATH, MARRIAGE, DIVORCE)

2. Missing reg_event_type Support (Medium Priority)

Spec expectation:
The reg_event_type field in search_criteria allows filtering by vital event type.

OpenCRVS behavior:
This field appears to be ignored or not supported. Event type filtering is done via reg_type instead.

3. Envelope Structure - Signature Wrapper (Medium Priority)

Spec expectation:
The DCI envelope structure is:

{
  "signature": "...",
  "header": { ... },
  "message": { ... }
}

OpenCRVS behavior:
OpenCRVS expects envelopes without the signature wrapper:

{
  "header": { ... },
  "message": { ... }
}

Suggested fix:
Accept both formats, or document that signature is not supported.

4. Required Fields Stricter Than Spec (Low Priority - Documentation)

OpenCRVS requires fields that are optional in the DCI spec:

• consent object (required by OpenCRVS, optional in spec)
• locale field (required by OpenCRVS, optional in spec)

This is acceptable behavior (stricter validation), but should be documented for implementers.

5. Expression Query Format (No Action Required)

OpenCRVS uses a MongoDB-style range query format for expression queries:

{
  "type": "ns:org:QueryType:expression",
  "value": {
    "dateOfEvent": {
      "type": "range",
      "gte": "2024-01-01",
      "lte": "2024-12-31"
    }
  }
}

This is valid per DCI spec since expression queries are explicitly implementation-specific. The spec states:

"Query expression's syntax / format is determined based on query-type."

Just documenting for clarity - no fix needed.

6. Predicate Query Support (Feature Request)

Spec definition:
The DCI spec defines a predicate query type with a standardized structure using operators: gt, lt, eq, ge, le, in. This enables interoperable structured queries across implementations.

{
  "query_type": "predicate",
  "query": [{
    "seq_num": 1,
    "expression1": { "attribute_name": "dateOfEvent", "operator": "ge", "attribute_value": "2024-01-01" },
    "condition": "and",
    "expression2": { "attribute_name": "dateOfEvent", "operator": "le", "attribute_value": "2024-12-31" }
  }]
}

Current state:
OpenCRVS appears to only support expression queries with a custom MongoDB-style format.

Why this matters:

• expression queries are implementation-specific - each system can use different syntax
• predicate queries are standardized - any DCI client can construct them without knowing implementation details
• For true interoperability, supporting predicate allows clients to query without custom adapters

Suggested priority: Medium - would significantly improve interoperability with other DCI-compliant systems.

Reproduction Steps

1. Send a DCI search request with:
   • reg_type: "ns:org:RegistryType:Civil" (per spec)
   • reg_event_type: "BIRTH" (per spec)
2. Observe that OpenCRVS does not return expected results
3. Change to reg_type: "birth" (OpenCRVS-specific)
4. Observe that OpenCRVS now works

Suggested Resolution Priority

1. High: Fix reg_type semantic usage
2. Medium: Add reg_event_type support
3. Medium: Accept envelope with signature wrapper
4. Medium: Add predicate query type support
5. Low: Document required fields

References

• SPDCI API Standards
• CRVS API v1.0.0 Spec
• DCI Standards Documentation

---

We're happy to collaborate on fixes or provide more details.

[naftis]

Hi @jeremi, thankful for your efforts and have iterated the changes.

0. OAuth now supports application/x-www-form-urlencoded

This was applied to opencrvs-core too and gets officially released for 2.0 🥳

curl --request POST \
  --url https://dci-crvs-api.vc-demo.opencrvs.dev/oauth2/client/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=461222e7-45b1-433b-adb5-d4287bbcf0e6 \
  --data client_secret=0f5c5a12-5025-48cb-a920-069b4964dfc7 \
  --data grant_type=client_credentials

1. reg_type corrected
2. reg_event_type corrected. I still use lowercase event names, as these are fully configurable per OpenCRVS instance and are case sensitive. A next iteration can fetch all possible event types from OpenCRVS and give proper validation error, but this validation isn't available in this version.

Example payload with both corrected

3. ❗ I haven't verified this yet. The validation

   dci-crvs-api/packages/http-api/src/validations.ts

   Lines 140 to 150 in fa6672f

   	const syncSearchRequest = z.object({
   	signature: z.string().optional(),
   	header: syncHeader,
   	message: searchRequestSchema
   	})
   	const encryptedSyncSearchRequest = z.object({
   	signature: z.string().optional(),
   	header: syncHeader,
   	message: encryptedMessage
   	})

   has it as optional - but manual testing TBC

4. consent & locale made optional

OpenCRVS doesn't handle these - more work to be done to refine and understand the need of these. I've set them as optional for now.

5. Expression format - right, this gets almost directly redirected to OpenCRVS. Gives flexibility if the other search types don't give enough support.

6. ❗I have added a basic support for predicate query - but yet untested. Will manually test ASAP.