Updated Age Verification proposal aligned with Spring25

[fernandopradocabrillo]

What type of PR is this?

Add one of the following kinds:

• enhancement/feature

What this PR does / why we need it:

This PR include all the changes and suggestions that haven been made these past months regarding Age Verification in PR #50.
It is a clean version with errors and descriptions aligned with the latest version of Commonalities for Spring25 meta release.

Additionally, it contains a proposal to include two new fields in the response: contentLock and parentalControl. Both fields come from the feedback of our partners in the UK.

This PR is ment to replace PR #50 as it seems easier to work on a updated fresh copy.

Please leave any comments or changes you feel appropriate.

Thanks!

[GillesInnov35]

@fernandopradocabrillo, thanks for this PR and the update of errors section schema (new Commonalities version). I've started the discussion internally at Orange for the new response attributes.

Gilles

[eric-murray]

I'm happy with this, so approving. A couple of comments for you to think on:

• Linting is not enabled for this repository, so you might like to run that separately
• You might like to add some guidance around providing the birthdate information. If an API consumer really knew the date of birth of the customer, they wouldn't need to use this API! So I assume this information is useful only in that it allows us to verify the customer more quickly in case they API consumer knows the correct date of birth. But if it is incorrect, it will be ignored and other parameters used to verify the identity of the customer.

[rartych]

@fernandopradocabrillo Thanks for this consolidated PR

The latest API Design guidelines add requirements for api-name and using it in file name and servers url .
I would also take the location-verification API as the reference.
Hence I suggest to set api-name=kyc-age-verification then we get:

• filename: kyc-age-verification.yaml
• url: "{apiRoot}/kyc-age-verification/vwip"
• path: (verb)

paths:
 /verify:

• security:

   - openId:
          - kyc-age-verification:verify

• operationId - OperationIds are defined in lowerCamelCase
  verifyAge - in line with location verification

• tags - Title Case
  Age Verification

[fernandopradocabrillo]

I'm happy with this, so approving. A couple of comments for you to think on:

• Linting is not enabled for this repository, so you might like to run that separately
• You might like to add some guidance around providing the birthdate information. If an API consumer really knew the date of birth of the customer, they wouldn't need to use this API! So I assume this information is useful only in that it allows us to verify the customer more quickly in case they API consumer knows the correct date of birth. But if it is incorrect, it will be ignored and other parameters used to verify the identity of the customer.

@eric-murray Thank you for the review! I will pass the linter locally, and I'll raise a PR to include it in the repo later (after Holidays probably haha)

Regarding the birthdate, from TEF we agree... It was in the original proposal and I just left it there, but you are right, it doesn't make much sense.

wdyt about the birthdate @GillesInnov35 @ToshiWakayama-KDDI

[fernandopradocabrillo]

@fernandopradocabrillo Thanks for this consolidated PR

The latest API Design guidelines add requirements for api-name and using it in file name and servers url . I would also take the location-verification API as the reference. Hence I suggest to set api-name=kyc-age-verification then we get:

• filename: kyc-age-verification.yaml
• url: "{apiRoot}/kyc-age-verification/vwip"
• path: (verb)

paths:
 /verify:

• security:

   - openId:
          - kyc-age-verification:verify

• operationId - OperationIds are defined in lowerCamelCase
  verifyAge - in line with location verification
• tags - Title Case
  Age Verification

Thanks @rartych, I have applied the changes to align with commonalities guidelines

[HuubAppelboom]

I'm happy with this, so approving. A couple of comments for you to think on:

• Linting is not enabled for this repository, so you might like to run that separately
• You might like to add some guidance around providing the birthdate information. If an API consumer really knew the date of birth of the customer, they wouldn't need to use this API! So I assume this information is useful only in that it allows us to verify the customer more quickly in case they API consumer knows the correct date of birth. But if it is incorrect, it will be ignored and other parameters used to verify the identity of the customer.

@eric-murray Hi Eric, this birthdate information is what the use claims it to be. If it it does not match, you are sure the end user is not the contract owner, and you can not return a reasonable answer. We propose to reply with "not_available" and not provide an identityMatchScore. See also the proposal I made here: #81 (comment)

[fernandopradocabrillo]

Linter issues fixed:

[eric-murray]

@HuubAppelboom

If it it does not match, you are sure the end user is not the contract owner, and you can not return a reasonable answer.

OK. So the API also allows the API consumer to confirm whether the DoB they have been given by the customer is correct.

[HuubAppelboom]

@eric-murray Yes, the DoB is then used as a first tollgate check. If it matches, you continue to processing the other input parameters that have been provided with which you can calculate the aggregate identity match score.

[ToshiWakayama-KDDI]

@fernandopradocabrillo Thanks for this consolidated PR
The latest API Design guidelines add requirements for api-name and using it in file name and servers url . I would also take the location-verification API as the reference. Hence I suggest to set api-name=kyc-age-verification then we get:

• filename: kyc-age-verification.yaml
• url: "{apiRoot}/kyc-age-verification/vwip"
• path: (verb)

paths:
 /verify:

• security:

   - openId:
          - kyc-age-verification:verify

• operationId - OperationIds are defined in lowerCamelCase
  verifyAge - in line with location verification
• tags - Title Case
  Age Verification

Thanks @rartych, I have applied the changes to align with commonalities guidelines

Hi @fernando, @rafal, all,

Thank you for intensive review of Age Verification API.

But, from KDDI side, I cannot accept all of this kind of last minute fundamental changes. We have already started implementation work, as this API has been discussed since January and the discussion had become stable before.

From KDDI side, I would like to ask to revert url and path to the previous ones, i.e.

• url: {apiRoot}/kyc-ageverify/vwip
• path: /ageverify
• Consecurtly I would propose to change the filename to: kyc-ageverify.yaml.

I do not think the above is not against commonalities guidelines.

Sorry for the late response due to the time difference, but your understanding would be appreciated.

Best reagrds,
Toshi
KDDI

[ToshiWakayama-KDDI]

Hi all,

I am checking other changes e.g. error responses, made by European colleagues during my night. Please allow me to take some time and comments.

Best regards,
Toshi
KDDI

[fernandopradocabrillo]

Hi @fernando, @rafal, all,

Thank you for intensive review of Age Verification API.

But, from KDDI side, I cannot accept all of this kind of last minute fundamental changes. We have already started implementation work, as this API has been discussed since January and the discussion had become stable before.

From KDDI side, I would like to ask to revert url and path to the previous ones, i.e.

• url: {apiRoot}/kyc-ageverify/vwip
• path: /ageverify
• Consecurtly I would propose to change the filename to: kyc-ageverify.yaml.

I do not think the above is not against commonalities guidelines.

Sorry for the late response due to the time difference, but your understanding would be appreciated.

Best reagrds, Toshi KDDI

Hi @ToshiWakayama-KDDI,

Sorry, I think you mentioned this before. For me there is no problem in reverting to the previous name and aligning the filename.

I like this one better, but I can live with it 😄