Prepare public release r3.2

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,110 @@ 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. It introduces breaking changes 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

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):**
+* **The latest public release is [r3.2](https://github.com/camaraproject/DeviceLocation/tree/r3.2), 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
 

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

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

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

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
   #
@@ -12,7 +12,7 @@ Feature: Camara Geofencing Subscriptions API, vwip - Operations on subscriptions
   # 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 the resource "{apiroot}/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"
 

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:
@@ -12,7 +12,7 @@ Feature: CAMARA Device location retrieval API, vwip - Operation retrieveLocation
   # 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 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"

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:
@@ -12,7 +12,7 @@ Feature: CAMARA Device location verification API, vwip - Operation verifyLocatio
   # 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 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"

documentation/API_documentation/geofencing-subscriptions-API-Readiness-Checklist.md

@@ -1,18 +1,18 @@
 # API Readiness Checklist
 
-Checklist for geofencing-subscriptions 0.5.0-rc.1 in r3.1
+Checklist for geofencing-subscriptions 0.5.0 in r3.2
 
 | Nr | API release assets                           | alpha | release-candidate | public-release<br>initial | public-release<br> stable | Status |                                               Reference information                                                |
 |----|----------------------------------------------|:-----:|:-----------------:|:-------------------------:|:-------------------------:|:------:|:------------------------------------------------------------------------------------------------------------------:|
 | 1  | API definition                               |   M   |         M         |             M             |             M             |   Y    |     [/code/API_definitions/geofencing-subscriptions.yaml](/code/API_definitions/geofencing-subscriptions.yaml)     |
-| 2  | Design guidelines from Commonalities applied |   O   |         M         |             M             |             M             |   Y    |                                                        r3.2                                                        |
-| 3  | Guidelines from ICM applied                  |   O   |         M         |             M             |             M             |   Y    |                                                        r3.2                                                        |
+| 2  | Design guidelines from Commonalities applied |   O   |         M         |             M             |             M             |   Y    |                                                        r3.3                                                        |
+| 3  | Guidelines from ICM applied                  |   O   |         M         |             M             |             M             |   Y    |                                                        r3.3                                                        |
 | 4  | API versioning convention applied            |   M   |         M         |             M             |             M             |   Y    |                                                                                                                    |
 | 5  | API documentation                            |   M   |         M         |             M             |             M             |   Y    |                                                   inline in yaml                                                   |
 | 6  | User stories                                 |   O   |         O         |             O             |             M             |   N    |                                                                                                                    |
 | 7  | Basic API test cases & documentation         |   O   |         M         |             M             |             M             |   Y    | [/code/Test_definitions/geofencing-subscriptions.feature](/code/Test_definitions/geofencing-subscriptions.feature) |
 | 8  | Enhanced API test cases & documentation      |   O   |         O         |             O             |             M             |   Y    | [/code/Test_definitions/geofencing-subscriptions.feature](/code/Test_definitions/geofencing-subscriptions.feature) |
-| 9  | Test result statement                        |   O   |         O         |             O             |             M             |   N    |                                           Test results not available (*)                                           |
+| 9  | Test result statement                        |   O   |         O         |             O             |             M             |   N    |                  |
 | 10 | API release numbering convention applied     |   M   |         M         |             M             |             M             |   Y    |                                                                                                                    |
 | 11 | Change log updated                           |   M   |         M         |             M             |             M             |   Y    |                                           [/CHANGELOG.md](/CHANGELOG.md)                                           |
 | 12 | Previous public-release was certified        |   O   |         O         |             O             |             M             |   N    |                                                                                                                    |