Valence treats `registry_data/manifest.toml` as the source of truth for domains, meshes, metadata, and registry identity. Derived files exist for distribution and visualization, but they are not authoritative.
Core records
- `Domain`: a named registry entity with display metadata and child meshes.
- `Mesh`: a versioned mesh record with format, source metadata, size, and gates.
- `content_uid`: optional deterministic identity over canonicalized mesh bytes.
- `normalized_uid`: identity over normalized geometry where available.
Example entries
One real [[domains]] header and one real [[domains.meshes]] block, quoted verbatim from registry_data/manifest.toml (a permissively-licensed entry — MIT):
[[domains]]
name = "WNAT"
full_name = "Western North Atlantic"
description = "Western North Atlantic Ocean basin for hurricane and storm-surge modeling"
category = "real-world"
continent = "Atlantic Ocean"
applications = ["Hurricane/Storm Surge", "Coastal Circulation"]
display_mesh = "hagen@v1"[[domains.meshes]]
uploaded_date = "2026-04-26"
modified_date = "2026-04-24"
contributor = "Dominik O Mattioli"
id = "hagen@v1"
filename = "WNAT_Hagen.14"
element_count = 98365
license = "MIT"
bounding_box = { min_lon = -97.856889, min_lat = 7.912906, max_lon = -60.040000, max_lat = 45.838806 }
description = "Western North Atlantic mesh (Hagen variant)"
size_mb = 5.48
element_type = "triangle"
aliases = ["WNAT_53K_Nodes"]
provenance = "upstream"
lineage = "Original ADCIRC public-domain mesh (NSF-funded). Complete boundary topology preserved: 113 declared BC segments including all island rings (e.g., Bermuda at segment [99])."lineage above is a free-text key some manifest entries carry; it is not a field on the Mesh dataclass (see the field table below) — `Domain.from_dict` / `Mesh.from_dict` only keep keys the dataclass declares, so unmodeled keys stay in the TOML file but are not loaded onto the object.
Domain fields
| Field | Type | Required | Meaning |
|---|---|---|---|
| `name` | string | yes | Unique domain name; must not contain `/` (breaks the composite mesh-id grammar). |
| `full_name` | string | no | Human-readable display name. |
| `description` | string | no | Free-text description. |
| `category` | string | no (default "real-world") | "real-world" or "synthetic". |
| `continent` | string | no | Coarse geographic browse label. |
| `applications` | list[string] | no (default `[]`) | Application tags. |
| `bounding_box` | table | no | {min_lon, min_lat, max_lon, max_lat}. |
| `meshes` | list[Mesh] | no (default `[]`) | Child mesh records, one `[[domains.meshes]]` block each. A Domain can exist with zero meshes (boundary only). |
| `content_uid` | string | no | `boundary-v1:` + sha256 over the domain's convex-hull boundary (computed, not hand-set). |
| `display_mesh` | string | no | Mesh id that represents this domain on the globe — a visualization choice only, never an approval or authority claim. |
Mesh fields
| Field | Type | Required | Meaning |
|---|---|---|---|
| `id` | string | yes | Composite mesh id within the domain, e.g. `hagen@v1`. |
| `filename` | string | yes | Bare filename (no path, no directory) matching the file on disk / the HF mirror. |
| `description` | string | no | Free-text description. |
| `size_mb` | float | no (default `0.0`) | File size in MB. |
| `node_count` | int | no | Node count from the file header. |
| `element_count` | int | no | Element count from the file header. |
| `element_type` | string | no | "triangle", "quadrilateral", or "Mixed-Element". |
| `format` | string | no (default "ADCIRC") | File format: "ADCIRC", "SMS_2DM", or "ADCIRC_GRD". |
| `contributor` | string | no | Contributor name. |
| `uploaded_date` | string | no | ISO 8601 date added to the registry. |
| `modified_date` | string | no | ISO 8601 date the file was last changed. |
| `refinement_level` | string | no | Coarse / medium / fine / very_fine label. |
| `features` | list[string] | no (default `[]`) | Feature tags, e.g. ["barrier_islands"]. |
| `aliases` | list[string] | no (default `[]`) | Alternate names for search. |
| `bounding_box` | table | no | {min_lon, min_lat, max_lon, max_lat}. |
| `license` | string | no (default "unknown") | One of the registry's valid license identifiers; gates HF-mirror redistribution. |
| `test_case` | bool | no (default `false`) | Surfaces the mesh on the Test Suites tab. |
| `kind` | string | no (default "mesh") | "mesh" or "boundary" (a boundary-only file with no element connectivity). |
| `content_uid` | string | no | `sha256-v1:` + sha256 over canonicalized `.14` bytes. |
| `provenance` | string | no | e.g. "upstream", "derivative-admesh", "synthetic". Not schema-required, but `validate` warns when a real-world mesh omits it, until provenance enforcement is fully tightened. |
| `version`, `authors`, `org`, `doi`, `datum`, `shoreline_source`, `generator`, `generator_version`, `parent_content_uid`, `application_class`, `resolution_envelope`, `known_limitations` | mixed | no | Mesh-card fields (design-doc §7.2): declared provenance/authorship/generation metadata. `application_class` is one of "surge", "tide", "compound-flood"; `resolution_envelope` is {min_m, max_m}. |
| `normalized_uid` | string | no | `normalized-v1:` identity over the normalized geometry (reserved identity slot). |
| `gate_reports` | list[string] | no (default `[]`) | `gate-report-v1:` digests of prior gate runs for this mesh. |
| `validation_summary` | table | no | Denormalized pointer + cached status to the authoritative gate report at `report_digest`. |
Schema version
SCHEMA_VERSION = "0.4" (`packages/valence_domains/schema.py`). The schema is still 0.x: there are no backward-compatibility shims, and an additive field does not bump the version — only a breaking change (field rename, removal, or type change) does.
The Parquet sidecar is derived at publish time from the TOML manifest and is never hand-edited — editing it directly would silently drift from the manifest, the single source of truth.
See Trust, Provenance & Authority Boundaries for why derived assets are never authoritative.