Align location-retrieval and location-verification with Commonalities r4.4

[hdamker]

Problem description

release-plan.yaml declares commonalities_release: r4.4 for release r4.2, and the r4.4 common files are now in code/common/ (#431), but location-retrieval.yaml and location-verification.yaml still declare x-camara-commonalities: 0.8.0 and still follow r4.3 patterns. This issue collects the points that need to be addressed to bring both APIs to Commonalities 0.9.0 (r4.4).

Note that CI validation is currently green except for two P-027 warnings and the S-211 findings restated below. Most of the items below are not covered by any validation rule — they come from the r4.4 changelog and Design Guide — so a passing pipeline should not be read as r4.4 alignment.

geofencing-subscriptions is aligned separately in #435. It is an explicit subscription API, so it carries the r4.4 subscription changes — the Config → ConfigBase refactor, the common Sink schema, SinkGone410 — plus two error-code widenings, none of which apply here. Splitting on that boundary keeps this issue free of any contract change.

This issue also absorbs the location-retrieval half of #433, which is closed as superseded by this issue and #435.

Expected behavior

No declared error-code set changes. Every response migration below is an exact-code-set $ref swap, verified against the r4.4 CAMARA_common.yaml.

Metadata and documentation

• Set x-camara-commonalities: 0.9.0 in both specs (r4.4 VERSION.yaml is 0.9.0).
• Re-copy the additional-error-responses mandatory info.description block from code/common/info-description-templates.yaml into both specs. This is the P-027 warning. Paragraph 3 changed in Fix stale API Readiness Checklist pointer in mandatory error-response template Commonalities#693: the sentence "The applicable Commonalities Release can be identified in the API Readiness Checklist document associated to this API version." becomes "The applicable Commonalities Release can be identified from the x-camara-commonalities field, the changelog and the metadata of the released API version." Re-copying also picks up the blank line added after each BEGIN marker in fix: add spacing after info.description markers Commonalities#660.

Error responses — migrate off the deprecated Generic<status> responses

r4.4 deprecates all Generic<status> responses in favour of a minimal named catalogue plus a shared example pool, and plans their removal next cycle (camaraproject/Commonalities#665).

• Replace with the catalogue entry where the code set is identical — the same four in both specs: Generic400 → BadRequestWithRange400 (INVALID_ARGUMENT, OUT_OF_RANGE), Generic401 → Unauthenticated401 (UNAUTHENTICATED), the local Generic403 → PermissionDenied403 (PERMISSION_DENIED), and the local RetrieveLocationNotFound404 / VerifyLocationNotFound404 → the common IdentifierNotFound404 (IDENTIFIER_NOT_FOUND). Delete the local definitions.
• Keep RetrieveLocationUnprocessableEntity422 and VerifyLocationUnprocessableEntity422 local. Each adds API-specific codes that no common response carries — LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE, .UNABLE_TO_FULFILL_MAX_SURFACE and .UNABLE_TO_LOCATE in the former.

Neither spec declares a 429, so there is nothing to migrate there.

Error examples — use the new shared example pool

r4.4 adds a components/examples section to CAMARA_common.yaml. After the migration above, the 422 is the only response still defined locally in each spec.

• Reference the common examples from both 422s for their generic codes, keeping inline only the API-specific LOCATION_RETRIEVAL.* codes, which have no common example.
• Note that three example names changed in r4.4, which suffixes the identifier examples with the subject type: GENERIC_422_MISSING_IDENTIFIER_DEVICE, GENERIC_422_UNSUPPORTED_IDENTIFIER_DEVICE and GENERIC_422_UNNECESSARY_IDENTIFIER_DEVICE. Both specs use the unsuffixed names today.

The pool examples carry description but no summary, and a $ref replaces the whole example object, so the local summary: lines are dropped. That is the shape Commonalities designed, not an accidental loss.

Unused schema components (S-211, from #433)

CAMARA Validation flags 8 unused schema components in location-retrieval.yaml. These are local pass-through aliases (SchemaName: {$ref: '../common/CAMARA_common.yaml#/components/schemas/SchemaName'}) left over from the Commonalities r4.3 sync (#408) that nothing in the spec references — all real use sites point directly at CAMARA_common.yaml, not at the local alias.

• Remove Device (line 251), AreaType (260), Circle (263), Polygon (266), PointList (269), Point (272), Latitude (275) and Longitude (278). Same cleanup already done for the other unused aliases in this file by fix(geofencing-subscriptions): resolve S-015 and S-211 validation warnings #417 and fix(geofencing-subscriptions): resolve remaining S-015 and S-211 warnings #420 — this list is what those two PRs missed.

DeviceResponse and Area are aliases in the same block but are referenced locally, which is why S-211 does not flag them; both stay. location-verification.yaml has no S-211 findings.

Test definitions

• Normalise the OAS pointers in location-retrieval.feature and location-verification.feature to the #/ prefix used by the r4.4 test template (Normalize artifact line endings and Gherkin formatting Commonalities#678, #683). Both currently mix #/components/schemas/X and /components/schemas/X.

No .feature file references any component deleted above, so no other test change is required.

Additional context

Verified as requiring no change for these two specs: the new 53-bit numeric bound (the largest value in either spec is 2147483647); the Design Guide and ICM documentation link bumps (no r4.3 or r3.3 links present); the removal of INVALID_TOKEN_CONTEXT from Generic403 and of CONFLICT from Generic409 (neither code appears); the Config → ConfigBase refactor, the new common Sink schema and the CreateSubscriptionDetail removal (neither spec is a subscription API); the new common Date and SingleIpv6Address schemas and the common Pagination schema (none referenced); and x-correlator, already supported in both specs.

Predecessor for the r4.3 sync: #408.