Phase 3, Task 6: SensorML Simple Process Parser

[Sam-Bolling]

Task

Implement a sub-parser for SensorML 3.0 SimpleProcess descriptors that parses the AbstractProcess-level properties (definition, typeOf, configuration, featuresOfInterest, inputs, outputs, parameters, modes) and the SimpleProcess-specific method property, converting raw JSON into typed SimpleProcess objects.

ROADMAP Reference: Phase 3, Task 6 — SensorML Simple Process Parser (~2-3 hours, Medium-High complexity)

---

Files to Create or Modify

File	Action	Est. Lines	Purpose
src/ogc-api/csapi/formats/sensorml/simple-process.ts	Create	~150-200	SimpleProcess sub-parser
src/ogc-api/csapi/formats/sensorml/simple-process.spec.ts	Create	~100-150	SimpleProcess parser tests

Blueprint Reference

Follow the EDR parser/helper patterns in src/ogc-api/edr/model.ts (126 lines) for function structure and JSDoc style. For test patterns, follow src/ogc-api/edr/model.spec.ts (42 lines) — fixture-based tests with descriptive names.

Scope — What to Implement

Parser Function

/**
 * Parse a raw SensorML 3.0 SimpleProcess JSON object into a typed SimpleProcess.
 * 
 * @param json - Raw JSON object with `type: 'SimpleProcess'`
 * @returns Parsed SimpleProcess object
 * @throws {SensorMLParseError} If the input is not a valid SimpleProcess
 * @see https://docs.ogc.org/is/23-000/23-000.html — OGC SensorML 3.0
 */
export function parseSimpleProcess(json: unknown): SimpleProcess

Properties to Parse

From AbstractProcess (inherited via DescribedObject → AbstractProcess → SimpleProcess):

The SimpleProcess sub-parser is responsible for parsing AbstractProcess-level properties that go beyond the base DescribedObject metadata. The DescribedObject-level properties (id, uniqueId, label, description, identifiers, classifiers, validTime, capabilities, characteristics, contacts, documents, history, securityConstraints, legalConstraints) may be parsed by shared helper functions that the main parser (Issue #22) coordinates, but this sub-parser must at minimum handle the AbstractProcess additions:

Property	Type	Required	OGC Spec	Description
type	'SimpleProcess' (const)	Yes	Part 1 L3681	Type discriminator
definition	string (URI)	No	Part 1 L3608	Process type as URI to ontology concept
typeOf	link-2	No	Part 1 L3612	Reference to base process this inherits from
configuration	Settings	No	Part 1 L3616	Value settings constraining base process properties
featuresOfInterest	FeatureList (link-2[])	No	Part 1 L3619	Sampling/domain features relevant to process
inputs	InputList (IOComponentChoice[])	No	Part 1 L3623	Process input specifications
outputs	OutputList (IOComponentChoice[])	No	Part 1 L3626	Process output specifications
parameters	ParameterList (IOComponentChoice[])	No	Part 1 L3629	Configuration parameters
modes	Mode[]	No	Part 1 L3632	Operating modes with configurations

SimpleProcess-specific property:

Property	Type	Required	OGC Spec	Description
method	ProcessMethod	No	Part 1 L3686	Algorithm description (machine-readable or natural language)

ProcessMethod structure (Part 1 L3671):

interface ProcessMethod {
  algorithm?: unknown;  // Machine-readable algorithm (inline or by reference)
  description?: string; // Natural language description
}

IOComponentChoice structure (Part 1 L3662):

Each input/output/parameter entry is a SoftNamedProperty combined with either:

• A SWE Common AnyComponent (DataComponent) — for typed data descriptions
• An ObservableProperty ({ type: 'ObservableProperty', definition: string }) — for observable property references

Error Handling

• Throw a descriptive error if type is not 'SimpleProcess'
• Throw if inputs/outputs/parameters items have invalid IOComponentChoice structure
• Handle missing optional properties gracefully (return undefined)
• Validate URI format for definition property if present

JSDoc Requirements

• Document the main parseSimpleProcess function with @param, @returns, @throws, @see
• Add @see links to OGC SensorML 3.0 (23-000) and Part 1 spec line numbers
• Document any helper functions (e.g., parseProcessMethod, parseIOComponentChoice)
• Follow the JSDoc style in src/ogc-api/edr/model.ts

Testing Requirements

• Create src/ogc-api/csapi/formats/sensorml/simple-process.spec.ts (~100-150 lines)
• Spec example fixtures: Test parsing a minimal valid SimpleProcess (type + required DescribedObject props)
• Full document parsing: Test with all optional properties populated (inputs, outputs, parameters, method, modes, etc.)
• Method parsing: Test ProcessMethod with algorithm only, description only, and both
• I/O parsing: Test inputs/outputs/parameters with both AnyComponent and ObservableProperty variants
• Invalid document handling: Test with missing type, wrong type value, malformed inputs
• Edge cases: Test with empty arrays, null optional fields, unknown extra properties
• Follow test patterns from src/ogc-api/edr/model.spec.ts

Scope — What NOT to Touch

• ❌ Do NOT parse DescribedObject-level properties independently — shared parsing helpers belong to Issue Phase 3, Task 9: SensorML Main Parser #22 (SensorML Main Parser); this sub-parser should accept already-parsed base properties or provide a function the main parser calls
• ❌ Do NOT implement AggregateProcess parsing — that belongs to Issue Phase 3, Task 7: SensorML Aggregate Process Parser #20 (SensorML Aggregate Process Parser)
• ❌ Do NOT implement PhysicalSystem or PhysicalComponent parsing — those belong to Issues Phase 3, Task 8: SensorML Physical System Parser #21 (Physical System Parser)
• ❌ Do NOT create formats/sensorml/parser.ts (main parser) — that belongs to Issue Phase 3, Task 9: SensorML Main Parser #22 (SensorML Main Parser)
• ❌ Do NOT create formats/sensorml/index.ts barrel file — that belongs to Issue Phase 3, Task 10: SensorML Index #23 (SensorML Index)
• ❌ Do NOT modify SensorML type definitions — those belong to Issue Phase 3, Task 5: SensorML Types #18 (SensorML Types)
• ❌ Do NOT implement SWE Common DataComponent parsers — those belong to Issues Phase 3, Task 11: SWE Common Simple Components Parser #24-Phase 3, Task 15: SWE Common Index #28 (SWE Common tasks); use types only via import type
• ❌ 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

• src/ogc-api/csapi/formats/sensorml/simple-process.ts exists with parseSimpleProcess function
• Parser handles all AbstractProcess-level properties (definition, typeOf, configuration, featuresOfInterest, inputs, outputs, parameters, modes)
• Parser handles SimpleProcess-specific method property with ProcessMethod structure
• Parser handles IOComponentChoice entries in inputs/outputs/parameters (both AnyComponent and ObservableProperty variants)
• Descriptive errors thrown for invalid SimpleProcess documents
• All new code has complete JSDoc documentation with @see links
• simple-process.spec.ts exists with tests for valid parsing, method parsing, I/O parsing, invalid documents, and edge cases
• Existing tests still pass (npm test)
• No lint errors

Dependencies

Blocked by:

• Issue Phase 3, Task 5: SensorML Types #18 — SensorML Types (provides SimpleProcess, ProcessMethod, IOComponentChoice, and related type definitions)
• Issue Phase 3.4: SWE Common Types #17 — SWE Common Types (provides SWEDataComponent, AnyComponent types used in IOComponentChoice)

Blocks:

• Issue Phase 3, Task 9: SensorML Main Parser #22 — SensorML Main Parser (delegates to this sub-parser for SimpleProcess documents)
• Issue Phase 3, Task 10: SensorML Index #23 — SensorML Index (re-exports parser from this file)

---

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	SensorML Handler section (Lines 2990-3045)	Full SensorML 3.0 parsing requirements, element list, capabilities
2	docs/planning/csapi-implementation-guide.md	§7 SensorML 3.0 Types (Lines 2657-2790)	Code template with SimpleProcess interface and SensorMLProcess union
3	src/ogc-api/edr/model.ts	Full file (126 lines)	Blueprint: function structure, JSDoc style, discriminated unions
4	src/ogc-api/edr/model.spec.ts	Full file (42 lines)	Blueprint: test structure, fixture-based testing pattern

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

#	Document	What to Import
1	src/ogc-api/csapi/formats/sensorml/types.ts (Issue #18)	SimpleProcess, ProcessMethod, IOComponentChoice, Mode, Settings, ObservableProperty
2	src/ogc-api/csapi/formats/swecommon/types.ts (Issue #17)	SWEDataComponent / AnyComponent (via import type only)

Research References (context, not required reading)

#	Document	What It Provides
1	docs/planning/ROADMAP.md (Lines 407-415)	Task definition, LOC estimates, test requirements

Specification References (for @see links and field accuracy)

#	Document	Use
1	OGC SensorML 3.0 (23-000)	Canonical SensorML 3.0 data model — primary @see target
2	docs/research/standards/ogcapi-connectedsystems-1.bundled.oas31.yaml	SimpleProcess schema (L3679), AbstractProcess (L3599), ProcessMethod (L3671), IOComponentChoice (L3662), InputList/OutputList/ParameterList (L3584-3596)
3	OGC API - Connected Systems Part 1 (23-001)	API-level requirements for SensorML encoding

Convention Quick Reference

Rule	Example
Use .js extension for relative imports	import type { SimpleProcess } from './types.js'
Use import type for interfaces/types	import type { SimpleProcess } from './types.js'
Three-tier hierarchy: import from lower tiers only	shared → ogc-api → csapi
Named exports for types and utilities	export function parseSimpleProcess(json: unknown): SimpleProcess
HTTP mocking: globalThis.fetch = jest.fn()	Never use nock, msw, or other libraries
Meaningful tests only	Verify parsed values match expected, not just "runs without throwing"

[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