Enhancing response to cover partial matches

Current response model just allows true/false as verificationResult, but there are scenarios where this result is not that straight-forward.

Let's review the following possible scenarios:

where

"Location Request" is a circle determined by the coordinates and accuracy (radius) in the request body. That is, the client wants to verify if the UE is within this circle.
"Network Location" is the area where the network estimates that the UE is. For simplicity we assume here a circle but in reality this is a polygon, depending on the cell distribution and coverage.

Scenarios

Scenario 1: "Network location" within "Location Request" - "verificationResult": true, no doubt
Scenario 2: "Network location" and "Location Request" are separated - "verificationResult": false, no doubt
Scenario 3: Partial matches between "Network location" and "Location Request" - Strictly false as request cannot be completely verified, but in some cases there is high probability to be true (right picture).
Scenario 4: There is match but the network estimation cannot satisfy the requested accuracy - Strictly false as request cannot be completely verified, but in some cases there is high probability to be true (right picture).

To address the different scenarios more properly, the response would need to be enhanced. An initial proposal:

    VerifyLocationResponse:
      type: object
      required:
        - verification_result
      properties:
        verification_result:
          $ref: '#/components/schemas/VerificationResult'
        match_rate:
          $ref: '#/components/schemas/MatchRate'
    VerificationResult:
      description: |-
        Verification request result:
        * `TRUE`: when the Network locates the device within the requested area
        * `FALSE`: when the requested area completely differs from the area where the Network locates the device
        * `PARTIAL` when the requested area is partially included in the area where the Network locates the device but not entirely. In this case `success_rate` must be included in the response
        * `UNDETERMINED` when the network cannot satisfy the requested accuracy in the request. Client may trigger a new request with a higher value for requested accuracy
        * `UNKNOWN` when the network cannot locate the requested device
      type: string
      enum:
        - TRUE
        - FALSE
        - PARTIAL
        - UNDETERMINED
        - UNKNOWN
    MatchRate:
      description: Match rate estimation for the location verification in percent
      type: integer
      minimum: 0
      maximum: 100
      example: 74

The value unknown would solve as well the issue #19.

camaraproject / DeviceLocation

Enhancing response to cover partial matches #20