Design your Multicast Notification Service event

This page helps services design events that will be published to Multicast Notification Service (MNS).

MNS mandates a constrained CloudEvents compatible format.

This comprises:

• context attributes - metadata describing an event
• a dataref - a link to an API where the full resource can be retrieved (this is optional but is usually included)
• filtering attributes - metadata used for subscription filtering
• a subject - identifier of the resource or entity affected (optional)
• a versionid - version of the resource or entity affected (optional)

The CloudEvents specification describes a number of context attributes, specifying some as required, some optional, and other “extension context attributes”.

The value of each attribute is constrained by the CloudEvents type system - context attributes must contain a value and cannot be null.

Additional context attributes are disallowed.

The source identifies the system or service that produced an event.  This is usually a service, as listed in the service catalogue.

We recommend prefixing the source with a reverse DNS name of the owning organisation (as you would a Java package name). Typically this will be uk.nhs.

An example: uk.nhs.personal-demographics-service

• uk.nhs is the second-level domain for the owning organisation
• personal-demographics-service is the service name, taken from the path component of the service catalogue page

The CloudEvents specification stipulates that the source must be a valid URI-reference.

Good examples

• uk.nhs.register-with-a-gp-surgery-service
• com.healthcaresoftwareprovider.new-gp-system

Bad or invalid examples

• uk.nhs.personal-demographics-service.node1.process123 - too specific / too much detail about your service implementation.
• uk.nhs.pds too brief, not easily human readable and prone to naming collisions.
• nhs uk personal-demographics-service does not follow the recommended format, is not a valid URI-reference.

The type describes the occurrence; the name of the event.

Type names must be unique within the context of the entire MNS service as subscriptions are made to an event type. The event type typically starts with a brief service name or acronym.

Types also carry basic event version information by suffixing with a number - for example, -1.

Event names should typically use past-tense as they describe something that has already happened - for example, user-login-failed or record-updated.

Good examples 

• pds-record-changed-1
• vaccs-immunisation-performed-1

Bad or invalid examples 

• record-updated-1 too general, does not describe the context of the event and is prone to name collision
• pds-update-needs-processing-1 style is not past-tense, sounds more like a “command message”
• pds-record-updated no version information
• pds-record-changed-1.0.1 version information too granular

The dataref is a link to an API on your service where subscribers retrieve full information about the event or the subject record.

The dataref points to the source-of-truth API where subscribers can retrieve the full details related to an event.

Events from services having multiple APIs may choose to omit the dataref  and instead use subject.

Good examples

• https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient/9912003888
• https://api.service.nhs.uk/immunisation-fhir-api/Immunization?patient.identifier=https%3A%2F%2Ffhir.nhs.uk%2FId%2Fnhs-number%7C9912003888

Bad or invalid examples

• https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient/ - it does not point to a specific record. Subscribers should not have to combine the dataref with other information (such as the subject).

The subject identifies the subject of the event in the context of the event producer/event type.

Your event may include a subject field where it is necessary for your use case. (This is discouraged as it compromises the design goals around data minimisation.)

Examples where subject is necessary:

• The source system has more than one API. Subscribers not using the primary API indicated in the dataref use the subject to retrieve a record from an alternative API.
• Subscriber-side filtering of events where it is impractical to use subscription-based filtering, for example, NHS Login subscribe to death notification events from the Personal Demographics Service, but are only concerned with the 30 million NHS Numbers registered on their service. It would be impractical for them to maintain this many subscription filters.

If your event carries a subject, it is expected that it will be included in every instance of the event.

You must describe the format and semantics of the subject field. (Often this is an NHS Number.)

The versionid is the version of the resource or record immediately following the occurrence of the event.

It will identify the relevant section of your API reference to help subscribers understand the format of this field and the semantics in the context of your source system.

It is particularly useful where your API supports retrieving specific versions. This field can help subscribers disambiguate or otherwise understand the case where multiple events have occurred that change the same property of the source record.

Other attributes which are required are:

• specversion - this is always set to the string "1.0". Indicates the major version of the CloudEvents specification.
• id - identifies the event. You must ensure that the source + id is unique for each distinct event. We recommend using a UUID.
• time - timestamp of when the occurrence happened. You must adhere to the format specified in RFC 3339. We recommend UTC.

The filtering object contains metadata used by MNS to determine which subscribers should receive an event. 

The filtering object is used only for subscription matching. It is removed before the event is delivered to subscribers.

Specifying the attributes of the filtering object are the main design element of your event. We recommend you constrain them to concrete subscriber use-cases - do not try to satisfy speculative future cases.

Filtering is optional but recommended as it helps meet data minimisation and subscriber relevancy goals.

The filter schema describes your filtering object and forms the contract between both the publisher and MNS, and the publisher and their event subscribers.

It’s a JSON schema document that describes the properties, values and their constraints.

The MNS team will generate the filter schema as part of the event design process. The example is included to aid understanding of the filtering implementation and capabilities.

The filter schema artefact is not visible to your subscribers. Filtering will be documented in prose and tables in your Event Catalogue entry.

We support the primitive types string, integer, boolean and null.

null is to be used in combination with another type to indicate that the value may not be present for every event. In this case the property is not included in the required list. As a publisher this means you can either not send the property, or send it with a value of null . For subscribers, the property will exist but have the value null 

Consider using enum to constrain values and provide clarity for your subscribers.

string types are accompanied with at least a minLength: 1 constraint to prevent empty values.

We support the array type for lists of values. Arrays can be constrained with minItems and uniqueItems.

We do not support the object type for properties within the filtering object.

additionalProperties is always set to false: you cannot send new filtering information before it is registered against your event. Contact the MNS team if you want to do this.

In the above example the nhs_number string-type property has a format annotation.

This means the information has specific semantic meaning to MNS, and we can derive (look up, or calculate) further information to be included in the filtering object prior to subscription matching.

We currently recognise and support the format values: 

In the nhsnumber case the new generalpractitioner property created by the enrichment process is of odscode format and subject to further enrichment into generalpractitioner_manufacturer_org, generalpractitioner_partykeys and generalpractitioner_asids properties.

New enrichment requests

If your use case requires new enrichment capabilities please discuss them with the MNS team.