# DCGM diagnostic JSON: Pass, Fail, Skip and schema versions

Parse DCGM diagnostic JSON with pinned versions, retained raw output and separate pass, fail, skip and unknown states. Test the consumer with non-disruptive fixtures.

Author: Retrivium team
Updated: 2026-11-01
Canonical URL: https://retrivium.ai/journal/dcgm-diagnostic-json-status/
Language: en

## Structured output still needs a contract

JSON is a transport format, not a promise that every future diagnostic release will emit the same document. Automation around DCGM should record the producer release, selected command and output mode before interpreting the result. A parser that silently accepts an empty document as success is a hardware-reporting defect even if it never crashes.

The [dcgmi diagnostic reference](https://docs.nvidia.com/datacenter/dcgm/latest/reference/command-line-reference/dcgmi/dcgmi-diag.html) documents the supported invocation and output for the current release. Treat those details as release-specific. Pin the diagnostic environment used by an acceptance pipeline and test its parser against retained output from that exact producer.

## Preserve the process envelope

Store the process exit status, standard output, standard error, start time, duration and selected device identities separately. A command that cannot initialize a dependency did not produce the same evidence as a completed hardware test. Likewise, receiving parseable JSON does not establish that all requested tests ran.

The [DCGM diagnostics guide](https://docs.nvidia.com/datacenter/dcgm/latest/learn/modules/dcgm-diagnostics.html) explains how diagnostic execution fits the operational workflow and points out the output's compatibility limits. If a long-lived integration requires a durable programmatic boundary, evaluate the documented APIs rather than assuming CLI JSON is an indefinitely stable schema.

## Separate result categories

For each selected entity and test, retain the raw status plus a normalized internal category. Successful execution, reported failure, skipped work, interrupted execution and unknown or unparsable output need distinct categories. The exact spelling and nesting must come from the pinned release, not from a plausible example invented by the parser author.

A skipped test is not a pass. It may reflect applicability, prerequisites or a decision made by the selected suite. Preserve the accompanying reason when present. Missing a required test should block a claim that the planned check completed, even if the tests that did run produced favorable results.

## Test parser behavior with small fixtures

Prepare saved examples for an expected pass, a reported failure, a skip, a missing required field, an unfamiliar additional field and truncated output. Add a process-level failure whose output is not a complete result. These fixtures test the consumer without running an invasive diagnostic for every software change.

For example, an added optional metadata field should not automatically invalidate an otherwise understood result, while an absent entity identifier must not attach a result to the first GPU in the inventory. Document which fields are required and how an unknown status is routed for review rather than coerced to success.

## Publish a bounded acceptance record

The resulting artifact should identify the requested checks, completed checks, skips, failures, parser version and original producer output. Keep raw evidence alongside the normalized summary so a future parser can reinterpret it. A successful parser run proves that the record was understood; a successful diagnostic proves only the selected tests under their execution conditions.

Before changing the pinned DCGM release, run retained fixtures and new-version results through the reviewed consumer. Update the environment only after checking that boundary, and annotate the compatibility change in the node-acceptance history.

## Related reading

- [Reproducible inference stacks: preserving a GPU pilot’s result](/journal/software-stack-reproducibility/)
- [GPU-node acceptance: evidence beyond an attractive benchmark](/journal/gpu-acceptance-evidence/)