Building Geoconnex Web Resources
This section provides step-by-step guidance to build Geoconnex Web Resources, which should be an HTML webpage with a unique URL within which is embedded an JSON-LD document.
Geoconnex JSON-LD elements
A Geoconnex JSON-LD document should be embedded in a human-readable website that is about either a Location or a Dataset.
- Documents about Locations should ideally include references to relevant Hydrologic Features, Cataloging Features, and Datasets.
- Documents about Datasets must include references to one or more relevant Reference Monitoring Locations or Hydrologic Features or Cataloging Features, or declare their spatial coverage.
Context
Geoconnex JSON-LD documents can have varying contexts. There are several vocabularies other than schema.org that may be useful, depending on the type of location and dataset being described and the level of specificity for which metadata is produced by the data provider. The example context below can serve as general-purpose starting point, although simpler contexts may be sufficient for many documents:
"@context": {
"@vocab": "https://schema.org/",
"xsd": "https://www.w3.org/TR/xmlschema-2/#",
"rdfs": "http://www.w3.org/2000/01/rdf-schema#",
"dc": "http://purl.org/dc/terms/",
"dcat": "https://www.w3.org/ns/dcat#",
"freq": "http://purl.org/cld/freq/",
"qudt": "http://qudt.org/schema/qudt/",
"qudt-units": "http://qudt.org/vocab/unit/",
"qudt-quantkinds": "http://qudt.org/vocab/quantitykind/",
"gsp": "http://www.opengis.net/ont/geosparql#",
"locType": "http://vocabulary.odm2.org/sitetype",
"odm2var":"http://vocabulary.odm2.org/variablename/",
"odm2varType": "http://vocabulary.odm2.org/variabletype/",
"hyf": "https://www.opengis.net/def/schema/hy_features/hyf/",
"skos": "https://www.opengis.net/def/schema/hy_features/hyf/HY_HydroLocationType",
"ssn": "http://www.w3.org/ns/ssn/",
"ssn-system": "http://www.w3.org/ns/ssn/systems/"
}
| Key | Description |
|---|---|
@vocab | specifies schema as the default vocabulary from https://schema.org |
xsd | is a general web-enabled data types vocabulary (e.g., text vs number vs. datetime) |
rdfs | is a general vocabulary for basic relationships |
dc | is the Dublin Core vocabulary for general information metadata attributes |
dcat | is the Data Catalog (DCAT) Vocabulary, a vocabulary for dataset metadata attributes |
freq | is the Dublin Core Collection Frequency Vocabulary, a vocabulary for dataset temporal resolution and update frequency |
qudt-units | provides standard identifiers for units (e.g. cubic feet per second) |
qudt-quantkinds | provides ids for general phenomena (e.g. Volume flow rate) which may be measured in various units |
gsp | provides ids for spatial relationships (e.g. intersects) |
odm2var | is a supplement to qudt-quantkinds, and includes ids for many variables relevant to water science and management (e.g. turbidity) |
odm2varType | is a supplement to odm2var that includes ids for large groupings of variables (e.g. Water Quality) |
hyf | provides ids for surface water hydrology concepts (e.g. streams) |
skos | provides general properties for relating different concepts (e.g. broader, narrower, exact Match) |
ssn | and ssn-system provide ids for aspects of observations and measurement (e.g. measurement methods) |
Reference Features
Embedding links to URIs of Reference Features are the best way to ensure that your data can be related to other data providers' data. URIs for reference features are available from the Geoconnex reference feature server. Reference features can be one of three types:
- Monitoring Locations which are common locations that many organizations might have data about such as a streamgage station e.g. https://geoconnex.us/ref/gages/1143822
- Hydrologic Features which are common specific features of the hydrologic landscape that many organizations have data about. These could include confluence points, aquifers, stream segments and river mainstems and named tributaries, e.g. https://geoconnex.us/ref/mainstems/29559>.
- Cataloging Features which are larger area units that are commonly used to group and filter data, such as HUCs1, states2, counties3, PLSS grids, public agency operating districts, etc.
Location or Dataset oriented?
Depending on what kind of resource i.e. (location or dataset) and the level of metadata you have available to publish, you can use different elements of the @context or use Reference Features in various ways.
There are two basic patterns to think about:
-
Location-orientedwebpages that include a catalog of parameters and periods of record for which there is data about the location. This pattern may be suitable where data can be accessed separately for each location and possibly for each parameter for each location. This is typical of streamgages, monitoring wells, water diversions, reservoirs, regulated effluent discharge locations, etc. where there is an ongoing monitoring or modeling program that includes data collection or generation for multiple parameters. The Monitor My Watershed Site pages published by the Stroud Center are an example of this pattern. At this page, one finds a variety of information about a specific location, such as that location's identifier and name and a map of where it is. In addition there is information about which continuous sensor and field water quality sample data are available about the location, and links to download these data. -
Dataset-orientedwebpages that tag which locations are relevant to the dataset described at a given page. This pattern may be suitable for static datasets where data was collected or modeled for a consistent set of parameters for a pre-specified research question and time period across one or more locations, and where it would not make sense to publish separate metadata for the parts of the dataset that are relevant to each individual feature and parameter. This is typical of datasets created for, and published in association withm scientific and regulatory studies. This dataset record published on CUAHSI's Hydroshare platform is an example, where there is a "Related Geospatial Features" section that explicitly identifies several features that the dataset has data about.
In some cases, it is possible to set up a web architecture that implements both patterns. For example, the Wyoming State Engineer's Office Web Portal conceptualizes a time series for a specific parameter at a specific location as a dataset. Thus, webpages exist for both Locations and Datasets, and they link to each other where relevant. In this case, it is only necessary to implement Geoconnex embedded JSON-LD at either the Location or Dataset level, although both could be done as well.