JSON output schemas

Every JSON document gha-doctor can emit has a published JSON Schema (draft 2020-12), for integrators who pipe --json output into dashboards, bots, or their own tooling.

Document	Produced by	Schema
Report	`gha-doctor --json` (default mode, with or without run-history analysis)	report.schema.json
Org scan	`gha-doctor --org NAME --json`	org.schema.json
Run deep dive	`gha-doctor --run ID --json`	run.schema.json
Fix preview	`gha-doctor --diff --json`	fix-preview.schema.json

Stable URLs (also each schema’s $id):

https://linnea-bakshi.github.io/gha-doctor/schema/report.schema.json
https://linnea-bakshi.github.io/gha-doctor/schema/org.schema.json
https://linnea-bakshi.github.io/gha-doctor/schema/run.schema.json
https://linnea-bakshi.github.io/gha-doctor/schema/fix-preview.schema.json

Config file schema

The .gha-doctor.yml repo config file has its own schema — gha-doctor-config.schema.json (draft-07, the dialect editors support best) — so your editor can autocomplete keys and rule IDs. With the YAML language server (the VS Code YAML extension), add one line to the file:

# yaml-language-server: $schema=https://linnea-bakshi.github.io/gha-doctor/schema/gha-doctor-config.schema.json
disable: [D004, D009]
runs: 150

Like the output schemas, it is generated (from the same rule table and validation limits the parser enforces) and CI fails on any drift; the test suite proves its property set and rule-ID enum match the parser exactly.

Why they can’t drift

The schemas are not hand-written. They are generated by reflecting over the exact Go types that encoding/json marshals — the same structs that produce the output. CI regenerates docs/schema/ on every push and fails on any diff, and the test suite validates real output documents (full and minimal) against the committed schemas. A new output field appears in the schema in the same commit that introduces it, or the build is red.

Presence semantics mirror encoding/json:

Fields without omitempty are required. Pointer/slice/map values may be JSON null (a nil Go value marshals to null), and the schema says so with an explicit anyOf: [..., null].
Fields with omitempty are optional and never null — the zero value is omitted entirely.
Objects set additionalProperties: false, so a schema-validating consumer also notices if a field is renamed.

Compatibility policy

Additive changes (new optional fields, new blocks like analysis.X) can arrive in any minor release. Validate with a tolerant consumer or re-fetch the schema; keys you don’t know are new features, not breakage.
Renames/removals/type changes of existing fields are breaking and only happen with a changelog callout.
Analysis blocks are only present when the corresponding data was measured — the same honesty gates that govern the human-readable report. Treat absence as “not measured”, never as zero.

Quick start

Validate a report with check-jsonschema:

$ gha-doctor --repo cli/cli --json > report.json
$ check-jsonschema --schemafile https://linnea-bakshi.github.io/gha-doctor/schema/report.schema.json report.json
ok -- validation done

Or just explore with jq — a few useful paths:

$ gha-doctor --json | jq '.score.grade, .score.points'
$ gha-doctor --json | jq '.findings[] | {rule, file, line, message}'
$ gha-doctor --json | jq '.analysis.flaky_tests'
$ gha-doctor --json | jq '.top_wins'