Add an “Area” data-type into CAMARA_common.yaml

[tlohmar]

Problem description

Multiple APIs are using a similar data type (a profiled variant) for describing an Area, which allows a description of a service area or geographical area in form of a circle and/or a polygon.

• The location-retrieval API (Device Location), region-device-count API and the proposed NetworkSliceBooking API allow an Area definition in form of a circle or a polygon.
• The geofencing-subscriptions API (Device Location) and the location-verification (Device Location) API only allow circles.
• The population-density-data API only allows a polygon.

Note, a similar ‘Area’ definition is also available in 3GPP (TS 29.572). There are some differences, like the data type is named GeographicArea or the PointList is a list of GeographicalCoordinates (no Points).

Expected action

• A new data type for describing service areas is added to CAMARA_common.yaml.
• Potential restrictions (e.g. allowing intersecting polygon lines, etc) should be discussed and documented.

[PedroDiez]

@jlurien FYI for any consideration. Issue is going to be enhanced with more info.

[tlohmar]

When creating an Area Data-Type in CAMARA_common.yaml, the following modifications/ extensions should be discussed

• Rename the Point Data-Type to GeographicalCoordinate (see 3GPP LMF Location) to make it more developer friendly.
• Make the AreaType definition extensible (forward compatible), so that additional types (like a 3D polygon to capture also drone/UAV use-cases) can be easily added in future.
• Allow different units in the circle definition. Currently, the unit of the radius is always in meter.
• Add constrains to the polygon definition to simplify implementations. For example, prohibit intersections.

[chinaunicomyangfan]

@tlohmar I support the idea. In fact, when defining areas in RegionDeviceCount and NetworkSliceBooking, we referred to the definition of area in DeviceLocation due to the lack of a common definition. If 3GPP has a complete definition standard, I believe it is reasonable to follow 3GPP's definition to create a common definition for area.

[gregory1g]

having a consistent representation of the same area is a good idea. From the PopulationDensity API group point of view the important criteria we must secure are: 1) every API can decide which type of areas it supports. For example, an API can support only circles or only polygons or both. 2) the structure representation must stay simple (afaik, this was one of the reasons why people did not take TS 29.572 "as is")

Besides this, there are two other issues which one need to decide: a. Should Camara API on the global level introduce limitations like 15 vertexes for a polygon? Why exactly 15 and why all APIs must follow it for input and output? b. Renaming (like Point -> GeographicalCoordinates) is a not backward compatible change, therefore it should better be agreed and adapted by all APIs before September meta release.

PS: regarding renaming suggested in the comment

Rename the Point Data-Type to GeographicalCoordinate (see 3GPP LMF Location)

TS 29.572 uses GeographicalCoordinateS (plural)

[tanjadegroot]

Another source of inspiration for the data type could be objects defined by The GeoJSON Specification (RFC 7946). See:

• https://geojson.org/
• https://datatracker.ietf.org/doc/html/rfc7946

[bigludo7]

Completely aligned on having a consistent representation across our API.

Now about the value itself I'm bit more mixed.

• in GeoJson I did no see a circle representation in the rfc9646 (I missed something @tanjadegroot ?)
• In 3GPP TS129 572 I did not find either circle & got a POINT_UNCERTAINTY_CIRCLE which is not very nice to put in our API for non-telco developer (I missed something @tlohmar @gregory1g? )

Could worth to have some discussion about keep it standard (and which standard?) vs keep simple.

[jlurien]

Our model in DeviceLocation is almost the same as 3GPP LMF Location API (TS29.572), but with different names. 3GPP PointUncertaintyCircle (point + uncertainty) is equivalent to our Circle (center + radius), and Polygon is also an array of coordinates delimiting the boundary (pointList vs boundary), both with length 3-15 (we copied the limit from them).

GeoJson uses a more complex, and I would say less intuitive, model. Polygons for example are defined as an array of arrays of arrays, allowing the definition of polygons with holes. And Circles are not explicitly specified AFAIK.

It would be good to include the common schemas in the common artifact and find some way to reference them from the specs. e.g. "$ref": "CAMARA_common.yaml#/components/schemas/XXX"