Fix documentation issues by GillesInnov35 · Pull Request #91 · camaraproject/KnowYourCustomerMatch

GillesInnov35 · 2026-09-15T15:28:37Z

What type of PR is this?

Add one of the following kinds:

correction

What this PR does / why we need it:

Fix documentation issues

Documentation issues #87 Typo in POST /match endpoint description
Documentation issues #87 Example Two-Legged and Three-leg Access Token Example: needs to be renamed.
Documentation issues #87 Review inclusion error code 404 NOT_FOUND,
Documentation issues #87 Consider including and documenting the 429 errors.
Documentation issues #87 Requirement for match score to use Jaro-Winkler distance algorithm is a little bit hidden in the documentation.

Which issue(s) this PR fixes:

Fixes #87

Fix documentation issues

camara-validation · 2026-09-15T15:29:14Z

CAMARA Validation — PASS

0 errors, 0 warnings, 16 hints | Profile: standard

View full results

PedroDiez

In order to avoid working twice (i.e. to define specific error response schemas now), we are fine if this PR is scoped and merged in these terms, adding Generic 429 Error case.

Nonetheless, our view is that scenarios applicability are:
IdentifierNotFound404 - https://github.com/camaraproject/Commonalities/blob/r4.4/artifacts/common/CAMARA_common.yaml#L517
TooManyRequests429 - https://github.com/camaraproject/Commonalities/blob/r4.4/artifacts/common/CAMARA_common.yaml#L624

That align can be done later after triggering RC cycle referred to Commonalities r4.4

PedroDiez · 2026-09-15T16:04:08Z

          $ref: '#/components/responses/Generic404'
        "422":
          $ref: '#/components/responses/Generic422'
+        "429":


Think 429 case is only TOO_MANY_REQUESTS

We are fine if this topic is addressed later, after triggering RC cycle, based on Commonalities r4.4

TooManyRequests429 - https://github.com/camaraproject/Commonalities/blob/r4.4/artifacts/common/CAMARA_common.yaml#L624

@PedroDiez , I've included Common artifacts - Generic429 to be consistent with the others errors blocs. But it's ok to limit to 429-TOO_MANY_REQUESTS.

@ToshiWakayama-KDDI, WDYT ?

It is fine to use Generic429 now and set up the limitation to 429-TOO_MANY_REQUESTS, when doing alignment with Commonalities r4.4

Thanks, @GillesInnov35 , @PedroDiez .

Sorry, I don't uderstand this part fully. Generic429 is now only for 429-TOO_MANY_REQUEST, based on the Commonalities r4.4, correct?

But Line716 and after include GENERIC_429_QUOTA_EXCEEDED as well. I don't understand this. Or GENERIC_429_QUOTA_EXCEEDED has to be removed but not yet done?

BR
Toshi

What I mean @ToshiWakayama-KDDI is that the applicable 429 Error in this API is only 429-TOO_MANY_REQUEST.

Generic429 provides both TOO_MANY_REQUEST and QUOTA_EXCEEDED.

It is fine in this PR to keep as is, but when doing Aligment with Commonalities r4.4 in a future PR this error model in 429 scenario should be replaced by:

TooManyRequests429 - https://github.com/camaraproject/Commonalities/blob/r4.4/artifacts/common/CAMARA_common.yaml#L624

Hope this helps for the understading

PedroDiez · 2026-09-15T16:06:10Z

          $ref: '#/components/responses/Generic401'
        "403":
          $ref: '#/components/responses/Generic403'
        "404":


Think only applies IdentifierNotFound404 - https://github.com/camaraproject/Commonalities/blob/r4.4/artifacts/common/CAMARA_common.yaml#L517

We are fine if this topic is addressed later, after triggering RC cycle, based on Commonalities r4.4

PedroDiez

Fine to proceed now as it is and later with Commonalities r4.4 aligment make fine grained alignment.

IdentifierNotFound404 - https://github.com/camaraproject/Commonalities/blob/r4.4/artifacts/common/CAMARA_common.yaml#L517
TooManyRequests429 - https://github.com/camaraproject/Commonalities/blob/r4.4/artifacts/common/CAMARA_common.yaml#L624

@GillesInnov35, @ToshiWakayama-KDDI if you are ok

Left LGTM in advance

GillesInnov35 · 2026-09-16T12:45:46Z

thanks @PedroDiez , I'm OK with your proposal but I'm wondering if we remove NOT_FOUND from HTTP 404 error code enum it'll not be a non backward compatibility with V0.4.0.

PedroDiez · 2026-09-16T13:15:35Z

thanks @PedroDiez , I'm OK with your proposal but I'm wondering if we remove NOT_FOUND from HTTP 404 error code enum it'll not be a non backward compatibility with V0.4.0.

Hi @GillesInnov35,

We can do safely as we are going to generate a major version v1, so it can be handled in a compatible way by API Consumers

GillesInnov35 · 2026-09-18T13:27:44Z

@ToshiWakayama-KDDI , @fernandopradocabrillo , @albertoramosmonagas , concerning issues below

Requirement for match score to use Jaro-Winkler distance algorithm is a little bit hidden in the documentation.

I thought we've added somewhere a link to jaro-winkler definition but not found. Does CAMARA recommends any web site, Wikipedia or any others ? We could simply move algorithm reference higher up. I'd prefer not to modify the sentence.

a numerical value that quantifies the similarity between two pieces of text based on the words they contain. Unless otherwise captured in the implementation notes which Operators may publish, score will use the Jaro-Winkler distance algorithm for all countries, for more details https://en.wikipedia.org/wiki/Jaro-Winkler_distance. This score is often used in various applications like text comparison, plagiarism detection, information retrieval, and natural language processing.

Review inclusion error code 404 NOT_FOUND - If there is a valid use for this error code, document it.

@PedroDiez (Telefonica) proposes to remove 404 - Not Found error (Commonalities 4.4). If approved by code owners, this issue will closed.

WDYT ?

PedroDiez · 2026-09-21T11:03:53Z

@ToshiWakayama-KDDI , @fernandopradocabrillo , @albertoramosmonagas , concerning issues below

Requirement for match score to use Jaro-Winkler distance algorithm is a little bit hidden in the documentation.

I thought we've added somewhere a link to jaro-winkler definition but not found. Does CAMARA recommends any web site, Wikipedia or any others ? We could simply move algorithm reference higher up. I'd prefer not to modify the sentence.

a numerical value that quantifies the similarity between two pieces of text based on the words they contain. Unless otherwise captured in the implementation notes which Operators may publish, score will use the Jaro-Winkler distance algorithm for all countries, for more details https://en.wikipedia.org/wiki/Jaro-Winkler_distance. This score is often used in various applications like text comparison, plagiarism detection, information retrieval, and natural language processing.

Review inclusion error code 404 NOT_FOUND - If there is a valid use for this error code, document it.

@PedroDiez (Telefonica) proposes to remove 404 - Not Found error (Commonalities 4.4). If approved by code owners, this issue will closed.

WDYT ?

From TEF side:

Regarding first bullet: Think we can simply add the reference for the algorithm. In line 13 of the YAML, just add the reference indicated:

...Unless otherwise captured in the implementation notes which Operators may publish, score will use the [Jaro-Winkler](https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance) distance algorithm for all countries....

That link is a good simplification as it summarizes mathematical model and mention the canonical references (1) and (2).

Jaro (1989): "Advances in Record-Linkage Methodology as Applied to Matching the 1985 Census of Tampa, Florida" — Journal of the American Statistical Association, 84(406): 414–420.
Winkler (1990): "String Comparator Metrics and Enhanced Decision Rules in the Fellegi-Sunter Model of Record Linkage" — Proceedings, American Statistical Association.
Regarding second bullet: We would like to confirm from codeowners that IdentifierNotFound404 - https://github.com/camaraproject/Commonalities/blob/r4.4/artifacts/common/CAMARA_common.yaml#L517 is the applicable 404 case. It is not needed to cover it within this PR. Just to have track of it to apply when making Commonalities r4.4 alignment related PR.

PedroDiez

LGTM

Please @GillesInnov35, @ToshiWakayama-KDDI, are you ok with doing this in a later PR when doing Commonalities r4.4 aligment?

We would like to confirm from codeowners that IdentifierNotFound404 - https://github.com/camaraproject/Commonalities/blob/r4.4/artifacts/common/CAMARA_common.yaml#L517 is the applicable 404 case. It is not needed to cover it within this PR. Just to have track of it to apply when making Commonalities r4.4 alignment related PR.

GillesInnov35 · 2026-09-21T12:42:45Z

@PedroDiez ,

clear reference to jaro-winkler in info.descripion section: updated as proposed.
Review inclusion error code 404 NOT_FOUND: it was just to keep in mind it should be done with Commonalities 4.4 alignment if approved by all code_owners. We (Orange) approve.

GillesInnov35 · 2026-09-24T08:29:34Z

@ToshiWakayama-KDDI , @fernandopradocabrillo , could you review this PR.

@ToshiWakayama-KDDI , I think question about 404 - NOT_FOUND error removed in error section (IdentifierNotFound404 would be the applicable 404 case) might have an impact on your side.

Thanks

ToshiWakayama-KDDI · 2026-09-24T09:35:30Z

    * **KYC**: stands for Know Your Customer and it is the process of a business verifying the identity of their clients and assessing their suitability, along with the potential risks of illegal intentions towards the business relationship.

-    * **Match Score**: a numerical value that quantifies the similarity between two pieces of text based on the words they contain. This score is often used in various applications like text comparison, plagiarism detection, information retrieval, and natural language processing. The score typically reflects how well the words in one text match the words in another text. In the context of this API, this score will be used to determine how much does the input information looks like the information stored in the Operator's system. Unless otherwise captured in the implementation notes which Operators may publish, score will use the Jaro-Winkler distance algorithm for all countries. This parameter, as optional, will be returned depending on the capability of the Operator to calculate the scoring value. This means that not all Operators will implement this functionality or won't have the requested parameter available. It can happen that an Operator implements the score functionality but, for whatever reason, is not able to calculate it based on the client's input or the related stored information. For these cases, the score property related won't be returned in the response.
+    * **Match Score**: a numerical value that quantifies the similarity between two pieces of text based on the words they contain. This score is often used in various applications like text comparison, plagiarism detection, information retrieval, and natural language processing. The score typically reflects how well the words in one text match the words in another text. In the context of this API, this score will be used to determine how much does the input information looks like the information stored in the Operator's system. Unless otherwise captured in the implementation notes which Operators may publish, score will use the [Jaro-Winkler](https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance) distance algorithm for all countries. This parameter, as optional, will be returned depending on the capability of the Operator to calculate the scoring value. This means that not all Operators will implement this functionality or won't have the requested parameter available. It can happen that an Operator implements the score functionality but, for whatever reason, is not able to calculate it based on the client's input or the related stored information. For these cases, the score property related won't be returned in the response.


Thanks, @GillesInnov35 .
To make this requirement clearer, I would like to suggest making this part bold, like Unless otherwise captured ~~~ algorithm for all countries.
WDTY?

ToshiWakayama-KDDI · 2026-09-24T09:38:10Z

              $ref: '#/components/schemas/KycMatchRequestBody'
            examples:
-              Two-Legged and Three-leg Access Token Example:
+              Two-Legged Example:


Thanks, @GillesInnov35 .

To improve consistency with the descriptions in the earlier sections of the YAML (where we use the terms "using a Two-legged access token" and "using a Three-legged access token"), I would like to suggest updating the example titles as follows:

Rename "Two-Legged and Three-leg Access Token Example" to "Example when using a Two-legged access token"

Rename "Three-Legged Without Phone Number Example" to "Example when using a Three-legged access token"

This alignment will make the specification much clearer and more intuitive for API consumers. What do you think?

BR
Toshi

fernandopradocabrillo

LGTM

GillesInnov35 added 2 commits September 15, 2026 17:21

Fix Documentation issues

5cb927a

Fix documentation issues

5ae49d1

Fix documentation issues

GillesInnov35 requested review from ToshiWakayama-KDDI and fernandopradocabrillo as code owners September 15, 2026 15:28

PedroDiez reviewed Sep 15, 2026

View reviewed changes

PedroDiez approved these changes Sep 16, 2026

View reviewed changes

Update kyc-match.yaml

188f81e

PedroDiez approved these changes Sep 21, 2026

View reviewed changes

ToshiWakayama-KDDI reviewed Sep 24, 2026

View reviewed changes

GillesInnov35 added 3 commits September 24, 2026 14:14

Update kyc-match.yaml

249f7dc

Update kyc-match.yaml

0854479

Update kyc-match.yaml

ecb4216

fernandopradocabrillo approved these changes Sep 29, 2026

View reviewed changes

GillesInnov35 merged commit 21c5b4b into main Oct 2, 2026
3 checks passed

Conversation

GillesInnov35 commented Sep 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Uh oh!

camara-validation Bot commented Sep 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CAMARA Validation — PASS

Uh oh!

PedroDiez left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PedroDiez left a comment

Choose a reason for hiding this comment

Uh oh!

GillesInnov35 commented Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

PedroDiez commented Sep 16, 2026

Uh oh!

GillesInnov35 commented Sep 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

PedroDiez commented Sep 21, 2026

Uh oh!

PedroDiez left a comment

Choose a reason for hiding this comment

Uh oh!

GillesInnov35 commented Sep 21, 2026

Uh oh!

GillesInnov35 commented Sep 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fernandopradocabrillo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

GillesInnov35 commented Sep 15, 2026 •

edited

Loading

camara-validation Bot commented Sep 15, 2026 •

edited

Loading

PedroDiez left a comment •

edited

Loading

GillesInnov35 commented Sep 16, 2026 •

edited

Loading

GillesInnov35 commented Sep 18, 2026 •

edited

Loading