Phase 3, Task 16: Format Constants

[Sam-Bolling]

Task

Create the Format Constants file (constants.ts) defining media type constants, resource type URI constants, and vocabulary URI constants used across all CSAPI format handlers.

ROADMAP Reference: Phase 3, Task 16 — Format Constants (~1-2 hours, Low complexity)

---

Files to Create or Modify

File	Action	Est. Lines	Purpose
src/ogc-api/csapi/formats/constants.ts	Create	~50-100	Media type, resource type, and vocabulary URI constants

Note: Per ROADMAP, no separate test file is needed — constants are validated by format detector tests (Issue #15).

Blueprint Reference

Follow the EDR pattern in src/ogc-api/edr/model.ts (126 lines) for file structure and JSDoc style.

Scope — What to Implement

Media Type Constants

Define constants for all CSAPI media types used in Content-Type headers and Accept header negotiation. Values sourced from OGC spec OpenAPI definitions.

// Part 1 media types
export const MEDIA_TYPE_GEOJSON = 'application/geo+json' as const;
export const MEDIA_TYPE_JSON = 'application/json' as const;
export const MEDIA_TYPE_SENSORML_JSON = 'application/sml+json' as const;

// Part 2 media types (SWE Common encodings)
export const MEDIA_TYPE_SWE_JSON = 'application/swe+json' as const;
export const MEDIA_TYPE_SWE_TEXT = 'application/swe+text' as const;
export const MEDIA_TYPE_SWE_CSV = 'application/swe+csv' as const;
export const MEDIA_TYPE_SWE_BINARY = 'application/swe+binary' as const;

Also provide a grouped as const array for format detection iteration:

export const CSAPI_MEDIA_TYPES = [
  MEDIA_TYPE_GEOJSON,
  MEDIA_TYPE_JSON,
  MEDIA_TYPE_SENSORML_JSON,
  MEDIA_TYPE_SWE_JSON,
  MEDIA_TYPE_SWE_TEXT,
  MEDIA_TYPE_SWE_CSV,
  MEDIA_TYPE_SWE_BINARY,
] as const;

Resource Type URI Constants

Define SOSA/SSN ontology URI constants for featureType discriminators. The SOSA ontology prefix is http://www.w3.org/ns/sosa/. Per the Guide, CSAPI also accepts compact sosa: prefixed forms.

System type URIs (SystemTypeUris):

• sosa:Sensor / http://www.w3.org/ns/sosa/Sensor
• sosa:Platform / http://www.w3.org/ns/sosa/Platform
• sosa:Actuator / http://www.w3.org/ns/sosa/Actuator
• sosa:Sampler / http://www.w3.org/ns/sosa/Sampler
• sosa:System / http://www.w3.org/ns/sosa/System

Deployment type URIs (DeploymentTypeUris):

• sosa:Deployment / http://www.w3.org/ns/sosa/Deployment

Procedure type URIs (ProcedureTypeUris):

• sosa:Procedure / http://www.w3.org/ns/sosa/Procedure
• sosa:ObservingProcedure / http://www.w3.org/ns/sosa/ObservingProcedure
• sosa:SamplingProcedure / http://www.w3.org/ns/sosa/SamplingProcedure
• sosa:ActuatingProcedure / http://www.w3.org/ns/sosa/ActuatingProcedure

Sampling Feature type URIs:

• sosa:SamplingFeature / http://www.w3.org/ns/sosa/SamplingFeature

Property type URIs:

• sosa:ObservableProperty / http://www.w3.org/ns/sosa/ObservableProperty
• sosa:ActuatableProperty / http://www.w3.org/ns/sosa/ActuatableProperty

Part 2 resource type URIs:

• sosa:ObservationCollection
• sosa:Observation

Provide grouped as const arrays for each category (e.g., SystemTypeUris, DeploymentTypeUris, ProcedureTypeUris).

Vocabulary URI Constants

Define namespace/vocabulary constants used in property definitions and semantic references:

// Ontology namespaces
export const SOSA_NS = 'http://www.w3.org/ns/sosa/' as const;
export const SSN_NS = 'http://www.w3.org/ns/ssn/' as const;

// Unit vocabularies
export const QUDT_NS = 'http://qudt.org/vocab/unit/' as const;
export const UCUM_NS = 'http://unitsofmeasure.org/' as const;

// Property vocabularies
export const CF_NS = 'http://vocab.nerc.ac.uk/standard_name/' as const;

Asset Type Constants

Define the assetType enumeration values for Systems (per Guide line 2962):

export const AssetTypes = [
  'Equipment', 'Human', 'LivingThing', 'Simulation', 'Process', 'Group', 'Other'
] as const;
export type AssetType = typeof AssetTypes[number];

JSDoc Requirements

• Module-level JSDoc documenting the purpose of the constants file
• Each constant or constant group documented with @see link to the relevant OGC spec section or SOSA ontology
• Document the relationship between compact prefix form (sosa:System) and full URI form
• Follow the JSDoc style in src/ogc-api/edr/model.ts

Scope — What NOT to Touch

• ❌ Do NOT create or modify format parser files — those belong to Issues Phase 3.1: GeoJSON Handler Extensions #14-Phase 3.3: Validator Extensions #16, Phase 3, Task 5: SensorML Types #18-Phase 3, Task 15: SWE Common Index #28
• ❌ Do NOT create or modify model.ts — that belongs to Issue Phase 2.1: Systems Methods #5 (CSAPI Types)
• ❌ Do NOT create or modify url_builder.ts — that belongs to Issues Phase 2.2: Deployments Methods #6-Phase 2.9: Commands Methods #13
• ❌ Do NOT create or modify formats/index.ts — that belongs to Issue Phase 3, Task 17: Format Index #30 (Format Index)
• ❌ 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

• constants.ts exists with all media type constants matching OGC spec values
• All resource type URI constants defined with both compact (sosa:) and full URI forms
• Vocabulary URI constants defined (SOSA, SSN, QUDT, UCUM, CF)
• Asset type constants defined with as const array and derived type
• Grouped as const arrays for each resource type category
• All constants use as const assertions for literal types
• All new code has complete JSDoc documentation with @see spec references
• Existing tests still pass (npm test)
• No lint errors

Dependencies

Blocked by: None (constants are self-contained definitions)
Blocks: Issue #15 — Format Detector (uses media type constants for recognition), Issue #16 — Validator (uses resource type URIs for validation), Issue #30 — Format Index (re-exports constants)

---

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	Lines 2073-2077 (File Structure)	File location showing constants.ts (~50-100 lines) with media types, namespaces
2	docs/planning/csapi-implementation-guide.md	Lines 3130-3145 (Format Detector)	Media type recognition table: application/sml+json, application/swe+json, application/swe+text, application/swe+csv, application/swe+binary, application/geo+json
3	docs/planning/csapi-implementation-guide.md	Lines 2960-2975 (GeoJSON Handler)	Resource type URIs: SystemTypeUris, DeploymentTypeUris, ProcedureTypeUris with all values
4	docs/planning/csapi-implementation-guide.md	Lines 2290-2345 (CSAPI Types)	featureType fields on System, Deployment, Procedure interfaces
5	src/ogc-api/edr/model.ts	Full file (126 lines)	Blueprint — file structure, JSDoc style, export conventions

Specification References (for exact constant values)

#	Document	Use
1	docs/research/standards/ogcapi-connectedsystems-1.bundled.oas31.yaml	Part 1 media types: application/geo+json (L5040), application/json (L4873), application/sml+json (L5121)
2	docs/research/standards/ogcapi-connectedsystems-2.bundled.oas31.yaml	Part 2 media types: application/swe+json (L1602), application/swe+text (L1610), application/swe+csv (L1618), application/swe+binary (L1633)
3	SOSA/SSN Ontology	Full URI forms for SOSA resource types (System, Sensor, Platform, etc.)
4	QUDT Units Ontology	QUDT namespace URI
5	CF Standard Names	CF conventions namespace URI

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'
as const arrays for enum-like values	export const XTypes = [...] as const
Derived literal union types	export type X = typeof XTypes[number]
Named exports only (no default)	export const MEDIA_TYPE_X = '...' as const

[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