Technical feedback from the OpenSPP & OpenCRVS demonstration

[euanmillar]

Overall the standard has been flexible enough for our integration and no major refactors have had to be done. We have proposed using well-known standards like JWT authorization headers, JSON-LD, Schema.org, and most of the changes have been well-received and implemented.

We have some suggestions and questions that probably should be discussed either in this thread or perhaps broken out into new discussions if deemed appropriate. We (@naftis @jeremi @dasunhegoda ) think that the standards & documentation could be improved if these items are addressed. Here they are in no particular order:

• The documentation of some* attributes needs to be improved with examples. Consider when adding parameters to the standard, description & examples need to be mandatory.

• We think that less flexibility is needed to better align how values and attributes are shared. Rather we should start strict and contained and then expand if needed.

1. query_type - "idtype-value", "expression", "predicate"
2. query can be interpreted in different ways based on the implementation which can be both bad and good
3. attribute names need to be strictly defined in queries and in sorting
4. for known search parameters like birth_date or name, the spec can be stricter and have usage examples
5. for unknown and custom parameters, the spec can be flexible

• The querying syntax needs some refinement regarding how would we handle multiple OR/AND operation combinations.
• Introduce the operators such as not equal and not in
• Perhaps we can limit the number of parameters to reduce complexity? E.G.:

1. safer to use a URI configured during the onboarding process and exclude sender_uri in the specification.
2. remove action since URL contains it.
3. timestamp can be removed as it’s in the header
4. reg_type and reg_event_type can be combined

• How should the following params be used? i.e: consent, authorize
• How is the action param not required in the sync implementation?
• The status and status_reason_code are repeated in the response header and search_response. The use of HTTP status codes would be better. The approach of not using partially succeeded responses seems optimal, as it encourages API users to retry when necessary. This means that the status and status_reason_code fields are most relevant in error responses only

[tntra-dhananjay]

Hi @euanmillar

Thanks for you feedback / suggestions,We have shared in slack channel for expert feedback.

Slack reference link - https://spdci.slack.com/archives/C05TZPXRDDJ/p1702446879331569

Request to all experts please share your thoughts.

[tntra-dhananjay]

We created separate comment for each point described in technical feedback section.

[tntra-dhananjay]

1 The documentation of some* attributes needs to be improved with examples. Consider when adding parameters to the standard, description & examples need to be mandatory.
DCI : Can you please share a list of specific attributes that need more description with examples so we can focus more on similar attributes

[tntra-dhananjay]

1 query_type - "idtype-value", "expression", "predicate"
2 query can be interpreted in different ways based on the implementation which can be both bad and good
DCI - If you want to specify any other way for query please feel free to add example so we can apply changes that example

[tntra-dhananjay]

3 attribute names need to be strictly defined in queries and in sorting
DCI - List of supported attributes solely depends on implementer , Still we can have list of attributes that we can put as suggestion. Please share list of attributes specific to CRVS so we can add in documentations

[tntra-dhananjay]

4 for known search parameters like birth_date or name, the spec can be stricter and have usage examples
DCI - We have added examples at https://api.spdci.org/release/sample-jsons/crvs.html for few process flow, please share details of more process flow so we can prepare such search request and response

[tntra-dhananjay]

5 for unknown and custom parameters, the spec can be flexible

• The querying syntax needs some refinement regarding how would we handle multiple OR/AND operation combinations.
  DCI - We shall bring this in discussion with experts, Created separate discussion forum for this

• Introduce the operators such as not equal and not in

DCI : We do not restrict to add more operator, we will add not-eq,not-in in example.

• Perhaps we can limit the number of parameters to reduce complexity? E.G.:

DCI - Implementer can decide put such restrictions

[tntra-dhananjay]

6 safer to use a URI configured during the onboarding process and exclude sender_uri in the specification.
DCI - We shall bring this in discussion with experts, Created separate discussion forum for this, As of now it gives flexibility to implementer to send/receive data on dynamic URLs
DCI - Discussion thread created - #16

[tntra-dhananjay]

7 Remove action since URL contains it.
DCI - We shall bring this in discussion with experts, Created separate discussion forum for this, The
DCI - Discussion thread created #17

[tntra-dhananjay]

8 timestamp can be removed as it’s in the header
DCI - We shall bring this in discussion with experts, Created separate discussion forum for this
DCI - Discussion thread created #18

[tntra-dhananjay]

9 reg_type and reg_event_type can be combined
DCI - The reg_type indicate registry like crvs,social etc and reg_event_type indicate birth/death/marriage or any other event that are registry specific.

[tntra-dhananjay]

10 How should the following params be used? i.e: consent, authorize
DCI - Discussion thread created #19

[tntra-dhananjay]

11 How is the action param not required in the sync implementation?
DCI - The action param is now required in sync, we created discussion thread to discuss usability of this
DCI - Discussion thread created #17

[tntra-dhananjay]

12 The status and status_reason_code are repeated in the response header and search_response. The use of HTTP status codes would be better. The approach of not using partially succeeded responses seems optimal, as it encourages API users to retry when necessary. This means that the status and status_reason_code fields are most relevant in error responses only
DCI - The status in header over all status of request while status inside search_response indicate details of individual request , The APIs are capable of accepting multiple search requests so status and status_reason_code shall be there for each request too. The status and status_reason_code value may be different for header and search_response.