Phase 1.1: Create Type System (csapi/model.ts)

[Sam-Bolling]

Task

Create the CSAPI type system in src/ogc-api/csapi/model.ts (~350-400 lines) and its test file src/ogc-api/csapi/model.spec.ts (~200-300 lines).

ROADMAP Reference: Phase 1, Task 1 — Create Type System (~4-5 hours, Low complexity)

---

Files to Create

File	Action	Est. Lines	Purpose
src/ogc-api/csapi/model.ts	Create	~350-400	All CSAPI resource interfaces, query options, enums
src/ogc-api/csapi/model.spec.ts	Create	~200-300	Type validation tests

Blueprint Reference

Follow the EDR pattern established in src/ogc-api/edr/model.ts (126 lines). The CSAPI model is larger because it covers 9 resource types vs EDR's simpler parameter types.

Scope — What to Implement

Part 1 Resource Interfaces (5)

• System — id, name, description, systemType, validTime, geometry, links, properties
• Deployment — id, name, description, validTime, geometry, links, properties
• Procedure — id, name, description, procedureType, links, properties
• SamplingFeature — id, name, description, featureType, geometry, sampledFeature, links, properties
• Property — id, name, description, definition, objectType, links

Part 2 Resource Interfaces (4)

• DataStream — id, name, description, observationType, resultType, phenomenonTime, resultTime, schema, links
• Observation — id, phenomenonTime, resultTime, result, parameters, links
• ControlStream — id, name, description, commandType, schema, links
• Command — id, issueTime, executionTime, currentStatus, result, parameters, links

Query Options Interfaces

• CSAPIQueryOptions — base (limit, offset, cursor, bbox, datetime, q, id, uid, f, sortBy, sortOrder)
• Resource-specific options extending base (e.g., SystemQueryOptions adds parentId, procedureId; ObservationQueryOptions adds phenomenonTime, resultTime, obsFormat)

Three-Tier Type Hierarchy

src/shared/models.ts          → import BoundingBox, CrsCode, MimeType, DateTimeParameter
src/ogc-api/model.ts           → import ConformanceClass (if needed)
src/ogc-api/csapi/model.ts     → NEW (this task)

Also import from the geojson package for Geometry, Feature, FeatureCollection types.

JSDoc Requirements

• Document ALL interfaces with property descriptions
• Mark required vs optional fields
• Add @see links to CSAPI spec sections where appropriate
• Follow the JSDoc style in src/ogc-api/edr/model.ts

Testing Requirements

• Create src/ogc-api/csapi/model.spec.ts (~200-300 lines)
• Test type guards or string-to-enum converters if any are defined
• Test CSAPIResourceTypes array and type discrimination
• Test as const arrays produce correct union types
• Follow test patterns from src/ogc-api/edr/model.spec.ts

Scope — What NOT to Touch

• ❌ Do NOT create helpers.ts — that belongs to Phase 1.2 (issue Phase 1.2: Create Helper Utilities (csapi/helpers.ts) #2)
• ❌ Do NOT create url_builder.ts — that belongs to Phase 1.3 (issue Phase 1.3: Create Stub QueryBuilder (csapi/url_builder.ts) #3)
• ❌ Do NOT modify endpoint.ts — that belongs to Phase 1.4 (issue Phase 1.4: Integrate with OgcApiEndpoint #4)
• ❌ Do NOT modify index.ts exports — that belongs to Phase 1.4 (issue Phase 1.4: Integrate with OgcApiEndpoint #4)
• ❌ Do NOT add any runtime logic beyond type guards or string-to-enum converters (if needed for tests)
• ❌ Do NOT create fixtures yet
• ❌ Do NOT modify files outside the "Files to Create" table above
• ❌ Do NOT refactor existing code unless required to complete this task

Acceptance Criteria

• src/ogc-api/csapi/model.ts exists with all 9 resource interfaces + query options
• All interfaces have complete JSDoc documentation
• Three-tier import hierarchy is correct (shared → ogc-api → csapi)
• src/ogc-api/csapi/model.spec.ts exists with type validation tests
• Existing tests still pass (npm test)
• No lint errors

Dependencies

Blocked by: Nothing (this is the first task)
Blocks: All subsequent Phase 1 and Phase 2 issues (#2-#13)

---

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: "Type System Architecture"	Lines 2170-2460	Complete model.ts template — every interface, every field, all imports, the full ~357-line code block ready to adapt. This is the primary specification.
2	src/ogc-api/edr/model.ts	Full file (126 lines)	Upstream blueprint — the accepted pattern for JSDoc style, @see links, type unions, string-to-value converters. Match this style exactly.
3	src/ogc-api/edr/model.spec.ts	Full file (39 lines)	Test blueprint — the accepted pattern for type/model test files. Match describe/test structure.

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

#	Document	What to Import
4	src/shared/models.ts	BoundingBox, CrsCode, MimeType, DateTimeParameter, Contact
5	src/ogc-api/model.ts	OgcApiCollectionInfo, OgcApiDocumentLink, ConformanceClass
6	geojson package (npm)	Geometry, Point, Feature, FeatureCollection

Research References (context, not required reading)

#	Document	What It Provides
7	docs/research/design/csapiquerybuilder/architecture-decision/results/DECISION-part2-implementation.md	Architecture decision rationale for type system design — why single model.ts, why three-tier hierarchy, why these specific interface shapes
8	docs/research/upstream/typescript-types-analysis.md	Analysis of upstream type patterns — how existing WFS/WMS/WMTS/EDR types are structured, conventions to follow
9	docs/planning/ROADMAP.md Phase 1, Task 1	Lines 70-80 — task description with time estimates and checkpoint guidance

Specification References (for @see links in JSDoc)

#	Document	Use
10	OGC API - Connected Systems Part 1 (23-001)	Part 1 resource definitions — Systems, Deployments, Procedures, Sampling Features, Properties
11	OGC API - Connected Systems Part 2 (23-002)	Part 2 resource definitions — DataStreams, Observations, Control Streams, Commands
12	docs/research/standards/ogcapi-connectedsystems-1.bundled.oas31.yaml	Part 1 OpenAPI schema — exact property names, required fields, value constraints
13	docs/research/standards/ogcapi-connectedsystems-2.bundled.oas31.yaml	Part 2 OpenAPI schema — exact property names, required fields, value constraints

Convention Quick Reference

Rule	Example
Use .js extension for relative imports	import { BoundingBox } from '../../shared/models.js'
Use import type for interfaces/types	import type { Geometry } from 'geojson'
Three-tier hierarchy: import from lower tiers only	shared → ogc-api → csapi (never reverse)
Named exports for all types	export interface System { ... }
as const arrays for enum-like values	export const CSAPIResourceTypes = [...] as const

See Guide §6 "Import Conventions" (lines 2460-2550) for the complete import pattern specification.