HFX auxiliary schema: D8 raster v2

Schema ID: hfx.aux.d8_raster.v2

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

hfx.aux.d8_raster.v2 declares a paired D8 flow-direction raster and flow-accumulation raster for optional terminal-unit refinement. It supersedes hfx.aux.d8_raster.v1. The v2 metadata declares the raster CRS, flow-direction encoding, and flow-accumulation units. Raster dtype and nodata remain authoritative in each GeoTIFF header.

Manifest declaration

{
  "schema": "hfx.aux.d8_raster.v2",
  "artifacts": {
    "flow_dir": "flow_dir.tif",
    "flow_acc": "flow_acc.tif"
  },
  "metadata": {
    "crs": "EPSG:8857",
    "flow_dir_encoding": "grass",
    "flow_acc_units": "km2"
  }
}

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
`crs`	string	Yes	Raster CRS as an uppercase EPSG authority string matching `^EPSG:[1-9][0-9]*$`, such as `EPSG:8857`
`flow_dir_encoding`	string	Yes	One of `esri`, `taudem`, or `grass`
`flow_acc_units`	string	Yes	One of `cells` or `km2`

All three metadata fields are required. The schema defines no default values. Additional metadata properties are forbidden by the companion JSON Schema. A future additive revision of this schema version may publish additional properties.

Raster header contract

The GeoTIFF headers are authoritative for dtype and nodata. Metadata MUST NOT duplicate dtype or nodata. Each raster MUST contain a nodata tag. The schema does not constrain the nodata value.

Both artifacts MUST be readable Cloud-Optimized GeoTIFFs with internal tiling. Both raster header CRSs MUST resolve to metadata.crs. The flow_dir and flow_acc rasters MUST have the same CRS, dimensions, affine transform, pixel dimensions, and grid alignment.

Artifact	Allowed header dtype
`flow_dir`	`uint8` or `int8`
`flow_acc`	`float32` or `int32`

Flow-direction encoding

The value of metadata.flow_dir_encoding selects one column from this table.

Direction	ESRI, powers of 2	TauDEM, 1 through 8 from east	GRASS `r.watershed`, 1 through 8 counterclockwise from northeast
East	1	1	8
Southeast	2	8	7
South	4	7	6
Southwest	8	6	5
West	16	5	4
Northwest	32	4	3
North	64	3	2
Northeast	128	2	1

For grass with a uint8 header dtype, valid data values MUST be codes 0 through 8. Code 0 MUST denote a terminal cell with no downstream neighbor. Nodata MUST be declared in the GeoTIFF header.

For grass, positive values 1 through 8 encode the directions shown above. A negative value encodes the direction of its absolute value and indicates that flow exits raster coverage. A negative GRASS value is terminal for upstream tracing. The GRASS value 0 indicates a sink or depression and is terminal for upstream tracing.

Engines normalize the declared encoding on read. A D8 flow-direction raster MUST remain on the grid where its neighbor pointers were derived. Producers and consumers MUST NOT warp a flow-direction raster to another CRS.

Flow-accumulation units

metadata.flow_acc_units defines the physical meaning of flow_acc values.

`flow_acc_units`	Meaning	Allowed `flow_acc` dtype
`cells`	Upstream cell count	`float32`
`km2`	Upstream drainage area in square kilometers	`int32` or `float32`

An entry declaring cells MUST use float32 flow accumulation. An entry declaring km2 MAY use int32 or float32 flow accumulation.

Per-entry CRS and overlap coherence

Each D8 auxiliary entry declares the CRS of its own raster pair. Entries MAY declare different EPSG CRSs.

Two entries whose geographic footprints overlap MUST be windows of the same grid. Same-grid windows have the same CRS, pixel dimensions, pixel basis, and grid alignment. Every shared cell MUST contain identical flow_dir and flow_acc values in every overlapping entry. Entries on different grids MUST have disjoint geographic footprints.

Because overlapping entries agree, a consumer selecting an entry for a region fully contained by more than one entry MAY use any covering entry. Consumers are not required to mosaic, reconcile, or arbitrate between coherent overlapping entries.

Validation expectations

A validator implementing this schema checks:

The flow_dir and flow_acc artifact keys are present.
metadata.crs, metadata.flow_dir_encoding, and metadata.flow_acc_units are present.
metadata.crs is an EPSG authority string matching ^EPSG:[1-9][0-9]*$.
metadata.flow_dir_encoding is esri, taudem, or grass.
metadata.flow_acc_units is cells or km2.
The metadata object has no additional properties.
Both artifact paths resolve inside the dataset root.
Both files are present and readable as internally tiled Cloud-Optimized GeoTIFFs.
Both raster header CRSs resolve to the EPSG code declared by metadata.crs and match each other.
The raster dimensions, affine transform, pixel dimensions, and grid alignment match within the pair.
flow_dir has header dtype uint8 or int8 and carries a nodata tag.
flow_acc has header dtype float32 or int32 and carries a nodata tag.
A cells entry uses float32 flow accumulation.
A km2 entry uses int32 or float32 flow accumulation.
Each raster extent is transformed from the declared raster CRS to EPSG:4326 with densified edge sampling and intersects the manifest bbox.
Overlapping entries are same-grid windows with identical values at shared cells.
Entries on different grids have disjoint footprints.

The transformed-extent intersection is a gross-mislocation smoke check. Edge-sampling density is an implementation choice. The check does not establish precision coverage of the manifest bbox. The union of multiple entries SHOULD cover the manifest bbox. Consumers MAY query coverage at read time from raster headers.

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