Research: Cross-resource references — `@link` objects only vs. flat `@id` strings for interoperability

[Sam-Bolling]

Finding

The server returns cross-resource references exclusively as @link objects (e.g., "system@link": { "href": "systems/<uuid>", "rel": "..." }) and never as flat @id strings (e.g., "system@id": "0520"). This is a research spike to determine which cross-reference format(s) the OGC spec mandates, what clients should expect, and whether both formats should be supported for interoperability.

Review Source: Live integration testing and client library audit from ogc-csapi-explorer and ogc-client-CSAPI_2
Severity: P4-Informational (research spike)
Category: API Design / Interoperability
Ownership: connected-systems-go

---

Problem Statement

When fetching resources like datastreams, the Go server returns cross-references to parent systems using @link objects:

{
  "id": "abc-123",
  "name": "Temperature",
  "system@link": {
    "href": "systems/def-456",
    "rel": "parent",
    "type": "application/geo+json"
  }
}

It does NOT return a flat system@id field. In contrast, OSH SensorHub returns flat @id references:

{
  "id": "0812",
  "name": "Temperature",
  "system@id": "0520"
}

Comparative behavior:

Server	system@id (flat)	system@link (object)
OSH SensorHub	✅ Present	❌ Absent
connected-systems-go	❌ Absent	✅ Present

Impact on clients:

Our client library (ogc-client-CSAPI_2) originally parsed only system@id. When pointed at the Go server, datastreams appeared to have no parent system — breaking the Explorer's map view (0 datastreams shown) and the data model diagram's system↔datastream navigation.

Workarounds applied:

1. Library parser (part2.ts): Added system@link.href fallback in parseBaseStream() — extracts system ID from the link href
2. Explorer (MapViewPage.vue): Added extractSystemId() helper that checks system@link.href → system@id → system@link chain
3. Explorer (DataModelDiagram.vue): Added system@link.href fallback for diagram navigation
4. Filed as library issue: Phase 8 / Task C1: Issue #166 — Part 2 @link fallback in cross-reference fields ogc-client-CSAPI_2#166

Research Questions

This spike should produce analysis, findings, and recommendations that may result in follow-on issues:

1. What does OGC 23-002 specify for cross-resource references? Does it mandate @id, @link, or both?
2. Are @id and @link supposed to be alternative encodings of the same relationship, or do they have different semantics? (e.g., @id for in-collection references, @link for cross-collection)
3. Should a conformant server provide BOTH @id AND @link? Or is one sufficient?
4. What about @link.href format — should it be a relative path (systems/uuid) or an absolute URL? Our Explorer's extractSystemId() must handle both.
5. How do other OGC API implementations handle this? (e.g., pygeoapi, ldproxy, GeoServer)
6. Should connected-systems-go also emit system@id alongside system@link for backward compatibility? Would this be a simple addition?
7. Are there other cross-reference patterns we haven't encountered yet? (e.g., deployment@link, procedure@link, datastream@link)

Expected Deliverables

• Analysis of OGC 23-002 cross-reference encoding requirements
• Inventory of all cross-reference fields in Part 1 and Part 2 resource types
• Comparison of @id vs @link behavior across known CSAPI server implementations
• Recommendation: emit both, emit one, or make it content-negotiable
• If changes are recommended, file follow-on implementation issue(s)

Scope

• ❌ Do NOT implement changes in this spike — research and recommend only
• ❌ Do NOT change client-side workarounds — they handle both formats and should remain

Related Issues

• ogc-client-CSAPI_2 #166: Library parsers only check @id, need @link.href fallback

References

#	Document	What It Provides
1	OGC 23-001 §7.2	Resource links and cross-references
2	OGC 23-002 §8-10	Part 2 resource JSON encoding
3	GeoJSON (RFC 7946)	Base format that CSAPI extends
4	ogc-client-CSAPI_2 #166	Library issue for @id vs @link parsing
5	Explorer commit 2f0869a	Client-side workaround for system@link.href fallback

[Sam-Bolling]

Evaluation result — research-resolved, no code changes recommended for this issue

Full write-up: docs/research/issue-evaluations/issue-006.md. Evidence (spec inventory + live transcripts) under docs/research/evidence/issue-006/.

Headline: the comparative table in the issue body has the conformance polarity inverted

Server	system@id (flat)	system@link (object)	OGC 23-002 says
OSH SensorHub	✅ Present	❌ Absent	Non-conformant — system@id is not defined on Datastream
cs-go	❌ Absent	✅ Present	Conformant — system@link is the spec field

A line-by-line read of OGC 23-002 (.tmp-csapi-part2.yaml lines 312/376/383/390/397 for Datastream, 3124/3135/3142/3149/3156 for ControlStream, 2602/2607/2611/2635 for Observation, 4053/4058/4062 for Command) yields a clean rule:

• @link (object with required href) for cross-collection / hierarchical refs that may carry rel, type, title, uid, hreflang, rt, if — i.e. wherever the target lives in a different collection or where the client may want a typed/titled reference. Used on Datastream/ControlStream/Observation/Command/CommandStatus/System/SamplingFeature/Deployment.
• @id (flat string) only for the immediate parent of a sub-resource where the parent collection is contextually fixed: observation.datastream@id (REQUIRED), command.controlstream@id (REQUIRED), commandStatus.command@id (REQUIRED), plus same-collection siblings samplingFeature@id on obs/cmd.

There is no system@id field defined on Datastream or ControlStream anywhere in the spec. The shape SensorHub emits at that level is a fork-local extension, not a spec encoding.

cs-go's implementation is exactly conformant

internal/model/domains/*.go mirrors the spec field-for-field — no plumbed-but-unconsumed gaps (contrast with #4):

• Datastream.{SystemLink,ProcedureLink,DeploymentLink,FeatureOfInterest,SamplingFeatureLink} → all @link ✓
• Observation.DatastreamID/Command.ControlStreamID → @id ✓
• Observation.ProcedureLink/Command.ProcedureLink → @link ✓ (procedure crosses collections)

Live confirmation on HEAD (https://129-80-248-53.sslip.io/csapi-go-head/):

// GET /datastreams?limit=1
{
  "id": "cf4cd80c-...",
  "system@link": { "href": "systems/666ed3fe-..." },   // spec-conformant
  "links": [
    { "href": "https://.../systems/666ed3fe-...", "rel": "ogc-rel:systems" }, // supplementary absolute
    { "href": "https://.../datastreams/cf4cd80c-.../observations", "rel": "ogc-rel:observations" }
  ]
}
// GET /observations?limit=1
{ "id": "...", "datastream@id": "b93d0040-...", "phenomenonTime": "...", "result": 42 }   // spec-conformant

Note: clients already have two discoverability paths to the parent system on a datastream — system@link.href (relative, spec-mandated) and links[rel="ogc-rel:systems"].href (absolute, derived in appendDatastreamAssociationLinks).

Verdicts on the seven research questions

1. Spec mandate? @link for the resources listed above; @id only at the in-collection / parent positions listed above. They coexist by design.
2. Same semantics? No. Different positions, different metadata capacity. Not interchangeable.
3. Emit BOTH? No. Spec defines exactly one shape per relationship. Adding system@id on Datastream is a non-spec extension that creates two sources of truth and may fail strict OAS31 validators.
4. Relative vs absolute href? Spec is format: uri (typically absolute) with an absolute example; cs-go emits relative "systems/<uuid>" inline. Candidate P3 enhancement to fix.
5. Other implementations? Out of spike scope — spec authority is sufficient.
6. Backward-compat system@id for SensorHub interop? No. Client-side handling is correct; ogc-client-CSAPI_2 #166 fixed it. If cross-stack interop is a project priority, file an issue against SensorHub instead.
7. Other cross-ref patterns? Inventoried — no surprises beyond the spec list.

Two minor polish items surfaced (will file as follow-ups, not blockers for closing #6)

• G1 [P3 enhancement] Inline system@link.href (and equivalents) is relative; spec example is absolute. Trivial fix — wrap via formaters.ToFunctionalAssociationHref exactly like the existing links[] builder does.
• G2 [P4 enhancement] Inline @link carries only href. The Link struct already supports rel/type/title/uid; populating type + title would save clients a round-trip when rendering previews. Pure UX win; zero spec risk.

Recommendation

Close #6 as research-resolved. No implementation owed against this issue. Client-side parser already handles the spec shape (#166). I'll file G1 and G2 as separate small enhancement issues for the conformance polish.

---

Methodology note: This was the inverse of issue #4. For #4, model fields were plumbed but not consumed; for #6, every model field IS consumed and IS spec-conformant — the issue's premise was a client expectation calibrated on a different (non-conformant) server, projected onto the conformant one as a "missing feature". Future spikes that ask "why doesn't server X look like server Y?" should start with the spec inventory, not the comparative table.

[Sam-Bolling]

Closing as not planned, in agreement with the maintainer.

Resolution

@SomethingCreativeStudios on the upstream triage pass: "Not conformant with spec." — i.e. the maintainer is rejecting the change this issue would have asked for, on the same grounds the evaluation reached. Posting the rationale chain so the closure is auditable.

Why no code change

The issue's premise was that cs-go emits system@link (object) where OSH SensorHub emits system@id (flat string), and asked whether cs-go should also emit system@id for backwards compat. After spec inspection the framing is inverted:

• system@link (object) is the spec-mandated shape for that relationship on Datastream and ControlStream. The bundled OAS31 (docs/research/standards/ogcapi-connectedsystems-2.bundled.oas31.yaml) defines no system@id field on either resource.
• The spec uses @link and @id for different positions in the data model — they are not interchangeable encodings:
  • @link (object with required href, optional rel/type/title/uid) is used for cross-collection / hierarchical refs: Datastream's system@link, procedure@link, deployment@link, featureOfInterest@link, samplingFeature@link; ControlStream's same five; Observation's procedure@link / result@link; Deployment's platform@link / deployedSystems@link; SamplingFeature's sampledFeature@link; System's systemKind@link; CommandStatus's oneOf link group.
  • @id (bare string) is used only where the target collection is contextually fixed: Observation's datastream@id (REQUIRED), samplingFeature@id; Command's controlstream@id (REQUIRED), samplingFeature@id; CommandStatus's command@id (REQUIRED).

So adding system@id on Datastream / ControlStream would introduce a non-spec extension property carrying two sources of truth for the same reference (drift risk, breaks strict OAS31 validators). That is exactly what the maintainer's "not conformant with spec" note is rejecting.

What the fork already gets right

cs-go's struct tags mirror the spec field-for-field (verified in §3 of the evaluation):

Resource model	Field tag	Spec match
Datastream.SystemLink	json:"system@link,omitempty"	✓
Datastream.{Procedure,Deployment,FeatureOfInterest,SamplingFeature}Link	@link variants	✓
ControlStream.*Link	(same five)	✓
Observation.DatastreamID	json:"datastream@id" (no omitempty — spec REQUIRED)	✓
Command.ControlStreamID	json:"controlstream@id" (no omitempty — spec REQUIRED)	✓
Deployment.{Platform,DeployedSystems}	@link	✓
SamplingFeature.SampledFeatureLink	sampledFeature@link	✓
System.SystemKind	systemKind@link	✓

Live confirmation on HEAD 4b994212 (T1, T3 in docs/research/evidence/issue-006/live-tests-head-2026-04-30.txt) matches: GET /datastreams carries system@link, GET /observations carries datastream@id, both spec-conformant.

Where the interop fix belongs

The publisher symptom that triggered this issue (clients expecting system@id from cs-go because SensorHub emits it) is a client-side problem:

• The client-side fix has already landed downstream in OS4CSAPI/ogc-client-CSAPI_2 #166 — clients should resolve via @link.href for cross-collection refs and via @id for context-fixed refs, exactly as the spec defines.
• If wider OSH ↔ cs-go interop is desired, the appropriate venue is an issue against OSH SensorHub (which is the non-conformant party here), not cs-go.

Sibling enhancements that DID land elsewhere

Two minor conformance / UX gaps the §6 evaluation flagged are already resolved upstream — distinct from #6 but worth noting so this closure doesn't paper over the related fixes:

• G1 — @link.href absolute vs relative. Originally inline system@link.href was "systems/<uuid>" (relative). Filed as [P3 enhancement] Inline @link.href should be absolute URI to match spec format: uri #24 and addressed in upstream commit d2d1347 ("Cleaned up data/controlstream's SystemLink"). Maintainer's note on [P3 enhancement] Inline @link.href should be absolute URI to match spec format: uri #24: "@link should be absolute, now all links follow config baseUrl."
• G2 — @link carries only href. Filed as [P4 enhancement] Populate rel/type/title/uid on inline @link objects #25; partially addressed in the same d2d1347 window. Maintainer's note: "Mostly there for most associations however not all fully enriched."

Neither belongs to #6 itself; both are tracked separately and either complete or in progress.

Mapping rationale → original research questions

Question (issue body)	Answer
Q1 — What does OGC 23-002 specify?	@link for cross-collection / hierarchical refs; @id for in-collection / context-fixed parent refs. Both coexist by design.
Q2 — Are @id and @link alternative encodings of the same relationship?	No. Different positions, different semantics.
Q3 — Should a conformant server emit both for the same relationship?	No. Single source of truth.
Q4 — Should @link.href be relative or absolute?	Absolute (per spec example). Already addressed via #24.
Q5 — How do other OGC API implementations handle this?	Out of scope; spec authority is sufficient.
Q6 — Should cs-go also emit system@id for backward compat?	No. This is the question the maintainer is closing as not-conformant-with-spec.
Q7 — Other cross-reference patterns?	Full inventory in §2 of the evaluation.

Cross-references

• Original evaluation: docs/research/issue-evaluations/issue-006.md (full spec inventory, struct-tag audit, T1–T3 live tests).
• Sibling enhancements addressed elsewhere: [P3 enhancement] Inline @link.href should be absolute URI to match spec format: uri #24 (absolute @link.href, fixed in d2d1347), [P4 enhancement] Populate rel/type/title/uid on inline @link objects #25 (richer @link enrichment, partially addressed in the same window).
• Client-side interop fix tracked at OS4CSAPI/ogc-client-CSAPI_2 #166.

Closing as not planned (won't fix), in agreement with the maintainer's triage.