reference mainstems

docs/contributing/going-further/reference.md

@@ -1,3 +1,23 @@
+---
+title: Adding reference features
+---
+
 # Adding reference features to reference.geoconnex.us
 
-[https://reference.geoconnex.us](https://reference.geoconnex.us) is available to host community reference features. See the readme in the [reference folder](https://github.com/internetofwater/geoconnex.us/tree/master/namespaces/ref) for more info.
+[reference.geoconnex.us](https://reference.geoconnex.us/) can host community reference feature collections. Any group willing to steward a collection over time can propose one — the maintenance is a longer commitment than the initial publication.
+
+## What a collection needs
+
+**An identifier scheme.** Identifiers take the form `https://geoconnex.us/ref/{collection}/{id}`. An opaque local part is the safer choice, because one that carries no parseable meaning cannot be invalidated when whatever it encoded changes. Some collections do reuse a stable external code — FIPS for counties and states, HUC for hydrologic units — but that only holds where the code is centrally governed and is not renumbered.
+
+**A commitment to uniqueness and permanence.** One identifier, one real-world feature, never reused and never removed. This is the one policy shared across all collections. See [Reference Features](/reference/reference_features).
+
+**A documented maintenance policy.** How features qualify for an identifier, how representations improve, how supersession is decided and recorded, who does the work, and on what cadence. These answers depend on your feature type and belong in your collection's own documentation.
+
+**Landing content.** Each feature needs a description that resolves, links to representations and related features, and states relationships between identifiers rather than between pages. See the [JSON-LD primer](/reference/data-formats/jsonld/primer/) and the [best practices registry](/reference/overview).
+
+## Getting started
+
+Open an issue in [geoconnex.us](https://github.com/internetofwater/geoconnex.us/issues) describing the feature type, the scope of the collection, and who will steward it. The [Geoconnex working group](/about/community) reviews proposals. The README in the [reference folder](https://github.com/internetofwater/geoconnex.us/tree/master/namespaces/ref) covers the mechanics of the namespace.
+
+[ref_rivers](https://github.com/internetofwater/ref_rivers) and its [users manual](https://internetofwater.github.io/ref_rivers/) show a collection that has worked through these decisions in public.

docs/reference/reference_features.md

@@ -1,17 +1,44 @@
+---
+title: Reference Features
+sidebar_position: 2
+---
+
 # Reference Features
 
-Geoconnex uses reference features to standardize references to the same real-world things such as watersheds, monitoring locations, or counties. 
+Geoconnex uses reference features to standardize references to the same real-world things — watersheds, monitoring locations, mainstem rivers, dams, counties. Two organizations that use the same identifier for the same feature can combine their data without having agreed on anything else in advance.
+
+A reference feature is identified by a persistent identifier (PID) of the form `https://geoconnex.us/ref/{collection}/{id}`. Reference features are served from [reference.geoconnex.us](https://reference.geoconnex.us/), an OGC API - Features implementation; see [Access Geoconnex reference features](/access/reference/) for how to work with them.
+
+## The identifier policy
+
+One rule holds across every reference collection: **an identifier is unique and permanent**. It refers to one real-world feature, it is never reused for a different feature, and it is never removed.
+
+## What is collection-specific
+
+Everything other than uniqueness depends on the kind of feature being identified: for example, the criteria that distinguish one river from another do not apply to dams. Each collection's stewards decide the following and document it with the collection:
+
+- What an identifier represents. A reference collection only covers what its purpose requires, not necessarily every possible feature of that type.
+- How a feature's reference representation is improved over time, and what changes, or doesn't, when it is.
+- When an identifier is superseded, how that is recorded, and how you find the replacement. Superseded identifiers are retained rather than deleted, so they still resolve.
+- Who maintains the collection, on what cadence, and how to propose a change.
+
+:::tip
+Consult the documentation for the collection you are using, not this page, for any of the above. [Reference Mainstems](https://internetofwater.github.io/ref_rivers/) is an example of a collection documenting these decisions.
+:::
 
-The Geoconnex system uses persistent identifiers, also known as PIDs. These associate a feature with a static number so that one can change the name or details of a feature without breaking associated links.
+## Resolution
 
-These features can be found at https://reference.geoconnex.us/ and a guide to use reference feature data can be found in the [`Access Data` tab](../access/reference/)
+A reference feature identifier is a URI for a real-world thing, not the location of a document. Resolving it redirects to landing content on `reference.geoconnex.us` that describes the feature and links to representations and data. You can negotiate content from the identifier itself — `?f=json`, `?f=jsonld`, `?f=html`, or an `Accept` header — so a client never needs to hold the landing-content URL.
 
+:::warning
+Reference the identifier, never the landing-content URL you arrive at after the redirect. That URL only describes the identifier and can change when the service implementation changes, so it should not appear as the subject or object of a statement in your data. This follows the separation between the URI that identifies a thing and the URL that describes it — URI-14 and URL-14 in [SELFIE](https://docs.ogc.org/per/20-067.html).
+:::
 
 :::tip
 
 See the following pages for more background info:
 
-- [view how reference features fit into the overall system architecture](../about/system-architecture/stack.md)
+- [how reference features fit into the overall system architecture](../about/system-architecture/stack.md)
 - [how you can contribute reference features](../contributing/going-further/reference.md)
 
-:::
+:::