Align geofencing-subscriptions 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 geofencing-subscriptions.yaml still declares x-camara-commonalities: 0.8.0 and still follows r4.3 patterns. This issue collects the points that need to be addressed to bring geofencing-subscriptions to Commonalities 0.9.0 (r4.4).

Note that CI validation is currently green except for one P-027 warning, the S-211 findings restated below, and the G-004 scenario count and S-313 hints already deferred in #422. 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.

This is the only explicit subscription API in the repository, so the r4.4 changes aimed at subscriptions all land here: the Config → ConfigBase refactor (camaraproject/Commonalities#670), the common Sink schema (#646), SinkGone410, and the deprecation of CreateSubscriptionUnprocessableEntity422. location-retrieval and location-verification are aligned separately in #434, which carries no contract change at all — this issue is separated from it because it contains the two widenings below.

This issue also absorbs the geofencing-subscriptions half of #433, which is closed as superseded by this issue and #434.

Expected behavior

Two items widen a documented error-code set by one code each, marked Breaking below — adding a new response code to an existing operation is a breaking change under Design Guide §7.4. Both are permitted because this API is still at Initial status (0.y.z): the last public version is 0.5.0 (r3.2) and 0.6.0 has so far shipped only as 0.6.0-rc.1 in the r4.1 pre-release. Each needs an explicit breaking-change callout in the release CHANGELOG, not just an ### Added bullet.

Where a catalogue response's code set is a superset of the local one and the extra codes are reachable, the common response is referenced rather than a narrower local copy being kept. Where it is a subset and the omitted codes cannot occur, the narrower catalogue response is referenced, following the r4.4 subscription template.

Metadata and documentation

• Set x-camara-commonalities: 0.9.0 (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. 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, and delete the local definition in each case: Generic400 → BadRequest400 (list operation and notification callback, where OUT_OF_RANGE cannot occur), Generic401 → Unauthenticated401, local Generic403 → PermissionDenied403, local Generic404 → the common NotFound404, local Generic410 in the notification callback → CAMARA_event_common.yaml#/components/responses/SinkGone410, and local SubscriptionIdRequired → CAMARA_event_common.yaml#/components/responses/SubscriptionIdRequired400. Reference the common SubscriptionPermissionDenied403 directly and delete the local pass-through alias.
• Keep the create-subscription 429 local as TooManyRequestsWithQuota429. It declares both TOO_MANY_REQUESTS and QUOTA_EXCEEDED; the catalogue's TooManyRequests429 declares only the former. The notification callback references TooManyRequests429, as QUOTA_EXCEEDED is not meaningful for the listener.

Together with the two items below, this reduces the spec from ten locally defined error responses to two.

Subscription error responses

• Rename the local CreateSubscriptionUnprocessableEntity422. That is the exact name r4.4 deprecated in CAMARA_event_common.yaml, so as it stands a reader cannot tell whether the spec uses the deprecated common response. Suggested: CreateGeofencingSubscriptionDevice422, echoing the common CreateSubscriptionDevice422 that it is a superset of. It has one definition site and one use-site, and no .feature file references it.
• Breaking. Add MULTIEVENT_COMBINATION_TEMPORARILY_NOT_SUPPORTED to that response — the one code of common CreateSubscriptionDevice422's seven that it currently lacks. The local response then reads as exactly common's seven plus the two GEOFENCING_SUBSCRIPTIONS.* codes, which is what makes keeping it local reviewable. The code cannot occur while types has maxItems: 1, the same as the already declared MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED. Relaxing maxItems later is non-breaking, adding the code later is not — declaring both now, at Initial status, keeps a future multi-event extension non-breaking.
• Breaking. Replace the local CreateSubscriptionBadRequest400 with the common CAMARA_event_common.yaml#/components/responses/CreateSubscriptionBadRequest400, deleting the local definition. The local one declares five of the common response's six codes, lacking only OUT_OF_RANGE — which is reachable, since subscriptionMaxEvents is bounded 1..1000000 and radius and subscriptionExpireTime are range-constrained.

Subscription schemas

• Extend the common ConfigBase instead of hand-rolling it. r4.4 replaced the common Config with ConfigBase — no subscriptionDetail, no initialEvent — and deleted the common CreateSubscriptionDetail placeholder (Refactor configuration schema in CAMARA_event_common.yaml  Commonalities#670); API projects define a local Config extending ConfigBase via allOf. The local Config here is currently a private copy of what ConfigBase now is, so it becomes allOf: [ConfigBase, {initialEvent}], with ConfigRequest and ConfigResponse keeping their existing allOf on it unchanged — which keeps initialEvent declared once and preserves the request/response split that exists to carry Device versus DeviceResponse in subscriptionDetail.
• Move the note about an initialEvent-triggered event counting towards subscriptionMaxEvents onto initialEvent's own description. It currently sits on the local subscriptionMaxEvents description, which ConfigBase now owns. This is where both the r4.4 template artifacts/api-templates/sample-service-subscriptions.yaml and the already-aligned device-reachability-status-subscriptions.yaml put API-specific initialEvent prose, and it avoids re-declaring subscriptionMaxEvents in the second allOf branch just to preserve a sentence.
• Reference the new common CAMARA_event_common.yaml#/components/schemas/Sink (Define common Sink schema to be used by API templates Commonalities#646) from both sites that inline the sink string today — in SubscriptionRequest and in HTTPSubscriptionResponse. Both are constraint-identical to the common schema.
• Delete the local ErrorInfo pass-through alias and reference CAMARA_common.yaml#/components/schemas/ErrorInfo directly from the responses that remain local. This matches fix(geofencing-subscriptions): drop duplicate local x-correlator header/parameter #424 and the other two specs in this repository, which already reference the common schema with no local wrapper.

Error examples — use the new shared example pools

r4.4 adds a components/examples section to both common files. Every error response in the spec currently carries inline examples.

• Reference the common examples from the three responses that stay local. Generic codes come from CAMARA_common.yaml; the subscription-specific ones (SUBSCRIPTION_MISMATCH, the multievent codes, PRIVATE_KEY_JWT_NOT_CONFIGURED) from CAMARA_event_common.yaml.
• 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. The spec uses the unsuffixed names today.
• Keep inline only the GEOFENCING_SUBSCRIPTIONS.AREA_NOT_COVERED and .INVALID_AREA examples, which have no common equivalent.

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 4 unused schema components. 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 PhoneNumber (line 602), NetworkAccessIdentifier (605), Port (608) and DeviceIpv6Address (611). 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.

Test definitions

• Normalise the OAS pointers in geofencing-subscriptions.feature to the #/ prefix used by the r4.4 test template (Normalize artifact line endings and Gherkin formatting Commonalities#678, #683). The file currently mixes #/components/schemas/X and /components/schemas/X.

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

Alternative solution

One r4.4 change is deliberately not proposed here: pagination on retrieveGeofencingSubscriptionList. It is optional in r4.4, and §7.4 classifies a change requiring new client behaviour such as pagination as breaking, so the unpaginated maxItems: 20 array stays as it is.

Additional context

Verified as requiring no change: the new 53-bit numeric bound (the largest value in the 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 sinkCredential model alignment (camaraproject/Commonalities#656 — sinkCredential appears in the subscription request only, already resolved by #638); INVALID_TOKEN in the subscription 400 (already declared); the CreateSubscriptionDetail removal (the spec defines its own SubscriptionDetailRequest / SubscriptionDetailResponse and never referenced the common placeholder); the new CreateSubscriptionConflict409 (no 409 is declared today, so adding one would be an enhancement rather than an alignment item); the new common Date and SingleIpv6Address schemas and the common Pagination schema (none referenced); and x-correlator, already supported since #424.

The G-004 scenario count and the S-313 hints remain deferred in #422 and are not addressed here.

Predecessor for the r4.3 sync: #408.