Skip to content

Link your data to a mainstem

Linking means storing the mainstem URI alongside your feature — a monitoring site, a reach-based assessment, a permit, a modeled output — so that anyone holding the same URI can find your data and you can find theirs.

What to store

Store the full URI, https://geoconnex.us/ref/mainstems/29559, not the bare integer. The URI is resolvable and self-describing; the integer requires a reader to know the URI namespace.

Store the URI identifier, never the reference.geoconnex.us URL you land on after the redirect — see Reference Features.

If your feature is a point on a river, store the mainstem URI plus your own position information — a COMID, a measure, or coordinates. The mainstem reference says which river; it does not say where on the river.

The omission is deliberate on the reference side. Position along a river is the part of a link that breaks when the channel is remapped or the segmentation changes, so the reference model records only that a location is on a given mainstem and leaves measure to the applications that need it.

Choosing the right mainstem

Every location should get one mainstem and only one. Point features take the mainstem of the flowline they sit on, resolved through the COMID or NHDPlusHR crosswalk rather than by nearest-line distance. At a confluence, the location could belong to the receiving mainstem or the tributary. In cases where a site's position is uncertain relative to a receiving / tributary pair, additional evidence such as name or drainage area is often needed.

Features that span a river — a reach assessment, a segment-based model output — take the mainstem of the segments they cover. Where they cross a confluence such that more than one mainstem applies, more than one link can be recorded rather than picking the larger river.

Polygon features on the water follow the same one-mainstem rule with a tiebreaker: a lake or wide-river polygon takes the most downstream mainstem flowing out of it. Where more than one mainstem exits a single waterbody, the polygon can link to multiple mainstems or linked to the most prominent one.

Re-check your links against each minor release. The work is a filter on superseded and a follow of new_mainstemid, described in Persistence and change. Between releases nothing needs to happen.

Tools that automate mainstem identifier maintenance will be made available in the future.

To make your links discoverable, publish them through the geoconnex system so the crawler picks them up and your data appears on the mainstems it references. The mechanics — namespace registration, identifier minting, sitemaps, and how to structure landing content and relations — are documented in the contributing guide and the JSON-LD primer.

The mainstem-specific part is which URI to put in the hyf:referencedPosition of your feature — hyf: being the HY_Features vocabulary used in geoconnex JSON-LD — which the sections above cover.