master
daa6a4ae8c
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Build Test Deploy / build-test (push) Has been cancelled
Build Test Deploy / authority-container (push) Has been cancelled
Build Test Deploy / docs (push) Has been cancelled
Build Test Deploy / deploy (push) Has been cancelled
31 lines
1.8 KiB
Markdown
31 lines
1.8 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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.
|