# JSON Schema

See also [CLI Contract](cli-contract.md) for which output formats are considered
stable.

The stable JSON interfaces currently emit schema version `1.0.0`.

Authoritative schema files:

- `schema/pi-doctor-report.v1.schema.json` for `pi-doctor check --json`
- `schema/doctor-response.v1.schema.json` for `pi-doctor --json doctor camera`
  and `pi-doctor --json doctor gpio`
- `schema/support-bundle.v1.schema.json` for `pi-doctor --json support-bundle`

The stable finding registry is `schema/finding-registry.v1.json`.

`check --json` top-level fields:

- `metadata`: command metadata such as the command name.
- `schema_version`: stable schema identifier for automation clients.
- `overall_status`: one of `healthy`, `warning`, `degraded`, or `critical`.
- `probe_health`: per-probe collection outcome records.
- `system`: board, distro, kernel, and Raspberry Pi identity summary.
- `config`: parsed `config.txt` source path, diagnostics count, and entry list.
- `camera`: modern camera-tool presence plus parsed camera inventory.
- `python`: Python executable, venv state, external-management flag, and detected distro packages.
- `groups`: findings grouped by domain in deterministic order.
- `findings`: flattened findings list in deterministic order.

Each `probe_health` entry contains:

- `name`: probe name, such as `board`, `camera`, or `python`.
- `outcome`: one of `success`, `unavailable`, `permission_denied`, `command_failed`, `parse_failed`, or `timed_out`.
- `detail`: nullable diagnostic text for incomplete probes.

`metadata` includes:

- `pi_doctor_version`: package version that emitted the report.
- `build_revision`: build-time revision identifier when available.
- `target_architecture`: architecture of the running binary.
- `supported_os`: support-matrix detection result for the inspected host.
- `probe_availability`: counts of probe outcomes in `probe_health`.

Each finding contains an `impact` field. `impact` drives `overall_status` and is
independent of the finding ID or title.

Focused doctor JSON contains:

- `metadata`
- `schema_version`
- `target`: `camera` or `gpio`
- `summary`: target-specific diagnostic summary
- `findings`: registry-backed finding objects

Support-bundle JSON contains:

- `metadata`
- `schema_version`
- `dry_run`
- `output_root`
- `bundle_dir`
- `privacy_mode`
- `redaction_enabled`
- `files`
- `collection_plan`
- `manifest`
- `report_schema_version`

Domain order:

1. `system`
2. `power`
3. `thermal`
4. `config`
5. `gpio`
6. `camera`
7. `python`

Overall status rules:

- `healthy`: no finding above `info` impact
- `warning`: highest finding impact is `warning`
- `degraded`: highest finding impact is `degraded`
- `critical`: highest finding impact is `critical`, such as active firmware throttling or CPU temperature in likely-throttling range

Stability notes:

- Automation should gate behavior on `schema_version`.
- Unknown fields should be ignored.
- Human-readable CLI output is not covered by this schema contract.

Versioning rules:

- v1 field meanings are frozen for the lifetime of schema version `1.0.0`.
- Additive fields may be introduced in compatible releases.
- Removing fields, changing enum values, or changing the meaning of an existing
  field requires a schema version bump.
- Finding ID severity, impact, and remediation category changes require an
  update to the finding registry and release notes.
