Verdict Schema | NVIDIA Health Validation

Type definitions behind the verdict JSON. Enums serialize as strings, and struct fields are listed with their JSON key names. The machine-readable contract is node-verdict.schema.json.

Structs

AffectedComponent

AffectedComponent summarizes a category with non-Pass results.

Field	JSON name	Type
`CheckIDs`	`check_ids`	`[]string`
`Entities`	`entities`	`[]string`
`Category`	`category`	`Category`
`MaxSeverity`	`max_severity`	`Severity`

CheckDefinition

CheckDefinition is the canonical shape of a health check in the catalog. Each definition encodes NVIDIA’s operational judgment about a specific hardware or driver condition: which signals to examine, what thresholds apply, what action to recommend, and how far the condition reaches. Check definitions are data. They carry no sensor or hardware dependencies. Evaluation happens when a caller provides signal values to [Catalog.Evaluate].

Field	JSON name	Type	Description
`Thresholds`	`thresholds`	`map[string]ThresholdSpec`
`FeasibilityClass`	`feasibility_class`	`string`
`Description`	`description`	`string`
`Name`	`name`	`string`
`ID`	`id`	`string`
`Dependencies`	`dependencies`	`[]string`	Dependencies names check IDs whose Critical verdict explains this check’s inability to collect. Checks never read each other’s results, so a dependency has no effect on whether this check runs, what it reports, or its severity. Its only effect is that a verdict for an entity this check could not read at all gains a message naming the dependency as the cause. An ID that is not registered is an inactive edge by design, so a consumer may register any subset of the catalog. Validate rejects only a check that names itself.
`Architectures`	`architectures`	`[]string`
`Rules`	`rules`	`[]Rule`
`ExecutionContexts`	`execution_contexts`	`[]ExecutionContext`
`Prerequisites`	`prerequisites`	`[]Prerequisite`
`RequiredSignals`	`required_signals`	`[]string`
`RecommendedAction`	`recommended_action`	`RecommendedAction`
`Timeout`	`timeout`	`time.Duration`
`MaturityLevel`	`maturity_level`	`MaturityLevel`
`SchedulingCadence`	`scheduling_cadence`	`SchedulingCadence`
`Category`	`category`	`Category`
`ConditionScope`	`condition_scope`	`ConditionScope`
`Provenance`	`provenance`	`Provenance`
`ExecutionClass`	`execution_class`	`ExecutionClass`

CheckVerdict

CheckVerdict is the outcome of evaluating a single check against signal values. It carries all context needed for downstream systems to make remediation decisions without referencing catalog source. Every Rule whose expression matched contributes one entry to Messages. Severity is the most severe across the matching rules; RecommendedAction comes from the highest-priority matching rule’s override (or the check default when no override applies).

Field	JSON name	Type	Description
`Timestamp`	`timestamp`	`time.Time`
`ObservedValues`	`observed_values`	`map[string]any`
`Thresholds`	`thresholds`	`map[string]ResolvedThreshold`
`CheckID`	`check_id`	`string`
`SpanID`	`span_id`	`string`	Unique per check invocation.
`TraceID`	`trace_id`	`string`	Shared by all checks in the same run.
`SkipDetail`	`skip_detail`	`string`
`Messages`	`messages`	`[]string`
`AffectedEntities`	`affected_entities`	`[]string`
`RecommendedAction`	`recommended_action`	`RecommendedAction`
`Severity`	`severity`	`Severity`
`Category`	`category`	`Category`
`ConditionScope`	`condition_scope`	`ConditionScope`	Blast radius; NODE when collection failed.
`SkipReason`	`skip_reason`	`SkipReason`
`MaturityLevel`	`maturity_level`	`MaturityLevel`
`Skipped`	`skipped`	`bool`
`NVIDIAEndorsed`	`nvidia_endorsed`	`bool`

ErroredMeasurement

ErroredMeasurement records one per-signal collection failure on a measurement. Sensors append entries via the typed measurement’s AddError method (e.g. [GPUMeasurement.AddError]) as they encounter failures while measuring different fields, so a single measurement may carry several entries — one per failing call. The catalog fails a check Critical when any entry’s FailedSignals overlaps with the check’s RequiredSignals; the verdict’s message joins the matching entries’ Err.Error() strings. Checks whose required signals were all collected still run normally on the partial data. The zero value is not valid; construct entries with [NewErroredMeasurement] (or via the typed measurement’s AddError), which guarantees Err is non-nil so consumers always have a surfaceable failure cause.

FixedThresholdError

FixedThresholdError is returned when an operator attempts to override a threshold classified as Fixed.

Field	JSON name	Type	Description
`ThresholdName`		`string`
`CheckID`		`string`

NodeVerdict

NodeVerdict aggregates per-check verdicts into a node-level health assessment.

Field	JSON name	Type	Description
`SchemaVersion`	`schema_version`	`string`
`CatalogVersion`	`catalog_version`	`string`	Catalog module version compiled into the producer.
`Timestamp`	`timestamp`	`time.Time`
`NodeID`	`node_id`	`string`	Opaque identifier for the node under test.
`TraceID`	`trace_id`	`string`	Shared by all checks in this run; echoed on each CheckVerdict.
`SeverityByDomain`	`severity_by_domain`	`map[Category]Severity`
`AffectedComponents`	`affected_components`	`[]AffectedComponent`
`CheckResults`	`check_results`	`[]CheckVerdict`
`SkippedChecks`	`skipped_checks`	`[]CheckVerdict`
`OverallSeverity`	`overall_severity`	`Severity`

Prerequisite

Prerequisite declares a minimum software requirement for a check.

Field	JSON name	Type	Description
`Name`	`name`	`string`
`MinVersion`	`min_version`	`string`

RecommendedAction

RecommendedAction is the structured remediation a check carries. OperationalState is the high-level state change to apply; RemediationActions is the ordered sequence of remediation steps a cluster operator’s remediation engine should work through, and is only meaningful (and only emitted in JSON) when OperationalState is [OperationalDrain]. Use [Drain] / [Monitor] / [NoAction] for readable call sites instead of constructing the struct directly.

Field	JSON name	Type	Description
`RemediationActions`	`remediation_actions`	`[]RemediationAction`
`OperationalState`	`operational_state`	`OperationalState`

ResolvedThreshold

ResolvedThreshold is a threshold value after operator overrides have been applied. It tracks provenance so downstream systems can audit whether NVIDIA defaults or operator-supplied values were used.

Field	JSON name	Type
`Value`	`value`	`any`
`OriginalValue`	`original_value`	`any`
`Category`	`category`	`ThresholdCategory`
`Overridden`	`overridden`	`bool`

Rule

Rule defines a single evaluation condition within a check. Every rule is evaluated and the matches are aggregated: the verdict’s severity is the worst across matching rules, Messages holds one entry per matching rule in declaration order, and RecommendedAction comes from the highest-severity matching rule (ties go to declaration order); its override applies when present, otherwise the check-level action is used.

Field	JSON name	Type	Description
`Expression`	`expression`	`string`	Expression is a CEL expression that evaluates to a boolean. Variables available are the union of signal field names and threshold names from the parent CheckDefinition.
`Message`	`message`	`string`	Message describes the detected condition. May contain ${variable} placeholders interpolated from signal and threshold values.
`RecommendedAction`	`recommended_action`	`RecommendedAction`	RecommendedAction, when non-zero (see [RecommendedAction.IsZero]), overrides the parent [CheckDefinition.RecommendedAction] in the resulting [CheckVerdict]. Use it when a specific failure mode warrants a different remediation sequence than the check’s default. A zero value leaves the check-level action in place.
`Severity`	`severity`	`Severity`	Severity produced when this rule matches.

ThresholdSpec

ThresholdSpec defines a threshold in a check definition. It carries the catalog-authored value and its governance classification.

Field	JSON name	Type	Description
`Value`	`value`	`any`
`PerArchitecture`	`per_architecture`	`map[string]any`	PerArchitecture overrides Value for a specific detected architecture (keyed by the catalog architecture identifier, e.g. “H100”). It lets one check carry per-architecture defaults — e.g. NVLink speed differs by GPU generation. Architectures absent from the map fall back to Value. When the check declares Architectures, registration requires this map to include every listed architecture; Value may then be omitted.
`Description`	`description`	`string`
`Unit`	`unit`	`string`
`Category`	`category`	`ThresholdCategory`
`RequiredOverride`	`required_override`	`bool`	RequiredOverride marks a threshold with no meaningful catalog value that the operator must supply per fleet. It is independent of Category, which governs whether an override is permitted at all; pairing it with [FixedThreshold] is rejected at registration. A check whose RequiredOverride threshold is unset is skipped with [ThresholdUnconfigured] rather than evaluated.

Enums

Name	JSON value	Description
`GPU`	`gpu`	GPU covers GPU device health: driver-reported events (XID), thermal state, driver status, power, and clock behavior.
`NVLink`	`nvlink`	NVLink covers NVLink interconnect health: replay counters, link errors, and fabric state.
`PCIe`	`pcie`	PCIe covers PCI Express bus health: link width, speed degradation, and error counters.
`InfiniBand`	`infiniband`	InfiniBand covers InfiniBand network health: port state, error rates, and link integrity.
`Storage`	`storage`	Storage covers storage health in NVIDIA-validated configurations: NVMe state, SMART counters.
`Node`	`node`	Node covers host-wide GPU-system signals that are not bound to any single device — GPU count, driver version, and similar inventory checks.
`Xid`	`xid`	Xid covers NVRM Xid fault events logged by the NVIDIA driver to the kernel ring buffer. Xid measurements are collected separately from GPU telemetry and route only to Xid checks.
`CPU`	`cpu`	CPU covers host processor inventory and availability signals.

ConditionScope

ConditionScope records how far the condition a check detects reaches: the smallest boundary that must be inspected to explain it. It is independent of [RecommendedAction], which stays node-local: a ClusterScope verdict reports what the fault implicates, not that the cluster should be acted on. NodeScope is the zero value, so a check that omits it is treated as node-local, which is how consumers already treat every check. The NODE value is distinct from the [Node] Category: one is a blast radius, the other a hardware domain. They serialize with different casing.

Name	JSON value	Description
`NodeScope`	`NODE`	This node’s own hardware explains the condition.
`DomainScope`	`DOMAIN`	Explaining it requires the NVLink domain shared with peer nodes.
`ClusterScope`	`CLUSTER`	Explaining it requires the cluster network fabric beyond the node.

ExecutionClass

ExecutionClass distinguishes passive observation from active probing.

Name	JSON value	Description
`Passive`	`PASSIVE`	Reads existing state without perturbing the system.
`Active`	`ACTIVE`	May exercise hardware or run diagnostic commands.

ExecutionContext

ExecutionContext identifies where a health check can run within a GPU cluster.

Name	JSON value	Description
`OperatorInfra`	`OPERATOR_INFRA`	Host OS or CSP privileged control-plane VM.
`TenantGuest`	`TENANT_GUEST`	Tenant VM, container, or K8s worker node.
`OutOfBand`	`OUT_OF_BAND`	BMC via Redfish API.

MaturityLevel

MaturityLevel describes how production-ready a check is.

Name	JSON value	Description
`Stable`	`stable`	Vetted for production use.
`Experimental`	`experimental`	Under evaluation; may change or be withdrawn.

OperationalState

OperationalState names the node-level state change a verdict recommends. It is the high-level “what should happen to the node?” answer; the [RemediationAction] companion sequence narrows the why when the state is [OperationalDrain].

Name	JSON value	Description
`OperationalReady`	`ready`	OperationalReady is the zero value: the node stays ready for work and no node-level action is recommended.
`OperationalMonitor`	`monitor`	OperationalMonitor keeps the node in service but flags the finding for trending; no action required right now.
`OperationalDrain`	`drain`	OperationalDrain removes the node from scheduling so the finding can be remediated. The accompanying [RemediationAction] sequence names the specific remediation steps.

Provenance

Provenance identifies who authored a check definition and determines the trust level of its verdicts.

Name	JSON value	Description
`NVIDIA`	`nvidia`	Authored and maintained by NVIDIA.
`Community`	`community`	Community-contributed, NVIDIA-reviewed.
`Private`	`private`	Privately authored for a specific deployment.

SchedulingCadence

SchedulingCadence describes how often a check is meant to run in a node’s operational lifecycle. The cadences nest by frequency — Continuous > Prolog > MaintenanceWindow — so a check declared at a more frequent cadence is also eligible to run in every less frequent window: a Continuous check runs at prolog and in maintenance windows, a Prolog check runs in maintenance windows. See [SchedulingCadence.Covers]. Continuous is the zero value: a check that omits SchedulingCadence defaults to the most frequent cadence, so it runs in every window rather than being silently excluded from more frequent ones.

Name	JSON value	Description
`Continuous`	`CONTINUOUS`	During normal operation (most frequent); the zero-value default.
`Prolog`	`PROLOG`	Before job dispatch.
`MaintenanceWindow`	`MAINTENANCE`	During scheduled maintenance (least frequent).

Severity

Severity represents the graduated health severity of a check result. The levels form a total order: Pass < Info < Warning < Critical. Unknown is a special case indicating the check could not complete.

Name	JSON value	Description
`Pass`	`PASS`	Pass indicates no condition detected. The monitored state is within normal operating bounds.
`Info`	`INFO`	Info indicates an anomaly detected within safe operating bounds. The node may remain in service; monitor for trend.
`Warning`	`WARNING`	Warning indicates a condition that degrades performance or increases failure risk. The node may continue in service for a bounded window pending operator action.
`Critical`	`CRITICAL`	Critical indicates imminent risk of failure, data corruption, or unrecoverable state. The node should be removed from service without delay.
`Unknown`	`UNKNOWN`	Unknown indicates the check could not complete. Service eligibility for the affected component cannot be assessed. This typically results from tool failures or insufficient data.

SkipReason

SkipReason provides a machine-readable code for why a check did not run.

Name	JSON value	Description
`NotSkipped`	`NOT_SKIPPED`	Check ran normally.
`ArchitectureUnsupported`	`SIGNAL_UNAVAILABLE_ARCHITECTURE`	Wrong GPU architecture.
`DeploymentUnsupported`	`SIGNAL_UNAVAILABLE_DEPLOYMENT_MODEL`	Requires different execution context.
`CheckDisabled`	`CHECK_DISABLED`	Operator disabled this check.
`InsufficientHistory`	`INSUFFICIENT_HISTORY`	Time-window data not yet available.
`ThresholdUnconfigured`	`THRESHOLD_UNCONFIGURED`	Required threshold not supplied for this fleet.
`NoApplicableMeasurement`	`NO_APPLICABLE_MEASUREMENT`	No supplied measurement carries the check’s required signals.
`SensorMissing`	`SENSOR_MISSING`	SensorMissing marks a check whose whole category was expected but never arrived: the sensor is absent, unconfigured, or its backend was never constructed. It is distinct from NoApplicableMeasurement, which means the category was collected but no measurement carried this check’s required signals, and from a Critical errored verdict, which means the sensor ran and failed.
`CadenceMismatch`	`CADENCE_MISMATCH`	Check is not scheduled for the requested cadence.

ThresholdCategory

ThresholdCategory classifies how a threshold value may be modified by operators. The catalog enforces governance rules: Fixed thresholds reject override attempts with an error; Default and Adjustable thresholds accept operator-supplied values.

Name	JSON value	Description
`DefaultThreshold`	`DEFAULT`	DefaultThreshold is NVIDIA’s recommended starting value. Operators may override it via a parameter file.
`FixedThreshold`	`FIXED`	FixedThreshold is a hard boundary that cannot be overridden. Attempts to override produce an error and the check will not run with an invalid override applied.
`AdjustableThreshold`	`ADJUSTABLE`	AdjustableThreshold may be tuned by operators within documented bounds.