Deferred enhancement: SWE Common–aware result-vector extraction (out-of-scope until upstream broadens scope)

[Sam-Bolling]

Status — Deferred

This issue is filed deferred from day one. It is the architecturally correct successor to #169 (which closed wontfix because the heuristic version proposed there had unrecoverable design problems). It is not intended to be picked up before:

1. Upstream PR #136 lands (or is decisively rejected), AND
2. Library scope is explicitly broadened to include SWE Common parsing, AND
3. There is at least a second consumer beyond ogc-csapi-explorer demonstrating need.

Filed now solely so the architecturally correct future path has a tracking number distinct from the heuristic approach rejected in #169.

Problem

CSAPI observation result payloads carry schema-described data, but our library currently passes result through as unknown (src/ogc-api/csapi/model.ts:595). Consumers wanting to extract structured values (most commonly geographic coordinates for map rendering) must build per-consumer extraction logic. The heuristic field-name-matching approach was rejected in #169 on five grounds — see that issue's status banner for the full reasoning. Headlines: unit ambiguity (km/m/ft/unspecified across publishers), false-positive risk, schema-blindness, maintenance trap, and discouraging publishers from putting position on SamplingFeature where it spec-belongs.

The architecturally correct path

OGC 23-002 Part 2 references SWE Common for result schemas. SWE Common defines:

• Vector types with an explicit referenceFrame (CRS URI — e.g. EPSG:4326 for WGS 84)
• Per-component definition URIs (e.g. SWE Common's standard latitude/longitude/altitude definitions)
• Per-component uom (units of measure) — eliminates the unit-ambiguity problem from Closed (wontfix): heuristic coordinate extraction not adopted; architecturally correct path tracked at #171 #169 entirely

A schema-aware extractor would:

1. Read the datastream's resultStructure (and optionally resultEncoding) to locate components by definition URI.
2. Apply the per-component uom to return values with explicit, typed units (e.g. { value: 408, unit: 'km' } rather than { alt: 408 }).
3. Optionally project to a target CRS using the declared referenceFrame.

This is the right answer. It is also a substantial body of work — SWE Common parsing is non-trivial, and the library does not currently parse SWE Common at all.

Out of scope until trigger conditions are met

• ❌ Do not start implementing this until trigger conditions 1+2+3 above are all met. Pre-implementation work has a high probability of being thrown away if upstream rejects D-1: Resolve SystemTypeUris name collision between model.ts and constants.ts #136 or scopes the library narrowly.
• ❌ Do not "start small" with a heuristic version. The heuristic version is exactly what Closed (wontfix): heuristic coordinate extraction not adopted; architecturally correct path tracked at #171 #169 rejected. Either we have schema-aware extraction or we don't ship library-level extraction at all.
• ❌ Do not absorb the consumer's 30-line helper from ogc-csapi-explorer's MapViewPage.vue. That helper continues to be the right home for non-schema-aware extraction in the consumer's repo.

Acceptance criteria (when this is eventually picked up)

• Trigger conditions 1+2+3 in the Status section are all met before work begins.
• Extractor reads resultStructure (not field names) to identify components.
• Returns values with explicit uom attached (no bare number for quantities with units).
• Returns referenceFrame (CRS URI) for vector quantities so consumers can project.
• Tests cover at least three real publishers from different SWE Common encodings.
• Does not regress the result?: unknown pass-through behavior — extraction is opt-in via a separate function.

References

#	Source	Role
1	OS4CSAPI/ogc-client-CSAPI_2#169	Closed wontfix predecessor; reasoning for rejecting the heuristic approach
2	docs/research/references.md — Research Findings Not Adopted, Finding 1	Six-convention table + rejection rationale + defensive guidance
3	OGC 23-002 §13.3	Observation resources — result is schema-dependent
4	OGC SWE Common Data Model 2.0 (OGC 08-094r1)	Vector / DataRecord / uom definitions
5	OS4CSAPI/ogc-csapi-explorer MapViewPage.vue	Current consumer-side 30-line extractLatLonFromResult() — TODO filed to replace with this once shipped
6	Upstream PR #136	Trigger condition for picking this up