change metadata field to be processor only and update docs

Signed-off-by: Frank Ye <franky@spotify.com>

docs/notifications/usage.md

@@ -215,7 +215,32 @@ notificationsApi.getNotification(lastSignal.notification_id);
 
 The metadata field is a freeform object that is designed to be used by processors.
 
-For example, for a custom processor that supports markdown format the metadata field can be used to pass an optional `markdown` field.
+### Well-known Notification Metadata Fields
+
+Below are metadata fields that will be commonly used between processors and have defined schematics.
+
+#### backstage.io/body.markdown
+
+```ts
+# Example:
+const payload = {
+  title: 'Entities Require Attention',
+  description: 'Entities: Service A, Service B'
+  metadata: {
+     'backstage.io/body.markdown': `
+        # Entities
+        - Service A
+        - System B
+     `
+  }
+}
+```
+
+This value of this metadata field should be the notification message in markdown format. This allows additional formatting options for processors that support markdown.
+
+### Usage
+
+Below is an example of using the `backstage.io/body.markdown` metadata field in a custom processor.
 
 When sending a notification:
 
@@ -226,7 +251,7 @@ notificationService.send({
     title: 'Notification',
     description: 'Description'
     metadata: {
-      markdown: `
+      'backstage.io/body.markdown': `
         ### Notification
         Description
       `,
@@ -235,14 +260,18 @@ notificationService.send({
 });
 ```
 
-In your processor, you can then use the metadata field accordingly:
+In the processor, you can then use the metadata field accordingly:
 
 ```ts
 async postProcess(notification: Notification): Promise<void> {
+  // We suggest you parse the metadata field with a schema, i.e. Zod
+  const parseResult = CustomProcessorMetadataSchema.safeParse(notification.payload.metadata ?? {});
+  const metadata = parseResult.success ? parseResult.data : {};
+
   customNotificationSender.send({
     to: getUsers(notification.recipients),
     subject: notification.payload.title,
-    markdownText: notification.payload.metadata?.markdown ?? notification.payload.description,
+    markdownText: metadata['backstage.io/body.markdown'] ?? notification.payload.description,
   });
 }
 ```