master
daa6a4ae8c
1.8 KiB
Event Envelope Schemas
Platform services publish strongly typed events; the JSON Schemas in this directory define those envelopes. File names follow <event-name>@<version>.json so producers and consumers can negotiate contracts explicitly.
Catalog
scanner.report.ready@1.json— emitted by Scanner.WebService once a signed report is persisted. Consumers: Notify, UI timeline.scheduler.rescan.delta@1.json— emitted by Scheduler when BOM-Index diffs require fresh scans. Consumers: Notify, Policy Engine.attestor.logged@1.json— emitted by Attestor after storing the Rekor inclusion proof. Consumers: UI attestation panel, Governance exports.
Additive payload changes (new optional fields) can stay within the same version. Any breaking change (removing a field, tightening validation, altering semantics) must increment the @<version> suffix and update downstream consumers.
CI validation
The Docs CI workflow (.gitea/workflows/docs.yml) installs ajv-cli and compiles every schema on pull requests. Run the same check locally before opening a PR:
for schema in docs/events/*.json; do
npx ajv compile -c ajv-formats -s "$schema"
done
Tip: run npm install --no-save ajv ajv-cli ajv-formats once per clone so npx can resolve the tooling offline.
If a schema references additional files, include -r flags so CI and local runs stay consistent.
Working with schemas
- Producers should validate outbound payloads using the matching schema during unit tests.
- Consumers should pin to a specific version and log when encountering unknown versions to catch missing migrations early.
- Store real payload samples under
samples/events/(mirrors the schema version) to aid contract testing.
Contact the Platform Events group in Docs Guild if you need help shaping a new event or version strategy.