Merge pull request #374 from camaraproject/create-public-r3.2

bigludo7 · web-flow · commit bc17ceeb4ee3 · 2025-09-16T13:39:46.000+02:00
Create public r3.2 (M4 Fall25)
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,8 +2,9 @@
 
 ## Table of Contents
 
+- **[r3.2](#r32) (Fall25 public release)**
 - [r3.1](#r31)
-- **[r2.2](#r21) (Spring25 public release)**
+- **[r2.2](#r22) (Spring25 public release)**
 - [r2.1](#r21)
 - **[r1.2](#r12) (Fall24 public release)**
 - [r1.1](#r11)
@@ -19,6 +20,112 @@ The below sections record the changes for each API version in each release as fo
 * for subsequent release-candidate(s), only the delta to the previous release-candidate
 * for a public release, the consolidated changes since the previous public release
 
+# r3.2
+
+This **public release** contains the definition and documentation of
+* location-verification v3.0.0
+* location-retrieval v0.5.0
+* geofencing-subscriptions v0.5.0
+
+The API definition(s) are based on
+* Commonalities r3.3
+* Identity and Consent Management r3.3
+
+## location-verification v3.0.0
+
+location-verification v3.0.0 is the public release for the next stable version of the API Location Verification.
+
+**There is breaking change compared to the previous release r2.2**, due to the deprecation of `UNKNOWN` value for `verificationResult` in favor of the new error `422 LOCATION_VERIFICATION.UNABLE_TO_LOCATE`.
+
+* API definition with **inline documentation**:
+
+  - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r3.2/code/API_definitions/location-verification.yaml&nocors)
+  - [View it on Swagger Editor](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r3.2/code/API_definitions/location-verification.yaml)
+  - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceLocation/blob/r3.2/code/API_definitions/location-verification.yaml)
+
+### Added
+
+* New error code `422 LOCATION_VERIFICATION.UNABLE_TO_LOCATE`.
+* New `DeviceResponse` object in responses limited to one identifier.
+* Clarifications on non-documented error responses.
+
+### Changed
+
+* Updated string pattern for `x-correlator`headers.
+* Type of `radius` for CIRCLE Area changed from `integer` to `number`, and maximum removed.
+* Clarified format for properties with format `date-time`.
+
+### Removed
+
+* `verificationResult: UNKNOWN` for 200 responses.
+* Error `422 IDENTIFIER_MISMATCH`.
+* Error `401 AUTHENTICATION_REQUIRED`.
+
+## location-retrieval v0.5.0
+
+location-retrieval v0.5.0 is the public release for the next initial version of the API Location Retrieval. It introduces breaking changes compared to the previous release r2.2, due to the deprecation of error `404 LOCATION_RETRIEVAL.DEVICE_NOT_FOUND` in favor of the new error `422 LOCATION_RETRIEVAL.UNABLE_TO_LOCATE`.
+
+* API definition with **inline documentation**:
+
+  - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r3.2/code/API_definitions/location-retrieval.yaml&nocors)
+  - [View it on Swagger Editor](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r3.2/code/API_definitions/location-retrieval.yaml)
+  - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceLocation/blob/r3.2/code/API_definitions/location-retrieval.yaml)
+
+### Added
+
+* New error `422 LOCATION_RETRIEVAL.UNABLE_TO_LOCATE`.
+* New `DeviceResponse` object in responses limited to one identifier.
+* Clarifications on non-documented error responses.
+
+### Changed
+
+* Updated string pattern for `x-correlator`headers.
+* Clarified format for properties with format `date-time`.
+
+### Removed
+
+* Error `404 LOCATION_RETRIEVAL.DEVICE_NOT_FOUND`.
+* Error `422 IDENTIFIER_MISMATCH`.
+* Error `401 AUTHENTICATION_REQUIRED`.
+
+## geofencing-subscriptions v0.5.0
+
+geofencing-subscriptions v0.5.0 is the public release for the next initial version of the API Geofencing Subscriptions. It introduces breaking changes compared to the previous release r2.2, coming from the alignment to the new guidelines in Commonalities for APIs with subscriptions.
+
+* API definition with **inline documentation**:
+
+  - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r3.2/code/API_definitions/geofencing-subscriptions.yaml&nocors)
+  - [View it on Swagger Editor](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r3.2/code/API_definitions/geofencing-subscriptions.yaml)
+  - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceLocation/blob/r3.2/code/API_definitions/geofencing-subscriptions.yaml)
+
+### Added
+
+* New subscription event types for `subscription-started` and `subscription-updated`.
+* New `DeviceResponse` object in responses and events, limited to one identifier.
+* Pattern to property `sink` and new error `400 INVALID_SINK`.
+* Clarifications on non-documented error responses.
+
+### Changed
+
+* Subscription event type `subscription-ends` renamed to `subscription-ended`.
+* Property `id` becomes required for `SubscriptionAsync` objects.
+* operationId `createSubscription` renamed to `createGeofencingSubscription`.
+* Updated string pattern for `x-correlator`headers.
+* Type of `radius` for CIRCLE Area changed from `integer` to `number`, and maximum removed.
+* Clarified format for properties with format `date-time`.
+
+### Fixed
+
+* Subscription types array items must be limited to allowed `SubscriptionEventType` values
+
+### Removed
+
+* Error `422 IDENTIFIER_MISMATCH`.
+* Error `401 AUTHENTICATION_REQUIRED`.
+
+**Changelog since r2.2**
+* Full Changelog with the list of PRs and contributors: https://github.com/camaraproject/DeviceLocation/compare/r2.2...r3.2
+
 # r3.1
 
 ## Release Notes
@@ -117,6 +224,7 @@ geofencing-subscriptions v0.5.0-rc.1 is the first release candidate for the next
 * Error `422 IDENTIFIER_MISMATCH`.
 * Error `401 AUTHENTICATION_REQUIRED`.
 
+
 # r2.2
 
 ## Release Notes
@@ -586,3 +694,4 @@ The API definition(s) are based on
 
 * New API `location`, v0.1.0, with a single operation for location verification:
     - Given a device identified by the `ueId` object, a set of coordinates (`latitude` and `longitude`), and the requested `accuracy`, returns a boolean `verificationResult`, verifying if the device is within the circular area delimited by the coordinates and the accuracy radius.
+
diff --git a/README.md b/README.md
@@ -31,24 +31,22 @@ Incubating API Repository to evolve and maintain the definitions and documentati
 
 * Note: Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until a new release is created. For example, changes may be reverted before a release is created. **For best results, use the latest available release**.
 
-**NEW**: Pre-release [r3.1](https://github.com/camaraproject/DeviceLocation/releases/tag/r3.1) with location-verification v3.0.0-rc.1, location-retrieval v0.5.0-rc.1 and geofencing-subscriptions v0.5.0-rc.1 is available.
-
-* **The latest public release is [r2.2](https://github.com/camaraproject/DeviceLocation/tree/r2.2), with the following API definitions (with inline documentation):**
+* **NEW: public release** [r3.2](https://github.com/camaraproject/DeviceLocation/releases/r3.2) is available, with the following API definitions (with inline documentation):**
   
-  - **location-verification v2.0.0** 
-  [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r2.2/code/API_definitions/location-verification.yaml)
-  [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r2.2/code/API_definitions/location-verification.yaml&nocors)
-  [[View it on Swagger Editor]](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r2.2/code/API_definitions/location-verification.yaml)
-
-  - **location-retrieval v0.4.0** 
-  [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r2.2/code/API_definitions/location-retrieval.yaml)
-  [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r2.2/code/API_definitions/location-retrieval.yaml&nocors)
-  [[View it on Swagger Editor]](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r2.2/code/API_definitions/location-retrieval.yaml)
-
-  - **geofencing-subscriptions v0.4.0**
-  [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r2.2/code/API_definitions/geofencing-subscriptions.yaml)
-  [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r2.2/code/API_definitions/geofencing-subscriptions.yaml&nocors)
-  [[View it on Swagger Editor]](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r2.2/code/API_definitions/geofencing-subscriptions.yaml)
+  - **location-verification v3.0.0** 
+  [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r3.2/code/API_definitions/location-verification.yaml)
+  [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r3.2/code/API_definitions/location-verification.yaml&nocors)
+  [[View it on Swagger Editor]](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r3.2/code/API_definitions/location-verification.yaml)
+
+  - **location-retrieval v0.5.0** 
+  [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r3.2/code/API_definitions/location-retrieval.yaml)
+  [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r3.2/code/API_definitions/location-retrieval.yaml&nocors)
+  [[View it on Swagger Editor]](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r3.2/code/API_definitions/location-retrieval.yaml)
+
+  - **geofencing-subscriptions v0.5.0**
+  [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r3.2/code/API_definitions/geofencing-subscriptions.yaml)
+  [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r3.2/code/API_definitions/geofencing-subscriptions.yaml&nocors)
+  [[View it on Swagger Editor]](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r3.2/code/API_definitions/geofencing-subscriptions.yaml)
 
 ## Contributing
 
diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
@@ -114,7 +114,7 @@ info:
 
     (FAQs will be added in a later version of the documentation)
 
-  version: wip
+  version: 0.5.0
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
@@ -124,7 +124,7 @@ externalDocs:
   url: https://github.com/camaraproject/DeviceLocation
 
 servers:
-  - url: "{apiRoot}/geofencing-subscriptions/vwip"
+  - url: "{apiRoot}/geofencing-subscriptions/v0.5"
     variables:
       apiRoot:
         default: http://localhost:9091
@@ -672,7 +672,7 @@ components:
           $ref: "#/components/schemas/ConfigResponse"
         id:
           type: string
-          description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification).
+          description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as subscriptionId as per Commonalities Event Notification Model.
           example: "1119920371"
         startsAt:
           type: string
@@ -724,7 +724,7 @@ components:
 
     SubscriptionId:
       type: string
-      description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification).
+      description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as subscriptionId as per Commonalities Event Notification Model.
       example: qs15-h556-rt89-1298
 
     Device:
diff --git a/code/API_definitions/location-retrieval.yaml b/code/API_definitions/location-retrieval.yaml
@@ -108,7 +108,7 @@ info:
     # Further info and support
 
     (FAQs will be added in a later version of the documentation)
-  version: wip
+  version: 0.5.0
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
@@ -117,7 +117,7 @@ externalDocs:
   description: Project documentation at Camara
   url: https://github.com/camaraproject/DeviceLocation
 servers:
-  - url: '{apiRoot}/location-retrieval/vwip'
+  - url: '{apiRoot}/location-retrieval/v0.5'
     variables:
       apiRoot:
         default: http://localhost:9091
diff --git a/code/API_definitions/location-verification.yaml b/code/API_definitions/location-verification.yaml
@@ -92,7 +92,7 @@ info:
     # Further info and support
 
     (FAQs will be added in a later version of the documentation)
-  version: wip
+  version: 3.0.0
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
@@ -101,7 +101,7 @@ externalDocs:
   description: Project documentation at CAMARA
   url: https://github.com/camaraproject/DeviceLocation
 servers:
-  - url: "{apiRoot}/location-verification/vwip"
+  - url: "{apiRoot}/location-verification/v3"
     variables:
       apiRoot:
         default: http://localhost:9091
diff --git a/code/Test_definitions/geofencing-subscriptions.feature b/code/Test_definitions/geofencing-subscriptions.feature
@@ -1,4 +1,4 @@
-Feature: Camara Geofencing Subscriptions API, vwip - Operations on subscriptions
+Feature: Camara Geofencing Subscriptions API, v0.5.0 - Operations on subscriptions
 
   # Input to be provided by the implementation to the tester
   #
@@ -8,11 +8,13 @@ Feature: Camara Geofencing Subscriptions API, vwip - Operations on subscriptions
   # Testing assets:
   # * A device object which location is known by the network when connected. 2 distinct device are required for some scenario.
   # * A moveable device to trigger area-left / area-entered events.
+  # * apiRoot: API root of the server URL
   #
   # References to OAS spec schemas refer to schemas specifies in geofencing-subscriptions.yaml
 
   Background: Common Geofencing Subscriptions setup
-    Given the resource "{apiroot}/geofencing-subscriptions/vwip/" as geofencing base-url
+    Given an environment at "apiRoot"
+    And the resource  "/geofencing-subscriptions/v0.5/" as geofencing base-url
     And the header "Authorization" is set to a valid access token
     And the header "x-correlator" complies with the schema at "#/components/schemas/XCorrelator"
 
diff --git a/code/Test_definitions/location-retrieval.feature b/code/Test_definitions/location-retrieval.feature
@@ -1,4 +1,4 @@
-Feature: CAMARA Device location retrieval API, vwip - Operation retrieveLocation
+Feature: CAMARA Device location retrieval API, v0.5.0 - Operation retrieveLocation
   # Input to be provided by the implementation to the tester
   #
   # Implementation indications:
@@ -8,11 +8,13 @@ Feature: CAMARA Device location retrieval API, vwip - Operation retrieveLocation
   # * A device object which location is known by the network when connected. 2 distinct device are required for some scenario.
   # * A device object identifying a device commercialized by the implementation for which the service is not applicable
   # * A device object which location cannot be provided during test by the network.
+  # * apiRoot: API root of the server URL
   #
   # References to OAS spec schemas refer to schemas specifies in location-retrieval.yaml
 
   Background: Common retrieveLocation setup
-    Given the resource "/location-retrieval/vwip/retrieve"                                                              |
+    Given an environment at "apiRoot"
+    And the resource "/location-retrieval/v0.5/retrieve"                                                              |
     And the header "Content-Type" is set to "application/json"
     And the header "Authorization" is set to a valid access token
     And the header "x-correlator" complies with the schema at "#/components/schemas/XCorrelator"
@@ -261,4 +263,4 @@ Feature: CAMARA Device location retrieval API, vwip - Operation retrieveLocation
     And the response header "x-correlator" has same value as the request header "x-correlator"
     And the response property "$.status" is 422
     And the response property "$.code" is "LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE"
-    And the response property "$.message" contains a user friendly text
+    And the response property "$.message" contains a user friendly text
diff --git a/code/Test_definitions/location-verification.feature b/code/Test_definitions/location-verification.feature
@@ -1,4 +1,4 @@
-Feature: CAMARA Device location verification API, vwip - Operation verifyLocation
+Feature: CAMARA Device location verification API, v3.0.0 - Operation verifyLocation
   # Input to be provided by the implementation to the tester
   #
   # Implementation indications:
@@ -8,11 +8,13 @@ Feature: CAMARA Device location verification API, vwip - Operation verifyLocatio
   # * A device object which location is known by the network when connected. To test all scenarios, at least 2 valid devices are needed
   # * The known location of the testing devices
   # * A device object identifying a device commercialized by the implementation for which the service is not applicable, if any
+  # * apiRoot: API root of the server URL
   #
   # References to OAS spec schemas refer to schemas specifies in location-verification.yaml
 
   Background: Common verifyLocation setup
-    Given the resource "/location-verification/vwip/verify"
+    Given an environment at "apiRoot"
+    And the resource "/location-verification/v3/verify"
     And the header "Content-Type" is set to "application/json"
     And the header "Authorization" is set to a valid access token
     And the header "x-correlator" complies with the schema at "#/components/schemas/XCorrelator"
@@ -308,4 +310,4 @@ Feature: CAMARA Device location verification API, vwip - Operation verifyLocatio
     Then the response status code is 422
     And the response property "$.status" is 422
     And the response property "$.code" is "LOCATION_VERIFICATION.UNABLE_TO_LOCATE"
-    And the response property "$.message" contains a user-friendly text
+    And the response property "$.message" contains a user-friendly text
diff --git a/documentation/API_documentation/geofencing-subscriptions-API-Readiness-Checklist.md b/documentation/API_documentation/geofencing-subscriptions-API-Readiness-Checklist.md
diff --git a/documentation/API_documentation/location-retrieval-API-Readiness-Checklist.md b/documentation/API_documentation/location-retrieval-API-Readiness-Checklist.md
diff --git a/documentation/API_documentation/location-verification-API-Readiness-Checklist.md b/documentation/API_documentation/location-verification-API-Readiness-Checklist.md
