SpatialPoint Serialization/Deserialization: Fixes spatial point serialization/deserialization bug

[dibahlfi]

Pull Request Template

Description

This PR adds System.Text.Json (STJ) serialization/deserialization support for all Microsoft.Azure.Cosmos.Spatial geometry types, resolving a bug where spatial types like Point could not be serialized or deserialized when using UseSystemTextJsonSerializerWithOptions or a custom STJ-based serializer.

closes #4744

Problem

The SDK's spatial types (Point, LineString, Polygon, etc.) only had Newtonsoft.Json converters. When users configured CosmosClientOptions.UseSystemTextJsonSerializerWithOptions, two failures occurred:

1. Deserialization failure — System.NotSupportedException on CreateItemAsync / ReadItemAsync because Point lacks a parameterless constructor and had no STJ JsonConverter.
2. Incorrect serialization — PatchItemAsync produced malformed JSON (e.g., raw CLR property names like position.longitude instead of GeoJSON coordinates arrays), because STJ fell back to default property serialization.

Solution

A complete set of 8 new STJ converters mirrors the existing Newtonsoft converter architecture, producing GeoJSON-compliant output identical to the Newtonsoft serializers. Dual [JsonConverter] attributes on each spatial model class allow the runtime to automatically select the correct converter based on the serializer in use.

Design

Architecture

GeometrySTJConverter          ← polymorphic factory for all 7 geometry types
├── PositionSTJConverter      ← [longitude, latitude, altitude?]
├── BoundingBoxSTJConverter   ← [minLon, minLat, ..., maxLon, maxLat, ...]
├── CrsSTJConverter           ← Named / Linked / Unspecified CRS
├── LinearRingSTJConverter    ← closed ring of positions
├── LineStringCoordinatesSTJConverter
├── PolygonCoordinatesSTJConverter
└── STJMetaDataFields         ← centralized GeoJSON property-name constants

Key Design Decisions

Decision	Rationale
Parallel implementation (not shared with Newtonsoft)	STJ and Newtonsoft have fundamentally different APIs (JsonElement vs JToken); sharing code is not feasible.
GeometrySTJConverter implements full Write()	Unlike Newtonsoft's GeometryJsonConverter (CanWrite = false), STJ requires explicit write logic for precise control over property order and formatting.
Dual [JsonConverter] attributes on model classes	[Newtonsoft.Json.JsonConverter] and [System.Text.Json.Serialization.JsonConverter] coexist on Geometry, Position, BoundingBox, Crs, etc. The runtime picks the correct one based on which serializer is active.
Numeric formatting matches Newtonsoft	Integer coordinates render as x.0; non-integers use "R" format for full precision. This ensures Assert.AreEqual(newtonsoftJson, stjJson) passes in tests.
STJMetaDataFields constants	Single source of truth for GeoJSON property names ("type", "coordinates", "geometries", "bbox", "crs", etc.) to prevent string-literal errors.

GeoJSON Types Supported

All 7 GeoJSON geometry types per RFC 7946:

• Point — single position
• LineString — array of positions
• Polygon — array of linear rings (exterior + holes)
• MultiPoint — array of positions
• MultiLineString — array of line-string coordinates
• MultiPolygon — array of polygon coordinates
• GeometryCollection — array of nested geometry objects (uses "geometries" key)

CRS (Coordinate Reference System) Handling

CRS Type	JSON Representation
Default (OGC WGS84)	Omitted from output
Named	{ "type": "name", "properties": { "name": "EPSG:4326" } }
Linked	{ "type": "link", "properties": { "href": "...", "type": "..." } }
Unspecified	null

Type Discrimination

The GeometrySTJConverter uses the "type" field in the GeoJSON payload to determine which Geometry subclass to instantiate during deserialization, mirroring the existing GeometryJsonConverter pattern.

Type of change

• Bug fix (non-breaking change which fixes an issue)

Changes

New Files (8)

• Spatial/Converters/STJConverters/GeometrySTJConverter.cs — polymorphic converter handling all geometry types
• Spatial/Converters/STJConverters/PositionSTJConverter.cs — [lon, lat, alt?] array converter
• Spatial/Converters/STJConverters/BoundingBoxSTJConverter.cs — flat min/max coordinate array
• Spatial/Converters/STJConverters/CrsSTJConverter.cs — Named, Linked, and Unspecified CRS
• Spatial/Converters/STJConverters/LinearRingSTJConverter.cs — closed position ring
• Spatial/Converters/STJConverters/LineStringCoordinatesSTJConverter.cs — multi-line coordinates
• Spatial/Converters/STJConverters/PolygonCoordinatesSTJConverter.cs — multi-polygon coordinates
• Spatial/Converters/STJConverters/STJMetaDataFields.cs — GeoJSON property-name constants

Modified Files (17)

• Spatial model classes (Point.cs, Position.cs, Geometry.cs, BoundingBox.cs, Crs.cs, LineString.cs, Polygon.cs, MultiPoint.cs, MultiLineString.cs, MultiPolygon.cs, GeometryCollection.cs, LinearRing.cs, LineStringCoordinates.cs, PolygonCoordinates.cs) — added [System.Text.Json.Serialization.JsonConverter] attribute
• CrsJsonConverter.cs — minor cleanup

Test Files (2)

• STJSpatialTest.cs — ~20+ test methods covering all geometry types, CRS variants, bounding boxes, additional properties, and round-trip fidelity (verifies STJ output exactly matches Newtonsoft output)
• ClientTests.cs — emulator integration tests for spatial types with STJ serialization

[sourabh1007]

If you are still making the changes, you can convert this PR to "draft" mode.

[xperiandri]

Looks like it needs to be rebased

[xperiandri]

@dibahlfi, any updates?

[kirankumarkolli]

It's different from existing Newtonsoft conversion. It seems the final form is not 1-1 JSON types conversion (like "prop" = "Value")

All converters need to exactly match existing Newton converts. And also lets please revisit the test coverage also.

[dibahlfi]

let me take a look.

[dibahlfi]

@kirankumarkolli Could you pls take a look again. I matched the STJ conversion to newtonsoft and updated the test cases.

[Copilot]

@NaluTripician I've opened a new pull request, #5638, to work on those changes. Once the pull request is ready, I'll request review from you.

[Maya-Painter]

Any reason there are not STJConverters for all of the spatial types?

[NaluTripician]

Any reason there are not STJConverters for all of the spatial types?

All spatial types are covered. The GeometrySTJConverter is a factory converter that handles all 7 geometry types (Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection) — mirroring how the Newtonsoft GeometryJsonConverter factory works. Individual STJ converters exist for coordinate/metadata types (Position, LinearRing, LineStringCoordinates, PolygonCoordinates, BoundingBox, CRS), providing exact 1:1 parity with the Newtonsoft converter set.