CCM-13080: Event data schemas for queue, viewer, core and reporting (#113)

tdroza-nhs · web-flow · commit 05e5233f22e1 · 2025-11-18T16:37:06.000Z
* CCM-13080: Event data schemas for queue, viewer, core and reporting
- Remove placeholder messages.status.updated schema
- Replace generic schema references with specific data schemas

New data schemas:
- Add digital-letters-digital-letter-read-data for viewer events
- Add digital-letters-message-request-{submitted,failed}-data for message lifecycle
- Add digital-letters-queue-item-{enqueued,dequeued,removed}-data for queue operations
- Add digital-letters-reporting-{generate-report,report-generated,report-sent}-data for reporting
diff --git a/.gitleaksignore b/.gitleaksignore
@@ -12,3 +12,7 @@ cd9c0efec38c5d63053dd865e5d4e207c0760d91:docs/guides/Perform_static_analysis.md:
 973c8a1feb76f3cd8743ce27b14e4acc4252240c:src/TESTING_PLAN.md:ipv4:2507
 cc74128e4207833109339e96f3aaebf3cd40dd65:src/TESTING_PLAN.md:ipv4:2507
 791619daf5af4806da7266fa301c0e82145b6de8:src/TESTING_PLAN.md:ipv4:2507
+f8546e35b77b69ba7b15dbe3174d2d7e375200ef:utils/utils/src/__tests__/key-generation/validate-private-key.test.ts:private-key:7
+f8546e35b77b69ba7b15dbe3174d2d7e375200ef:utils/utils/src/__tests__/key-generation/get-private-key.test.ts:private-key:23
+f8546e35b77b69ba7b15dbe3174d2d7e375200ef:utils/utils/src/__tests__/key-generation/get-private-key.test.ts:private-key:30
+f8546e35b77b69ba7b15dbe3174d2d7e375200ef:utils/utils/src/__tests__/key-generation/get-private-key.test.ts:private-key:46
diff --git a/README.md b/README.md
diff --git a/scripts/config/vale/styles/config/vocabularies/words/accept.txt b/scripts/config/vale/styles/config/vocabularies/words/accept.txt
@@ -16,6 +16,7 @@ Cognito
 config
 Cyber
 datetime
+[Dd]equeued
 deduplication
 Dependabot
 dereference
@@ -24,6 +25,7 @@ dev
 draw.io
 drawio
 D'Roza
+[Ee]nqueued
 [Ee]num
 endcapture
 endfor
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-digital-letter-read-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-digital-letter-read-data.schema.yaml
@@ -0,0 +1,13 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: DigitalLetterRead Data
+description: Data payload of the DigitalLetterRead event
+type: object
+additionalProperties: false
+properties:
+  messageReference:
+    $ref: ../defs/requests.schema.yaml#/properties/messageReference
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+required:
+  - messageReference
+  - senderId
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-mesh-inbox-message-received-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-mesh-inbox-message-received-data.schema.yaml
@@ -1,14 +1,10 @@
 $schema: https://json-schema.org/draft/2020-12/schema
-title: Placeholder Data
-description: Base data for digital letters - a placeholder until all data schemas are defined
+title: MESHInboxMessageReceived Data
+description: Data payload of the MESHInboxMessageReceived event
 type: object
 additionalProperties: false
 properties:
   meshMessageId:
-    type: string
-    minLength: 1
-    description: Id of the message in the MESH inbox
-    examples:
-      - "20200601122152994285_D59900"
+    $ref: ../defs/mesh.schema.yaml#/properties/meshMessageId
 required:
   - meshMessageId
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-message-request-failed-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-message-request-failed-data.schema.yaml
@@ -0,0 +1,19 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: MessageRequestSendingFailed Data
+description: Data payload of the MessageRequestSendingFailed event
+type: object
+additionalProperties: false
+properties:
+  messageReference:
+    $ref: ../defs/requests.schema.yaml#/properties/messageReference
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+  messageUri:
+    $ref: ../defs/requests.schema.yaml#/properties/messageUri
+  failureCode:
+    $ref: ../defs/core.schema.yaml#/properties/failureCode
+required:
+  - messageReference
+  - senderId
+  - messageUri
+  - failureCode
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-message-request-submitted-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-message-request-submitted-data.schema.yaml
@@ -0,0 +1,19 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: NotifyMessageRequestSubmitted Data
+description: Data payload of the NotifyMessageRequestSubmitted event
+type: object
+additionalProperties: false
+properties:
+  messageReference:
+    $ref: ../defs/requests.schema.yaml#/properties/messageReference
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+  messageUri:
+    $ref: ../defs/requests.schema.yaml#/properties/messageUri
+  notifyId:
+    $ref: ../defs/core.schema.yaml#/properties/notifyId
+required:
+  - messageReference
+  - senderId
+  - messageUri
+  - notifyId
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-queue-item-dequeued-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-queue-item-dequeued-data.schema.yaml
@@ -0,0 +1,16 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: ItemDequeued Data
+description: Data payload of the ItemDequeued event
+type: object
+additionalProperties: false
+properties:
+  messageReference:
+    $ref: ../defs/requests.schema.yaml#/properties/messageReference
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+  messageUri:
+    $ref: ../defs/requests.schema.yaml#/properties/messageUri
+required:
+  - messageReference
+  - senderId
+  - messageUri
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-queue-item-enqueued-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-queue-item-enqueued-data.schema.yaml
@@ -0,0 +1,16 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: ItemEnqueued Data
+description: Data payload of the ItemEnqueued event
+type: object
+additionalProperties: false
+properties:
+  messageReference:
+    $ref: ../defs/requests.schema.yaml#/properties/messageReference
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+  messageUri:
+    $ref: ../defs/requests.schema.yaml#/properties/messageUri
+required:
+  - messageReference
+  - senderId
+  - messageUri
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-queue-item-removed-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-queue-item-removed-data.schema.yaml
@@ -0,0 +1,16 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: ItemRemoved Data
+description: Data payload of the ItemRemoved event
+type: object
+additionalProperties: false
+properties:
+  messageReference:
+    $ref: ../defs/requests.schema.yaml#/properties/messageReference
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+  messageUri:
+    $ref: ../defs/requests.schema.yaml#/properties/messageUri
+required:
+  - messageReference
+  - senderId
+  - messageUri
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-reporting-generate-report-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-reporting-generate-report-data.schema.yaml
@@ -0,0 +1,10 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: GenerateReport Data
+description: Data payload of the GenerateReport event
+type: object
+additionalProperties: false
+properties:
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+required:
+  - senderId
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-reporting-report-generated-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-reporting-report-generated-data.schema.yaml
@@ -0,0 +1,13 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: ReportGenerated Data
+description: Data payload of the ReportGenerated event
+type: object
+additionalProperties: false
+properties:
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+  reportUri:
+    $ref: ../defs/reporting.schema.yaml#/properties/reportUri
+required:
+  - senderId
+  - reportUri
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-reporting-report-sent-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-reporting-report-sent-data.schema.yaml
@@ -0,0 +1,13 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: ReportSent Data
+description: Data payload of the ReportSent event
+type: object
+additionalProperties: false
+properties:
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+  meshMailboxId:
+    $ref: ../defs/mesh.schema.yaml#/properties/meshMailboxId
+required:
+  - senderId
+  - meshMailboxId
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/messages.status.updated-data.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/messages.status.updated-data.v1.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/defs/core.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/defs/core.schema.yaml
@@ -0,0 +1,20 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: Request data
+description: Reusable types for NHS Notify payload schemas.
+type: object
+properties:
+  notifyId:
+    type: string
+    description: "KSUID assigned by Notify to uniquely identify the message request"
+    minLength: 27
+    maxLength: 27
+    pattern: "^[0-9a-zA-Z]{27}$"
+    examples:
+      - "35bVTLgU9sVCukH6Cgri39g5xPF"
+  failureCode:
+    type: string
+    description: "A code representing the reason for failure"
+    examples:
+      - "CM_NOT_ALLOWED"
+      - "CM_NO_SUCH_ROUTING_PLAN"
+      - "CM_DUPLICATE_REQUEST"
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/defs/mesh.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/defs/mesh.schema.yaml
@@ -0,0 +1,17 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: Request data
+description: Reusable types for NHS Notify payload schemas.
+type: object
+properties:
+  meshMessageId:
+    type: string
+    minLength: 1
+    description: Id of the message in the MESH inbox
+    examples:
+      - "20200601122152994285_D59900"
+  meshMailboxId:
+    type: string
+    minLength: 1
+    description: Id of the mailbox
+    examples:
+      - "MAILBOX01"
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/defs/reporting.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/defs/reporting.schema.yaml
@@ -0,0 +1,11 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: Request data
+description: Reusable types for NHS Notify payload schemas.
+type: object
+properties:
+  reportUri:
+    type: string
+    format: uri
+    description: Uri to the storage location of the generated status report
+    examples:
+      - "s3://my-bucket/path/to/my-report"
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.messages.request.sent.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.messages.request.sent.v1.schema.yaml
@@ -1,24 +1,23 @@
 $schema: https://json-schema.org/draft/2020-12/schema
-title: NotifyMessageRequestSentToCitizen
+title: MessageRequestFailed
 type: object
 allOf:
   - $ref: ../digital-letters-messages-profile.schema.yaml
 properties:
   type:
     type: string
     const: uk.nhs.notify.digital.letters.messages.request.sent.v1
-    description: Concrete versioned event type string for this example event (.vN suffix).
+    description: Concrete versioned event type string for this event (.vN suffix).
   source:
     type: string
     pattern: ^/nhs/england/notify/(production|staging|development|uat)/(primary|secondary|dev-[0-9]+)/data-plane/digitalletters/messages
-    description: Event source for digital letters  examples.
+    description: Event source for digital letters.
 
   dataschema:
     type: string
-    const: ../data/messages.status.updated-data.v1.schema.yaml
-    description: Canonical URI of the example event's data schema.
+    const: ../data/digital-letters-message-request-failed-data.schema.yaml
+    description: Canonical URI of the event's data schema.
     examples:
-      - messages.status.updated-data.v1.schema.yaml
+      - digital-letters-message-request-failed-data.schema.yaml
   data:
-    $ref: ../data/messages.status.updated-data.v1.schema.yaml
-    description: Example payload wrapper containing notify-payload.
+    $ref: ../data/digital-letters-message-request-failed-data.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.messages.request.submitted.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.messages.request.submitted.v1.schema.yaml
@@ -1,24 +1,23 @@
 $schema: https://json-schema.org/draft/2020-12/schema
-title: NotifyMessageRequestSubmitted
+title: MessageRequestSubmitted
 type: object
 allOf:
   - $ref: ../digital-letters-messages-profile.schema.yaml
 properties:
   type:
     type: string
     const: uk.nhs.notify.digital.letters.messages.request.submitted.v1
-    description: Concrete versioned event type string for this example event (.vN suffix).
+    description: Concrete versioned event type string for this event (.vN suffix).
   source:
     type: string
     pattern: ^/nhs/england/notify/(production|staging|development|uat)/(primary|secondary|dev-[0-9]+)/data-plane/digitalletters/messages
-    description: Event source for digital letters  examples.
+    description: Event source for digital letters.
 
   dataschema:
     type: string
-    const: ../data/messages.status.updated-data.v1.schema.yaml
-    description: Canonical URI of the example event's data schema.
+    const: ../data/digital-letters-message-request-submitted-data.schema.yaml
+    description: Canonical URI of the event's data schema.
     examples:
-      - messages.status.updated-data.v1.schema.yaml
+      - digital-letters-message-request-submitted-data.schema.yaml
   data:
-    $ref: ../data/messages.status.updated-data.v1.schema.yaml
-    description: Example payload wrapper containing notify-payload.
+    $ref: ../data/digital-letters-message-request-submitted-data.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.queue.item.dequeued.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.queue.item.dequeued.v1.schema.yaml
@@ -7,18 +7,17 @@ properties:
   type:
     type: string
     const: uk.nhs.notify.digital.letters.queue.item.dequeued.v1
-    description: Concrete versioned event type string for this example event (.vN suffix).
+    description: Concrete versioned event type string for this event (.vN suffix).
   source:
     type: string
     pattern: ^/nhs/england/notify/(production|staging|development|uat)/(primary|secondary|dev-[0-9]+)/data-plane/digitalletters/queue
-    description: Event source for digital letters  examples.
+    description: Event source for digital letters.
 
   dataschema:
     type: string
-    const: ../data/digital-letter-base-data.schema.yaml
-    description: Canonical URI of the example event's data schema.
+    const: ../data/digital-letters-queue-item-dequeued-data.schema.yaml
+    description: Canonical URI of the event's data schema.
     examples:
-      - digital-letter-base-data.schema.yaml
+      - digital-letters-queue-item-dequeued-data.schema.yaml
   data:
-    $ref: ../data/digital-letter-base-data.schema.yaml
-    description: Example payload wrapper containing notify-payload.
+    $ref: ../data/digital-letters-queue-item-dequeued-data.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.queue.item.enqueued.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.queue.item.enqueued.v1.schema.yaml
@@ -7,18 +7,17 @@ properties:
   type:
     type: string
     const: uk.nhs.notify.digital.letters.queue.item.enqueued.v1
-    description: Concrete versioned event type string for this example event (.vN suffix).
+    description: Concrete versioned event type string for this event (.vN suffix).
   source:
     type: string
     pattern: ^/nhs/england/notify/(production|staging|development|uat)/(primary|secondary|dev-[0-9]+)/data-plane/digitalletters/queue
-    description: Event source for digital letters  examples.
+    description: Event source for digital letters.
 
   dataschema:
     type: string
-    const: ../data/digital-letter-base-data.schema.yaml
-    description: Canonical URI of the example event's data schema.
+    const: ../data/digital-letters-queue-item-enqueued-data.schema.yaml
+    description: Canonical URI of the event's data schema.
     examples:
-      - digital-letter-base-data.schema.yaml
+      - digital-letters-queue-item-enqueued-data.schema.yaml
   data:
-    $ref: ../data/digital-letter-base-data.schema.yaml
-    description: Example payload wrapper containing notify-payload.
+    $ref: ../data/digital-letters-queue-item-enqueued-data.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.queue.item.removed.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.queue.item.removed.v1.schema.yaml
@@ -7,18 +7,17 @@ properties:
   type:
     type: string
     const: uk.nhs.notify.digital.letters.queue.item.removed.v1
-    description: Concrete versioned event type string for this example event (.vN suffix).
+    description: Concrete versioned event type string for this event (.vN suffix).
   source:
     type: string
     pattern: ^/nhs/england/notify/(production|staging|development|uat)/(primary|secondary|dev-[0-9]+)/data-plane/digitalletters/queue
-    description: Event source for digital letters  examples.
+    description: Event source for digital letters.
 
   dataschema:
     type: string
-    const: ../data/digital-letter-base-data.schema.yaml
-    description: Canonical URI of the example event's data schema.
+    const: ../data/digital-letters-queue-item-removed-data.schema.yaml
+    description: Canonical URI of the event's data schema.
     examples:
-      - digital-letter-base-data.schema.yaml
+      - digital-letters-queue-item-removed-data.schema.yaml
   data:
-    $ref: ../data/digital-letter-base-data.schema.yaml
-    description: Example payload wrapper containing notify-payload.
+    $ref: ../data/digital-letters-queue-item-removed-data.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.reporting.generate.report.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.reporting.generate.report.v1.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.reporting.report.generated.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.reporting.report.generated.v1.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.reporting.report.sent.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.reporting.report.sent.v1.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.reporting.report.timer.expired.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.reporting.report.timer.expired.v1.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.viewer.digital.letter.read.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.viewer.digital.letter.read.v1.schema.yaml
diff --git a/src/cloudevents/readme-index.yaml b/src/cloudevents/readme-index.yaml
