[location-verification / geofencing]: decrease radius minimum to "1" for circle-area

code/API_definitions/geofencing-subscriptions.yaml

@@ -8,6 +8,9 @@ info:
 
     With this API, API consumers can create subscriptions for their devices to receive notifications when a device enters or exits a specified area.
 
+    * If the provided area is out of the operator's coverage or it is not supported for any reason, an error `422 GEOFENCING.AREA_NOT_COVERED` will be returned.
+    * Legal restrictions regarding privacy, or other regulatory or implementation issues, may force the operator to set restrictions to the provided area, such as setting a minimum value to the accepted radius. In these cases, an error `422 GEOFENCING.INVALID_AREA` will be returned and the error message will refer to the reason of the limitation.
+
     The area provided in the request is described by a circle determined by coordinates (latitude and longitude) and an accuracy defined by the radius.
 
     Upon successfully creating a subscription, the API will provide an Event Subscription ID, and it will indicate the subscription's expiration date.
@@ -718,8 +721,10 @@ components:
               $ref: "#/components/schemas/Point"
             radius:
               type: integer
-              description: Expected accuracy for the subscription event of device location in m, from location (radius).
-              minimum: 2000
+              description: |
+                Expected accuracy for the subscription event of device location, in meters from `center`.
+                Note: The area surface could be restricted locally depending on regulations. Implementations may enforce a larger minimum radius (e.g. 1000 meters).
+              minimum: 1
               maximum: 200000
           required:
             - center
@@ -1323,18 +1328,14 @@ components:
                       - 422
                   code:
                     enum:
-                      - AREA_NOT_COVERED
                       - IDENTIFIER_MISMATCH
                       - MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED
                       - SERVICE_NOT_APPLICABLE
                       - UNNECESSARY_IDENTIFIER
                       - UNSUPPORTED_IDENTIFIER
+                      - GEOFENCING.AREA_NOT_COVERED
+                      - GEOFENCING.INVALID_AREA
           examples:
-            GENERIC_422_AREA_NOT_COVERED:
-              value:
-                status: 422
-                code: AREA_NOT_COVERED
-                message: The specified area cannot be covered or is too small to be valid
             GENERIC_422_IDENTIFIER_MISMATCH:
               description: Inconsistency between device identifiers not pointing to the same device.
               value:
@@ -1364,6 +1365,20 @@ components:
                 status: 422
                 code: UNSUPPORTED_IDENTIFIER
                 message: The identifier provided is not supported.
+            GEOFENCING_422_AREA_NOT_COVERED:
+              summary: The area cannot be covered
+              description: The system is not able cover the requested area
+              value:
+                status: 422
+                code: GEOFENCING.AREA_NOT_COVERED
+                message: "Unable to cover the requested area"
+            GEOFENCING_422_INVALID_AREA:
+              summary: Invalid area
+              description: The requested area is too small to be supported by the system.
+              value:
+                status: 422
+                code: GEOFENCING.INVALID_AREA
+                message: "The requested area is too small"
     Generic429:
       description: Too Many Requests
       headers:

code/API_definitions/location-verification.yaml

@@ -8,14 +8,17 @@ info:
 
     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).
 
+    * If the provided area is out of the operator's coverage or it is not supported for any reason, an error `422 LOCATION_VERIFICATION.AREA_NOT_COVERED` will be returned.
+    * Legal restrictions regarding privacy, or other regulatory or implementation issues, may force the operator to set restrictions to the provided area, such as setting a minimum value to the accepted radius. In these cases, an error `422 LOCATION_VERIFICATION.INVALID_AREA` will be returned and the error message will refer to the reason of the limitation.
+
     The verification result depends on the network's ability and accuracy to locate the device at the requested area.
 
     * If the network's estimation of the device's location is fully contained within the requested area, the verification result is `TRUE`.
     * If the network's estimation of the device's location does not overlap with the requested area at all, the verification result is `FALSE`.
-    * If the network's estimation of the device's location partially overlaps with the requested area, or it fully contains the requested area (because it is larger), the result is 'PARTIAL'. In this case, a `match_rate` is included in the response, indicating an estimation of the likelihood of the match in percent.
+    * If the network's estimation of the device's location partially overlaps with the requested area, or it fully contains the requested area (because it is larger), the result is `PARTIAL`. In this case, a `match_rate` is included in the response, indicating an estimation of the likelihood of the match in percent.
     * Lastly, the network may not be able to locate the device. In this case, the verification result is `UNKNOWN`.
 
-    The client may optionally include a `maxAge` indication. If the location information known to the server is older than the specified `maxAge`, an error 422 with code LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE is sent back.
+    The client may optionally include a `maxAge` indication. If the location information known to the server is older than the specified `maxAge`, an error with code `422 LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE` is sent back.
 
     `lastLocationTime` will be always included in the success response unless there is no historical location information available for the device. In this case, `UNKNOWN` will be returned without `lastLocationTime`.
 
@@ -34,7 +37,7 @@ info:
 
      * **Max Age**: Maximum age of the location information which is accepted for the location verification (in seconds).
         * Absence of maxAge means "any age" is acceptable for the client. In other words, this is like maxAge=infinite. In this case the system will still return lastLocationTime, if available.
-        * maxAge=0 means a fresh calculation is requested by the client. If the system is not able to provide the fresh location, an error 422 with code LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE is sent back.
+        * maxAge=0 means a fresh calculation is requested by the client. If the system is not able to provide the fresh location, an error with code `422 LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE` is sent back.
 
 
     * **Verification**: Process triggered in the API server to confirm or contradict the expectation assumed by the API client about the device location.
@@ -243,8 +246,10 @@ components:
               $ref: "#/components/schemas/Point"
             radius:
               type: integer
-              description: Expected accuracy for the verification in meters, from center
-              minimum: 2000
+              description: |
+                Expected accuracy for the verification, in meters from `center`.
+                Note: The area surface could be restricted locally depending on regulations. Implementations may enforce a larger minimum radius (e.g. 1000 meters).
+              minimum: 1
               maximum: 200000
           required:
             - center
@@ -583,6 +588,8 @@ components:
                       - MISSING_IDENTIFIER
                       - UNSUPPORTED_IDENTIFIER
                       - UNNECESSARY_IDENTIFIER
+                      - LOCATION_VERIFICATION.AREA_NOT_COVERED
+                      - LOCATION_VERIFICATION.INVALID_AREA
                       - LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE
           examples:
             GENERIC_422_IDENTIFIER_MISMATCH:
@@ -615,6 +622,20 @@ components:
                 status: 422
                 code: UNNECESSARY_IDENTIFIER
                 message: The device is already identified by the access token.
+            LOCATION_VERIFICATION_422_AREA_NOT_COVERED:
+              summary: The area cannot be covered
+              description: The system is not able cover the requested area
+              value:
+                status: 422
+                code: LOCATION_VERIFICATION.AREA_NOT_COVERED
+                message: "Unable to cover the requested area"
+            LOCATION_VERIFICATION_422_INVALID_AREA:
+              summary: Invalid area
+              description: The requested area is too small to be supported by the system.
+              value:
+                status: 422
+                code: LOCATION_VERIFICATION.INVALID_AREA
+                message: "The requested area is too small"
             LOCATION_VERIFICATION_422_UNABLE_TO_FULFILL_MAX_AGE:
               summary: Unable to fulfill maxAge
               description: The system is not able to provide the fresh location required by the client

code/Test_definitions/geofencing-subscriptions.feature

@@ -1,11 +1,11 @@
 @Geofencing 
-Feature: Camara Geofencing Subscriptions API, v0.3.0 - Operations on subscriptions 
+Feature: Camara Geofencing Subscriptions API, vwip - Operations on subscriptions
 
 # Input to be provided by the implementation to the tests
-# References to OAS spec schemas refer to schemas specified in geofencing-subscriptions.yaml, version v0.3.0
+# References to OAS spec schemas refer to schemas specified in geofencing-subscriptions.yaml, version vwip
 
   Background: Common Geofencing Subscriptions setup
-    Given the resource "{apiroot}/geofencing-subscriptions/v0.3/" as geofencing base-url                                                           
+    Given the resource "{apiroot}/geofencing-subscriptions/vwip/" as geofencing base-url
     And the header "Authorization" is set to a valid access token
     And the header "x-correlator" is set to a UUID value
 
@@ -309,14 +309,14 @@ Feature: Camara Geofencing Subscriptions API, v0.3.0 - Operations on subscriptio
     And the response property "$.code" is "NOT_FOUND"
     And the response property "$.message" contains a user friendly text
 
-  @geofencing_subscriptions_28_create_with_invalid_area
+  @geofencing_subscriptions_28_create_with_an_unsupported_area
   Scenario: Create subscription with an invalid area
     Given the request body property "$.area" is set to an unsupported or invalid area
     When the HTTP "POST" request is sent
     Then the response status code is 422
     And the response property "$.status" is 422
-    And the response property "$.code" is "AREA_NOT_COVERED"
-    And the response property "$.message" contains "The specified area cannot be covered or is invalid."
+    And the response property "$.code" is "GEOFENCING.AREA_NOT_COVERED"
+    And the response property "$.message" contains "Unable to cover the requested area"
 
   @geofencing_subscriptions_29_create_with_identifier_mismatch
   Scenario: Create subscription with identifier mismatch
@@ -352,4 +352,13 @@ Feature: Camara Geofencing Subscriptions API, v0.3.0 - Operations on subscriptio
     Then the response status code is 422
     And the response property "$.status" is 422
     And the response property "$.code" is "UNSUPPORTED_IDENTIFIER"
-    And the response property "$.message" contains "The identifier provided is not supported."
+    And the response property "$.message" contains "The identifier provided is not supported."
+
+  @geofencing_subscriptions_33_create_with_an_invalid_area
+  Scenario: Create subscription with an invalid area
+    Given the request body property "$.area" is set with an too small area-size
+    When the HTTP "POST" request is sent
+    Then the response status code is 422
+    And the response property "$.status" is 422
+    And the response property "$.code" is "GEOFENCING.INVALID_AREA"
+    And the response property "$.message" contains "The requested area is too small"