JSON Reference
Every --format json answer follows one schema,
diagnostics-schema.json.
New fields may appear over time, so ignore any you do not know; schemaVersion changes only when an
existing field changes meaning. Fields marked always are present in every answer.
The answer
| Field | Type | Meaning |
|---|---|---|
schemaVersion always | integer | Version of this schema. Currently 1. A version gains optional fields and new command values as commands land, so a consumer must ignore members it does not recognise; the number changes only when an existing field changes shape or meaning.
|
ok always | boolean | Whether the command did what was asked. Semantics are per-command; see the per-command table in agent-protocol.md. |
command always | string | The command that produced this envelope: ‘check’, ‘build’, ‘run’, ‘test’, ‘explain’, ‘fix’, ‘determinism’, ‘view’, ‘patch’, or ‘skill’. |
diagnostics always | array of JsonDiagnostic | Array of diagnostic messages (errors, warnings, notes). |
artifact | string or null | Path to the build artifact (for build/run commands only). Absent or null if no artifact was produced. |
exitCode | integer or null | Process exit code. Semantics vary by command: for run, this is the program’s exit status; for other commands, 0 means ok, non-zero means failed. See the per-command table in agent-protocol.md. |
signal | integer or null | Signal number if the process was killed by a signal (for run/test commands on Unix only). Absent or null if the process exited normally or on non-Unix platforms. |
stdoutTail | string or null | Last N bytes of the program’s stdout (for run/test commands only). Absent or null if not captured. |
stderrTail | string or null | Last N bytes of the program’s stderr (for run/test commands only). Absent or null if not captured. |
stdoutTruncated | boolean or null | True if stdoutTail was truncated; false if complete. Absent or null if stdout was not captured. |
stderrTruncated | boolean or null | True if stderrTail was truncated; false if complete. Absent or null if stderr was not captured. |
durationMs | integer or null | Elapsed time in milliseconds for the command execution. Absent or null if not measured. |
tests | JsonTestSummary | Test summary (for test command only). Absent or null for other commands. |
explanation | JsonExplanation | Documentation for one diagnostic code (for explain command only). Absent or null for other commands. |
view | JsonView | The canonical source a scoped read returned (view command only). Absent or null for other commands. |
patch | JsonPatch | Patch results: applied edits and revalidation count (patch command only). Absent or null for other commands. |
skills | array or null | Skills from the embedded catalogue (skill command only). Absent or null for other commands. |
codes | array or null | Diagnostic code registry (explain list command only). Absent or null for other commands. |
gpu | JsonGpuTelemetry | What the run’s GPU work cost (run command only). Absent for a program that never reached the GPU runtime, which is what distinguishes no GPU work from GPU work that cost nothing. |
A diagnostic
| Field | Type | Meaning |
|---|---|---|
severity always | string | Severity level of the diagnostic. |
code | string or null | Stable diagnostic code (e.g., ‘MER_TYP_010’) for documentation and tooling. Absent or null for some synthetic diagnostics. |
message always | string | Human-readable diagnostic message. |
path | string or null | Source file path where the issue occurred. Absent or null for diagnostics without a source location. |
line | integer or null | 1-indexed line number in source where the issue occurred. Absent or null if no source location. |
column | integer or null | 1-indexed column number in source where the issue occurred. Absent or null if no source location. |
length | integer or null | Length in bytes of the error span. Absent or null if no source location. |
expected | string or null | Expected type/value for type mismatch errors. Populated for explicitly-typed error variants (TypeMismatch, ArityMismatch, etc) and selectively for family-coded errors (e.g., MER_TYP_002). Absence does not imply types are unknown; some families do not yet carry structured type information. |
actual | string or null | Actual type/value for type mismatch errors. Populated for explicitly-typed error variants (TypeMismatch, ArityMismatch, etc) and selectively for family-coded errors (e.g., MER_TYP_002). Absence does not imply types are unknown; some families do not yet carry structured type information. |
help | string or null | Actionable help text explaining how to resolve the issue. Absent or null if no help is available. |
fixSafety | string or null | Fix-safety level of this diagnostic’s repair, if the diagnostic carries a repair. One of: ‘format-only’, ‘behavior-preserving’, ‘local-edit’, ‘api-changing’, ‘target-changing’, or ‘requires-human-review’. It classifies the risk of the edit, not whether one exists — the presence of the ‘repair’ member is what says that. Absent or null if the diagnostic carries no repair. |
repair | JsonRepair | Always absent in schema version 1; reserved for the repair-plan surface in future versions. |
related always | array of JsonRelated | Related diagnostics (notes, additional context). Empty if no related diagnostics. |
preexisting | boolean or null | True if this diagnostic existed in the pre-edited version (patch command only). False if the edit introduced it. Absent or null for commands other than patch, for a patch command’s own refusal notice (e.g., MER_BLD_011), or for a warning, which is never partitioned against the pre-edited version. |
A repair
| Field | Type | Meaning |
|---|---|---|
id always | string | Stable identifier for the repair shape, such as ‘let-to-var’ or ‘add-import’. miri explain --list --format json names the repairs each code can offer.
|
summary always | string | Human-readable summary of the repair. |
edits always | array of JsonEdit | The edits that carry out this repair, in source order. Never empty: a repair exists only when the compiler determined the edit. |
An edit
| Field | Type | Meaning |
|---|---|---|
path always | string | File path (absolute or relative) to edit. |
start always | integer | Start byte offset (inclusive). |
end always | integer | End byte offset (exclusive). |
replacement always | string | Text replacing the range. Empty to delete the range; the range may be empty to insert. |
A test run
| Field | Type | Meaning |
|---|---|---|
total always | integer | Total number of tests run (including passed, failed, ignored, etc). |
passed always | integer | Number of tests that passed. |
failed always | integer | Number of tests that failed. |
ignored always | integer | Number of tests that were ignored. |
results always | array of JsonTestResult | Individual test results. |
rejectedFiles always | array of JsonRejectedFile | Files that were rejected from the test run (e.g., unparseable or declaring main). |
filesRead always | integer | Number of .mi files discovery opened and read, whether or not they declared a test. With total 0 it separates ‘read files, none declared a test’ from ‘read no files at all’. |
One test
| Field | Type | Meaning |
|---|---|---|
path always | string | Path to the test file. |
name always | string | Name of the test. |
outcome always | string | Outcome of the test. |
detail | string or null | Additional detail about the test result (e.g., error message or timing). Absent or null if no detail. |
code | string or null | Diagnostic code for assertion failures (e.g., “MER_RT_005”). Absent or null if no failure. |
line | integer or null | 1-indexed line number where the assertion failed. Absent or null if not applicable. |
column | integer or null | 1-indexed column number where the assertion failed. Absent or null if not applicable. |
expected | string or null | For assert_eq, the expected value; for assert_panics, the expected message. Absent or null if not applicable. |
actual | string or null | For assert_eq, the actual value; for assert_panics, the caught message. Absent or null if not applicable. |
expression | string or null | The expression text for bare assert, or null/absent for other assertions. |
message | string or null | Optional user-provided message for the assertion. |