This folder contains the NHS Notify CloudEvents standards: a set of JSON Schemas, examples and generated documentation that define the structure and requirements for event-driven messaging in the NHS Notify ecosystem.
CloudEvents is a vendor-neutral specification for describing event data. These standards provide:
cloudevents/
├── src/ # Source YAML schemas (authoritative)
│ ├── common/ # Shared NHS Notify schemas
│ ├── examples/ # Example event domain
│ └── supplier-allocation/ # Supplier allocation domain
├── schemas/ # Published JSON schemas (with public URLs)
├── docs/ # Generated markdown documentation
├── output/ # Build artifacts (for local validation)
└── Makefile # Build, test, and deployment commands
| Schema | Source (YAML) | Published Schema | Documentation |
|---|---|---|---|
| NHS Notify Profile | src/common/2025-11-draft/nhs-notify-profile.schema.yaml |
schemas/common/2025-11-draft/nhs-notify-profile.schema.json |
../../docs/cloudevents/common/2025-11-draft/nhs-notify-profile.schema.md |
Purpose:
Purpose: Demonstration event showing complete CloudEvents structure with NHS Notify profile, payload, and metadata
| Event Name | Event Instance | Documentation |
|---|---|---|
| NHS Notify Example Event | ../../docs/cloudevents/examples/2025-10/example-events/nhs-notify-example-event-event.json |
../../docs/cloudevents/examples/2025-10/example-events/nhs-notify-example-event-event.md |
| Event Name | Event Instance | Documentation |
|---|---|---|
| NHS Notify Example Event | ../../docs/cloudevents/examples/2025-11-draft/example-events/nhs-notify-example-event-event.json |
../../docs/cloudevents/examples/2025-11-draft/example-events/nhs-notify-example-event-event.md |
Purpose: Production domain for supplier allocation file processing events
$refs: References between schemas use relative pathssrc/{domain}/{version}/$id fields use https://notify.nhs.uk/cloudevents/schemas/ URLs$refs: All references use public URLs for external consumptionschemas/{domain}/{version}/$ref dependencies inlined into a single file$defs: Common definitions kept only once (not fully dereferenced)$id removed: Prevents AJV resolution conflictsallOf object schemas merged where safeallOf: Incompatible constraints fall back to property-level combination# Build all schemas (YAML → JSON)
make build
# Deploy schemas to schemas/ with public URLs
make deploy
# Generate documentation
make build-docs
# Run validation tests
make test
# Clean all generated files
make clean
# Complete workflow
make deploy build-docs
Use the published JSON Schema to validate your CloudEvent payloads:
import Ajv from "ajv/dist/2020.js";
import addFormats from "ajv-formats";
const ajv = new Ajv({ strict: false });
addFormats(ajv);
// Load the published schema
const schema = await fetch(
"https://notify.nhs.uk/cloudevents/schemas/examples/2025-10/events/nhs-notify-example-event.schema.json"
).then((res) => res.json());
// Validate your event
const valid = ajv.validate(schema, yourEvent);
if (!valid) {
console.error(ajv.errors);
}
Example event instances are generated during the build process:
output/examples/example-events/nhs-notify-example-event-event.jsonoutput/supplier-allocation/example-events/file-received-event.jsonCreate a new domain folder under src/:
mkdir -p src/my-domain/2025-10/{defs,data,events}
Create a domain Makefile:
# src/my-domain/Makefile
DOMAIN := my-domain
PUBLISH_VERSION := 2025-10
ROOT_DIR := $(shell cd ../.. && pwd)
include ../common.mk
Create your YAML schemas following the patterns in existing domains
Build and test:
cd src/my-domain
make build test
npm install
src/{domain}/{version}/make buildmake testmake build-docsmake deployBenefits of distributed Makefiles:
To add a new schema to an existing domain:
Create the YAML file in the appropriate directory:
src/{domain}/{version}/{domain}-profile.schema.yamlsrc/{domain}/{version}/defs/*.schema.yamlsrc/{domain}/{version}/data/*.schema.yamlsrc/{domain}/{version}/events/*.schema.yamlThe build system auto-discovers new schemas - just run:
make build
Update this README to include the new schema in the appropriate table
Regenerate documentation:
make build-docs
$id Convention/ for AJV compatibility
$id: /examples/2025-10/events/nhs-notify-example-event.schema.json$ref resolution in documentation generation$id: https://notify.nhs.uk/cloudevents/schemas/examples/2025-10/events/nhs-notify-example-event.schema.jsonBundled artifacts are produced via json-schema-ref-parser bundle() (not full dereference) to:
$defs unique (not duplicated)$defs$id values to avoid AJV resolution conflictsMarkdown documentation uses json-schema-static-docs with:
output/ to docs/See repository root for licensing information.