Commonalities: add GeoJSON (RFC 7946) as optional alternative geometry model

[sergiobrisio]

Proposal: add GeoJSON as optional alternative geometry model in Camara Commonalities

Summary

The current CAMARA Area datatype (CIRCLE/POLYGON with a custom schema) was originally adequate for simple geofencing-like use cases [location-retrieval API (Device Location), region-device-count API, NetworkSliceBooking API,population-density-data API, dedicated-network API, MostFrequentLocation API].
However, with the introduction of the Service Areas Discovery API (e.g., POST /retrieve-service-areas), CSP implementations now need to perform geographic search operations, such as:

• point‑in‑area
• area‑overlap
• area‑coverage

These are standard GIS operations, but the current CAMARA’s custom geometry model is not compatible with the search capability offered by GIS engines and spatial databases that CSPs use internally.

This Issue proposes that CAMARA adopt GeoJSON RFC 7946 as an alternative, fully valid geometry representation, while keeping the legacy Area schema for backward compatibility.

It also clarifies how to safely support circles in a world where GeoJSON has no native “Circle” type, which has generated concerns in the previous similar issue #242.

---

1. Problem Overview

1.1 A new requirement in CAMARA: geographic search

The new Service Areas discovery flow introduces three search modes that require spatial algorithms:

• atLocation → check whether a point lies inside an area
• overlappingArea → check whether two areas intersect
• coveringArea → check whether one area fully contains another

These operations require:

• geometric computation,
• spatial indexing (e.g., R‑tree),
• consistent coordinate handling.

1.2 Current issue

The existing CAMARA Area schema (custom JSON for CIRCLE/POLYGON) cannot be consumed directly by GIS engines, forcing each operator to:

• build custom parsers,
• re‑implement spatial algorithms (give up optimizations already available natively in GIS products),
• maintain dual geometry models,
• add unnecessary translation logic between CAMARA and internal GIS/Inventory systems,
• risk inconsistencies and different behaviors across implementations.

This Issue proposes that CAMARA Commonalities should adopt GeoJSON RFC 7946 as an alternative supported geometry model, while keeping the existing CAMARA Area type for backward compatibility.

---

2. Why GeoJSON is the right standard

GeoJSON RFC 7946 is:

• widely adopted across spatial DBs, GIS engines, backend systems, Front-End libraries;
• directly indexable using native spatial indexes by the most common GIS engines PostGIS, Oracle Spatial, SQL Server Geography, Elasticsearch, MongoDB, but also MariaDB, Snowflake used as spatial DB;
• simple and JSON-native, fits API payload with minimal cognitive load;
• sufficient for all area discovery requirements: Polygon, MultiPolygon, GeometryCollection, LineString, GeometryCollection.

3 About Circles: is the lack of a “Circle” type in RFC 7946 a blocker?

This was a major concern in Issue #242, but is technically solvable and aligned with GIS industry practice.

3.1 How GIS systems handle circles internally

Most telco planning systems and spatial DBs represent “circles” in one of two ways:

flowchart LR
    A[/Circle as Input/] -->|Internal<br/>Geometry<br/>Engine| B["Native curved type(e.g.,<br/>SQL/MM CircularString,<br/>Oracle SDO_GEOMETRY arcs)"]
    B --> C["Linearization for operations<br/>(spatial index, queries)"]
    C --> D[/Polygon for export / API/]

Loading

In practice:

• Even GIS tools themselves do not index GeoJSON directly, they all convert it into geometry models and index those
• Internally in GIS: Some engines support curved geometries (e.g., SQL/MM CircularString in PostGIS/SQL Server; Oracle Spatial arcs).
• For indexing and search: All engines convert curves → polygonal approximation for spatial operations.
• For exchange formats:
  • Shapefile → polygon only
  • GeoPackage → polygon only
  • GeoJSON → polygon only

This means CAMARA has not advantages in preserving an internal curved representation, because operators will still have to flatten it to polygons to perform spatial queries in their backend GIS or Spatial DB systems.
Asking CSPs to index a custom CAMARA geometry model is not giving benefits...

CSPs would need to build a custom equivalent of PostGIS/Oracle for spatial search on CIRCLE / POLYGON JSON fragments with no toolchain support

flowchart LR

    %% --- RIGHT SIDE: CAMARA CUSTOM GEOMETRY (inefficient) ---
    subgraph B[CUSTOM CAMARA<br/>Geometry Flow]
        B1["CAMARA CIRCLE / POLYGON<br/>(Non-standard JSON)"]
        B2[Custom Parser & Converter]
        B3["Home-made Spatial Index<br/>(CSP must build)"]
        B4["Reimplemented Spatial Ops<br/>(within / overlaps / contains)"]
    end

    %% --- LEFT SIDE: GEOJSON PATH (correct, efficient) ---
    subgraph A[GeoJSON-based Flow]
        A1["GeoJSON Geometry<br/>(Polygon / MultiPolygon)"]
        A2["Native GIS Engine<br/>(PostGIS / Oracle / SQL Server / Spatial DB)"]
        A3[Spatial Index<br/>R-tree / GiST / Native]
        A4[Efficient Spatial Search<br/>within / overlaps / contains]
    end

    A1 -->|Interchange format <br/>understood by GIS| A2
    A2 -->|Stores as<br/>internal geometry| A3
    A3 -->|Indexed operations| A4



    B1 -->|CSP must translate<br/>with custom algorithms| B2
    B2 -->|No native<br/>GIS support| B3
    B3 -->|Custom math<br/>& algorithms| B4

    %% --- VISUAL CONTRAST ---
    A4 -- Efficient &<br/>reusable --> Result1((✔️))
    B4 -- Complex, costly,<br/>inconsistent --> Result2((⚠️))

Loading

3.2 Safe options for representing circles in GeoJSON

3.2.1 Option A — Convert circles to Polygon (recommended, RFC-compliant)

• Circle approximated with N segments (N>=32 or tolerance-based)
• Industry standard
• Works with all GIS engines and DBs
• No ambiguity

3.2.2 Option B — Use a Feature(Point) + radius property (GeoJSON extension)

As implemented officially by Microsoft Azure Maps:

{
  "type": "Feature",
  "geometry": { "type": "Point", "coordinates": [lon, lat] },
  "properties": { "subType": "Circle", "radius": 100 }
}

Used only as an input shorthand; provider converts to polygon.

3.2.3 Option C — Allow a non-standard "type": "Circle" for backwards compatibility

Acceptable only as a transitional mechanism, with mandatory conversion to Polygons internally.

4. The Real Problem: Dual Geometry Model → High Implementation Cost

CSPs must currently maintain two parallel geometry models:

• CAMARA’s custom Area schema
• GeoJSON/geometry model used by internal GIS systems

This results in:

• custom spatial indexing
• error-prone conversions
• differences in precision
• inconsistent behavior among providers
• loss of optimized GIS features

4.1 Dual‑model complexity today

flowchart TB
    subgraph CAMARA_API["CAMARA API<br/>(custom geometry)"]
        A1[CIRCLE schema]
        A2[POLYGON schema]
        A3[Search Request]
    end

    subgraph BACKEND["Operator Backend"]
        B1["GIS / Spatial DB<br/>(consumes GeoJSON)"]
        B2["Spatial Index<br/>(R-tree, GiST…)"]
        B3[Native Spatial Ops]
    end

    A1 -->|custom parsing| C1[Converter]
    A2 -->|custom parsing| C1
    A3 -->|needs spatial ops| C1
    C1 --> B1
    B1 --> B2 --> B3
    B3 -->|results| C2[Convert back<br>to CAMARA schema]
    C2 --> A3

Loading

This increases cost, leads to performance variability, and introduces interoperability risks.

5. Why GeoJSON solves the spatial search problem

With GeoJSON, CSPs can forward the geometry directly to spatial engines and databases, without translation, without custom indexing logic.

flowchart TB
    subgraph CAMARA_GJ["CAMARA API using GeoJSON"]
        G1[GeoJSON geometry]
        G2[Search Request]
    end

    subgraph BACKEND_GJ["Native GIS Backend"]
        H1[Spatial DB]
        H2[Spatial Index]
        H3[GIS Search]
    end

    G1 --> H1
    G2 --> H1
    H1 --> H2 --> H3
    H3 --> G2

Loading

Using GeoJSON allows operators to reuse:

• existing GIS infrastructure,
• existing spatial DB queries,
• existing indexing structures,
• existing frontend mapping libraries.

This means CAMARA does not need to encode circles natively.

6. Benefits

Benefit	Impact
Interoperability	Ensures consistent behaviour across CSPs using a common geometry standard.
Deterministic geometry behaviour	Reduces discrepancies in precision, tolerance, and geometric evaluations.
Simpler implementations	Allows CSPs to reuse existing GIS logic instead of reimplementing spatial algorithms.
Faster certification & testing	Standard geometry model reduces ambiguity and provider-specific variations.
Performance	Leverages optimised spatial operations of mature GIS/DB engines.
Future-proofing	Provides a scalable base for future CAMARA APIs requiring spatial operations.
Flexibility	Legacy CAMARA Area model remains valid; GeoJSON used when needed.
No dual-model	Eliminates the need to maintain both CAMARA Area and internal GeoJSON/GIS models.
No conversion overhead	Removes parsing, translation, and geometry reconstruction between models.
GIS-native spatial queries	Enables direct use of DB/GIS spatial indexes (R-tree, GiST) for within/overlaps/contains.

7. Open Questions

1. Should GeoJSON become the preferred geometry model for all new CAMARA APIs? (recommended vs required)
2. Should CAMARA define a standard polygon tolerance for circle -> polygon conversion?
3. Should the Point+radius extension be formally included as a Commonalities extension?
4. Should the legacy CIRCLE type of Camara model be deprecated in future major releases?

8. Proposal

We propose that CAMARA introduce GeoJSON RFC 7946 as an alternative geometry model in Commonalities.

This enables APIs that require spatial predicates (within, overlaps, contains, intersection area) to rely on a GIS‑native format, while keeping the existing CAMARA Area datatype unchanged for APIs with simpler needs.

GeoJSON SHOULD be:

• optional,
• available as a reusable Commonalities schema,
• recommended for APIs requiring geometric search or comparison,
• coexisting with the existing Area/Circle/Polygon datatypes.

This ensures zero impact on existing APIs while providing a scalable path for new ones.

---

8.1 Detailed Proposal (draft PR)

8.1.1 Add GeoJSON as a valid alternative representation in Commonalities

Introduce a new reusable type, compliant with RFC 7946:

components:
  schemas:
    GeoJSONGeometry:
      description: RFC 7946 GeoJSON geometry object
      type: object
      additionalProperties: true

Allow both representations wherever areas are used:

oneOf:
  - $ref: "#/components/schemas/Area"      # current CAMARA model
  - $ref: "#/components/schemas/GeoJSONGeometry"  # new standard model

Notes:
In this way GeoJSON is introduced as an optional geometry representation.

Existing APIs do not change and may continue to use the current CAMARA Area model (Circle/Polygon).
API designers MAY choose either model:

• CAMARA AreaType model → for simple geometries and APIs that only produce areas.
• GeoJSON → for APIs requiring spatial search, geometric comparison, indexing, or advanced area handling.

This establishes a clear and non-breaking evolution path.

8.1.2 Define Circle handling

Define clear rules for Circle handling:

• Circles MUST be converted to Polygon for the authoritative geometry
• APIs MAY accept a Feature(Point+radius) as convenience
• Providers MUST return Polygons in the official representation

Provide guidance for:

• polygon tolerances
• geodesic buffering recommendations
• expected orientation and closure rules

8.1.3 Recommend spatial-index rules

• GeoJSON geometries SHOULD be passed directly to spatial DB indexes.
• No reimplementation of spatial algorithms is required at CAMARA level.

8.1.4 API Design Guidance

• Simple APIs (that only return a device location or a provisioning area) MAY continue using the existing Area / Circle / Polygon.
• APIs that require spatial predicates (e.g., containment, overlap, intersection area, match rate) SHOULD use GeoJSON, as GIS engines natively support these operations on standard geometries.

This keeps the learning curve low while ensuring consistency where geometry becomes operationally significant.

Optional: include guidance in the API Design Guide to clarify when to use CAMARA Area vs GeoJSON.

8.1.5 Cross‑reference with Device Location Verification

The Device Location Verification API (from the DeviceLocationVerification also relies on geometric comparisons (within/contains/intersects/overlaps/disjoint, intersection area). Using GeoJSON in Commonalities would provide a shared, standards‑based geometry for those APIs as well.

---

[PedroDiez]

Think is reasonable to define a GeoJSON schema in Commonalities for those APIs which may need such approach based on their scenarios and business needs.

However, would not force that all APIs that use the Area concept MUST support both options in their design, each initiative should analyze which area model might be most suitable. So as we should not impose the oneOf model for these kind of APIs

[bigludo7]

Thanks for the proposal @sergiobrisio - make sense for me your proposal to define Commononalities schema

I see the value of this proposal and I imagine that GeoJSON can provide new capabilities for geometry model but even if @sergiobrisio explain very well it brings additional layer of complexity.

In my view, "CAMARA Philosophy" is to bring very simple API to developer that are not Telco or GIS "fluent".

So I imagine we can have some UC where the consumer is familiar with GeoJSON and will leverage it but we must not enforce it and should be a project per project discussion IMHO. As such I tend to be aligned with @PedroDiez to not enforce the oneOf.

[sergiobrisio]

Just created the PR:

#594

@PedroDiez @bigludo7 may you contribute in the review?

Special notes for reviewers:

• GeoJSON is proposed as an optional alternative, not as a required model.
• The existing CAMARA Area model remains valid and unchanged.
• No oneOf pattern is mandated.
• This PR only provides guidance + optional schema, enabling GIS‑native behavior for APIs that require spatial predicates.
• Adds no operational complexity to APIs that simply return a device area.

Feedback on naming, wording of the guidance, and file placement (e.g., docs/geojson-guidance.md and, if included, code/API_definitions/geojson.yaml) is welcome.