Skip to content

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

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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