Hydrology Domain And Receptor Contract
Purpose
P114.1 defines the public spatial domain that later forest-hydrology and flood-risk work uses. It records watersheds, stream networks, roads, DEMs, land cover, soils, climate, hydrometric gauges, downstream receptors, HRUs, and provenance in one versioned manifest.
This is a data contract only. It does not download layers or run a hydrology model.
Domain Manifest
The manifest uses schema femic.hydrology.domain.v1 and the source
registry uses femic.hydrology.sources.v1. It records:
domain identity, creation time, CRS, and resolution;
layer roles, paths, formats, CRS, geometry, source IDs, licence, checksums, sizes, and optional resolution;
watershed records linked to a watershed layer;
downstream receptors linked to a watershed and receptor layer;
hydrometric gauges linked to a watershed and optional gauge layer;
caveats and provenance, including the source-registry version.
Required layer roles are:
watershedstreamroaddem
A domain must contain at least one watershed and at least one receptor. A gauge is strongly recommended but optional; a domain without one is valid with a calibration warning.
Source Registry
The default public registry covers:
Freshwater Atlas watersheds and streams;
Digital Road Atlas and forest-tenure road sections;
LidarBC DEM/DSM products;
VRI land cover;
BC soil landscapes;
PCIC climate data;
Water Survey of Canada gauges;
a reviewed receptor inventory.
Each source records a role, catalogue/service URL where available, licence, native CRS, required fields, and notes. Climate, soil, gauge, and receptor sources may require a reviewed local layer before use.
Python Usage
from pathlib import Path
from femic.hydrology.domain import (
HydrologyGauge,
HydrologyLayerSpec,
HydrologyReceptor,
HydrologyWatershed,
audit_hydrology_domain,
build_hydrology_domain,
write_hydrology_domain_manifest,
)
layers = (
HydrologyLayerSpec(
layer_id="watersheds",
role="watershed",
path="data/hydrology/watersheds.gpkg",
format="gpkg",
crs="EPSG:3005",
source_id="fwa_watersheds",
),
HydrologyLayerSpec(
layer_id="streams",
role="stream",
path="data/hydrology/streams.gpkg",
format="gpkg",
crs="EPSG:3005",
source_id="fwa_streams",
),
HydrologyLayerSpec(
layer_id="roads",
role="road",
path="data/hydrology/roads.gpkg",
format="gpkg",
crs="EPSG:3005",
source_id="road_atlas",
),
HydrologyLayerSpec(
layer_id="dem",
role="dem",
path="data/hydrology/dem.tif",
format="tif",
crs="EPSG:3005",
source_id="lidarbc_dem",
),
HydrologyLayerSpec(
layer_id="receptors",
role="receptor",
path="data/hydrology/receptors.gpkg",
format="gpkg",
crs="EPSG:3005",
source_id="receptor_inventory",
),
)
domain = build_hydrology_domain(
domain_id="example-watershed",
name="Example public watershed",
layers=layers,
watersheds=(
HydrologyWatershed("ws1", "Example Creek", 42.0, "watersheds"),
),
receptors=(
HydrologyReceptor(
"r1",
"Downstream community",
"community",
"ws1",
"receptors",
capacity_m3s=120.0,
),
),
gauges=(
HydrologyGauge("g1", "Example Creek gauge", "ws1"),
),
)
write_hydrology_domain_manifest(
domain,
Path("metadata/hydrology/domain.json"),
)
audit = audit_hydrology_domain(
Path("metadata/hydrology/domain.json"),
data_root=Path("."),
)
Audit
The local audit checks:
structural validation and cross-references;
layer file existence;
declared size;
optional SHA-256 checksums;
relative path resolution against the declared data root;
missing gauges as a warning, not an error.
The audit does not inspect every geospatial field. Field-level validation belongs to P114.2 when the public data bundle is assembled.
Public-Data Boundary
Use public or reviewed sources only. No private data in tracked files.
Record licence, source URL, and checksum for every layer.
Keep relative layer paths portable.
Do not add private, Indigenous, or licence-restricted data to tracked files.
Do not create a provincial mirror.