Add optional GeoJSON geometry schema and design guidance to Commonalities

[sergiobrisio]

docs: add optional GeoJSON geometry guidance for CAMARA APIs

What type of PR is this?

• enhancement/feature
• documentation

What this PR does / why we need it:

This PR introduces optional, non‑breaking support for GeoJSON (RFC 7946) as an additional geometry model in Commonalities.

Several CAMARA APIs (e.g., Dedicated Network Service Areas, Device Location Verification) require geometric comparison or spatial predicates such as within, overlaps, contains, or intersection area. These operations are natively supported by spatial engines and databases only when using standard geometry formats such as GeoJSON.

This PR:

• adds guidance documentation on when to use the existing CAMARA Area datatype vs. when to consider GeoJSON;
• introduces a new optional GeoJSONGeometry schema for initiatives that need GIS‑native behavior;
• preserves the CAMARA simplicity philosophy by keeping the existing Area/Circle/Polygon model fully valid;
• does not require any API to adopt GeoJSON;
• does not impose a oneOf pattern or force dual‑model support;
• allows each API initiative to independently evaluate which geometry model is most appropriate.

This ensures that advanced spatial APIs can rely on GIS‑native capabilities, without adding complexity to APIs that only require simple geometries.

Which issue(s) this PR fixes:

#586 and fixes camaraproject/DedicatedNetworks#93

Does this PR introduce a breaking change?

• Yes
• No

This PR only adds documentation and an optional GeoJSON schema.
It does not change the existing Area/Circle/Polygon datatypes, nor require any API to adopt GeoJSON. The schema is made available for future initiatives that may benefit from it.

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.

Changelog input

release-note
Add optional GeoJSONGeometry schema and guidance for APIs requiring spatial predicates; no changes to existing CAMARA Area model.

Additional documentation:

documentation/geojson-guidance.md

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: sergiobrisio / name: Stefano Brivio (73df44d, 845c9cb, e539209)

[rartych]

@sergiobrisio You can find more info about EasyCLA here: https://github.com/camaraproject/EasyCLA

[rartych]

GeoJSONGeometry:
type: object
description: RFC 7946 GeoJSON geometry object

I guess we need to define the object in details.

The example definition found on web:
GeoJSON-OAS3.yaml

[PedroDiez]

GeoJSONGeometry:
type: object
description: RFC 7946 GeoJSON geometry object

I guess we need to define the object in details.

The example definition found on web: GeoJSON-OAS3.yaml

And also add it in CAMARA_Common.yaml

[tlohmar]

Section 2.1 (link) refers to CAMARA common data types, which include the different Area Data Types.

I suggest in include some simple statements about the Areas data types and use of GeoJSON within Section 2.1 of the Design Guide document, including a link to this new document.

[tlohmar]

This new geojson-guidance.md document seem to be more a discussion document, motivating the needs for introducing GeoJSON. Maybe it is possible to describe the key aspects direction within Section 2.1 of the Design Guideline.

Key Aspects are:

• it is recommended to use the current CAMARA Area model (Circle / Polygon using custom JSON) from CAMARA_common.yaml for simple API transactions.
• APIs performing spatial predicates are recommended from using a GeoJSON, as defined in RFC 7946.
  • Could make sense to add Section 3.3 (When GeoJSON helps) and Section 4 (Circles in GeoJSON)
  • Maybe add an example definition.

[patrice-conil]

Integrating GeoJSON as an alternative is an excellent initiative. While experimenting with population density data, I realized that some of our previous choices were problematic. Specifically, the naming conventions for some discriminators don't allow for the easy integration of new models. In our Area definitions, the discriminator is called "areaType," whereas it's called "type" in the GeoJSON standard... making it difficult to easily code the oneOf property.

We would likely benefit from consistently naming the property used as a discriminator to more effectively manage polymorphism ... probably using "type" the most common choice. What do you think about?