How to handle case when the country CAMARA implementation wants to be more restrictive than CAMARA defintion

[bigludo7]

We've an interesting case in one country wanting to implement KYC Match API. The requirement here and shared by the Telco is to enforce the presence of one attribute (documentId). This attribute should not be mandatory in the CAMARA as not relevant on other country.

How we can do locally this restriction?

• Changing the cardinality in a country-specific yaml seems to me a bit too rigid
• Perhaps adding a 422 with a code specifying that documentId is mandatory for this service could be a better approach

The exemple is for this API but probably is relevant in other APIs.

Looking for guidance from the community...

[gmuratk]

This is an example where 'Runtime Restrictions' will help. Use of Capabilities and Runtime Restrictions enable an API provider to 'Mandate an optional parameter'.

For discussion's sake, let's say 'birthdate' parameter is required in one country, or one API provider would like to mandate. The restriction provided below would allow an API provider to point a CAMARA API version they support and also communicate to API Consumer that this restriction (e.g. birthdate is a required parameter) applies.

(Runtime Restriction - Partial Example)

"KYCRequiredParameter": {
 ...
	"context": [
		{
			"operationIds": [
				"https://raw.githubusercontent.com/camaraproject/KnowYourCustomer/refs/heads/main/code/API_definitions/kyc-match.yaml/~1match/operationId"
			]
		}
	],
	"subjects": [
		"https://raw.githubusercontent.com/camaraproject/KnowYourCustomer/refs/heads/main/code/API_definitions/kyc-match.yaml#/paths/~1match/post/requestBody/content/application~1json/schema/KYC_MatchRequestBody/properties/birthdate"
	],
	"restrictions": [
		{
			"rrType": "ParameterRestriction",
			"mandatory_rr": true
		}
	]
...
}

cc @lbertz02

[bigludo7]

Thanks @gmuratk
Got it ! this API will allow consumer to know specific rules before using other APIs.

Suppose, in Runtime Restriction API you have defined the birthdate as mandatory in CAMARA API xyz. Additionally ...

• Do you craft a specific yaml for API xyz with this birthdate mandatory?
• Do you keep the xyz yaml as it is in CAMARA but add a 4xx error if birthdate is missing?
• Other mechanism?

[lbertz02]

You leave xyz YAML as is - no change.

The example above is actually a json document and not yaml. You don't create new YAML but send json based on the runtime restrictions yaml. This avoids any sort of recompilation when a rule is added/removed and allows for dynamic rule instances.

As for the error code, in the xyz YAML itself you would add the appropriate error code. Given the rules can be dynamic something in the 4xx seems the most appropriate in this situation.

[bigludo7]

Thanks @lbertz02

[fernandopradocabrillo]

Hi @bigludo7!
I think this is an interesting topic to discuss that may apply to more scenarios, for example more restrictive validations regarding phone number validations. But, at least for this one, I think it is easy to solve it with spec documentation.

If you are referring to the requirement of the idDocument as part of the match process, in v0.2 we have included guidelines on how to use it if it is relevant in the country: https://github.com/camaraproject/KnowYourCustomer/blob/main/code/API_definitions/kyc-match.yaml#L78
It is not required per se, only if the operator decides it.

On the other hand, if the issue here is that it makes no sense for the operator to allow the client to even send the property in first place because is not relevant in the country, I agree, but the design of KYC allows the operator to return a "not_available" if this is the case. It happens to us also for japanese specific properties, we simply return not_available.

[bigludo7]

Thanks @fernandopradocabrillo
Look good for me.