| output | ||
|---|---|---|
|
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).
| Best Practice | Context | Detailed Explanation | 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. | Establish an identifier scheme |
| Register PIDs with geoconnex.us | Follow the established process for adding identifiers to the official registry | Refer to the Registry 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. | Geoconnex architecture overview |
| Maintain backwards compatibility | Never reuse or delete a previously assigned URI | Ensure URI stability as explained in the Reference features explanation to support legacy data references. | Updating PIDs via GitHub |
| Distinguish between URI-14 and URL-14 | Follow SELFIE's resource model to separate identifiers from landing pages | Apply concepts from the SELFIE resource model to differentiate resource types. | Implementing 303 redirects |
| Best Practice | Context | Detailed Explanation | Geoconnex Usage / Relevant Tutorials |
|---|---|---|---|
| Structure JSON-LD by resource type | Use appropriate templates for locations vs datasets | Leverage separate Location-oriented and Dataset-oriented templates, inspired by best practices in W3C SDW. | Templating JSON-LD |
| 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. | Location-oriented JSON-LD |
| Validate JSON-LD structure | Ensure your JSON-LD is valid and parsable | Use tools like the JSON-LD Playground to validate structure as outlined in the JSON-LD overview. | Templating verification |
| 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 spatial data |
| Best Practice | Context | Detailed Explanation | 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. | Location-oriented 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 |
| Best Practice | Context | Detailed Explanation | 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. | Location-oriented 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. | Dataset-oriented 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 | Follow precision guidelines from SELFIE geometry precision guidance to ensure optimal data representation. | Implementing right-sized geometries |
| Best Practice | Context | Detailed Explanation | 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. | Dataset section 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 as per W3C SDW API recommendations and OGC API standards. | 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-oriented example |
| 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 'convenience APIs' | Create user-friendly APIs tailored for specific uses | Follow W3C convenience API recommendations to provide simplified data access. | Building APIs with OGC standards |
| Best Practice | Context | Detailed Explanation | Geoconnex Usage / Relevant Tutorials |
|---|---|---|---|
| Document measurement techniques | Distinguish between observed, modeled, or derived data | Detail measurement techniques per W3C SDW best practices and internal Measurement technique reference. | Variables and Methods |
| Specify data collection methods | Include details on instrumentation and procedures | Follow guidelines using the measurementMethod property as recommended by W3C SDW. | Dataset section example |
| Include temporal resolution | Document the frequency of observations | Use temporal metadata practices as per W3C temporal data guidance to clearly document observation frequency. | Dataset section example |
| 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. | Identifiers and provenance |
| Describe the changing nature of spatial things | Document how features change over time | Address temporal changes as per W3C temporal guidance to track feature evolution. | Versioning spatial features |
| Best Practice | Context | Detailed Explanation | 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 | Embed structured data as per 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 |
| Best Practice | Context | Detailed Explanation | Geoconnex Usage / Relevant Tutorials |
|---|---|---|---|
| Use OGC API-Features for reference data | Implement standard APIs for accessing feature data | Leverage the OGC API -- Features specification to standardize data access. | Accessing reference features |
| Expose data via pygeoapi | Leverage open-source tools for OGC API deployment | Utilize pygeoapi following deployment guidelines to meet OGC standards. | Wrapping data with pygeoapi |
| Generate sitemaps for harvesters | Enable automated discovery of all resources | Create sitemaps as per W3C recommendations to support automated harvesters. | Geoconnex architecture |
| 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. | Implementing content negotiation |
| Best Practice | Context | Detailed Explanation | 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. | Ethical spatial data publication |