Phase 2.6: DataStreams Methods

[Sam-Bolling]

Task

Implement all 11 DataStreams methods in url_builder.ts and add DataStreams method tests to url_builder.spec.ts. DataStreams is the sixth Phase 2 resource type, the first Part 2 resource, and introduces temporal query parameters (phenomenonTime, resultTime) and schema retrieval.

ROADMAP Reference: Phase 2, Task 6 — DataStreams Methods (~2–2.5 hours implementation + ~0.5 hour testing, Medium-High complexity)

---

Files to Create or Modify

File	Action	Est. Lines	Purpose
src/ogc-api/csapi/url_builder.ts	Modify	~75–100 added	Add 11 DataStreams methods with resource validation
src/ogc-api/csapi/url_builder.spec.ts	Modify	~45–55 added	Add DataStreams method tests

Blueprint Reference

Follow the Systems methods pattern established in Issue #5 (same file). Also reference the EDR pattern in src/ogc-api/edr/url_builder.ts (562 lines) for resource validation, URL construction, and query parameter appending. The schema endpoint (getDataStreamSchema) and observation creation (createObservation) are new patterns not present in Part 1 resources.

Scope — What to Implement

11 DataStreams Methods

Each method validates resource availability (~2 lines), builds a URL using buildResourceUrl(), appends query parameters using buildQueryString(), and returns the constructed URL string.

Collection query:

• getDataStreams(options?: DataStreamQueryOptions): string — GET /datastreams with pagination, filtering, temporal params, sorting

Single resource:

• getDataStream(id: string, options?): string — GET /datastreams/{id}

CRUD operations:

• createDataStream(body: object): string — POST /datastreams
• updateDataStream(id: string, body: object): string — PUT /datastreams/{id}
• deleteDataStream(id: string): string — DELETE /datastreams/{id}

Schema retrieval:

• getDataStreamSchema(id: string, options?): string — GET /datastreams/{id}/schema (note: obsFormat parameter is required per Part 2, Req 11; omitting it returns 400)

Observation sub-resource:

• getDataStreamObservations(id: string, options?): string — GET /datastreams/{id}/observations (supports cursor-based pagination)
• createObservation(datastreamId: string, body: object): string — POST /datastreams/{datastreamId}/observations

Association links:

• getDataStreamSystems(id: string, options?): string — GET /datastreams/{id}/systems (systems producing this stream)
• getDataStreamProcedures(id: string, options?): string — GET /datastreams/{id}/procedures (procedures for this stream)

History:

• getDataStreamHistory(id: string, options?): string — GET /datastreams/{id}/history

DataStreams Query Parameters

DataStreams support: system, observedProperty, foi, samplingFeature, procedure, datetime, id, uid, q, property filters, limit, offset, f, sortBy, sortOrder.

Additionally, the getDataStreamObservations sub-resource method supports Part 2 temporal parameters: phenomenonTime, resultTime (including the latest special value for resultTime), and cursor-based pagination (cursor instead of offset).

All parameters are serialised by the shared buildQueryString() helper (Issue #3). Temporal support: datetime (validTime), phenomenonTime, resultTime — see Guide §6 temporal applicability matrix.

JSDoc Requirements

• Document each method with @param for all parameters, @returns description, and usage example
• Add @see links to OGC CSAPI Part 2 specification sections for DataStreams endpoints
• Document the obsFormat requirement on getDataStreamSchema
• Document temporal query patterns (phenomenonTime, resultTime, latest special value)
• Follow the JSDoc style in src/ogc-api/edr/url_builder.ts and the Systems methods from Issue Phase 2.1: Systems Methods #5

Testing Requirements

• Extend src/ogc-api/csapi/url_builder.spec.ts (~45–55 lines)
• Test temporal filtering (getDataStreams with phenomenonTime, resultTime parameters)
• Test schema retrieval (getDataStreamSchema with obsFormat parameter)
• Test observation creation (createObservation with datastream ID)
• Test cursor-based pagination on getDataStreamObservations
• Test CRUD operations produce correct URLs
• Test resource validation — calling any DataStreams method when datastreams is not in availableResources throws an error
• Follow test patterns from Systems tests (Issue Phase 2.1: Systems Methods #5) and src/ogc-api/edr/url_builder.spec.ts

Scope — What NOT to Touch

• ❌ Do NOT implement Systems, Deployments, Procedures, Sampling Features, Properties, Observations, Control Streams, or Commands methods — those belong to Issues Phase 2.1: Systems Methods #5–Phase 2.5: Properties Methods #9 and Phase 2.7: Observations Methods #11–Phase 2.9: Commands Methods #13
• ❌ Do NOT modify model.ts — type definitions belong to Issue Phase 1.1: Create Type System (csapi/model.ts) #1
• ❌ Do NOT modify helpers.ts — helper utilities belong to Issue Phase 1.2: Create Helper Utilities (csapi/helpers.ts) #2
• ❌ Do NOT modify the constructor, buildResourceUrl(), buildQueryString(), extractAvailableResources(), or availableResources — those belong to Issue Phase 1.3: Create Stub QueryBuilder (csapi/url_builder.ts) #3
• ❌ Do NOT modify endpoint.ts, info.ts, or src/index.ts — integration belongs to Issue Phase 1.4: Integrate with OgcApiEndpoint #4
• ❌ Do NOT modify any Part 1 resource methods (Issues Phase 2.1: Systems Methods #5–Phase 2.5: Properties Methods #9)
• ❌ 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

• url_builder.ts contains all 11 DataStreams methods listed above
• Each method validates resource availability before constructing a URL
• Each method uses buildResourceUrl() and buildQueryString() helpers
• getDataStreamSchema correctly includes the obsFormat parameter
• All new methods have complete JSDoc documentation with @param, @returns, @see
• url_builder.spec.ts contains DataStreams tests covering temporal filtering, schema retrieval, observation creation, cursor pagination, CRUD, and resource validation (~45–55 lines)
• Existing tests still pass (npm test)
• No lint errors

Dependencies

Blocked by: Issue #1 (Type System — provides DataStreamQueryOptions and resource types), Issue #2 (Helper Utilities — provides encoding helpers including encodeDateTime), Issue #3 (Stub QueryBuilder — provides constructor, buildResourceUrl, buildQueryString, availableResources), Issue #5 (Systems Methods — establishes the pattern)
Blocks: Issue #11 (Observations Methods — observes through DataStreams), Issues #12–#13 (Control Streams and Commands)

---

Operational Constraints

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

Key constraints for this task:

• Precedence: OGC specifications → AI Collaboration Agreement → This issue description → Existing code → Conversational context
• No scope expansion: Do not infer unstated requirements or add unrequested features
• No refactoring: Do not rename, restructure, or "improve" code outside this issue's scope
• Minimal diffs: Prefer the smallest change that satisfies the acceptance criteria
• Ask when unclear: If intent is ambiguous, stop and ask for clarification

---

References

Read these documents before starting implementation. They are ordered by priority.

Primary References (must read)

#	Document	Section/Lines	What It Provides
1	docs/planning/csapi-implementation-guide.md	§6 DataStreams Resource Methods (lines 1601–1665)	Full CRUD operations, schema operations, query parameters, obsFormat, temporal patterns
2	docs/planning/csapi-implementation-guide.md	§6 Complete Query Parameter Support (lines 1921–2006)	All query parameters including phenomenonTime, resultTime, cursor, obsFormat
3	docs/planning/csapi-implementation-guide.md	§6 Query Parameters and Code Reuse (lines 720–900)	Temporal applicability matrix showing DataStreams supports datetime + phenomenonTime + resultTime
4	src/ogc-api/edr/url_builder.ts	Full file (562 lines)	Blueprint: method structure, resource validation, URL construction pattern
5	src/ogc-api/edr/url_builder.spec.ts	Full file	Blueprint: test patterns for URL builder methods
6	docs/planning/ROADMAP.md	Phase 2, Task 6 (lines 236–255)	Authoritative task definition, method list, test requirements

Upstream Type/Import References (files this task imports from)

#	Document	What to Import
7	src/ogc-api/csapi/model.ts	DataStreamQueryOptions, ObservationQueryOptions, CSAPIResourceType (created by Issue #1)
8	src/ogc-api/csapi/helpers.ts	Encoding helpers: encodeDateTime, encodeArray (created by Issue #2)

Research References (context, not required reading)

#	Document	What It Provides
9	docs/research/requirements/csapi-part2-requirements.md	Detailed client implementation requirements for DataStreams including schema handling
10	docs/research/requirements/csapi-query-parameters.md	Complete catalog of all CSAPI query parameters
11	docs/research/upstream/pr114-analysis.md	Architectural patterns for DataStreams implementation

Specification References (for @see links and field accuracy)

#	Document	Use
12	OGC API - Connected Systems Part 2 (23-002)	DataStreams resource definitions, schema endpoint, obsFormat requirement (Req 11)
13	OGC API - Connected Systems Part 2: OpenAPI Spec	DataStreams endpoint definitions — normative URL paths
14	OGC SWE Common 3.0 (24-014)	Format for result schemas and data encoding
15	OGC API - Connected Systems Part 1 (23-001)	Context for system-datastream associations from Part 1 side

Convention Quick Reference

Rule	Example
Use .js extension for relative imports	import { X } from './file.js'
Use import type for interfaces/types	import type { Y } from './model.js'
Three-tier hierarchy: import from lower tiers only	shared → ogc-api → csapi
Named exports for types and utilities	export interface Z { ... }
as const arrays for enum-like values	export const XTypes = [...] as const
HTTP mocking: globalThis.fetch = jest.fn()	Never use nock, msw, or other libraries
Meaningful tests only	Verify behavior, not that code runs without throwing

[Sam-Bolling]

⚠️ Required Pre-Reading: Lessons Learned

MANDATORY: Before starting work on this issue, read docs/governance/phase-2-lessons-learned.md.

This document contains actionable guardrails derived from real mistakes made in Phase 1–2.2. All 7 lessons apply to this issue. Key callouts for DataStreams:

Lesson	What to Do for This Issue
L1 — Test Checklist	Use the mandatory 8-item test checklist. DataStreams is the first Part 2 resource — set the thoroughness bar high for temporal parameter tests.
L2 — Query Parameters	Check the applicability table: DataStreams supports datetime, system, procedure, foi, observedProperty but NOT bbox, NOT phenomenonTime/resultTime (those belong to Observations).
L3 — Temporal Keys	⚠️ CRITICAL for this issue. DataStreams introduces datetime for temporal filtering. Verify that datetime is present in the buildQueryString temporal condition. If any temporal key used in DataStreamQueryOptions is missing from that condition, flag it as a comment.
L4 — Resource String	Every method must call this.assertResourceAvailable('datastreams') — grep to verify after implementation.
L5 — Files	All work in url_builder.ts + url_builder.spec.ts only. No new files.
L6 — Review Findings	Note any unexpected behavior as a comment on this issue.
L7 — DRY	Do not copy-paste method bodies. Call shared helpers.