Release Review: NumberVerification r4.2 (public Sync26)

[camara-release-automation]

Release Review: r4.2 public

This PR finalizes the reviewable release content for the active snapshot.

Edit and review this PR before merging it into the release snapshot. After Codeowner and Release Management approval, merging this PR creates the draft release.

Release contents

API	Version	Status	Comparison target
number-verification	2.1.1	stable public	2.1.0

Dependencies: Commonalities r4.4, ICM r4.2

Codeowner Actions

Tick each box once done. Ticking the last box — "The release is ready for Release Management review" — starts the Release Management review.

• Update the CHANGELOG

  What to do:

  • Copy all API-consumer-relevant changes from the provided list into the appropriate Breaking changes / Added / Changed / Fixed / Removed sections for each API. List breaking changes both in Breaking changes and in their normal change category.
  • Do not copy administrative, tooling-only, or internal maintenance changes unless they affect API consumers.
  • For each API, fill the CHANGELOG against the stated comparison target, following the release-type rules at the top of the CHANGELOG.

• Document deferred validation warnings (and hints)

  What to do:

  • Check the CAMARA Validation comment on this PR for warnings and hints.
  • For each warning you do not fix, document it in an issue: include a copy of the validation summary line(s) and the reason the fix is deferred.
  • Document in the same way any validation hint that is applicable to the API and needs to be fixed later.
  • You may group several findings into one issue or split them across issues — either is fine.
  • List the documenting issue(s) in a comment on this PR.
  • Note: documenting deferred warnings is optional but recommended for alpha pre-releases, and mandatory for rc pre-releases and public releases.

• The release is ready for Release Management review

  Check that:

  • All mandatory release assets for the declared status(es) are present (see the table below "Required release assets per API status" by expanding the arrow);
  • API documentation and test cases are adequate for the target status.

  Tick this box to confirm readiness and to start the Release Management review.

Release Management Actions

The following actions and checks are done by a Release Management reviewer before approving the PR:

• Assign the Release Management reviewer(s) as assignee(s) of this PR
• CHANGELOG follows the release documentation rules
• Breaking changes are documented and version updates follow SemVer rules
• Mandatory release assets are present for each API according to its status
• All remaining validation warnings are documented in issues and the reasons for deferral are defensible
• Content findings needing a main PR are collected as sub-issues of one issue titled Release r4.2 review findings (see Recording review findings)

Required release assets per API status

Nr	Asset	alpha	rc	initial public	stable public
1	Release Plan	M	M	M	M
2	API Definition(s)	M	M	M	M
3	Commonalities compliance	O	M	M	M
4	API Documentation	M	M	M	M
5	User Stories	O	O	O	M
6	Test Cases (basic)	O	M	M	M
7	Test Cases (enhanced)	O	O	O	M
8	API Description	O	O	M	M

M = Mandatory, O = Optional — Full documentation

Valid next actions for codeowners

• Merge this PR when all Codeowner Actions and Release Management Actions are complete and the required approvals are present — creates the draft release
• Use /discard-snapshot <reason> in the Release Issue to discard this snapshot, return to planned, and update content on main

---

Snapshot: r4.2-f7ae538

[camara-validation]

CAMARA Validation — PASS

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

View full results

[hdamker]

CHANGELOG review for r4.2 (number-verification 2.1.1, compared to 2.1.0 / r3.2):

Correct as is

• Patch classification, release notes, dependencies (match release-metadata.yaml) and the compare/r3.2...r4.2 link.
• Breaking changes: N/A: oasdiff reports the new maxLength on phoneNumber, hashedPhoneNumber and x-correlator as breaking, but the existing patterns already limit these values to the same lengths, so nothing that was valid before is rejected now.
• fix(number-verification): correct RFC 2119 keywords and indentation in description #263 is included in Fixed, which is the only API change since r4.1.

Suggested additions

1. The Commonalities alignment is not listed in the API section. 2.1.0 was based on Commonalities 0.6; 2.1.1 is based on 0.9.0 (fix validation rc Sync26 #235, fix(number-verification): re-sync additional-error-responses description and bump commonalities to 0.9.0 #252, Align Error response to the Commonalities r4.4 catalogue #253). Generated clients and documentation will show these changes, so I suggest adding to Changed:

   * Aligned with Commonalities r4.4 (0.9.0) by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/235 and @hdamker in https://github.com/camaraproject/NumberVerification/pull/252:
     * Error responses changed to reference `BadRequest400` and `Unauthenticated401` instead of `Generic400` / `Generic401`; error examples moved to `components/examples` by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/253
     * `maxLength` added to `phoneNumber`, `hashedPhoneNumber`, `x-correlator` and the `ErrorInfo` properties (no change in accepted values)
     * Tag names changed to `Phone Number Verify` / `Phone Number Share`
     * Added the mandatory "Request body strictness" section to `info.description`
   

2. The Added entry for Access token security considerations for Number Verification API #226 uses only the PR title. The PR adds MUST-level requirements for access tokens with Number Verification scopes. I suggest stating them in the entry:

   * Added access token requirements for Number Verification scopes: tokens are single-use, refresh tokens are not issued, and expiry is at most 300 seconds by @jpengar in https://github.com/camaraproject/NumberVerification/pull/226
   

3. The entries mix imperative PR titles ("Add ...", "Refactor ...", "fix(number-verification): correct ...") with other forms. I suggest aligning all entries to past tense, e.g.:

   * Added companion whitepaper: Operator Token Acquisition for Number Verification on Android (TS.43/OpenID4VP) by @albertoramosmonagas in https://github.com/camaraproject/NumberVerification/pull/238
   * Refactored DevicePhoneNumber reference in YAML by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/249
   * Corrected Gherkin test definition defects by @hdamker in https://github.com/camaraproject/NumberVerification/pull/255
   

[bigludo7]

Thanks @hdamker for the review. Fixed as you suggested.

[hdamker]

Looks good to merge from Release Management perspective.