fix validation rc Sync26 by jlurien · Pull Request #408 · camaraproject/DeviceLocation

jlurien · 2026-06-11T15:58:19Z

What type of PR is this?

enhancement/feature

What this PR does / why we need it:

Adapts the three DeviceLocation APIs to CAMARA Commonalities r4.3 / 0.8.0 (Sync26), aligning schemas, responses, parameters and info.description structure with CAMARA_common.yaml and CAMARA_event_common.yaml.

location-verification.yaml

Added mandatory info.description  markers (authorization-and-authentication, identifying-device-from-access-token, additional-error-responses, request-body-strictness)
Replaced local schemas with $ref to CAMARA_common.yaml: Device, DeviceResponse, PhoneNumber, NetworkAccessIdentifier, DeviceIpv4Addr, SingleIpv4Addr, Port, DeviceIpv6Address, Point, Latitude, Longitude, ErrorInfo
Replaced Generic400 and Generic401 local responses with $ref to CAMARA_common.yaml
Updated ErrorInfo refs in Generic403, VerifyLocationNotFound404, VerifyLocationUnprocessableEntity422
Fixed validation warnings: MaxAge (format: int32, maximum: 2147483647), MatchRate (format: int32), LastLocationTime (maxLength: 64), tag Title Case
Deleted obsolete location-verification-API-Readiness-Checklist.md (P-032)

location-retrieval.yaml

Added mandatory info.description BEGIN/END markers and request-body-strictness section; x-camara-commonalities: 0.8.0
Replaced local x-correlator parameter/header/XCorrelator schema with $ref to CAMARA_common.yaml
Replaced local schemas with $ref to CAMARA_common.yaml: full Device chain + Area chain (Circle, Polygon, PointList, Point, Latitude, Longitude), ErrorInfo
Replaced Generic400 and Generic401 local responses with $ref to CAMARA_common.yaml
Fixed validation warnings: maxAge/maxSurface (format: int32, maximum: 2147483647), LastLocationTime (maxLength: 64), tag Title Case
Deleted obsolete location-retrieval-API-Readiness-Checklist.md (P-032)

geofencing-subscriptions.yaml

Added mandatory info.description BEGIN/END markers and request-body-strictness section; x-camara-commonalities: 0.8.0
Replaced notificationsBearerAuth with $ref to CAMARA_event_common.yaml
Replaced local x-correlator parameter/header/XCorrelator schema with $ref to CAMARA_common.yaml
Replaced local schemas with $ref to CAMARA_common.yaml: full Device chain, Point, Latitude, Longitude, ErrorInfo
Replaced local schemas with $ref to CAMARA_event_common.yaml: CloudEvent (P-020 allOf pattern with discriminator), Source, SubscriptionId, SinkCredential, AccessTokenCredential, PrivateKeyJWTCredential, HTTPSettings, InitiationReason, UpdateReason
Replaced Protocol with $ref to CAMARA_event_common.yaml (HTTP-only); removed MQTT3/5, AMQP, NATS, KAFKA schemas and related Request/Response/Settings schemas
Replaced Generic400 and Generic401 local responses with $ref to CAMARA_common.yaml
Added maxItems: 20 to GET /subscriptions 200 response array (S-309)
Fixed validation warnings: Config.subscriptionMaxEvents (format: int32, maximum: 1000000), Config.subscriptionExpireTime (maxLength: 64), sink (maxLength: 2048), Subscription.id (maxLength: 256), startsAt/expiresAt (maxLength: 64), SubscriptionStarted/Updated/Ended description fields (maxLength: 512), ConfigRequest/ConfigResponse top-level description, HTTPSubscriptionRequest/Response description, tag Title Case
Deleted obsolete geofencing-subscriptions-API-Readiness-Checklist.md (P-032)

Which issue(s) this PR fixes:

Fixes #409
Fixes #410
Fixes #411

Special notes for reviewers:

All changes are non-breaking (minor version bump target: 3.1 for location-verification, minor updates for location-retrieval and geofencing-subscriptions). Schema substitutions use $ref pointing to ../common/CAMARA_common.yaml and ../common/CAMARA_event_common.yaml (Commonalities r4.3 / 0.8.0).

Pay special attention to the new limits, some may be arbitrary

location-verification.yaml

Property	Constraint added	Rationale
`MaxAge`	`format: int32`, `maximum: 2147483647`	S-310/S-311: integer fields must declare format; maximum = INT32_MAX for consistency with the declared type
`MatchRate`	`format: int32`	S-310/S-311
`LastLocationTime`	`maxLength: 64`	Aligned with `DateTime` schema in `CAMARA_common.yaml` (`maxLength: 64`)

location-retrieval.yaml

Property	Constraint added	Rationale
`RetrievalLocationRequest.maxAge`	`format: int32`, `maximum: 2147483647`	S-310/S-311; maximum = INT32_MAX
`RetrievalLocationRequest.maxSurface`	`format: int32`, `maximum: 2147483647`	S-310/S-311; maximum = INT32_MAX
`LastLocationTime`	`maxLength: 64`	Aligned with `DateTime` schema in `CAMARA_common.yaml`

geofencing-subscriptions.yaml

Property	Constraint added	Rationale
GET /subscriptions response array	`maxItems: 20`	S-309: arrays must declare `maxItems`
`SubscriptionRequest.sink` / `Subscription.sink`	`maxLength: 2048`	Aligned with `Source` schema in `CAMARA_event_common.yaml` (`maxLength: 2048`), standard URI length convention
`Config.subscriptionExpireTime`	`maxLength: 64`	Taken from `Config.subscriptionExpireTime` in `CAMARA_event_common.yaml` (= `DateTime` in `CAMARA_common.yaml`)
`Config.subscriptionMaxEvents`	`format: int32`, `maximum: 1000000`	Taken from `Config.subscriptionMaxEvents` in `CAMARA_event_common.yaml`
`Subscription.id`	`maxLength: 256`	Aligned with `SubscriptionId` schema in `CAMARA_event_common.yaml` (`maxLength: 256`)
`Subscription.startsAt` / `expiresAt`	`maxLength: 64`	`date-time` fields aligned with `DateTime` schema in `CAMARA_common.yaml`
`SubscriptionStarted.initiationDescription`	`maxLength: 512`	S-312: string fields must declare `maxLength`; 512 chosen as reasonable upper bound for free-text description fields
`SubscriptionUpdated.updateDescription`	`maxLength: 512`	S-312, same rationale
`SubscriptionEnded.terminationDescription`	`maxLength: 512`	S-312, same rationale

Changelog input

release-note: Sync all three DeviceLocation APIs (location-verification, location-retrieval, geofencing-subscriptions) with CAMARA Commonalities r4.3 / 0.8.0 (Sync26): align schemas, responses, parameters and info.description mandatory markers

Additional documentation

This section can be blank.

docs

…with \ to CAMARA_common - Replace Generic400 and Generic401 responses with direct \ to CAMARA_common - Replace ErrorInfo refs in Generic403, VerifyLocationNotFound404, VerifyLocationUnprocessableEntity422 - Remove local schemas Device, DeviceResponse, PhoneNumber, NetworkAccessIdentifier, DeviceIpv4Addr, SingleIpv4Addr, Port, DeviceIpv6Address, Point, Latitude, Longitude, ErrorInfo - Update internal refs to point to ../common/CAMARA_common.yaml for all substituted schemas

camara-validation · 2026-06-11T15:59:13Z

CAMARA Validation — PASS

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

View full results

… S-312, S-021, P-032 - MaxAge: add format int32, maximum 2147483647 (S-310, S-311) - MatchRate: add format int32 (S-310) - LastLocationTime: add maxLength 64 (S-312) - Tag name: 'Location verification' -> 'Location Verification' (S-021) - Remove location-verification-API-Readiness-Checklist.md (P-032)

- Add BEGIN/END markers for mandatory info.description templates (P-026) - Add missing request-body-strictness template section - Update x-camara-commonalities: tbd -> 0.8.0 - Replace local x-correlator parameter, header and XCorrelator schema with \ to CAMARA_common - Replace Device chain schemas (Device, DeviceResponse, PhoneNumber, NetworkAccessIdentifier, DeviceIpv4Addr, SingleIpv4Addr, Port, DeviceIpv6Address) with \ to CAMARA_common - Replace Area chain schemas (Area, AreaType, Circle, Polygon, PointList, Point, Latitude, Longitude) with \ to CAMARA_common - Remove local ErrorInfo schema; update refs in all responses to CAMARA_common - Replace Generic400 and Generic401 responses with direct \ to CAMARA_common (Opcion A: includes OUT_OF_RANGE) - maxAge/maxSurface: add format int32, maximum 2147483647 (S-310, S-311) - LastLocationTime: add maxLength 64 (S-312) - Tag name: 'Location retrieval' -> 'Location Retrieval' (S-021) - Remove location-retrieval-API-Readiness-Checklist.md (P-032)

…ne merge)

…event_common r4.3 - Add mandatory info.description BEGIN/END markers (authorization-and-authentication, identifying-device-from-access-token, additional-error-responses, request-body-strictness) - Update x-camara-commonalities: tbd -> 0.8.0 - notificationsBearerAuth: local -> \ to CAMARA_event_common (resolves S-011 description) - XCorrelator schema -> \ to CAMARA_common (resolves S-011 + S-312) - Device chain schemas (Device, PhoneNumber, NetworkAccessIdentifier, DeviceIpv4Addr, SingleIpv4Addr, Port, DeviceIpv6Address, DeviceResponse) -> \ to CAMARA_common - Point, Latitude, Longitude -> \ to CAMARA_common - CloudEvent: local -> allOf [\ CAMARA_event_common] with discriminator (P-020) - Source, DateTime -> \ to CAMARA_event_common / CAMARA_common - SubscriptionId, SinkCredential, AccessTokenCredential, PrivateKeyJWTCredential, HTTPSettings -> \ to CAMARA_event_common (resolves S-312) - InitiationReason, UpdateReason -> \ to CAMARA_event_common - ErrorInfo -> \ to CAMARA_common - Generic400, Generic401 -> \ to CAMARA_common (resolves S-309 for common responses) - Add maxItems: 20 to GET /subscriptions 200 array (resolves S-309) - Config.subscriptionExpireTime: add maxLength: 64 - Config.subscriptionMaxEvents: add format: int32, maximum: 1000000 - SubscriptionRequest.sink: add maxLength: 2048 - Subscription.id: add maxLength: 256 - MQTTSettings: add maxLength, format int32, min/max, descriptions - AMQPSettings: add maxLength, descriptions - ApacheKafkaSettings: add maxLength, format int32, min/max, descriptions - NATSSettings: add maxLength, description - SubscriptionStarted/Updated/Ended description fields: add maxLength: 512 - Tag: 'Geofencing subscriptions' -> 'Geofencing Subscriptions' (Title Case)

…common (HTTP-only) - Protocol: local enum -> \ to CAMARA_event_common (HTTP only, MQTT/AMQP/NATS/KAFKA commented as future) - SubscriptionRequest discriminator: remove MQTT3/MQTT5/AMQP/NATS/KAFKA mappings, keep HTTP only - Subscription discriminator: same, keep HTTP only - Remove schemas: MQTTSubscriptionRequest/Response, MQTTSettings, AMQPSubscriptionRequest/Response, AMQPSettings, ApacheKafkaSubscriptionRequest/Response, ApacheKafkaSettings, NATSSubscriptionRequest/Response, NATSSettings

- ConfigRequest/ConfigResponse: move description to top-level schema (S-011) - HTTPSubscriptionRequest/Response: add top-level description (S-011) - Subscription.sink: add maxLength: 2048 (S-312) - Subscription.startsAt/expiresAt: add maxLength: 64 (S-312) - Delete geofencing-subscriptions-API-Readiness-Checklist.md (P-032)

- geofencing-subscriptions.yaml: 'API root' -> standard text - location-retrieval.yaml: 'API root' -> standard text

bigludo7

Thanks @jlurien
LGTM
I need to understand how to generate the complete yaml as when I copy/paste the file on my favorite yaml editor I'm not able to have the full yaml but only ref. Trickiest to validate.

maxl2287 · 2026-06-29T19:24:32Z

Thanks @jlurien LGTM I need to understand how to generate the complete yaml as when I copy/paste the file on my favorite yaml editor I'm not able to have the full yaml but only ref. Trickiest to validate.

@bigludo7 I am able to do so:

Using IntelliJ and providing the Common.yaml as well ends up in:

Showing me the correct YAML including references
Complete Code-Generation

I was surprised that this is working that good! :D

jlurien added 5 commits June 11, 2026 18:02

Update location-verification.yaml

5b95ed3

Update location-verification.yaml

c14556c

fix(location-retrieval): fix YAML syntax error in securitySchemes (li…

7e1b2dd

…ne merge)

jlurien changed the title ~~location-verification rc Sync26~~ fix validation rc Sync26 Jun 11, 2026

jlurien added 3 commits June 11, 2026 20:27

jlurien marked this pull request as ready for review June 12, 2026 08:01

jlurien requested review from bigludo7 and maxl2287 as code owners June 12, 2026 08:01

fix: update apiRoot description to standard CAMARA text (S-023)

d2ca6e1

- geofencing-subscriptions.yaml: 'API root' -> standard text - location-retrieval.yaml: 'API root' -> standard text

bigludo7 approved these changes Jun 16, 2026

View reviewed changes

maxl2287 approved these changes Jun 29, 2026

View reviewed changes

jlurien merged commit 0c73334 into main Jun 30, 2026
3 checks passed

Navigation Menu

Repository navigation

fix validation rc Sync26 - #408

fix validation rc Sync26#408
jlurien merged 10 commits into
mainfrom
sync-location-verification-common-r4.3

jlurien commented Jun 11, 2026 •

edited

Loading

Uh oh!

camara-validation Bot commented Jun 11, 2026 •

edited

Loading

Uh oh!

bigludo7 left a comment

Uh oh!

maxl2287 commented Jun 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

jlurien commented Jun 11, 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:

Special notes for reviewers:

location-verification.yaml

location-retrieval.yaml

geofencing-subscriptions.yaml

Changelog input

Additional documentation

Uh oh!

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

Uh oh!

CAMARA Validation — PASS

Uh oh!

bigludo7 left a comment

Choose a reason for hiding this comment

Uh oh!

maxl2287 commented Jun 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jlurien commented Jun 11, 2026 •

edited

Loading

camara-validation Bot commented Jun 11, 2026 •

edited

Loading