123 lines
6.0 KiB
Markdown
123 lines
6.0 KiB
Markdown
# 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
|
|
make validate INPUT=examples/example-report.yaml
|
|
make validate INPUT=examples/example-report.json
|
|
make test
|
|
```
|
|
|
|
`make test` 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
|
|
make render INPUT=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+, Python 3.11+, PyYAML,
|
|
jsonschema, and selected fonts are external 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.
|
|
- `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` | — |
|
|
|
|
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. 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 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](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.
|