HFX Auxiliary Schema: D8 Raster v1

Schema ID: hfx.aux.d8_raster.v1

Normative keywords in this document are to be interpreted as described in RFC 2119.

hfx.aux.d8_raster.v1 declares a paired D8 flow-direction raster and flow-accumulation raster for optional terminal-unit refinement. It replaces HFX v0.1's first-class flow_dir.tif and flow_acc.tif artifacts.

Manifest Declaration

{
  "schema": "hfx.aux.d8_raster.v1",
  "artifacts": {
    "flow_dir": "flow_dir.tif",
    "flow_acc": "flow_acc.tif"
  },
  "metadata": {
    "flow_dir_encoding": "esri"
  }
}

Required Artifact Keys

Key	Description
`flow_dir`	D8 flow-direction Cloud-Optimized GeoTIFF
`flow_acc`	Flow-accumulation Cloud-Optimized GeoTIFF

Both artifacts are required. Paths are relative to the HFX dataset root and MUST NOT escape it.

Required Metadata

Field	Type	Required	Description
`flow_dir_encoding`	string	Yes	One of `"esri"` or `"taudem"`

Additional metadata fields are allowed only after this schema version is extended additively.

`flow_dir` Contract

Property	Value
Format	Cloud-Optimized GeoTIFF (COG)
dtype	`uint8`
NoData	`255`
CRS	EPSG:4326; MUST match all vector data
Tiling	Internal tiles required; 256x256 or 512x512 px
Encoding	Declared by `metadata.flow_dir_encoding`

Encoding Conventions

Direction	ESRI (powers of 2)	TauDEM (1-8, E origin)
East	1	1
Southeast	2	8
South	4	7
Southwest	8	6
West	16	5
Northwest	32	4
North	64	3
Northeast	128	2

Engines normalize to their internal convention at read time based on flow_dir_encoding. Producers do not need to re-encode source rasters.

`flow_acc` Contract

Property	Value
Format	Cloud-Optimized GeoTIFF (COG)
dtype	`float32`
NoData	`-1.0`
CRS	MUST match `flow_dir` exactly
Values	Upstream cell count, not area
Tiling	Same as `flow_dir`

float32 is required. int32 can overflow on large basins. Engines compute area from cell size and CRS when needed.

Validation Expectations

A validator implementing this schema checks:

flow_dir and flow_acc artifact keys are present.
metadata.flow_dir_encoding is "esri" or "taudem".
Both artifact paths resolve inside the dataset root.
Both files are present.
Both rasters are readable COG GeoTIFFs.
flow_dir has dtype uint8, NoData 255, internal tiling, and CRS EPSG:4326.
flow_acc has dtype float32, NoData -1.0, internal tiling, and the same CRS as flow_dir.
Each raster's spatial extent overlaps the manifest bbox (catches mislocated or misprojected rasters -- e.g. a CRS slip that places the raster in the wrong hemisphere).
The per-entry contains-the-manifest-bbox requirement from v0.1-era validators is dropped to permit multi-entry datasets where each entry covers a sub-region of the manifest bbox (e.g. per-basin partitioning of a planetary d8 fabric). Producers SHOULD declare multiple entries whose union covers the manifest bbox; consumers MAY query coverage at read time by inspecting each entry's raster header.

Overlap Coherence

Multi-entry datasets partition one source D8 fabric, but the entries' axis-aligned rectangular extents may overlap (irregular basins do not tile into disjoint rectangles). Where two or more entries' extents overlap, every overlapping entry MUST report identical flow_dir and flow_acc values at each shared cell. The entries MUST be windows cut from a single coherent D8 fabric, not independently mosaicked sources. A producer that cannot guarantee this MUST NOT declare overlapping entries.

Because overlapping entries agree, a consumer selecting a D8 tile for a region fully contained by more than one entry MAY pick any covering entry (e.g. the first in manifest order); the result is independent of the choice. Consumers are not required to mosaic, reconcile, or arbitrate between overlapping entries.

Raster refinement is an engine behavior. This auxiliary schema only declares the data contract.