5.6 KiB
Report contract version 1
report.schema.json is the implemented JSON Schema Draft 2020-12 interface for generic YAML/JSON report definitions. Validation is available now; PDF rendering is the next implementation slice.
Standalone validation
Python 3.11 or newer is required. From this component checkout:
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python tools/validate.py examples/example-report.yaml
.venv/bin/python tools/validate.py examples/example-report.json
.venv/bin/python -m unittest discover -s tests -p 'test_*.py'
On Windows substitute .venv\Scripts\python.exe. With uv, use uv venv and
uv pip sync --python .venv/bin/python requirements.txt. The dependency lock pins
transitive versions. Validation needs no Typst or sibling repositories and works
from any working directory using explicit paths. It writes no files. Exit codes:
0 valid, 1 invalid/unreadable input or missing dependencies, 2 CLI usage error.
Errors identify the offending JSON path; unsupported file extensions are rejected.
Required and optional content
Only schema_version: 1, nonblank title, and metadata containing nonblank
Author and a calendar-valid Date string (YYYY-MM-DD) are required.
examples/minimal-report.json demonstrates omitted optional fields. The larger
YAML/JSON examples have identical parsed content and contain no organisation assets
or actual incident data.
Optional fields retain useful legacy structure:
id,subtitle,report_type(technicalorbriefing),status,severity.summary,closing: supplied prose, never generated from technical observations.timeline: rows withtime,event, optionalnotes.findings: title, optional ID/severity/status, separateevidenceandassessment, and optionalevidence_refscontaining artifact, JSON pointer, and optional label.sections,appendices: titled sections containing generic content blocks.actions_title,actions: action titles, optional status/text/command strings.provenance: generic source records with artifact and optional SHA-256/schema version/producer, and optionalrendered_bytool name/version. Do not fabricate missing historical provenance or claim a render before it happens.
Finding IDs, when supplied, must be unique. Evidence pointers are syntax-checked;
this validator does not open referenced evidence or prove report assertions.
Additional metadata labels may contain JSON scalar values. Unknown fields elsewhere
are rejected, including legacy diagnostics, top-level organization and named
theme fields. Status is a supplied nonblank display label; severity is one of
info, low, medium, high, critical, warning, ok, success, unanalysed.
Blocks
type |
Required content | Optional content |
|---|---|---|
text |
text |
— |
bullets |
nonempty items of strings |
— |
steps |
nonempty items of strings |
— |
callout |
text |
title, kind (severity token) |
code |
text |
— |
subsection |
title, nonempty nested content |
— |
Unknown or misspelled blocks fail validation. Text and commands are data, not code for the validator to execute. The renderer must preserve that boundary.
Branding and path resolution
branding is optional and contains optional organization, logo, and theme.
A theme is an object with optional font, mono_font, and six-digit hex colors:
ink, muted, line, paper_soft, accent, info, warning, critical,
success. No organisation, author, logo, or incident name is hard-coded.
Logo and artifact paths use relative forward-slash paths without parent/dot segments, backslashes, drive letters, or control characters. For the future renderer, resolve assets relative to the input report directory; missing branding means neutral defaults with no logo, and a missing specified asset is an error. This pass validates the contract shape, not asset availability or actual layout. The intended rendering CLI will accept one report and an explicit output path; there is no implemented render command yet.
YAML/JSON behavior
Input must fit the JSON data model: string mapping keys, strings, finite numbers, booleans, null, arrays, and objects. Quote dates/timestamps and identifier-like values so YAML cannot reinterpret them. Duplicate keys, non-finite numbers, unsafe tags, recursive aliases, and YAML merge keys are rejected. Acyclic aliases are allowed when their expanded values satisfy the same schema. Multiple YAML documents are not accepted. YAML and JSON validation use the same schema and semantic checks.
Legacy migration and compatibility
Add an explicit version and title to legacy reports, retain metadata.Date and
metadata.Author, and move organization into branding.organization. Resolve
named legacy palettes into explicit branding.theme values. Supply a logo only
when the report's owner provides it. Map diagnostic hypotheses and fixed domain
sections into generic sections/cards; they are not a required renderer feature.
Do not relabel Windows raw captures as report inputs.
Unsupported versions fail validation. Breaking structural or semantic changes require a new schema version and migration notes. The pinned legacy examples remain unchanged for visual comparison; the new examples show contract-v1 authoring.
See JSON Schema validation and jsonschema format checking for the underlying validation rules. Local semantic checks additionally reject repeated finding IDs.