# Report contract version 1 [report.schema.json](../schema/report.schema.json) is the implemented JSON Schema Draft 2020-12 interface for generic YAML/JSON report definitions. Validation and PDF rendering are implemented by the standalone component. ## Standalone validation Typst and Bash are required at runtime. From this component checkout: ```bash bash tools/validate.sh examples/example-report.yaml bash tools/validate.sh examples/example-report.json ./tests/test.sh ``` `./tests/test.sh` creates and synchronizes `.venv` with uv before invoking Python. Python is not used by validation or rendering. Validation needs no 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. ## Rendering CLI After installing Typst: ```bash ./render.sh examples/example-report.yaml --output output/report.pdf ``` Validation always runs before Typst. Relative branding assets resolve from the input report directory and are staged with the report; traversal and symlinks are rejected. Rendering occurs in a temporary project and publishes the completed PDF only after Typst succeeds. Existing output requires `--force`. The command is independent of the caller's working directory. Exit codes are 0 for a published PDF, 1 for data, validation, asset, rendering or I/O failure, and 2 for invalid invocation. Typst 0.15+ and selected fonts are runtime dependencies. Python, PyYAML, and jsonschema are test-only dependencies. PDF bytes can vary with Typst and font versions; record them when historical reproduction matters. ## 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` (`technical` or `briefing`), `status`, `severity`. - `summary`, `closing`: supplied prose, never generated from technical observations. - `metrics`: up to four supplied label/value cards with an optional severity tone. - `timeline`: rows with `time`, `event`, optional `notes`. - `findings`: title, optional ID/severity/status, separate `evidence` and `assessment`, and optional `evidence_refs` containing 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 optional `rendered_by` tool 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` | — | | `card` | `title`, nonempty nested `content` | `tone` (severity token) | Unknown or misspelled blocks fail validation. Text and commands are data, not code for the validator to execute. The renderer must preserve that boundary. Within a `text` block, balanced single backticks mark inline code, for example `` `5661ea1` ``. The renderer shows Typst's inline raw text as a small rounded pill; unmatched backticks remain literal. This formatting never executes report text. Cards render as rounded, shaded panels. Omit `tone` for a neutral panel or set it to a severity token to tint its border and background. A card may contain the same block types as a section, including lists and nested subsections. ```yaml sections: - title: Review content: - type: card title: Evidence preserved tone: success content: - type: text text: The original capture and its hash are retained. ``` ## Branding and path resolution `branding` is optional and contains optional `organization`, `logo`, and `theme`. Set `branding.theme` to the built-in name `default` or `teal`, or provide an object with optional `font`, `mono_font`, and six-digit hex colors: `ink`, `muted`, `line`, `paper_soft`, `accent`, `info`, `warning`, `critical`, `success`. `default` matches the neutral fallback palette; `teal` selects a blue-green palette. 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. The renderer resolves assets relative to the input report directory; missing branding means neutral defaults with no logo, and a missing specified asset is an error. It accepts one report and one explicit output path. ## 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 palettes to `branding.theme` names or explicit 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](https://json-schema.org/draft/2020-12/json-schema-validation) and [jsonschema format checking](https://python-jsonschema.readthedocs.io/en/stable/validate/) for the underlying validation rules. Local semantic checks additionally reject repeated finding IDs.