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 (payload embeds the canonical report plus DSSE envelope). Consumers: Notify, UI timeline.
scanner.scan.completed@1.json — emitted alongside the signed report to capture scan outcomes/summary data for downstream automation. Consumers: Notify, Scheduler backfills, UI timelines.
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.

Envelope structure

All event envelopes share the same deterministic header. Use the following table as the quick reference when emitting or parsing events:

Field	Type	Notes
`eventId`	`uuid`	Must be globally unique per occurrence; producers log duplicates as fatal.
`kind`	`string`	Fixed per schema (e.g., `scanner.report.ready`). Downstream services reject unknown kinds or versions.
`tenant`	`string`	Multi‑tenant isolation key; mirror the value recorded in queue/Mongo metadata.
`ts`	`date-time`	RFC 3339 UTC timestamp. Use monotonic clocks or atomic offsets so ordering survives retries.
`scope`	`object`	Optional block used when the event concerns a specific image or repository. See schema for required fields (e.g., `repo`, `digest`).
`payload`	`object`	Event-specific body. Schemas allow additional properties so producers can add optional hints (e.g., `reportId`, `quietedFindingCount`) without breaking consumers. For scanner events, payloads embed both the canonical report document and the DSSE envelope so consumers can reuse signatures without recomputing them. See `docs/runtime/SCANNER_RUNTIME_READINESS.md` for the runtime consumer checklist covering these hints.
`attributes`	`object`	Optional metadata bag (`string` keys/values) for downstream correlation (e.g., pipeline identifiers). Omit when unused to keep payloads concise.

When adding new optional fields, document the behaviour in the schema’s description block and update the consumer checklist in the next sprint sync.

Canonical samples & validation

Reference payloads live under docs/events/samples/, mirroring the schema version (<event-name>@<version>.sample.json). They illustrate common field combinations, including the optional attributes that downstream teams rely on for UI affordances and audit trails. Scanner samples reuse the exact DSSE envelope checked into samples/api/reports/report-sample.dsse.json, and unit tests (ReportSamplesTests, PlatformEventSchemaValidationTests) guard that payloads stay canonical and continue to satisfy the published schemas.

Run the following loop offline to validate both schemas and samples:

# Validate schemas (same check as CI)
for schema in docs/events/*.json; do
  npx ajv compile -c ajv-formats -s "$schema"
done

# Validate canonical samples against their schemas
for sample in docs/events/samples/*.sample.json; do
  schema="docs/events/$(basename "${sample%.sample.json}").json"
  npx ajv validate -c ajv-formats -s "$schema" -d "$sample"
done

Consumers can copy the samples into integration tests to guarantee backwards compatibility. When emitting new event versions, include a matching sample and update this README so air-gapped operators stay in sync.

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 docs/events/samples/ (mirrors the schema version) and mirror them into samples/events/ when you need fixtures in integration repositories.

Contact the Platform Events group in Docs Guild if you need help shaping a new event or version strategy.

4.9 KiB Raw Blame History Unescape Escape