Task

Preserve OGC 23-002 Required cross-reference fields (system@id, datastream@id, controlstream@id, command@id, etc.) in the five Part 2 parser functions by adding optional parent-reference properties to model interfaces and extracting them during parsing.

Finding Reference: Demo app finding from ogc-csapi-explorer commit ecce874 (parent navigation breadcrumbs) and ogc-csapi-explorer#32 (command status history)
Severity: Moderate
Category: Design gap — spec-required associations discarded during parsing
Ownership: Ours

Problem Statement

The five Part 2 parser functions (parseDatastream, parseControlStream, parseObservation, parseCommand, parseCommandStatus) intentionally discard all cross-reference fields present in the raw JSON. These fields encode Required parent–child associations per OGC 23-002 resource model tables:

Each parser's JSDoc explicitly says "intentionally ignored" and the test suite has ~10 not.toHaveProperty assertions verifying the stripping.

Evidence:

// ogc-csapi-explorer ResourceDetail.vue — must read from raw JSON, not parsed model
if (typeof raw['system@id'] === 'string') {
  links.push({ resourceType: 'systems', resourceId: raw['system@id'] })
}
if (typeof raw['datastream@id'] === 'string') {
  links.push({ resourceType: 'datastreams', resourceId: raw['datastream@id'] })
}

Impact: Any consumer wanting to navigate upward in the resource hierarchy (observation → datastream → system) must bypass typed models and work with raw JSON, undermining the purpose of having typed parsers.

Findings Report

Issue #103 Findings Report — Parsed Part 2 Models Discard Cross-Reference Fields

Recommendation: FIX — purely additive change (optional interface fields, same extraction pattern), zero backward-compatibility risk, strengthens spec conformance of the contribution.

Files to Create or Modify

Proposed Fix

Add optional parent-reference fields to the 5 Part 2 model interfaces and extract them in the parsers using the same tolerant extraction pattern already in use.

Interface additions (all optional ?):

• Datastream.systemId?: string
• ControlStream.systemId?: string
• Observation.datastreamId?: string, samplingFeatureId?: string, featureOfInterestId?: string
• Command.controlStreamId?: string
• CommandStatus.commandId?: string

Parser extraction (same typeof obj['field'] === 'string' ? { fieldName: ... } : {} pattern):

...(typeof obj['system@id'] === 'string'
  ? { systemId: obj['system@id'] as string }
  : {}),

Scope boundary — @link fields: The minimum viable fix extracts @id fields only (simple strings). The @link structured objects ({ href, uid?, title? }) are a lower-priority addition that can be deferred to keep the initial diff smaller.

Scope — What NOT to Touch

• ❌ Do NOT modify Part 1 parsers (GeoJSON Feature parsers) — they handle cross-references differently
• ❌ Do NOT modify the links array handling — @id extraction is additive, not a replacement
• ❌ Do NOT modify url_builder.ts — that issue is tracked separately ([SPLIT] assertResourceAvailable() overly strict for per-ID methods → #156 + #157 #100, [DEFERRED] URL builder: command/observation CRUD methods require top-level endpoints, fail on nested-only servers #102)
• ❌ Do NOT modify assertResourceAvailable() — that issue is tracked separately ([SPLIT] assertResourceAvailable() overly strict for per-ID methods → #156 + #157 #100)
• ❌ Do NOT add @link structured objects in the initial fix — scope to @id strings only
• ❌ Do NOT modify files outside the "Files to Create or Modify" table above
• ❌ Do NOT refactor existing code unless required to complete this task

Acceptance Criteria

• model.ts has optional cross-reference fields on all 5 Part 2 interfaces
• part2.ts parsers extract @id fields using the existing tolerant extraction pattern
• All new interface fields are optional (?) — zero impact on existing consumers
• part2.spec.ts ~10 not.toHaveProperty assertions updated to verify extraction
• New test cases verify extraction of each cross-reference field
• Existing tests still pass (npm test)
• No lint errors
• No TypeScript compilation errors (tsc --noEmit)

Dependencies

Blocked by: Nothing
Blocks: Nothing (purely additive)

Operational Constraints

⚠️ MANDATORY: Before starting work on this issue, review docs/governance/AI_OPERATIONAL_CONSTRAINTS.md.

Key constraints:

• Precedence: OGC specifications → AI Collaboration Agreement → This issue description → Existing code → Conversational context
• No scope expansion: Fix the finding, nothing more — extract @id fields only
• Minimal diffs: Use the identical tolerant extraction pattern already in every parser (~3–5 lines per function)
• No refactoring: Do not change existing field types, reorder existing fields, or restructure parser logic
• Backward compatibility is paramount: All new fields must be optional — existing consumers must see zero difference

References

Related Issues

• #102 — URL builder nested paths (DEFERRED); workaround required extracting controlstream@id from raw JSON — the exact gap this issue addresses
• #100 — assertResourceAvailable() overly strict (DEFERRED); related Part 2 interoperability theme
• #101 — parseDataRecord() complex types (FIX applied); similar spec-conformance gap precedent
• ogc-csapi-explorer#32 — Command status history; first encountered missing controlstream@id