Hydrology Data Bundle Contract
Purpose
This page is the short source-of-truth contract for FEMIC P114.2 hydrology data bundles. It defines the layout, manifest, licence/checksum rules, gap policy, audit semantics, and DataLad boundary.
A bundle packages reviewed public or approved inputs. It does not download layers or run a hydrology model.
Quick Contract
Schema:
femic.hydrology.bundle.v1.Manifest:
bundle.json.Layer root:
layers/<layer_id>/<filename>.Required roles:
watershed,stream,road,dem.Every layer records licence, format, CRS, source ID, relative path, status, size, and optional SHA-256.
A build requires a local source for every domain layer.
A plan may contain gaps; a build may not.
No private, Indigenous, or licence-restricted data in tracked files.
Large layers belong in DataLad/Arbutus, not git.
Bundle Layout
<bundle>/
bundle.json
layers/<layer_id>/<filename>
The manifest never stores the absolute bundle root, so it remains portable. Relative layer paths are resolved against the bundle directory during audit.
Manifest Schema
Top-level fields:
schema_versionandbundle_id.bundle_versionandgenerated_utc.domain_idanddomain_sha256.aoi_bbox_epsg3005.summarywith layer, materialized, gap, and completeness counts.layers,gaps,caveats, andprovenance.
Each layer record carries:
layer_id,role,source_id, andrelative_path.format,crs, andlicence_id.status:planned,materialized, ormissing.checksum_sha256,size_bytes,source_url, andretrieval_utc.
The bundle ID is deterministic from the domain digest, AOI, bundle version, and layer metadata/checksums. It does not include the absolute output path.
Versioning And Pinning
Pin the bundle ID and bundle version, then verify every layer’s SHA-256 before use. A changed domain, AOI, layer byte, licence, or bundle version produces a different bundle ID.
Audit Rules
audit_hydrology_bundle checks:
manifest schema and required roles;
bundle and domain identifiers;
AOI bounds;
licence presence;
layer existence, size, and SHA-256;
path containment inside the bundle;
gaps and completeness.
A bundle is valid when its manifest and materialized files are internally consistent. It is complete only when every layer is materialized, every checksum matches, and no gaps remain.
Gap Policy
A plan may be valid but incomplete. Gaps explain why a layer is not available. A build refuses to proceed while any gap remains. This prevents a partial data audit from being mistaken for a finished bundle.
DataLad Boundary
Commit bundle.json, the domain manifest, and small metadata. Annex large
layers to the instance’s Arbutus remote. Audit only after the annex pointers
are materialized; a pointer stub is not a layer payload.
Pilot Boundary
A pilot starts as a plan with no sources; the gap list is the public-data audit. Record watershed/stream/road/DEM coverage, gauge period of record, receptor evidence, and licence status before committing a pilot selection.