Skip to content

Audit T2.10: PR #114 Pattern Alignment #26

@Sam-Bolling

Description

@Sam-Bolling

Audit: PR #114 Pattern Alignment (Structural Reference Only)

Parent Issue: #16 - Phase 6: Pre-Submission Audit
Tier: 2 - Maintainer Requirements & Patterns (CRITICAL) ⚠️
Reference: camptocamp/ogc-client#114
Priority: CRITICAL


⚠️ CRITICAL SCOPE LIMITATION

PR #114 is a STRUCTURAL REFERENCE ONLY - NOT a specification reference.

The maintainer (@jahow) provided PR #114 as an example of contribution structure and integration patterns for adding a new OGC API to the ogc-client library. This audit focuses exclusively on:

What to learn from EDR PR #114:

  • File organization and directory structure
  • Navigator class patterns and URL builder conventions
  • Model definition patterns (interfaces, query options)
  • Test organization and fixture structure
  • Integration with main library exports
  • Code style and TypeScript conventions
  • Build and packaging integration

What NOT to absorb from EDR:

  • EDR-specific API endpoints or resources
  • EDR query parameter names or semantics
  • EDR data models or response formats
  • EDR-specific validation logic
  • Any OGC API - Environmental Data Retrieval standard details

CSAPI implementation MUST follow OGC API - Connected Systems (OGC 23-001r2, OGC 23-002r1) specifications, NOT EDR specifications.


Contamination Risk Assessment

High-Risk Areas for EDR Contamination

  1. Query Parameter Names: EDR uses parameters like parameter-name, coords, z, datetime - CSAPI has different filters
  2. Resource Names: EDR has collections, instances, positions - CSAPI has systems, deployments, procedures, etc.
  3. Data Formats: EDR responses vs CSAPI GeoJSON/SensorML formats
  4. Validation Rules: EDR-specific validation should not appear in CSAPI validators

Verification Checklist for EDR Contamination

Before completion of this audit, verify:

  • No EDR-specific query parameters in CSAPI query options interfaces
  • No EDR resource names (collections, instances, positions, areas, locations, corridors, cubes, trajectories) in CSAPI code
  • No EDR response format expectations in CSAPI parsers
  • No EDR-specific validation in CSAPI validators
  • All CSAPI resources align with OGC 23-001r2/23-002r1, not EDR standard
  • URL patterns follow CSAPI spec, not EDR patterns (except where general OGC API patterns apply)

Audit Objective

Verify CSAPI implementation follows the structural patterns and integration conventions established by PR #114, while ensuring zero contamination from EDR-specific specifications. This audit focuses on code organization, not API specifics.


A. File Structure and Organization

A.1 Directory Structure Pattern (STRUCTURAL ONLY)

What to verify:

  • EDR Pattern: src/ogc-api/edr/ directory structure
  • CSAPI Implementation: src/ogc-api/csapi/ with similar organization
  • Verify file naming conventions match library standards
  • Verify directory structure is consistent with other OGC APIs in library
  • Evidence: File structure mirrors EDR organization (NOT EDR content)

Contamination Check:

  • Verify no files named with EDR-specific terms (positions, instances, areas, etc.)
  • Verify all file names reflect CSAPI resources (systems, deployments, procedures, etc.)

A.2 Index File (src/ogc-api/csapi/index.ts)

What to verify:

  • EDR Pattern: Exports all public types and classes
  • CSAPI Implementation: Similar export structure (NOT same types)
  • Verify all CSAPI public APIs exported (not EDR APIs)
  • Verify no private/internal exports
  • Code: src/ogc-api/csapi/index.ts
  • Evidence: Export structure follows EDR pattern, content is CSAPI-specific

Contamination Check:

  • Verify no EDR types exported from CSAPI index
  • Verify all exported types are CSAPI-specific (SystemFeature, not PositionFeature)

A.3 Main Module Export (src/index.ts)

What to verify:

  • EDR Pattern: Re-exports from ogc-api/edr
  • CSAPI Implementation: Re-exports from ogc-api/csapi (separate from EDR)
  • Verify CSAPI exported alongside EDR, WFS, STAC, etc. (not merged with EDR)
  • Code: src/index.ts
  • Evidence: CSAPI integrated as independent module

Contamination Check:

  • Verify CSAPI and EDR are separate, independent exports
  • Verify no shared types between CSAPI and EDR modules

B. Model Definitions (model.ts)

B.1 Query Options Interfaces (PATTERN ONLY, NOT CONTENT)

What to verify:

  • EDR Pattern: Interface structure for query parameters
  • CSAPI Implementation: Similar interface patterns with CSAPI-specific parameters
  • Verify interfaces use consistent naming conventions with library
  • Verify optional properties use ? syntax
  • Verify no required properties that should be optional
  • Code: src/ogc-api/csapi/model.ts
  • Evidence: Query options follow library interface pattern

Contamination Check:

  • CRITICAL: Verify NO EDR query parameters (parameter-name, coords, z, within, within-units)
  • REQUIRED: All parameters from OGC 23-001r2/23-002r1 specs (limit, bbox, datetime, q, id, foi, system, etc.)
  • Verify parameter names match CSAPI spec exactly (camelCase as per CSAPI standard)

EDR Parameters to AVOID:

// ❌ NEVER use these in CSAPI code:
parameter-name?: string;  // EDR-specific
coords?: string;          // EDR-specific  
z?: string;               // EDR-specific
within?: number;          // EDR-specific
within-units?: string;    // EDR-specific

CSAPI Parameters (Examples):

// ✅ Use CSAPI-specific parameters from OGC 23-001r2/23-002r1:
limit?: number;
bbox?: BoundingBox;
datetime?: DateTimeParameter;
q?: string;
id?: string | string[];
foi?: string | string[];
system?: string;
procedure?: string;
observedProperty?: string;
controlledProperty?: string;
// etc. - ALL from CSAPI spec

B.2 Type Definitions (PATTERN ONLY)

What to verify:

  • EDR Pattern: Separate directories for complex types
  • CSAPI Implementation: GeoJSON, SensorML, SWE Common types in separate directories
  • Verify type organization matches library structure (not EDR content)
  • Code: src/ogc-api/csapi/geojson/, sensorml/, swe-common/
  • Evidence: Type organization follows library conventions

Contamination Check:

  • Verify no EDR-specific types (PositionFeature, CoverageJSON, etc.)
  • Verify all types from CSAPI/SensorML/SWE Common specs

B.3 Resource Interfaces (CSAPI-SPECIFIC)

What to verify:

  • EDR Pattern: Feature interfaces extend GeoJSON Feature where appropriate
  • CSAPI Implementation: SystemFeature, DeploymentFeature, etc. extend GeoJSON Feature
  • Verify interfaces follow GeoJSON pattern (not EDR data model)
  • Verify property naming matches CSAPI spec (camelCase per OGC 23-001r2)
  • Code: GeoJSON type files
  • Evidence: Resource interfaces follow GeoJSON/CSAPI patterns

Contamination Check:

  • ❌ Verify NO EDR resources (Position, Area, Location, Corridor, Cube, Trajectory)
  • ✅ Only CSAPI resources (System, Deployment, Procedure, SamplingFeature, Property, Datastream, Observation, ControlStream, Command)

C. Navigator Class (navigator.ts)

C.1 Class Structure (PATTERN ONLY)

What to verify:

  • EDR Pattern: Navigator class with URL builder methods
  • CSAPI Implementation: CSAPINavigator class follows same structural pattern
  • Verify constructor pattern matches library conventions
  • Code: src/ogc-api/csapi/navigator.ts
  • Evidence: Navigator class structure consistent with library

Contamination Check:

  • Verify class name is CSAPINavigator (or similar), NOT EdrNavigator
  • Verify no EDR methods (getPositionsUrl, getAreasUrl, etc.)

C.2 URL Builder Method Naming (PATTERN ONLY)

What to verify:

  • EDR Pattern: Descriptive method names following library conventions
  • CSAPI Implementation: Consistent naming for CSAPI resources
  • Verify CRUD method naming conventions:
    • GET collection: getResourcesUrl() (e.g., getSystemsUrl())
    • GET individual: getResourceUrl(id) (e.g., getSystemUrl(id))
    • POST: createResourceUrl() (e.g., createSystemUrl())
    • PUT: updateResourceUrl(id) (e.g., updateSystemUrl(id))
    • DELETE: deleteResourceUrl(id) (e.g., deleteSystemUrl(id))
  • Code: Navigator method names
  • Evidence: Naming conventions match library pattern

Contamination Check:

  • CRITICAL: Verify NO EDR method names:
    • getCollectionsUrl() - generic, but should be CSAPI-specific
    • getInstancesUrl() - EDR-specific
    • getPositionsUrl() - EDR-specific
    • getAreasUrl() - EDR-specific
    • getLocationsUrl() - EDR-specific
    • getCorridorsUrl() - EDR-specific
    • getCubesUrl() - EDR-specific
    • getTrajectoriesUrl() - EDR-specific
  • REQUIRED: Only CSAPI method names:
    • getSystemsUrl(), getSystemUrl(id)
    • getDeploymentsUrl(), getDeploymentUrl(id)
    • getProceduresUrl(), getProcedureUrl(id)
    • getSamplingFeaturesUrl(), getSamplingFeatureUrl(id)
    • getPropertiesUrl(), getPropertyUrl(id)
    • getDatastreamsUrl(), getDatastreamUrl(id)
    • getObservationsUrl(), getObservationUrl(id)
    • getControlStreamsUrl(), getControlStreamUrl(id)
    • getCommandsUrl(), getCommandUrl(id)

C.3 URL Construction Logic (PATTERN ONLY)

What to verify:

  • EDR Pattern: URL building utilities, proper query string encoding
  • CSAPI Implementation: Same URL construction approach
  • Verify query parameters properly encoded
  • Verify path construction follows library conventions
  • Code: URL construction code
  • Evidence: URL building logic matches library pattern

Contamination Check:

  • Verify URL paths match CSAPI spec, not EDR spec
  • Example: /systems not /collections/{collectionId}/instances
  • Verify query string parameters match CSAPI spec

D. Parsers and Validators

D.1 Parser Pattern (STRUCTURE ONLY)

What to verify:

  • EDR Pattern: Parser organization and error handling structure
  • CSAPI Implementation: Parsers for CSAPI resources with similar structure
  • Verify parsers handle CSAPI-specific formats (GeoJSON, SensorML, SWE Common)
  • Verify parsers handle errors gracefully
  • Code: src/ogc-api/csapi/parsers/
  • Evidence: Parser structure consistent with library

Contamination Check:

  • ❌ Verify NO EDR format parsers (CoverageJSON, etc.)
  • ✅ Only CSAPI format parsers (GeoJSON Features, SensorML 3.0, SWE Common)

D.2 Validator Pattern (STRUCTURE ONLY)

What to verify:

  • EDR Pattern: Validator organization structure
  • CSAPI Implementation: Validators for CSAPI resources following similar structure
  • Verify validators check CSAPI-specific requirements
  • Verify validators return meaningful error messages
  • Code: src/ogc-api/csapi/validation/
  • Evidence: Validator structure consistent with library

Contamination Check:

  • ❌ Verify NO EDR validation rules
  • ✅ Only CSAPI validation rules (GeoJSON Feature validation, SensorML 3.0 validation, SWE Common validation)

E. Testing Strategy

E.1 Test File Organization (PATTERN ONLY)

What to verify:

  • EDR Pattern: Test file organization structure
  • CSAPI Implementation: Same organization pattern with CSAPI-specific tests
  • Verify test files mirror source file structure
  • Code: Test file structure
  • Evidence: Test organization matches library conventions

Contamination Check:

  • Verify no EDR test fixtures used for CSAPI tests
  • Verify all test data is CSAPI-compliant (from OGC 23-001r2/23-002r1 examples)

E.2 Mock Data and Fixtures

What to verify:

  • EDR Pattern: Fixtures directory structure
  • CSAPI Implementation: CSAPI fixtures in similar structure
  • Verify fixture data is CSAPI spec-compliant
  • Code: fixtures/ogc-api/csapi/ or similar
  • Evidence: Fixture organization consistent with library

Contamination Check:

  • CRITICAL: Verify NO EDR fixture data in CSAPI tests
  • REQUIRED: All fixtures from CSAPI spec examples or conformant servers
  • Verify fixtures match CSAPI response formats (GeoJSON Features, SensorML, not CoverageJSON)

F. Documentation Style

F.1 JSDoc Comments (STYLE ONLY)

What to verify:

  • EDR Pattern: JSDoc style and format
  • CSAPI Implementation: Same JSDoc style with CSAPI-specific descriptions
  • Verify parameter descriptions reference CSAPI spec
  • Verify examples are CSAPI-specific
  • Code: JSDoc in navigator and model files
  • Evidence: Documentation style matches library

Contamination Check:

  • Verify JSDoc descriptions don't reference EDR spec
  • Verify all spec references are to OGC 23-001r2 or OGC 23-002r1
  • Verify examples use CSAPI resources, not EDR resources

G. Code Review Checklist for EDR Contamination

Before marking this audit complete, perform final contamination check:

G.1 String Literal Search

Search codebase for EDR-specific terms that should NOT appear:

  • "parameter-name" - EDR query param
  • "coords" - EDR query param
  • "within-units" - EDR query param
  • "instance" - EDR resource (unless in generic context)
  • "position" (check context - can be geometry position vs EDR Position resource)
  • "area" (check context - can be geometric area vs EDR Area resource)
  • "corridor" - EDR resource
  • "cube" - EDR resource
  • "trajectory" - EDR resource
  • "CoverageJSON" - EDR format
  • Reference to EDR spec (OGC 19-086r6 or similar)

G.2 Import Statement Review

  • Verify no imports from ogc-api/edr/ in CSAPI code
  • Verify CSAPI and EDR are completely independent modules

G.3 Type Definition Review

  • Verify all interfaces/types in CSAPI align with OGC 23-001r2/23-002r1
  • Verify no types borrowed from EDR implementation

G.4 Test Fixture Review

  • Verify all test fixtures are CSAPI-compliant
  • Verify no EDR response examples used in CSAPI tests

H. Positive Pattern Alignment (What to Match)

These are the patterns to positively match from EDR (structural only):

Directory Structure:

  • src/ogc-api/csapi/ (like src/ogc-api/edr/)
  • Separate subdirectories for types (geojson/, sensorml/, etc.)

File Organization:

  • index.ts - exports
  • model.ts - query options and types
  • navigator.ts - URL builders
  • formats.ts - format detection (if needed)

Navigator Method Patterns:

  • Consistent naming: getResourcesUrl(), getResourceUrl(id)
  • Query options as parameters
  • Returns URL strings, no HTTP calls

TypeScript Conventions:

  • Strong typing throughout
  • Interfaces for object types
  • JSDoc comments on public APIs
  • No implicit any

Test Organization:

  • *.spec.ts files mirror source structure
  • Describe blocks per resource/method
  • Fixtures in fixtures/ directory

Build Integration:

  • No special build steps
  • Standard TypeScript compilation
  • Integrates with existing build process

Verification Methodology

For Each Audit Section:

  1. Review EDR PR #114: Understand structural pattern only
  2. Locate CSAPI Code: Find corresponding implementation
  3. Verify Pattern Match: Structure matches, content is CSAPI-specific
  4. Verify No Contamination: No EDR specifics in CSAPI code
  5. Document Status: ✅ MATCHES | ⚠️ DEVIATION (JUSTIFIED) | ❌ CONTAMINATION FOUND
  6. Evidence: Link to code, contamination check results

Contamination Response:
If ANY EDR-specific content found in CSAPI code:

  1. Document finding with file/line reference
  2. Assess severity (HIGH if affects functionality, MEDIUM if naming/comments)
  3. Create remediation task to remove EDR contamination
  4. Mark as BLOCKER if high severity

Execution Status

  • EDR PR #114 Reviewed (structure only, not content)
  • CSAPI Code Compared (pattern alignment verified)
  • EDR Contamination Check Performed
  • Pattern Compliance Verified
  • Deviations Documented and Justified
  • Audit Complete

Audit Date: TBD
Auditor: TBD
Overall Status: 🔴 NOT STARTED


Final Checklist

Before closing this audit:

  • ✅ CSAPI follows EDR structural patterns
  • ✅ CSAPI has zero EDR-specific content
  • ✅ All CSAPI code references OGC 23-001r2/23-002r1 specs
  • ✅ No EDR query parameters in CSAPI
  • ✅ No EDR resource names in CSAPI
  • ✅ No EDR formats in CSAPI parsers
  • ✅ Test fixtures are CSAPI-compliant
  • ✅ Documentation references CSAPI spec only

PASS CRITERIA: Structural patterns match + ZERO contamination

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions