Phase 3.3: Validator Extensions

[Sam-Bolling]

Task

Extend the CSAPI helpers with client-side validation functions that check resource documents against OGC Connected Systems Part 1 and Part 2 requirements before sending requests or after parsing responses.

ROADMAP Reference: Phase 3, Task 3 — Validator Extensions (~3-4 hours, Medium complexity)

---

Files to Create or Modify

File	Action	Est. Lines	Purpose
src/ogc-api/csapi/helpers.ts	Modify	~150-200 (add ~100-150)	Add validation utility functions for Part 1 resources, Part 2 resources, and cross-reference integrity
src/ogc-api/csapi/helpers.spec.ts	Create	~200-400	Tests for all validation functions — focused on rejecting invalid inputs

Blueprint Reference

Follow the existing error pattern in src/shared/errors.ts (157 lines) — EndpointError for endpoint-level errors. The validation functions should throw EndpointError or return structured validation results following the existing library error conventions. Follow the resource availability validation pattern in the Guide §5 Resource Validation Strategy (lines 538-570) — throw new EndpointError(...) with descriptive messages including what was expected vs. what was found.

EDR blueprint: src/ogc-api/edr/helpers.ts — pure utility functions, no class dependencies.

Scope — What to Implement

Part 1 Resource Validation Functions

Add validation functions to helpers.ts that check GeoJSON-encoded resource documents against the OGC Part 1 OpenAPI spec required fields. Each validator takes a parsed resource object and returns validation errors.

Base Feature Validation (shared by all Part 1 GeoJSON resources):

• featureType — required string (from base feature schema)
• uid — required string, URI format
• name — required string, minLength 1

Systems:

• Base feature requirements (featureType, uid, name)
• featureType must be from SystemTypeUris enum (sosa:Sensor, sosa:Actuator, sosa:Platform, sosa:Sampler, sosa:System, or full URI equivalents)

Deployments:

• Base feature requirements (featureType, uid, name)
• featureType must be from DeploymentTypeUris enum (sosa:Deployment or full URI)
• validTime — required timePeriod object

Procedures:

• Base feature requirements (featureType, uid, name)
• featureType must be from ProcedureTypeUris enum

Sampling Features:

• Base feature requirements (featureType, uid, name)
• sampledFeature@link — required link object (must have valid href)

Properties (non-GeoJSON, DerivedProperty schema):

• uniqueId — required string, URI format
• label — required string
• baseProperty — required string, URI format

Part 2 Resource Validation Functions

• DataStreams: Validate that resultSchema is present and is a valid SWE Common DataComponent structure (structural check only — deep SWE validation is Issue Phase 3.4: SWE Common Types #17/Phase 3, Task 11: SWE Common Simple Components Parser #24-Phase 3, Task 15: SWE Common Index #28)
• Observations: Validate that phenomenonTime is present, result structure exists
• Control Streams: Validate that parameter schema is present, system association exists
• Commands: Validate that parameters structure exists

Cross-Reference Validation Functions

• Link validation: Links must have valid href (non-empty string, valid URI format), valid rel string
• URI format validation: Check URIs match RFC 3986 / RFC 8141 basic structure
• Temporal validation: ISO 8601 compliance for time instants and time periods, start before end

Validation Error Reporting

Follow the Guide's error reporting pattern:

• Error severity: Error (invalid/unusable), Warning (questionable/suboptimal)
• Error context: Property path to error location
• Error messages: Clear description — expected vs actual values
• Batch validation: Collect all errors, don't stop at first error

JSDoc Requirements

• Document each validation function with its purpose, parameters, and what spec requirement it enforces
• Add @see links to OGC Part 1 (23-001) for Part 1 validators, Part 2 (23-002) for Part 2 validators
• Add @see link to RFC 8141 for URI validation
• Follow JSDoc style from src/shared/errors.ts

Testing Requirements

• Create src/ogc-api/csapi/helpers.spec.ts (~200-400 lines)
• Part 1 validation tests — for each resource type:
  • Missing required fields (e.g., System without uid → error)
  • Invalid featureType (e.g., System with featureType: "invalid" → error)
  • Malformed URIs (e.g., uid: "not a uri" → error)
  • Invalid temporal ranges (e.g., Deployment with validTime.start > validTime.end → error)
  • Valid resources pass validation (minimal positive cases)
• Part 2 validation tests — for each resource type:
  • Missing schema (DataStream without resultSchema → error)
  • Missing required temporal fields (Observation without phenomenonTime → error)
• Cross-reference validation tests:
  • Invalid link objects (missing href → error)
  • Invalid URIs (malformed → error)
  • Invalid ISO 8601 strings (→ error)
• Error reporting tests:
  • Multiple errors collected in single validation pass
  • Error messages include property path and expected values
• Follow test patterns from src/shared/errors.spec.ts (202 lines)
• Per Guide §7 Validator: "Tests should verify the validator correctly rejects invalid inputs, not that fixture data passes validation"

Scope — What NOT to Touch

• ❌ Do NOT implement deep SWE Common schema validation (DataComponent type checking, encoding validation) — that belongs to Issues Phase 3.4: SWE Common Types #17 (SWE Common Types) and Phase 3, Task 11: SWE Common Simple Components Parser #24-Phase 3, Task 15: SWE Common Index #28 (SWE Common parsers)
• ❌ Do NOT implement deep SensorML validation — that belongs to Issues Phase 3, Task 5: SensorML Types #18-Phase 3, Task 10: SensorML Index #23 (SensorML types and parsers)
• ❌ Do NOT modify src/shared/errors.ts — use the existing EndpointError class as-is
• ❌ Do NOT modify src/ogc-api/csapi/url_builder.ts — the QueryBuilder's resource availability validation (Issue Phase 1.3: Create Stub QueryBuilder (csapi/url_builder.ts) #3) is separate from document content validation
• ❌ Do NOT implement server conformance testing — this is client-side input validation only
• ❌ Do NOT create fixture files — test with inline invalid objects
• ❌ Do NOT modify src/ogc-api/csapi/model.ts — type definitions are Issue Phase 1.1: Create Type System (csapi/model.ts) #1's scope
• ❌ 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

• helpers.ts exports validation functions for all 5 Part 1 resource types (Systems, Deployments, Procedures, Sampling Features, Properties)
• helpers.ts exports validation functions for all 4 Part 2 resource types (DataStreams, Observations, Control Streams, Commands)
• helpers.ts exports cross-reference validation utilities (link validation, URI format, temporal format)
• Validation rules match the OGC Part 1/Part 2 OpenAPI spec required fields exactly
• All Part 1 validators check base feature requirements (featureType, uid, name) plus resource-specific requirements
• All new code has complete JSDoc documentation with @see spec references
• helpers.spec.ts exists with tests that verify validators correctly reject invalid inputs
• Existing tests still pass (npm test)
• No lint errors

Dependencies

Blocked by: Issue #1 (Type System — provides CsapiSystem, CsapiDeployment, etc. interfaces that validators type-check against), Issue #2 (Helper Utilities — helpers.ts must exist before extending it)
Blocks: Issue #31 (Integration Tests — uses validators), Issue #32 (Unit Tests Completion — validator coverage)

---

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	§7 Validator (Lines 3118-3185)	Complete validation rules for Part 1, Part 2, and cross-reference validation; error reporting patterns
2	docs/planning/csapi-implementation-guide.md	§5 Resource Validation Strategy (Lines 538-570)	EndpointError throw pattern for validation failures
3	src/shared/errors.ts	Full file (157 lines)	Blueprint — EndpointError class definition and ServiceExceptionError pattern
4	src/shared/errors.spec.ts	Full file (202 lines)	Blueprint — test pattern for error classes
5	src/ogc-api/edr/helpers.ts	Full file	Blueprint — pure utility function pattern

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

#	Document	What to Import
1	src/shared/errors.ts	EndpointError class for validation error throwing
2	src/ogc-api/csapi/model.ts (Issue #1)	Resource type interfaces for type-safe validation

Research References (context, not required reading)

#	Document	What It Provides
1	docs/planning/ROADMAP.md (Lines 369-380)	Task scope definition and test requirements
2	docs/planning/csapi-implementation-guide.md (Lines 2061-2065)	Directory structure showing helpers.ts location

Specification References (for @see links and field accuracy)

#	Document	Use
1	OGC API - Connected Systems Part 1 (23-001)	Part 1 resource required fields
2	docs/research/standards/ogcapi-connectedsystems-1.bundled.oas31.yaml	Base feature schema (line 1835): featureType, uid, name required; SystemTypeUris (line 1876); DeploymentTypeUris (line 4555); ProcedureTypeUris; samplingFeature (line 4756); DerivedProperty / property (lines 4789-4840)
3	OGC API - Connected Systems Part 2 (23-002)	Part 2 resource required fields (DataStreams, Observations, Control Streams, Commands)
4	docs/research/standards/ogcapi-connectedsystems-2.bundled.oas31.yaml	Part 2 schema definitions
5	RFC 8141 (URN Syntax)	URI validation rules

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 function validateSystem(...) { ... }
HTTP mocking: globalThis.fetch = jest.fn()	Never use nock, msw, or other libraries
Meaningful tests only	Verify validator rejects invalid inputs, not that valid data passes

[Sam-Bolling]

📋 Required Reading: Phase 3 Lessons Learned

Before starting work on this issue, review the Phase 3 Lessons Learned document:

👉 docs/governance/phase-3-lessons-learned.md

Instructions:

1. Read the lessons learned document first — before reading the issue body
2. Read phase-2-lessons-learned.md second — Lessons 8 (multi-server) and 10 (read-only smoke tests) remain mandatory
3. Review AI_OPERATIONAL_CONSTRAINTS.md as always

Key lessons applicable to all Phase 3 work:

• Lesson 1: Upstream audit check — before building new layers
• Lesson 2: Postel's Law — never gate extraction on validation
• Lesson 10: Type naming rules when defining types from external specs