Problem description
Currently, device model is copied from the one originally introduced by QoD API, where both single IP addresses and IP subnets with masks were considered, but in this API and with the purpose of identification of mobile devices, only single IP addresses make sense.
This problem is shared with other APIs, such as DeviceStatus.

Expected behavior
A proposal to modify device has been created in QoD: camaraproject/QualityOnDemand#230 (comment)

The motivation of this issue is to have a common model for device across all CAMARA APIs which reuse it.

The only formats allowed in device would be those considered in JSON-schema:

IP Addresses
"ipv4": IPv4 address, according to dotted-quad ABNF syntax as defined in RFC 2373, section 3.2.
"ipv6": IPv6 address, as defined in RFC 2373, section 2.2.
The considerations about flows should be the same as if the device would be identified by other means, with a phone number for example.

Problem description
Implement use of linting rule set for Device Location API.
what we have to do is well documented in Commonalities:
camaraproject/Commonalities#110
camaraproject/Commonalities#74

Expected action
Check our APIs with linting rule set
provide feedback to commonalities team

Additional context
cc: @rartych who asked project volunteer to perform this action.
... Rafal also said that @jlurien is volunteer to run this :) :)

In this issue we would like to enable to verify the location for multiple devices in one call.

Change:

Request: instead of 1 device a list of devices should be used
Response: a list of verification results should be returned

Team,
We need a decision about introduction of 'geo fencing' notification endpoint.
We have 2 options:

1. Add this subscription endpoint in existing 'location verification' API
2. Create a whole new API for that.

From my perspective
Functionally, checking location & notification management for geofencing are very close and share a lot of in common.
From a business perspective, we'll probably have separate business case and model.

I tend to prefer option 1 to not multiply the API and we are in very similar context.
Please provide feedback in order to get discussion/decision in next meeting.

cc: @ukkaps

The device location API should enable UE location related queries.
In the first version the UE position can be verified against given coordinates and an accuracy, with a boolean response.

Problem description
There is no clear guideline about how to implement the response to location-verification, when result is PARTIAL, and it is not obvious how to calculate the matchRate

Expected action
Trigger discussion and agree on some guidelines for common implementation.

An initial proposal is presented, to cover several scenarios that may happen. Also with comments and concerns.

Additional context

Word Document:
Location Verification Implementation Guidelines.docx

I have created a first release tagged as 0.1.0, to freeze the current version (yaml + doc), inspired by what has been done in other WG. From now on, it seems that we should trigger new PRs towards main branch instead of having a separate branch for next release.

There are some ongoing discussions in Commonalities around these topics so we should align with them.

Problem description
Hello
Looking to define a standard behavior within our implementations.
If we got a suscription for org.camaraproject.geofencing.v0.area-entered event type for a device already present in the geo zone our understanding is to not trigger an event.
Same for org.camaraproject.geofencing.v0.area-left - if the device is not in the monitored zone we do not sent notification.

If for any reason the device is not localized at the time of the subscription we apply same rule

Given the event name seems that this is the expected behavior but looking for team feedback.

Possible evolution
A short description of this rule in the documentation

Alternative solution

Additional context

Problem description
Definition of the security scope for subscription endpoint.
As of now we have
GET geofencing subscriptions & GET /{id}: location-retrieval:read
POST geofencing subscriptions : no scope
DELETE geofencing subscriptions: location-retrieval:delete

Are we sure that we should not have subscriptions word in the technical scope ?
location-retrieval:read is used for location retrieval sync API and here this is distinct as the geofencing API can run for one time. I'm not a legal expert but from my perspective allowing to get my location now is distinct that allowing to get a notification each time I entered or left a defined area.

Possible evolution
Have specific scope like geofencing:subscription:add, geofencing:subscription:read and geofencing:subscription:delete

Alternative solution

Additional context

Problem description
Currently, the naming of endpoints is not consistent among the APIs in progress:

• location-verification, v0.2: POST /verifications { device, area } -> Uses plural
• location, v0.1: POST /retrieve-location { device } -> Uses verb for actions

Expected behavior
Decide on a common approach. Originally, location-verification used /verify-location but it was changed due to alignment with Commonalities guidelines, which at that time requested paths to be names, but recently a new decision was taken to favor verbs

When the POST method is used, the resource in the path must be a verb (e.g. retrieve-location and not location) to differentiate from an actual resource creation.

Proposal is to revert pàth to the previous name: /verify-location

Alternative solution
n/a

Additional context
n/a

The issue in Commonalities camaraproject/Commonalities#18 is referencing DeviceLocation subproject.
I propose to review current API specification with that subject and suggest respective guidelines if needed.

Problem description

Area uses a polymorphic model (oneOf)

Expected behavior

Guidelines favor inheritance (allOf)

Alternative solution

Remodel Area a base class and Circle as child

Additional context

Problem description
Different accuracy levels should be supported from privacy perspective as each Telco may have different policies.

Possible evolution
Define a way to offer different accuracy levels for the Device Location APIs (one time or subscription based) (i.e. precise, coarse).

Alternative solution
n/a

Additional context
#58 (comment)

Problem description
Checking the swagger on swagger.io editor got an error:

Semantic error at paths./subscriptions.post.security.1
Security requirements must match a security definition
Jump to line 150

CC: https://github.com/maxl2287 ;)

Expected behavior
Fix this small issue

Alternative solution
No alternative

Additional context
No additional context

Originating from the brief discussion in the meeting 2023-03-14.

In addition to being able to verify the location, Ericsson propose that a developer should also be able to get the raw location information of a device as known by the network.

This would serve use cases in which the device does not have built in GNSS support. Extended with subscription support it would also serve use cases for tracking such devices.

Location data should be provided in form of geographical coordinates (x, y, z). The reason for this is that network identities such as CellID etc. are typically not known by developers (and should perhaps not even be exposed externally). The location could be given as a point or a shape with uncertainty area.

Location is in most jurisdictions considered to be sensitive data and thereby consent by device owner/user must be verified before providing it to the developer.

Further more we believe that the API to access location data should be aligned with API to get device status information to make it easy for developers to request these at the same time (originally we have proposed them as one and the same API camaraproject/DeviceStatus#17

Location could be reported as for instance (but not limited to)

{
"ageOfLocationInfo": 0,
"geographicArea": {
"shape": "POINT",
"point": {
"lon": -180,
"lat": -90
}
}
}

or

{
"ageOfLocationInfo": 10,
"geographicArea": {
"shape": "POINT_UNCERTAINTY_CIRCLE",
"point": {
"lon": -180,
"lat": -90
},
"uncertainty": 200
}
}

Problem description
As of now we are only able to subscribe for a period of time but why not allowing also to subscribe to a number of notification?

We can have UC where we want to get notified when a device will reach or exit a geo zone once but without any time limit (like for sim card that are embedded in equipment that are not suppose to move like in traffic light...).

Possible evolution
Add capability to define a max number of notifications.

Alternative solution

Additional context

Problem description
In the current version of the location retrieval API when responding the location of a device, we always do this in form of a circle. However when requesting the location from a southbound system such as NEF/SCEF or GMLC it is common to receive a non-circular area. When transforming such non-circular area to a circle we will lose accuracy.

Possible evolution
Allow non-circular areas in the response. That would enable the location retrieval API to return what has been received from southbound systems without transformation. Thereby the accuracy will be kept.

Additional context
3GPP specifies the following geographical areas:

• Point
• PointUncertaintyCircle
• PointUncertaintyEllipse
• Polygon
• PointAltitude
• PointAltitudeUncertainty
• EllipsoidArc

Allow consumer to request the maximum accepted age of the verified location from the operator.

  schemas:
    VerifyLocationRequest:
      type: object
      properties:
        ueId:
          $ref: '#/components/schemas/UeId'
        uePort:
          $ref: '#/components/schemas/Port'
        latitude:
          $ref: '#/components/schemas/Latitude'
        longitude:
          $ref: '#/components/schemas/Longitude'
        accuracy:
          $ref: '#/components/schemas/Accuracy'
        maxLocationAge:
          $ref: '#/components/schemas/MaxAge'
      required:
        - ueId
        - latitude
        - longitude
        - accuracy
        - maxAge 

MaxAge:
      description: Max location aging validity required by the application in Minute, Default =0 for realtime location
      type: number
      minimum: 0
      maximum: 1440
      example: 30

hi,

do we have an meetings arrange for this working group ? I can't find a link.

Thanks,
Gareth

Problem description
In Geofencing we have:

  Area:
      type: object
      properties:
        areaType:
          $ref: "#/components/schemas/AreaType"
      required:
        - areaType
      discriminator:
        propertyName: "areaType"
        mapping:
          CIRCLE: "#/components/schemas/Circle"

   AreaType:
      type: string
      description: |
        Type of this area.
        CIRCLE - The area is defined as a circle.
      enum:
        - CIRCLE

in Location Verification we have:

Area:
      properties: 
        areaType:
          type: string
          description: Type of this area.
      required:
        - areaType
      discriminator: 
        propertyName: areaType
        mapping: 
          Circle:  "#/components/schemas/Circle"

In Location Retrieval

   Area:
      type: object
      required:
        - areaType
      properties:
        areaType:
          description: type of the area (like Circle or a Polygon)
          type: string
      discriminator: 
          propertyName: areaType
          mapping: 
            Circle:  "#/components/schemas/Circle"
            Polygon: "#/components/schemas/Polygon"

We have some inconsistencies here

1. use of enumeration for areaType
2. value in UPERCASE or CamelCase

Expected behavior
Align design within our API.
Probably we can align geofencing API with the 2 other APIs
Seems to me that alignement on case should be done for this RC
(I can do it)

Alternative solution

Additional context

We would like to add 2 new parameters to the location verification:

Request:

• maxAge: optional, if given it should be considered as the maximum age of the location information which is accepted for the verification

Response:

• lastLocationTime: mandatory, timestamp of the last location information

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.

Problem description
As decided during the last meeting, we are opening this issue to summarize the decisions and to be used as reference in the PRs.

Release 0.2.0 of the DeviceLocation API family will contain:

• API spec for location-verification, v0.2.0
• API spec for location-retrieval, v0.1.0
• API spec for geofencing, v0.1.0
• Updated README and CHANGELOG

Expected action

• Telefónica to create a Release Candidate version of location-verification v0.2.0-rc @jlurien
• Orange to create a Release Candidate version of location-retrieval v0.1.0-rc @bigludo7
• DT to create a Release Candidate version of geofencing v0.1.0-rc @akoshunyadi

taking into consideration:

• info.description updated with latest documentation
• scopes and securitySchemes aligned
• review examples
• assure that spec is correctly displayed in Swagger Editor and Redocly

Problem description
Two issues:

• lastLocationTime added in VerifyLocationResponse schema needs to be reflected in the examples.
• When maxAge conditions fail, it can result in UNKNOWN location response as discussed in here. However, it is better to capture the conclusion in the specification

Expected action
Spec update

For now we are not using the right code (as defined in the guidelines) for error in the OAS examples.

For 400 should be INVALID_ARGUMENT instead of INVALID_INPUT
for 401 ... UNAUTHENTICATED and not UNAUTHORIZED
same mismatch for 403, 500 & 503

This indirectly link to #15

@jlurien as it is only example change I can probably fix this now without changing version no?

Currently we have defined /verify path .
According to OpenAPI Guide and Design Guidelines path should be the name of resources (be a plural noun - Verbs are not allowed)
We have operationId: verifyLocation which is correct.

The path name should be changed to for example:
/verification
or event more correct:
/verifications

The full URI will look like that:

   http://localhost:9091/location/v0/verifications

This isssue is related to #15 (alignment with guidelines)

Summary

Create a subscription mode for the DeviceLocation API. So that developers are informed if a device is leaving or entering the "radius". This is important for tracking devices for Presetting of Homesettings or for tracking of logistics and more.

Changes

For this there are several changes to be done

• Adding new paths /subscriptions
  • Brining in new optional parameter
    • Based on /verify
    • EventType is an array which is giving the subscription mode
      • AREA_ENTERED = the device is leaving the defined radius
      • AREA_LEFT = the device is entering the defined radius
    • ExpireTime to set how long the subscription should be active
  • Activate Multiple Devices and Multiple Events

          As far as I know, this repo does not follow point 5 of that guide as no Gherkin or test cases are provided as required. PR#79 was an attempt to remedy this. As per @jlurien "HTML file as part of the documentation is not the way to manage them."

As per API-DocumentationTemplate, code snippets are also encouraged and this commit also provides that.

Originally posted by @questsin in #79 (comment)

As a provider implementor from 5GFF and Rogers Communications, contributions from our Compliance and Conformance test bed fulfill the minimum readiness criteria w.r.t API test cases and documentation, including in the Gherkin Style.
This can be easily translated to any language and framework of the day. It's just a start, but based on our real-life implementations and inspired by TMForum conformance and compliance tests in the same framework.
It's also self-contained and includes all the bells and whistles, batteries included, and can run anywhere 😀

Suggest we provide these tests covering all major languages, including code snippets of their use.

When asking to verify the location of a device you input a circle (a point + radius in form of accuracy) to which we will respond TRUE, FALSE, UNKNOWN or PARTIAL.

The accuracy that can be provided depends to a large degree on the underlying system as well as where the device is located. With some GMLC implementations the accuracy in ideal situations can be below 100m, Relying only on location reporting through 3GPP MONTE we have at best cell level granularity which in rural areas will be not very accurate.

One could expect that API invokers would like as high accuracy as possible. This means that we could have a scenario when the accuracy of the underlying system is to low and we will always return FALSE. How can we communicate this to the API invoker? Should we provide more detailed information in the API description or should we add information in the response that the asked for accuracy is not supported?

Problem Description

Remove "Location-based advertising" from YAML.

• “Location Verification could be useful in scenarios such as... Location-based advertising, to trigger **targeted advertising** after verifying the user is in the area of interest...”

The API’s reference to location-based advertising is problematic for GDPR. There’s uncertainty about whether users have agreed to let their location data be used for targeted advertising.

Expected Action

I strongly urge the group to remove that specific use case from the YAML, "Location-based advertising, to trigger targeted advertising after verifying the user is in the area of interest" from the API documentation.

Additional Context

For GDPR this API does not meet the standards of data ethics and legal compliance.

GDPR concerns

• Consent for Data Processing Section 4(1) stipulates that personal data can only be processed with the consent of the Data Principal for lawful purposes. The device location API, as described, seems to lack a clear mechanism for obtaining user consent, particularly for the purpose of location-based targeted advertising especially since this is in essence granting consent through a back door approach.

• Potential for Unlawful Data Profiling and Automated Decision-Making The use of data for automated decision-making or profiling without proper safeguards or consent contravenes Article 22 on automated individual decision-making, including profiling.

• Non-Compliance with Children’s Data Protection: If the API processes children’s data for advertising without proper consent, it would violate Article 8 concerning conditions applicable to child’s consent in relation to information society services rights.

@rartych may I ask you to do some magic to integrate CAMARA template for issue and PR for our project ?

I'm not familiar with this operation :)

Thanks

Postal codes are a common user friendly denominations for known areas.

Proposal is to add a new type of Area PostalCode

PostalCode:
  type: object
  required:
    - type
    - postalCode
  properties:
    type:
      type: string
      enum:
        - PostalCode
      description: Type of this area
    postalCode:
      type: string
      description: Postal Code (aka Zip code or Postcode), according to the local format. 
    countryCode:
      type: string
      pattern: '^[A-Z]{2}$' 
      description: ISO 3166-1 alpha-2 code for the country. Uppercase. If not specified, each implementation may apply a default value.

Optionally a country code may be needed in some global scenarios. Otherwise, each implementation may assume its own country.
There is no global pattern for postal codes. We could define some limits minLength , maxLength, apparently longest one is 10, but it may be better to leave all format verification to implementations.

Our current spec uses basePath = location, but we are now proposing a new API within this WG, and as they are separate APIs they must have different basePath.

Proposal is to rename current one to location-verification and the new one could keep just location, or even location-retrieval, to make it more explicit.

Thoughts, preferences?

Problem description
The org.camaraproject.geofencing.v0.subscription-ends notification type did not require a subscription. Indeed this notification type should be always send when the subscription terminates. As such this type must not be listed in the POST /Subscriptions (but this type could be of course used in the notification)

Expected behavior
In the yaml have a separate array for the event type in the subscription and the one for the notification in order to not allow org.camaraproject.geofencing.v0.subscription-ends in the POST /souscriptions

Alternative solution

Additional context

Currently is kilometers [km] but there is a proposal to use meters [m] instead

Opinions?

Problem description
MaxAge data type type: number and format: integer is conflicting with the OpenAPI specification

Expected behavior
Change type: integer and remove the format

Problem description

Does the workstream already have a definition for the " security" and "scope" values to specify the purpose of the location APIs? We are trying to streamline the consent flows, and we would like to align ourselves with the proposed values if there are any.

I can see there is an action item related to this in the MOM of last WG meeting.

Expected action

If these are not specified, think of going ahead with the values below. Appreciate it if the WG owners could provide some advice on this.

paths:
/retrieve:
post:
security:
- openid
- device-location:retrieve
tags:
- Location retrieval
summary: 'Execute location retrieval for a user equipment'
operationId: retrieveLocation

paths:
/verify:
post:
security:
- openid
- device-location:verify
tags:
- Location verification
summary: 'Execute location verification for a user equipment'
operationId: verifyLocation

Additional context

Problem description
In Area, the mapping uses CIRCLE to reference the Circle object... but CIRCLE should be Circle

Expected behavior
The left side of the mapping should be the object name, as explained in the design guidelines, to simplify implementation and consumption.

Alternative solution

        mapping:
          Circle: "#/components/schemas/Circle"

    AreaType:
      type: string
      description: |
        Type of this area.
        Circle - The area is defined as a circle.
      enum:
        - Circle

Problem description
Formal inclusion of the GSMA OGW Product WS request to include Postal/administrative Codes support for location verification services (basic API and geofencing/subscription API)

Possible evolution
API input includes not only center+radious or other geographical figure, but also administrative zones

Alternative solution
N/A

Additional context
More details included in the formal request file, attached
Camara Submission - DevLocVerifAdminCode v2.docx

As agreed for #18, we should move the new API proposal in PR #49 to a new API spec. Which name do you prefer:

• geofencing
• location-verification-subscription
• Other, please suggest

camaraproject/WorkingGroups#120

This API seems to be missing Changelog. Changelog helps people like me understand the changes across versions.
See the one for QoD as an example here. Similarly DeviceStatus has a changelog too.

cc: @gmuratk

UeId:
  description: User equipment identifier
  type: object
  properties:
    externalId:
      $ref: '#/components/schemas/ExternalId'
    msisdn:
      $ref: '#/components/schemas/MSISDN'
    ipv4Addr:
      $ref: '#/components/schemas/Ipv4Addr'
    ipv6Addr:
      $ref: '#/components/schemas/Ipv6Addr'
  minProperties: 1
- - -  

Shouldn't this be in CAMARA_common.json?

Problem description
As we saw with location-verification, the area where the network locates a device is not, or close to, a single point. It is an area that can be quite large compared with the geofence area. In order to decide when the device enters or leaves the geofence we have to agree on some rules based on the intersection of both areas.

Expected action
As we did with location-verification, we should discuss and agree on some guidelines for a common implementation.

Proposal (to start with):

In this case if we consider D (= area where network locates the device) and G (= geofence area), we may consider that:

• area-entered event is to be triggered when more than N% of D is within G, for the first time, or after area-left has been triggered.
• area-left event is to be triggered when, after area-entered event has been already triggered, then more than N% of D is outside G.

"N%" thresholds are to be decided. Instead of 50%, we may choose a higher % to leave some safe gap between both, for example 60% .

Summary

It can happen that the network can't locate the device, because it is offline and the location is also not cached. In this there should be coming the right response from the API.

Changes

Adding to true or false the return value unkown, when it is not possible to get the location

Problem description
To have a strong typed notificationUrl, add a format constraint on type.
This will simplify implementation and clarify usage.

    NotificationUrl:
      type: string
      format: uri
      example: "https://application-server.com"
      description: https callback address where the event notification must be POST-ed

Derived from discussion in #24

So far (as of v0.1.0), we have 3 properties to define the area, which is always a circle centered in (latitude, longitude) with radius accuracy:

    latitude:
      $ref: '#/components/schemas/Latitude'
    longitude:
      $ref: '#/components/schemas/Longitude'
    accuracy:
      $ref: '#/components/schemas/Accuracy

In order to support more areas, we can consider Area as a polymorphic object, for example:

Area:
  description: The geometrical area considered for device location
  oneOf:
    - $ref: '#/components/schemas/Circle'
    - $ref: '#/components/schemas/Polygon'
    - $ref: '#/components/schemas/PostCode'
  discriminator:
    propertyName: type   

Apart from the current Circle, there are proposals to support Polygon (Orange) and PostCode (Telefónica)

Problem description

Links in Release description of v0.1.0 pointed to main, not to the release branch: https://github.com/camaraproject/DeviceLocation/blob/release-v0.1.0/

Expected action

Links corrected.

Additional context

Change already done :-) ... please check and close the issue.

Some weeks ago, a set of API design guidelines have been approved in commonalities.

Regarding terminolgy and style:

• Reduce telco-specific terminology in API definitions.
  • Related to issue #12.
• URI paths in lowercase and separated-by-hyphens.
  • Our paths are single word and already in lowercase
• OperationIds are defined in lowerCamelCase.
  • We are already compliant
• Objects are defined in CamelCase inside properties field. This affects declarations within definitions that are $ref in other parts.
  • We are already compliant
• API input and output business data will follow the snake_case notation.
  • We are NOT compliant. This affects property names.

Errors must include:

• A field status, which can be identified in the response as a standard code from list of Hypertext Transfer Protocol (HTTP) response status codes.
  • We have to add it to our model.
• A unique error code, which can be identified and traced for more details. It must be human readable; therefore, it must not be a numeric code. In turn, to achieve a better location of the error, you can reference the value or field that is causing it, and include it in the message.
  • We should review our current codes and probably define new codes for expected logical errors.
• A detailed description of message.
  • We are already compliant.

Proposed actions

• Most of changes apply to current property names, as they must be formattted in snake_case. This can be addressed together with issue #12 in a new PR, when new terms are agreed.

• We have to adapt errors, adding status, and at a same time we could enhance current documentation and examples. This can be done in separate PR.

Include locationType as a request parameter to extend location verification for the following business use cases. Can assign numbers as identifiers for location type.

ex:

• Real time location.
• Office/work location (most latched site/location in the day time).
• Home location (most latched site/location in the night time).