Phase 3, Task 17: Format Index

[Sam-Bolling]

Task

Create the Format Index (formats/index.ts) — a top-level barrel file that re-exports all format parsers, types, and constants from a single entry point, providing a unified import surface for all CSAPI format handling.

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

---

Files to Create or Modify

File	Action	Est. Lines	Purpose
src/ogc-api/csapi/formats/index.ts	Create	~50-100	Barrel file re-exporting all format parsers, types, and constants
src/ogc-api/csapi/formats/index.spec.ts	Create	~50-100	Integration tests — export accessibility, tree-shaking, import path resolution

Blueprint Reference

Follow the EDR pattern in src/ogc-api/edr/model.ts (126 lines) for file structure and src/ogc-api/edr/model.spec.ts (42 lines) for test patterns.

Scope — What to Implement

Barrel File Exports

The Format Index re-exports from the 4 format module sources. Use named re-exports for tree-shaking friendliness and explicit API surface control.

Source modules to re-export from:

Source	Issue	What It Exports
./constants.js	#29	Media type constants, resource type URI constants, vocabulary URI constants, asset type constants
./geojson.js	#14	GeoJSON CSAPI property extraction utilities
./sensorml/index.js	#23	All SensorML parsers and types (via SensorML barrel)
./swecommon/index.js	#28	All SWE Common parsers and types (via SWE Common barrel)

Export Organization

Group exports logically with JSDoc section comments:

// --- Constants ---
export {
  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,
  CSAPI_MEDIA_TYPES,
  SOSA_NS,
  SSN_NS,
  QUDT_NS,
  UCUM_NS,
  CF_NS,
  SystemTypeUris,
  DeploymentTypeUris,
  ProcedureTypeUris,
  AssetTypes,
  // ... all constants
} from './constants.js';

export type { AssetType } from './constants.js';

// --- GeoJSON ---
export { /* GeoJSON utilities */ } from './geojson.js';

// --- SensorML ---
export {
  parseSensorML,
  parsePhysicalSystem,
  parseSimpleProcess,
  parseAggregateProcess,
  // ... all SensorML exports
} from './sensorml/index.js';

export type {
  SensorMLDocument,
  PhysicalSystem,
  SimpleProcess,
  AggregateProcess,
  // ... all SensorML types
} from './sensorml/index.js';

// --- SWE Common ---
export {
  parseSWEComponent,
  parseDataRecord,
  parseDataArray,
  parseSimpleComponent,
  detectEncoding,
  validateAgainstSchema,
  // ... all SWE Common exports
} from './swecommon/index.js';

export type {
  SWEDataComponent,
  DataRecord,
  DataArray,
  DataEncoding,
  ValidationResult,
  // ... all SWE Common types
} from './swecommon/index.js';

Use export type for all type/interface re-exports (TypeScript isolatedModules compatibility). Use named export for all value exports (no default exports, no export *).

JSDoc Requirements

• Module-level JSDoc documenting the formats module as the unified entry point for all CSAPI format handling
• Usage example showing the recommended import pattern: import { parseSWEComponent, parseSensorML, MEDIA_TYPE_SWE_JSON, type DataRecord } from './formats/index.js'
• Brief description of each export group (Constants, GeoJSON, SensorML, SWE Common)
• Add @see links to the relevant OGC specifications
• Follow the JSDoc style in src/ogc-api/edr/model.ts

Testing Requirements

• Create src/ogc-api/csapi/formats/index.spec.ts (~50-100 lines)
• Export accessibility tests:
  • All constant values exported and have expected values
  • All SensorML parser functions exported and callable
  • All SWE Common parser functions exported and callable
  • GeoJSON utilities exported and callable
  • Type exports resolve (TypeScript compilation test)
• Tree-shaking tests:
  • Named exports used throughout (no default exports)
  • No export * used (explicit named exports only)
  • Importing a single function does not pull in unrelated modules
• Import path resolution tests:
  • Importing from ./formats/index.js resolves all sub-module exports
  • No circular dependency issues between format modules
• Follow test patterns from src/ogc-api/edr/model.spec.ts

Scope — What NOT to Touch

• ❌ Do NOT create or modify constants.ts — that belongs to Issue Phase 3, Task 16: Format Constants #29 (Format Constants)
• ❌ Do NOT create or modify geojson.ts — that belongs to Issue Phase 3.1: GeoJSON Handler Extensions #14 (GeoJSON CSAPI Extensions)
• ❌ Do NOT create or modify any sensorml/ files — those belong to Issues Phase 3, Task 5: SensorML Types #18-Phase 3, Task 10: SensorML Index #23
• ❌ Do NOT create or modify any swecommon/ files — those belong to Issues 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
• ❌ Do NOT create or modify model.ts or url_builder.ts — those belong to other issues
• ❌ 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

• formats/index.ts exists as top-level barrel file re-exporting all format public API
• Re-exports from all 4 source modules: constants, geojson, sensorml, swecommon
• All type exports use export type syntax
• All value exports use named export (no default exports, no export *)
• Exports are organized with logical grouping comments
• Module-level JSDoc documents purpose and usage patterns
• formats/index.spec.ts exists with integration tests for export accessibility, tree-shaking, and import resolution
• No circular dependencies between format modules
• Existing tests still pass (npm test)
• No lint errors

Dependencies

Blocked by: Issue #14 — GeoJSON CSAPI Extensions, Issue #23 — SensorML Index, Issue #28 — SWE Common Index, Issue #29 — Format Constants
Blocks: None (this is the final Phase 3 deliverable for format handling)

---

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 2066-2068 (File Structure)	File location showing formats/index.ts (~50-100 lines) as barrel file
2	docs/planning/csapi-implementation-guide.md	Lines 2133-2139 (File Purposes)	Format files list: formats/index.ts = barrel file for parser exports
3	src/ogc-api/edr/model.ts	Full file (126 lines)	Blueprint — file structure, JSDoc style, export conventions
4	src/ogc-api/edr/model.spec.ts	Full file (42 lines)	Blueprint — test structure and patterns

Upstream Source Files (files this task re-exports from)

#	File	Issue	What It Exports
1	src/ogc-api/csapi/formats/constants.ts	#29	Media type, resource type URI, vocabulary URI, asset type constants
2	src/ogc-api/csapi/formats/geojson.ts	#14	GeoJSON CSAPI property extraction utilities
3	src/ogc-api/csapi/formats/sensorml/index.ts	#23	All SensorML parsers and types
4	src/ogc-api/csapi/formats/swecommon/index.ts	#28	All SWE Common parsers and types

Convention Quick Reference

Rule	Example
Use .js extension for relative imports	export { X } from './file.js'
Use export type for interfaces/types	export type { Y } from './model.js'
Named exports only (no default, no export *)	export { parseSWEComponent } from './swecommon/index.js'
Three-tier hierarchy: import from lower tiers only	shared → ogc-api → csapi
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 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