Overview
Geoconnex development is guided by the spatial data on the web best practices put forth by W3C and OGC.
Feedback
Geoconnex development occurs on Github and all technical details or feedback on best practices can be submitted via GitHub issues
Governance
All Geoconnex material, including these docs and ideas on best practices more generally are open to public discussions via all of the following:
- Email: internetofwater@lincolninst.edu
- The Geoconnex working group
- This group is open membership and discusses feature proposals and issues related to Geoconnex. The consensus of its quarterly meetings advises the technical implementation of Geoconnex in the Internet of Water Coalition
Below is the modified version of your Geoconnex Best Practices Registry table. Inline hyperlinks have been added to key terms and explanations so that readers can immediately access the original W3C, OGC, SELFIE, or other authoritative resources:
Geoconnex Best Practices Registry
Throughout the Geoconnex docs you can find links to explanations of general best practices that motivate Geoconnex development as well as how these best practices are implemented and used in practice. Many of these best practices are inspired by the W3C Spatial Data on the Web Best Practices and the Second Environmental Linked Features Experiment (SELFIE).
Persistent Identifiers & URI Management
| Best Practice | Context | Further Reference | Geoconnex Usage / Relevant Tutorials |
|---|---|---|---|
| Use stable HTTP URIs as identifiers | Create identifiers that remain consistent even when underlying resources change | Follow URI/URL separation principles per W3C SDW Best Practices. | Minting Persistent Identifiers |
| Implement well-structured URI hierarchies | Design URI patterns with logical organization by agency, feature type, and specific ID | Adopt structured naming as described in the Identification scheme guidelines, aligning with W3C best practices. | Picking an identifier scheme |
| Register PIDs with geoconnex.us | Follow the established process for adding identifiers to the official registry | Refer to the identifier explanation and register following standards for persistent identifiers. | CSV formatting for submissions |
| Use 303 redirects for non-information resources | Separate real-world features from their digital representations | Implement 303 redirects as per Linked Data principles. | Web architecture overview |
| Follow general identifier best practices | Ensure that URIs are truly persistent, resolvable, and usable | Ensure URI stability for scientific purposes as detailed here. | Minting Persistent Identifiers |
JSON-LD Implementation & Data Modeling
| Best Practice | Context | Further Reference | Geoconnex Usage / Relevant Tutorials |
|---|---|---|---|
| Conform to one canonical shape | Publish every resource against the same validated structure | Validate against the single Geoconnex SHACL shape, which formalizes the modeling guidance in W3C SDW. | Building Geoconnex Web Resources |
| Include complete context declarations | Define all vocabularies and prefixes used in your JSON-LD | Include full context definitions following JSON-LD standards, as referenced in the Context prefixes reference. | JSON-LD Primer |
| Use schema.org as primary vocabulary | Leverage widely adopted schema.org terms for core properties | Adopt the schema.org vocabulary for common properties, consistent with W3C best practices. | Example JSON-LD documents |
| Apply hydrologic domain vocabularies | Include specialized vocabularies for water-specific metadata | Integrate domain-specific vocabularies as shown in the HY_Features implementation following OGC guidelines. | Features in JSON-LD |
| Validate JSON-LD structure | Ensure your JSON-LD is valid and parsable | Use the JSON-LD Playground to check the document parses, then the Geoconnex SHACL shape to check it conforms. | SHACL validation playground |
| Differentiate in-band and out-of-band resources | Follow SELFIE's pattern to handle different resource types | Implement separation of resource types as described in the SELFIE in-band/out-of-band explanation. | Linking datasets |
Hydrologic Feature Representation
| Best Practice | Context | Further Reference | Geoconnex Usage / Relevant Tutorials |
|---|---|---|---|
| Reference established hydrologic features | Link locations to standard rivers, watersheds, or aquifers | Use established references to hydrologic features following guidelines in the Hydrologic references and OGC recommendations. | Adding contextual information |
| Use hyf:referencedPosition for surface water | Connect monitoring locations to specific stream segments | Utilize the HY_Features implementation approach, consistent with SELFIE guidance. | Features in JSON-LD |
| Implement isSampleOf for groundwater | Properly associate groundwater monitoring with specific aquifers | Follow best practices for linking sample data using isSampleOf, as detailed in the Groundwater references. | Adding context to data |
| Include hydrologic unit codes | Reference watershed boundaries at appropriate scale | Document hydrologic units based on reference cataloging features and align with OGC standards. | Spatial queries with reference features |
| Link to upstream/downstream features | Use mainstem references to enable network-based discovery | Implement network relationships as suggested in Finding related features and guided by SELFIE. | Datasets on rivers example |
| Use appropriate relation types | Apply SELFIE recommended relation types for feature connections | Refer to recommended spatial relationship patterns for establishing feature relationships. | Implementing feature relationships |
Geospatial Data Representation
| Best Practice | Context | Further Reference | Geoconnex Usage / Relevant Tutorials |
|---|---|---|---|
| Include both schema.org and GeoSPARQL geometry | Provide geometry in both simple and standards-compliant formats | Combine schema.org and GeoSPARQL geometries to support diverse client needs, as illustrated in the Spatial geometry in JSON-LD guide. | Features in JSON-LD |
| Specify coordinate reference systems | Always declare the CRS for spatial data | Clearly define CRS following GeoSPARQL implementation and best practices from W3C SDW. | Spatial geometry in JSON-LD |
| Represent complex geometries with WKT | Use Well-Known Text for non-point geometries | Utilize WKT for representing complex geometries, in line with the Spatial Coverage example. | Spatial Coverage JSON-LD |
| Define spatial coverage for datasets | Specify the geographic extent of datasets | Document dataset extents as described in Spatial Coverage in JSON-LD following W3C SDW guidelines. | Dataset spatial coverage |
| Support spatial queries in APIs | Enable filtering and discovery by location | Implement spatial queries as per OGC API – Features and W3C SDW Best Practices. | Spatial query capabilities |
| Provide geometries at appropriate precision | Balance detail level with usability | TBD | TBD |
Data Access & Distribution
| Best Practice | Context | Further Reference | Geoconnex Usage / Relevant Tutorials |
|---|---|---|---|
| Provide direct download links | Include URLs to access the actual data | Offer direct download links in compliance with W3C SDW distribution recommendations. | Distributions in JSON-LD |
| Document data formats | Specify encodingFormat for all data downloads | Clearly document formats using Data Distribution guidelines and common standards. | Finding datasets example |
| Include API endpoints | Reference web services that provide programmatic data access | Include service endpoints. | Distribution section |
| Specify license and access conditions | Document usage rights and any access restrictions | Clearly indicate licensing and restrictions following W3C licensing guidelines and industry standards. | Dataset properties |
| Reference data dictionaries | Link to documentation explaining data structure | Connect to data dictionaries as per Data conformance links and best practices. | Distribution example |
| Expose data through standard APIs | Leverage standard API patterns | Follow W3C spatial API recommendations to provide simplified data access, preferably using OGC API standards. | Building APIs with OGC standards |
Data Quality & Provenance
| Best Practice | Context | Further Reference | Geoconnex Usage / Relevant Tutorials |
|---|
| Include temporal resolution | Document the frequency of observations | Use temporal metadata practices as per W3C temporal data guidance to clearly document observation frequency. | Temporal coverage | | Provide quantitative unit definitions | Reference standard units from QUDT vocabulary | Define units using standard vocabularies (e.g. QUDT) in alignment with W3C data quality practices. | Variables and Methods | | Document data provider information | Include organization name, type, and contact information | Provide comprehensive provider metadata following W3C provenance guidelines and internal Provider specification. | Provider and publisher | | Describe the changing nature of spatial things | Document how features change over time | TBD | TBD |
Search Engine Optimization & Discoverability
| Best Practice | Context | Further Reference | Geoconnex Usage / Relevant Tutorials |
|---|---|---|---|
| Make data indexable by search engines | Enable web crawlers to discover and index spatial data | Optimize pages using W3C search indexing best practice guidelines. | Implementing crawler-friendly pages |
| Include structured data in HTML | Use JSON-LD in script tags with Schema.org vocabulary to enable web crawlers to discover and index spatial data | W3C recommendations to enhance search visibility. | Adding JSON-LD to HTML |
| Generate and maintain sitemaps | Help search engines discover all your spatial resources | Create and update sitemaps following sitemap generation best practices and W3C guidelines. | Geoconnex architecture |
| Create landing pages for all resources | Provide human-readable entry points for each resource | Develop clear landing pages as recommended by W3C landing page guidance. | Resource landing pages |
Technical Implementation
| Best Practice | Context | Further Reference | Geoconnex Usage / Relevant Tutorials |
|---|---|---|---|
| Use OGC API-Features for vector data | Implement standard APIs for accessing feature data | Leverage the OGC API – Features specification to standardize data access. | Accessing reference features |
| Expose data via open source tools | Leverage open-source tools for OGC API deployment | Utilize pygeoapi following deployment guidelines to meet OGC standards. | Wrapping data with pygeoapi |
| Support SPARQL for knowledge graph queries | Enable complex semantic queries | Implement SPARQL for querying linked data, following semantic web best practices. | Finding datasets with SPARQL |
| Implement GeoJSON outputs | Provide data in widely supported geospatial formats | Use the GeoJSON format to deliver spatial data in a web-friendly format. | Attribute queries |
| Support content negotiation | Allow clients to request preferred data formats | Enable content negotiation in your API to serve multiple representations. | Wrapping data with pygeoapi |
Community & Governance
| Best Practice | Context | Further Reference | Geoconnex Usage / Relevant Tutorials |
|---|---|---|---|
| Participate in Geoconnex governance | Contribute to the multi-stakeholder community process | Engage with the community and follow internal Governance explanation guided by open standards. | Geoconnex Community |
| Contribute reference features | Add missing reference features to benefit the whole community | Follow the process outlined in the Reference feature development guidelines. | Adding reference features |
| Consider Network Linked Data Index | Contribute to the USGS NLDI for hydrologic network discovery | Leverage approaches similar to NLDI integration to enhance network connectivity. | Contributing to NLDI |
| Follow open source development practices | Engage with the community via GitHub | Adhere to open source practices as documented in the Geoconnex repositories. | Project repositories |
| Contribute to documentation | Help improve guidance for the community | Participate in enhancing the Documentation repository through feedback and updates. | Submit feedback |
| Practice responsible data ethics | Handle spatial data ethically and respect privacy | Follow W3C responsible use guidance to ensure ethical management of spatial data. | TBD |