Merge pull request #252 from camaraproject/public-rel-r12_M4

Release PR for public release r1.2 (M4)

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Table of Contents
 
+- **[r1.2](#r12)**
 - [r1.1](#r11)
 - [v0.2.0](#v020)
 - [v0.1.0](#v010)
@@ -14,11 +15,84 @@ The below sections record the changes for each API version in each release as fo
 * for subsequent alpha or release-candidate API versions, the delta with respect to the previous pre-release
 * for a public API version, the consolidated changes since the release of the previous public API version
 
+# r1.2
+
+## Release Notes
+
+This **public release** contains the definition and documentation of
+* location-verification v1.0.0
+* location-retrieval v0.3.0
+* geofencing-subscriptions v0.3.0
+
+The API definition(s) are based on
+* Commonalities v0.4.0
+* Identity and Consent Management v0.2.0
+
+**Changelog since v0.2.0**
+
+* Full Changelog with the list of PRs and contributors: https://github.com/camaraproject/DeviceLocation/compare/v0.2.0...r1.2
+
+## location-verification v1.0.0
+
+### Added
+
+* Added x-correlator to requests and headers
+* Enhancements in documentation
+* Testing plan
+
+### Changed
+
+* Make `device` optional in requests, with related documentation
+* Make '+' mandatory for phoneNumber
+* Adjust `maxAge` behaviour and minimum, and adjust documentation
+* Alignment of errors with Commonalities
+
+### Fixed
+
+* Update the PARTIAL case description: `match_rate` is set in the response
+
+## location-retrieval v0.3.0
+
+### Added
+
+* Added x-correlator to requests and headers
+* Enhancements in documentation
+* Testing plan
+
+### Changed
+
+* Make `device` optional in requests, with related documentation
+* Make '+' mandatory for phoneNumber
+* Adjust `maxAge` behaviour and minimum, and adjust documentation
+* Alignment of errors with Commonalities
+
+### Fixed
+
+* Clarify that `lastLocationTime` is mandatory in responses
+
+## geofencing-subscriptions v0.3.0
+
+### Added
+
+* Adopt Commonalities guidelines for subscriptions (based on CloudEvents)
+* Add `subscriptionMaxEvents` for maximum number of notifications
+* Add `SUBSCRIPTION_DELETED` and `SUBSCRIPTION_UNPROCESSABLE` as termination reasons
+* Add `terminationsDescription` as optional event property
+* Added x-correlator to requests and headers
+* Enhancements in documentation
+* Testing plan
+
+### Changed
+
+* Change base path to `geofencing-subscriptions` and adapt security scopes 
+* Make '+' mandatory for phoneNumber
+* Alignment of errors with Commonalities
+
 # r1.1
 
 ## Release Notes
 
-This release contains the definition and documentation of
+This **pre-release** contains the definition and documentation of
 * location-verification v1.0.0-rc.1
 * location-retrieval v0.3.0-rc.1
 * geofencing-subscriptions v0.3.0-rc.1
@@ -27,7 +101,9 @@ The API definition(s) are based on
 * Commonalities v0.4.0-rc.1
 * Identity and Consent Management v0.2.0-rc.1
 
-**Full Changelog** with the list of PRs and contributors: https://github.com/camaraproject/DeviceLocation/compare/v0.2.0...r1.1
+**Changelog since v0.2.0**
+
+* Full Changelog with the list of PRs and contributors: https://github.com/camaraproject/DeviceLocation/compare/v0.2.0...r1.1
 
 ## location-verification v1.0.0-rc.1
 

README.md

@@ -26,11 +26,10 @@ Repository to describe, develop, document and test the DeviceLocation API family
 
 * 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**.
 
-* The latest pre-release is [r1.1](https://github.com/camaraproject/DeviceLocation/tree/r1.1)  
-The release r1.1 contains the following API definitions (with inline documentation):
-  - **location-verification v1.0.0-rc.1** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r1.1/code/API_definitions/location-verification.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.1/code/API_definitions/location-verification.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.1/code/API_definitions/location-verification.yaml)
-  - **location-retrieval v0.3.0-rc.1** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r1.1/code/API_definitions/location-retrieval.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.1/code/API_definitions/location-retrieval.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.1/code/API_definitions/location-retrieval.yaml)
-  - **geofencing-subscriptions v0.3.0-rc.1** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r1.1/code/API_definitions/geofencing.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.1/code/API_definitions/geofencing.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.1/code/API_definitions/geofencing.yaml)
+* The latest pre-release is [r1.2](https://github.com/camaraproject/DeviceLocation/tree/r1.2) with the following API definitions (with inline documentation):
+  - **location-verification v1.0.0** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r1.2/code/API_definitions/location-verification.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.2/code/API_definitions/location-verification.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.2/code/API_definitions/location-verification.yaml)
+  - **location-retrieval v0.3.0** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r1.2/code/API_definitions/location-retrieval.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.2/code/API_definitions/location-retrieval.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.2/code/API_definitions/location-retrieval.yaml)
+  - **geofencing-subscriptions v0.3.0** [[YAML OAS]](https://github.com/camaraproject/DeviceLocation/blob/r1.2/code/API_definitions/geofencing.yaml) [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.2/code/API_definitions/geofencing.yaml&nocors) [[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceLocation/r1.2/code/API_definitions/geofencing.yaml)
 
 ## Contributing
 

code/API_definitions/geofencing-subscriptions.yaml

@@ -6,7 +6,7 @@ info:
 
     # Introduction
 
-    With this API, customers can create subscriptions for their devices to receive notifications when a device enters or exits a specified area.
+    With this API, API consumers can create subscriptions for their devices to receive notifications when a device enters or exits a specified area.
 
     The area provided in the request is described by a circle determined by coordinates (latitude and longitude) and an accuracy defined by the radius.
 
@@ -65,15 +65,15 @@ info:
 
     The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile.
 
-    Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.
+    Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the API Provider, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.
 
     It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.
 
     # Further info and support
 
     (FAQs will be added in a later version of the documentation)
 
-  version: 0.3.0-rc.1
+  version: 0.3.0
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
@@ -83,7 +83,7 @@ externalDocs:
   url: https://github.com/camaraproject/DeviceLocation
 
 servers:
-  - url: "{apiRoot}/geofencing-subscriptions/v0.3rc1"
+  - url: "{apiRoot}/geofencing-subscriptions/v0.3"
     variables:
       apiRoot:
         default: http://localhost:9091

code/API_definitions/location-retrieval.yaml

@@ -6,12 +6,12 @@ info:
 
     # Introduction
 
-    With this API, customers can retrieve the area where a certain user device is localized.
+    With this API, API consumers can retrieve the area where a certain user device is localized.
     The area provided in the response could be described:
     -  by a circle determined by coordinates (latitude and longitude) and a radius.
     -  by a simple polygon delimited by segments connecting consecutively an array of coordinates (points). The last point connects to the first point to delimit a closed shape bounded with straight sides.
 
-    The retrieved shape depends on the network conditions at the subscriber's location and any of the supported shapes could be received.
+    The retrieved shape depends on the network conditions at the device's location and any of the supported shapes could be received.
 
     The requester could optionally ask for a freshness of the localization information by providing a `maxAge` ("I want a location not older than 600 seconds").
 
@@ -56,7 +56,7 @@ info:
 
     The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile.
 
-    Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.
+    Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the API Provider, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.
 
     It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.
 
@@ -87,7 +87,7 @@ info:
     # Further info and support
 
     (FAQs will be added in a later version of the documentation)
-  version: 0.3.0-rc.1
+  version: 0.3.0
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
@@ -96,7 +96,7 @@ externalDocs:
   description: Project documentation at Camara
   url: https://github.com/camaraproject/DeviceLocation
 servers:
-  - url: '{apiRoot}/location-retrieval/v0.3rc1'
+  - url: '{apiRoot}/location-retrieval/v0.3'
     variables:
       apiRoot:
         default: http://localhost:9091

code/API_definitions/location-verification.yaml

@@ -2,11 +2,11 @@ openapi: 3.0.3
 info:
   title: Device Location Verification
   description: |
-    This API provides the customer with the ability to verify the location of a device.
+    This API provides the consumer with the ability to verify the location of a device.
 
     # Introduction
 
-    Customers are able to verify whether the location of certain user device is within the area specified. Currently the only area supported as input is a circle determined by a set of coordinates (latitude and longitude) and some expected accuracy (radius).
+    API consumers are able to verify whether the location of certain user device is within the area specified. Currently the only area supported as input is a circle determined by a set of coordinates (latitude and longitude) and some expected accuracy (radius).
 
     The verification result depends on the network's ability and accuracy to locate the device at the requested area.
 
@@ -49,7 +49,7 @@ info:
 
     The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile.
 
-    Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.
+    Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the API Provider, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.
 
     It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.
 
@@ -80,7 +80,7 @@ info:
     # Further info and support
 
     (FAQs will be added in a later version of the documentation)
-  version: 1.0.0-rc.1
+  version: 1.0.0
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
@@ -89,7 +89,7 @@ externalDocs:
   description: Project documentation at CAMARA
   url: https://github.com/camaraproject/DeviceLocation
 servers:
-  - url: "{apiRoot}/location-verification/v1rc1"
+  - url: "{apiRoot}/location-verification/v1"
     variables:
       apiRoot:
         default: http://localhost:9091

code/Test_definitions/Location-Retrieval.feature → code/Test_definitions/location-retrieval.feature

@@ -1,4 +1,4 @@
-Feature: CAMARA Device location retrieval  API, v0.3-rc.1 - Operation retrieveLocation
+Feature: CAMARA Device location retrieval API, v0.3.0 - Operation retrieveLocation
   # Input to be provided by the implementation to the tester
   #
   # Implementation indications:
@@ -9,10 +9,10 @@ Feature: CAMARA Device location retrieval  API, v0.3-rc.1 - Operation retrieveLo
   # * 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.
   #
-  # References to OAS spec schemas refer to schemas specifies in location-retrieval.yaml, version 0.2.0
+  # References to OAS spec schemas refer to schemas specifies in location-retrieval.yaml
 
   Background: Common retrieveLocation setup
-    Given the resource "/location-retrieval/v0.3rc1/retrieve"                                                              |
+    Given the resource "/location-retrieval/v0.3/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" is set to a UUID value

code/Test_definitions/location-verification.feature

@@ -1,4 +1,4 @@
-Feature: CAMARA Device location verification API, v1.0-rc1 - Operation verifyLocation
+Feature: CAMARA Device location verification API, v1.0.0 - Operation verifyLocation
   # Input to be provided by the implementation to the tester
   #
   # Implementation indications:
@@ -9,10 +9,11 @@ Feature: CAMARA Device location verification API, v1.0-rc1 - Operation verifyLoc
   # * 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
   #
-  # References to OAS spec schemas refer to schemas specifies in location-verification.yaml, version 0.2.0
+  # References to OAS spec schemas refer to schemas specifies in location-verification.yaml
 
   Background: Common verifyLocation setup
-    Given the resource "/location-verification/v1rc1/verify"                                                              |
+    Given the resource "/location-verification/v1/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" is set to a UUID value