up

docs/events/README.md

@@ -1,9 +1,30 @@
 # Event Envelope Schemas
 
-Versioned JSON Schemas for platform events consumed by Scheduler, Notify, and UI.
+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.
 
-- `scanner.report.ready@1.json`
-- `scheduler.rescan.delta@1.json`
-- `attestor.logged@1.json`
+## 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.
 
-Producers must bump the version suffix when introducing breaking changes; consumers validate incoming payloads against these schemas.
+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.