-
Notifications
You must be signed in to change notification settings - Fork 0
Description
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
- Query Parameter Names: EDR uses parameters like
parameter-name,coords,z,datetime- CSAPI has different filters - Resource Names: EDR has
collections,instances,positions- CSAPI hassystems,deployments,procedures, etc. - Data Formats: EDR responses vs CSAPI GeoJSON/SensorML formats
- 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-specificCSAPI 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 specB.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))
- GET collection:
- Code: Navigator method names
- Evidence: Naming conventions match library pattern
Contamination Check:
- ❌ CRITICAL: Verify NO EDR method names:
getCollectionsUrl()- generic, but should be CSAPI-specificgetInstancesUrl()- EDR-specificgetPositionsUrl()- EDR-specificgetAreasUrl()- EDR-specificgetLocationsUrl()- EDR-specificgetCorridorsUrl()- EDR-specificgetCubesUrl()- EDR-specificgetTrajectoriesUrl()- 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:
/systemsnot/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/(likesrc/ogc-api/edr/)- Separate subdirectories for types (
geojson/,sensorml/, etc.)
✅ File Organization:
index.ts- exportsmodel.ts- query options and typesnavigator.ts- URL buildersformats.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.tsfiles 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:
- Review EDR PR #114: Understand structural pattern only
- Locate CSAPI Code: Find corresponding implementation
- Verify Pattern Match: Structure matches, content is CSAPI-specific
- Verify No Contamination: No EDR specifics in CSAPI code
- Document Status: ✅ MATCHES |
⚠️ DEVIATION (JUSTIFIED) | ❌ CONTAMINATION FOUND - Evidence: Link to code, contamination check results
Contamination Response:
If ANY EDR-specific content found in CSAPI code:
- Document finding with file/line reference
- Assess severity (HIGH if affects functionality, MEDIUM if naming/comments)
- Create remediation task to remove EDR contamination
- 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