nhs-notify-standards

NHS Notify CloudEvents Profile

NHS Notify profile for CloudEvents 1.0 including additional governance and tracing attributes.

$id	nhs-notify-profile.schema.json
$schema	https://json-schema.org/draft/2020-12/schema

Properties

Name		Type
specversion		String=1.0
id		String
source		String
subject		String
type	All of:	String
		String
		String
		String
		String
		String
		String
		String
		String
time		String
datacontenttype		String=application/json
dataschema		String
data		Object
traceparent		String
tracestate		String
partitionkey		String
recordedtime		String
sampledrate		Integer
sequence		String
severitytext		String
severitynumber		Integer
dataclassification		String
dataregulation		String
datacategory		String
All of:

Example

{
    "specversion": "1.0",
    "id": "6f1c2a53-3d54-4a0a-9a0b-0e9ae2d4c111",
    "source": "/data-plane/ordering",
    "subject": "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d",
    "type": "uk.nhs.notify.ordering.order.read",
    "time": "2025-10-01T10:15:30.000Z",
    "recordedtime": "2025-10-01T10:15:30.250Z",
    "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
    "tracestate": "rojo=00f067aa0ba902b7,congo=t61rcWkgMzE",
    "partitionkey": "customer-920fca11",
    "sequence": "00000000000000000042",
    "severitytext": "DEBUG",
    "severitynumber": 1,
    "datacontenttype": "application/json",
    "dataschema": "https://nhsdigital.github.io/nhs-notify-standards/cloudevents/nhs-notify-example-event-data.schema.json",
    "dataclassification": "restricted",
    "dataregulation": "ISO-27001",
    "datacategory": "sensitive",
    "sampledrate": 5,
    "data": {
        "notify-payload": {
            "notify-data": {
                "nhsNumber": "9434765919"
            },
            "notify-metadata": {
                "teamResponsible": "Team 1",
                "notifyDomain": "Ordering",
                "version": "1.3.0"
            }
        }
    }
}

---

specversion

Description	CloudEvents specification version (fixed to 1.0).
Type	String
Required	Yes
Const	1.0
Examples	1.0

id

Description	Unique identifier for this event instance (UUID).
Type	String
Required	Yes
Min Length	1
Format	uuid
Examples	6f1c2a53-3d54-4a0a-9a0b-0e9ae2d4c111

source

Description	Logical event producer path starting /data-plane or /control-plane followed by lowercase segments.
Type	String
Required	Yes
Min Length	12
Format	uri-reference
Pattern	^/(data-plane|control-plane)(?:/[a-z0-9-]+)*$
Examples	/data-plane/ordering /control-plane/audit

subject

Description	Resource path (no leading slash) within the source made of lowercase segments separated by '/'.
Type	String
Required	Yes
Min Length	5
Format	uri-reference
Pattern	^(?:[a-z0-9-]+)(?:/[a-z0-9-]+)*$
Examples	customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d

type

Description	Event type (uk.nhs.notify.*) using reverse-DNS style; ambiguous verbs (completed, finished, updated, changed, processed, handled, status, started, failed) disallowed.
Type	All of:	String
		String
		String
		String
		String
		String
		String
		String
		String
Required	Yes
Min Length	1
Pattern	^uk\.nhs\.notify\.[a-z0-9]+(\.[a-z0-9]+)*$
Examples	uk.nhs.notify.ordering.order.read

type.0

type.1

type.2

type.3

type.4

type.5

type.6

type.7

type.8

time

Description	Timestamp when the event occurred (RFC 3339).
Type	String
Required	Yes
Format	date-time
Examples	2025-10-01T10:15:30.000Z

datacontenttype

Description	Media type for the data field (fixed to application/json).
Type	String
Required	No
Const	application/json
Examples	application/json

dataschema

Description	URI of a schema that describes the event payload (notify-payload).
Type	String
Required	No
Examples	https://nhsdigital.github.io/nhs-notify-standards/cloudevents/nhs-notify-example-event-data.schema.json

data

Description	Container object wrapping the structured Notify payload.
Type	Object
Required	Yes

Properties

Name		Type
notify-payload		Object (of type ./nhs-notify-payload.schema.html)

data.notify-payload

Defined in ./nhs-notify-payload.schema.html

$id	nhs-notify-payload.schema.json
Description	Structured Notify payload containing domain data (notify-data) and metadata (notify-metadata).
Type	Object (of type ./nhs-notify-payload.schema.html)
Required	Yes

traceparent

Description	W3C Trace Context traceparent header value.
Type	String
Required	Yes
Min Length	1
Pattern	^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$
Examples	00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

tracestate

Description	Optional W3C Trace Context tracestate header value.
Type	String
Required	No
Examples	rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

partitionkey

Description	Partition / ordering key (lowercase alphanumerics and hyphen, 1-64 chars).
Type	String
Required	No
Min Length	1
Max Length	64
Pattern	^[a-z0-9-]+$
Examples	customer-920fca11

recordedtime

Description	Timestamp when the event was recorded/persisted (should be >= time).
Type	String
Required	Yes
Format	date-time
Examples	2025-10-01T10:15:30.250Z

sampledrate

Description	Sampling factor: number of similar occurrences this event represents.
Type	Integer
Required	No
Minimum	1
Examples	5

sequence

Description	Zero-padded 20 digit numeric sequence (lexicographically sortable).
Type	String
Required	No
Pattern	^\d{20}$
Examples	00000000000000000042

severitytext

Description	Log severity level name.
Type	String
Required	No
Enum	TRACE DEBUG INFO WARN ERROR FATAL
Examples	DEBUG

severitynumber

Description	Numeric severity (TRACE=0, DEBUG=1, INFO=2, WARN=3, ERROR=4, FATAL=5).
Type	Integer
Required	Yes
Maximum	5
Examples	1

dataclassification

Description	Data sensitivity classification.
Type	String
Required	No
Enum	public internal confidential restricted
Examples	restricted

dataregulation

Description	Regulatory regime tag applied to this data.
Type	String
Required	No
Enum	GDPR HIPAA PCI-DSS ISO-27001 NIST-800-53 CCPA
Examples	ISO-27001

datacategory

Description	Data category classification (e.g. standard, special-category).
Type	String
Required	No
Enum	non-sensitive standard sensitive special-category
Examples	sensitive

---

Schema

{
    "$id": "nhs-notify-profile.schema.json",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "NHS Notify CloudEvents Profile",
    "description": "NHS Notify profile for CloudEvents 1.0 including additional governance and tracing attributes.",
    "type": "object",
    "additionalProperties": false,
    "$comment": "CloudEvents allows arbitrary extension attributes. NHS profile: time (occurred-at) is mandatory though optional in CloudEvents spec.",
    "properties": {
        "specversion": {
            "type": "string",
            "const": "1.0",
            "description": "CloudEvents specification version (fixed to 1.0).",
            "examples": [
                "1.0"
            ],
            "$comment": "CloudEvents version used. Core attributes: specversion,id,source,type (+ optional subject,time,datacontenttype,dataschema,data). Ref: CloudEvents core spec."
        },
        "id": {
            "type": "string",
            "format": "uuid",
            "minLength": 1,
            "description": "Unique identifier for this event instance (UUID).",
            "examples": [
                "6f1c2a53-3d54-4a0a-9a0b-0e9ae2d4c111"
            ],
            "$comment": "Unique per (source,id). This should be a randomly generated guid that represents the id of the event itself."
        },
        "source": {
            "type": "string",
            "pattern": "^/(data-plane|control-plane)(?:/[a-z0-9-]+)*$",
            "minLength": 12,
            "format": "uri-reference",
            "description": "Logical event producer path starting /data-plane or /control-plane followed by lowercase segments.",
            "examples": [
                "/data-plane/ordering",
                "/control-plane/audit"
            ],
            "$comment": "Must begin with '/data-plane' or '/control-plane'. Subsequent segments: lowercase alphanumeric or hyphen. No trailing '/'."
        },
        "subject": {
            "type": "string",
            "pattern": "^(?:[a-z0-9-]+)(?:/[a-z0-9-]+)*$",
            "minLength": 5,
            "format": "uri-reference",
            "description": "Resource path (no leading slash) within the source made of lowercase segments separated by '/'.",
            "examples": [
                "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
            ],
            "$comment": "URI path: must not start with '/', only lowercase alphanumeric and hyphen segments separated by '/', must not end with '/'."
        },
        "type": {
            "type": "string",
            "minLength": 1,
            "pattern": "^uk\\.nhs\\.notify\\.[a-z0-9]+(\\.[a-z0-9]+)*$",
            "allOf": [
                {
                    "not": {
                        "pattern": "(?:^|\\.)completed(?:\\.|$)"
                    }
                },
                {
                    "not": {
                        "pattern": "(?:^|\\.)finished(?:\\.|$)"
                    }
                },
                {
                    "not": {
                        "pattern": "(?:^|\\.)updated(?:\\.|$)"
                    }
                },
                {
                    "not": {
                        "pattern": "(?:^|\\.)changed(?:\\.|$)"
                    }
                },
                {
                    "not": {
                        "pattern": "(?:^|\\.)processed(?:\\.|$)"
                    }
                },
                {
                    "not": {
                        "pattern": "(?:^|\\.)handled(?:\\.|$)"
                    }
                },
                {
                    "not": {
                        "pattern": "(?:^|\\.)status(?:\\.|$)"
                    }
                },
                {
                    "not": {
                        "pattern": "(?:^|\\.)started(?:\\.|$)"
                    }
                },
                {
                    "not": {
                        "pattern": "(?:^|\\.)failed(?:\\.|$)"
                    }
                }
            ],
            "description": "Event type (uk.nhs.notify.*) using reverse-DNS style; ambiguous verbs (completed, finished, updated, changed, processed, handled, status, started, failed) disallowed.",
            "examples": [
                "uk.nhs.notify.ordering.order.read"
            ],
            "$comment": "NHS naming: lower-dot namespaced; allowed chars a-z0-9 and dots; banned tokens: completed, finished, updated, changed, processed, handled, status, started, failed."
        },
        "time": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the event occurred (RFC 3339).",
            "examples": [
                "2025-10-01T10:15:30.000Z"
            ],
            "$comment": "RFC3339 UTC occurred-at (REQUIRED in NHS profile)."
        },
        "datacontenttype": {
            "type": "string",
            "const": "application/json",
            "description": "Media type for the data field (fixed to application/json).",
            "examples": [
                "application/json"
            ],
            "$comment": "Usually application/json."
        },
        "dataschema": {
            "type": "string",
            "description": "URI of a schema that describes the event payload (notify-payload).",
            "examples": [
                "https://nhsdigital.github.io/nhs-notify-standards/cloudevents/nhs-notify-example-event-data.schema.json"
            ],
            "$comment": "URI to event payload schema."
        },
        "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "notify-payload"
            ],
            "properties": {
                "notify-payload": {
                    "$ref": "./nhs-notify-payload.schema.json",
                    "description": "Structured Notify payload containing domain data (notify-data) and metadata (notify-metadata)."
                }
            },
            "description": "Container object wrapping the structured Notify payload.",
            "examples": [
                {
                    "notify-payload": {
                        "notify-data": {
                            "nhsNumber": "9434765919"
                        },
                        "notify-metadata": {
                            "teamResponsible": "Team 1",
                            "notifyDomain": "Ordering",
                            "version": "1.3.0"
                        }
                    }
                }
            ],
            "$comment": "Domain payload (arbitrary JSON value)."
        },
        "traceparent": {
            "type": "string",
            "minLength": 1,
            "pattern": "^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$",
            "description": "W3C Trace Context traceparent header value.",
            "examples": [
                "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"
            ],
            "$comment": "W3C Trace Context traceparent (required when tracing used)."
        },
        "tracestate": {
            "type": "string",
            "description": "Optional W3C Trace Context tracestate header value.",
            "examples": [
                "rojo=00f067aa0ba902b7,congo=t61rcWkgMzE"
            ],
            "$comment": "W3C Trace Context tracestate (optional)."
        },
        "partitionkey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "pattern": "^[a-z0-9-]+$",
            "description": "Partition / ordering key (lowercase alphanumerics and hyphen, 1-64 chars).",
            "examples": [
                "customer-920fca11"
            ],
            "$comment": "Non-empty partition key for scaling / causal grouping. Must be 1-64 characters, only lowercase letters, numbers, and hyphen."
        },
        "recordedtime": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the event was recorded/persisted (should be >= time).",
            "examples": [
                "2025-10-01T10:15:30.250Z"
            ],
            "$comment": "Bitemporal created-at; should be >= time."
        },
        "sampledrate": {
            "type": "integer",
            "minimum": 1,
            "description": "Sampling factor: number of similar occurrences this event represents.",
            "examples": [
                5
            ],
            "$comment": "Integer > 0 indicating how many similar occurrences this event represents."
        },
        "sequence": {
            "type": "string",
            "pattern": "^\\d{20}$",
            "description": "Zero-padded 20 digit numeric sequence (lexicographically sortable).",
            "examples": [
                "00000000000000000042"
            ],
            "$comment": "Lexicographically comparable ordering string per source. Must be a string of exactly 20 digits, left-padded with zeros, representing a 64-bit unsigned integer."
        },
        "severitytext": {
            "type": "string",
            "enum": [
                "TRACE",
                "DEBUG",
                "INFO",
                "WARN",
                "ERROR",
                "FATAL"
            ],
            "description": "Log severity level name.",
            "examples": [
                "DEBUG"
            ],
            "$comment": "Severity text (TRACE, DEBUG, INFO, WARN, ERROR, FATAL, etc.)."
        },
        "severitynumber": {
            "type": "integer",
            "minimum": 0,
            "maximum": 5,
            "description": "Numeric severity (TRACE=0, DEBUG=1, INFO=2, WARN=3, ERROR=4, FATAL=5).",
            "examples": [
                1
            ],
            "$comment": "Numeric severity corresponding to severitytext (TRACE=0..FATAL=5)."
        },
        "dataclassification": {
            "type": "string",
            "enum": [
                "public",
                "internal",
                "confidential",
                "restricted"
            ],
            "description": "Data sensitivity classification.",
            "examples": [
                "restricted"
            ],
            "$comment": "Data classification e.g. public|internal|confidential|restricted."
        },
        "dataregulation": {
            "type": "string",
            "enum": [
                "GDPR",
                "HIPAA",
                "PCI-DSS",
                "ISO-27001",
                "NIST-800-53",
                "CCPA"
            ],
            "description": "Regulatory regime tag applied to this data.",
            "examples": [
                "ISO-27001"
            ],
            "$comment": "Regulation tags e.g. GDPR, HIPAA."
        },
        "datacategory": {
            "type": "string",
            "enum": [
                "non-sensitive",
                "standard",
                "sensitive",
                "special-category"
            ],
            "description": "Data category classification (e.g. standard, special-category).",
            "examples": [
                "sensitive"
            ],
            "$comment": "Example: special-category (GDPR), phi (HIPAA)."
        }
    },
    "required": [
        "specversion",
        "id",
        "source",
        "subject",
        "type",
        "time",
        "recordedtime",
        "severitynumber",
        "traceparent",
        "data"
    ],
    "dependentRequired": {
        "severitynumber": [
            "severitytext"
        ]
    },
    "allOf": [
        {
            "if": {
                "properties": {
                    "source": {
                        "pattern": "^/data-plane"
                    }
                },
                "required": [
                    "source"
                ]
            },
            "then": {
                "properties": {
                    "subject": {
                        "pattern": "^customer/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(?:/(?:[a-z0-9-]+|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))*$",
                        "$comment": "When source is /data-plane..., subject must start with customer/{uuid} and may have further segments which are either lowercase tokens or UUIDs.",
                        "description": "Subject path for data-plane events: customer/{uuid}[/...]."
                    }
                },
                "required": [
                    "subject"
                ]
            }
        },
        {
            "if": {
                "properties": {
                    "severitytext": {
                        "const": "TRACE"
                    }
                },
                "required": [
                    "severitytext"
                ]
            },
            "then": {
                "properties": {
                    "severitynumber": {
                        "const": 0
                    }
                },
                "required": [
                    "severitynumber"
                ]
            }
        },
        {
            "if": {
                "properties": {
                    "severitytext": {
                        "const": "DEBUG"
                    }
                },
                "required": [
                    "severitytext"
                ]
            },
            "then": {
                "properties": {
                    "severitynumber": {
                        "const": 1
                    }
                },
                "required": [
                    "severitynumber"
                ]
            }
        },
        {
            "if": {
                "properties": {
                    "severitytext": {
                        "const": "INFO"
                    }
                },
                "required": [
                    "severitytext"
                ]
            },
            "then": {
                "properties": {
                    "severitynumber": {
                        "const": 2
                    }
                },
                "required": [
                    "severitynumber"
                ]
            }
        },
        {
            "if": {
                "properties": {
                    "severitytext": {
                        "const": "WARN"
                    }
                },
                "required": [
                    "severitytext"
                ]
            },
            "then": {
                "properties": {
                    "severitynumber": {
                        "const": 3
                    }
                },
                "required": [
                    "severitynumber"
                ]
            }
        },
        {
            "if": {
                "properties": {
                    "severitytext": {
                        "const": "ERROR"
                    }
                },
                "required": [
                    "severitytext"
                ]
            },
            "then": {
                "properties": {
                    "severitynumber": {
                        "const": 4
                    }
                },
                "required": [
                    "severitynumber"
                ]
            }
        },
        {
            "if": {
                "properties": {
                    "severitytext": {
                        "const": "FATAL"
                    }
                },
                "required": [
                    "severitytext"
                ]
            },
            "then": {
                "properties": {
                    "severitynumber": {
                        "const": 5
                    }
                },
                "required": [
                    "severitynumber"
                ]
            }
        }
    ],
    "examples": [
        {
            "specversion": "1.0",
            "id": "6f1c2a53-3d54-4a0a-9a0b-0e9ae2d4c111",
            "source": "/data-plane/ordering",
            "subject": "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d",
            "type": "uk.nhs.notify.ordering.order.read",
            "time": "2025-10-01T10:15:30.000Z",
            "recordedtime": "2025-10-01T10:15:30.250Z",
            "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
            "tracestate": "rojo=00f067aa0ba902b7,congo=t61rcWkgMzE",
            "partitionkey": "customer-920fca11",
            "sequence": "00000000000000000042",
            "severitytext": "DEBUG",
            "severitynumber": 1,
            "datacontenttype": "application/json",
            "dataschema": "https://nhsdigital.github.io/nhs-notify-standards/cloudevents/nhs-notify-example-event-data.schema.json",
            "dataclassification": "restricted",
            "dataregulation": "ISO-27001",
            "datacategory": "sensitive",
            "sampledrate": 5,
            "data": {
                "notify-payload": {
                    "notify-data": {
                        "nhsNumber": "9434765919"
                    },
                    "notify-metadata": {
                        "teamResponsible": "Team 1",
                        "notifyDomain": "Ordering",
                        "version": "1.3.0"
                    }
                }
            }
        }
    ]
}