NHS Notify Standards

NHS Notify – CloudEvents Standards

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.

Overview

CloudEvents is a vendor-neutral specification for describing event data. These standards provide:

Project Structure

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

Common Schemas (Shared Across All Domains)

Version: 2025-10

Schema Source (YAML) Published Schema Documentation
Nhs Notify Controlplane src/common/2025-10/defs/nhs-notify-controlplane.schema.yaml schemas/common/2025-10/defs/nhs-notify-controlplane.schema.json ../../docs/cloudevents/common/2025-10/defs/nhs-notify-controlplane.schema.md
Nhs Notify Dataplane src/common/2025-10/defs/nhs-notify-dataplane.schema.yaml schemas/common/2025-10/defs/nhs-notify-dataplane.schema.json ../../docs/cloudevents/common/2025-10/defs/nhs-notify-dataplane.schema.md
NHS Notify Metadata src/common/2025-10/defs/nhs-notify-metadata.schema.yaml schemas/common/2025-10/defs/nhs-notify-metadata.schema.json ../../docs/cloudevents/common/2025-10/defs/nhs-notify-metadata.schema.md
NHS Notify Payload src/common/2025-10/defs/nhs-notify-payload.schema.yaml schemas/common/2025-10/defs/nhs-notify-payload.schema.json ../../docs/cloudevents/common/2025-10/defs/nhs-notify-payload.schema.md
NHS Number src/common/2025-10/defs/nhs-number.schema.yaml schemas/common/2025-10/defs/nhs-number.schema.json ../../docs/cloudevents/common/2025-10/defs/nhs-number.schema.md
NHS Notify Profile src/common/2025-10/nhs-notify-profile.schema.yaml schemas/common/2025-10/nhs-notify-profile.schema.json ../../docs/cloudevents/common/2025-10/nhs-notify-profile.schema.md

Version: 2025-11-draft

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:

Examples Domain

Purpose: Demonstration event showing complete CloudEvents structure with NHS Notify profile, payload, and metadata

Version: 2025-10

Schema Type Source (YAML) Published Schema Documentation
Data Schema src/examples/2025-10/data/nhs-notify-example-event-data.schema.yaml schemas/examples/2025-10/data/nhs-notify-example-event-data.schema.json ../../docs/cloudevents/examples/2025-10/data/nhs-notify-example-event-data.schema.md
Event Schema src/examples/2025-10/events/nhs-notify-example-event.schema.yaml schemas/examples/2025-10/events/nhs-notify-example-event.schema.json ../../docs/cloudevents/examples/2025-10/events/nhs-notify-example-event.schema.md
Profile src/examples/2025-10/example-profile.schema.yaml schemas/examples/2025-10/example-profile.schema.json ../../docs/cloudevents/examples/2025-10/example-profile.schema.md

Example Events

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

Version: 2025-11-draft

Schema Type Source (YAML) Published Schema Documentation
Data Schema src/examples/2025-11-draft/data/nhs-notify-example-event-data.schema.yaml schemas/examples/2025-11-draft/data/nhs-notify-example-event-data.schema.json ../../docs/cloudevents/examples/2025-11-draft/data/nhs-notify-example-event-data.schema.md
Event Schema src/examples/2025-11-draft/events/nhs-notify-example-event.schema.yaml schemas/examples/2025-11-draft/events/nhs-notify-example-event.schema.json ../../docs/cloudevents/examples/2025-11-draft/events/nhs-notify-example-event.schema.md
Profile src/examples/2025-11-draft/example-profile.schema.yaml schemas/examples/2025-11-draft/example-profile.schema.json ../../docs/cloudevents/examples/2025-11-draft/example-profile.schema.md

Example Events

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

Supplier Allocation Domain

Purpose: Production domain for supplier allocation file processing events

Version: 2025-12

Schema Type Source (YAML) Published Schema Documentation
File Data src/supplier-allocation/2025-12/data/file-data.schema.yaml schemas/supplier-allocation/2025-12/data/file-data.schema.json ../../docs/cloudevents/supplier-allocation/2025-12/data/file-data.schema.md
Definitions src/supplier-allocation/2025-12/defs/someobject.schema.yaml schemas/supplier-allocation/2025-12/defs/someobject.schema.json ../../docs/cloudevents/supplier-allocation/2025-12/defs/someobject.schema.md
File Printed Event src/supplier-allocation/2025-12/events/file-printed.schema.yaml schemas/supplier-allocation/2025-12/events/file-printed.schema.json ../../docs/cloudevents/supplier-allocation/2025-12/events/file-printed.schema.md
File Received Event src/supplier-allocation/2025-12/events/file-received.schema.yaml schemas/supplier-allocation/2025-12/events/file-received.schema.json ../../docs/cloudevents/supplier-allocation/2025-12/events/file-received.schema.md
Profile src/supplier-allocation/2025-12/supplier-allocation-profile.schema.yaml schemas/supplier-allocation/2025-12/supplier-allocation-profile.schema.json ../../docs/cloudevents/supplier-allocation/2025-12/supplier-allocation-profile.schema.md

Example Events

Event Name Event Instance Documentation
File Printed ../../docs/cloudevents/supplier-allocation/2025-12/example-events/file-printed-event.json ../../docs/cloudevents/supplier-allocation/2025-12/example-events/file-printed-event.md
File Received ../../docs/cloudevents/supplier-allocation/2025-12/example-events/file-received-event.json ../../docs/cloudevents/supplier-allocation/2025-12/example-events/file-received-event.md

Schema Variants Explained

Modular Schemas (Source)

Published Schemas (Distribution)

Bundled Schemas

Flattened Schemas (Experimental)

Build Commands

# 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

Usage

Validate CloudEvents

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);
}

Reference Examples

Example event instances are generated during the build process:

Extend for New Domains

  1. Create a new domain folder under src/:

    mkdir -p src/my-domain/2025-10/{defs,data,events}
    
  2. Create a domain Makefile:

    # src/my-domain/Makefile
    DOMAIN := my-domain
    PUBLISH_VERSION := 2025-10
    ROOT_DIR := $(shell cd ../.. && pwd)
    
    include ../common.mk
    
  3. Create your YAML schemas following the patterns in existing domains

  4. Build and test:

    cd src/my-domain
    make build test
    

Development

Prerequisites

npm install

Schema Development Workflow

  1. Edit source YAML schemas in src/{domain}/{version}/
  2. Build to generate JSON: make build
  3. Test with validation: make test
  4. Generate docs: make build-docs
  5. Review changes in both schemas and documentation
  6. Deploy when ready: make deploy

Makefile Structure

Benefits of distributed Makefiles:

Adding New Schemas

To add a new schema to an existing domain:

  1. Create the YAML file in the appropriate directory:

    • Profile: src/{domain}/{version}/{domain}-profile.schema.yaml
    • Definitions: src/{domain}/{version}/defs/*.schema.yaml
    • Data: src/{domain}/{version}/data/*.schema.yaml
    • Events: src/{domain}/{version}/events/*.schema.yaml
  2. The build system auto-discovers new schemas - just run:

    make build
    
  3. Update this README to include the new schema in the appropriate table

  4. Regenerate documentation:

    make build-docs
    

Technical Notes

Schema $id Convention

Bundled Schema Implementation

Bundled artifacts are produced via json-schema-ref-parser bundle() (not full dereference) to:

Documentation Generation

Markdown documentation uses json-schema-static-docs with:

License

See repository root for licensing information.