Cm Subscriptions Docs

- Included documentation for an overview of Cm Data Subscription for the
  Create and Delete use case.
- Only included the json schemas for the events that are coming in and
  going out of NCMP.
- Not mentioning anything abt the internal events we use between DMIs.
- The docs can later be used to explain abt the notifications when they
  are implemented.

Issue-ID: CPS-2324
Change-Id: I2497656e0e56c93054b7e92b1742a668463c3ffc
Signed-off-by: mpriyank <priyank.maheshwari@est.tech>

4 files changed, 185 insertions, 0 deletions

diff --git a/docs/cm-notification-subscriptions.rst b/docs/cm-notification-subscriptions.rst
new file mode 100644
index 0000000000..14e871addc
--- /dev/null
+++ b/docs/cm-notification-subscriptions.rst
@@ -0,0 +1,48 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2024 Nordix Foundation
+
+.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
+.. _cmNotificationSubscriptions:
+
+
+CM Data Subscriptions
+#####################
+
+.. toctree::
+   :maxdepth: 1
+
+Introduction
+============
+CM Subscriptions are created to subscribe to notifications for CM related changes that happened in the network based on predicates.
+Predicates can be used to filter on CM Handle (id), Datastore and Xpath.
+
+The CM Subscription flow is event driven and adheres to the CNCF Cloud Events Specifications.
+
+Event to create and delete a subscription.
+
+:download:`CM Subscription Event Schema <schemas/ncmp-in-event-schema-1.0.0.json>`
+
+Event to receive status of participants in a subscription.
+
+:download:`CM Subscription Response Event Schema <schemas/ncmp-out-event-schema-1.0.0.json>`
+
+CM Subscriptions Creation
+-------------------------
+To create a subscription, a client sends an event to a configured topic to register its interest with NCMP allowing the client to receive notifications based on the subscription.
+
+CM Subscriptions Deletion
+-------------------------
+If a client no longer wishes to receive notifications based on a registered subscription, the client can delete the subscription by providing the subscription id.
+
+CM Subscriptions Response
+-------------------------
+The response for the involved subscription participants for the Create and Delete flow can be as follows based on how the DMI Plugin responds back to NCMP.
+    - **ACCEPTED:** DMI Plugin successfully applied the subscription.
+    - **REJECTED:** DMI Plugin failed to apply the subscription.
+    - **PENDING:** DMI Plugin failed to respond within a configured time.
+
+**Note.** The Cm Subscription feature relies on the DMI Plugin support for applying the subscriptions. This support is currently not implemented in the ONAP DMI Plugin.
+
+
+
diff --git a/docs/cps-events.rst b/docs/cps-events.rst
index 25a253bada..47aa73f12e 100644
--- a/docs/cps-events.rst
+++ b/docs/cps-events.rst
@@ -13,6 +13,7 @@ CPS Events
 
    cm-handle-lcm-events.rst
    data-operation-events.rst
+   cm-notification-subscriptions.rst
 
 .. note::
     Legacy async response on a client supplied topic for single cm handle data request are no longer supported. Click link below for the legacy specification.
diff --git a/docs/schemas/ncmp-in-event-schema-1.0.0.json b/docs/schemas/ncmp-in-event-schema-1.0.0.json
new file mode 100644
index 0000000000..f8b6c2e680
--- /dev/null
+++ b/docs/schemas/ncmp-in-event-schema-1.0.0.json
@@ -0,0 +1,73 @@
+{
+  "$id": "urn:cps:org.onap.cps.ncmp.events:cm-notification-subscription-ncmp-in-event:1.0.0",
+  "$ref": "#/definitions/NcmpInEvent",
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "definitions": {
+    "NcmpInEvent": {
+      "description": "The payload for subscription merge event.",
+      "javaType": "org.onap.cps.ncmp.impl.cmnotificationsubscription_1_0_0.client_to_ncmp.NcmpInEvent",
+      "properties": {
+        "data": {
+          "properties": {
+            "subscriptionId": {
+              "description": "The subscription details.",
+              "type": "string"
+            },
+            "predicates": {
+              "type": "array",
+              "description": "Additional values to be added into the subscription",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "targetFilter": {
+                    "description": "CM Handles to be targeted by the subscription",
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "scopeFilter": {
+                    "type": "object",
+                    "properties": {
+                      "datastore": {
+                        "description": "Datastore which is to be used by the subscription",
+                        "type": "string",
+                        "enum": ["ncmp-datastore:passthrough-operational", "ncmp-datastore:passthrough-running"]
+                      },
+                      "xpathFilter": {
+                        "description": "Filter to be applied to the CM Handles through this event",
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "additionalProperties": false,
+                    "required": [
+                      "xpathFilter"
+                    ]
+                  }
+                },
+                "additionalProperties": false,
+                "required": [
+                  "targetFilter"
+                ]
+              },
+              "additionalProperties": false
+            }
+          },
+          "required": [
+            "subscriptionId"
+          ],
+          "type": "object",
+          "additionalProperties": false
+        }
+      },
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "data"
+      ]
+    }
+  }
+}
\ No newline at end of file
diff --git a/docs/schemas/ncmp-out-event-schema-1.0.0.json b/docs/schemas/ncmp-out-event-schema-1.0.0.json
new file mode 100644
index 0000000000..d6ef55d063
--- /dev/null
+++ b/docs/schemas/ncmp-out-event-schema-1.0.0.json
@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "$id": "urn:cps:org.onap.cps.ncmp.events:cm-notification-subscription-ncmp-out-event-schema:1.0.0",
+  "$ref": "#/definitions/NcmpOutEvent",
+  "definitions": {
+    "NcmpOutEvent": {
+      "type": "object",
+      "description": "The payload applied cm subscription merge event coming out from NCMP.",
+      "javaType": "org.onap.cps.ncmp.impl.cmnotificationsubscription_1_0_0.ncmp_to_client.NcmpOutEvent",
+      "additionalProperties": false,
+      "properties": {
+        "data": {
+          "$ref": "#/definitions/Data"
+        }
+      },
+      "required": [
+        "data"
+      ],
+      "title": "NcmpOutEvent"
+    },
+    "Data": {
+      "type": "object",
+      "description": "Information about the targets and subscription",
+      "additionalProperties": false,
+      "properties": {
+        "subscriptionId": {
+          "type": "string",
+          "description": "The unique subscription id"
+        },
+        "acceptedTargets": {
+          "type": "array",
+          "description": "List of accepted targets",
+          "items": {
+            "type": "string"
+          }
+        },
+        "rejectedTargets": {
+          "type": "array",
+          "description": "List of rejected targets",
+          "items": {
+            "type": "string"
+          }
+        },
+        "pendingTargets": {
+          "type": "array",
+          "description": "List of pending targets",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "required": [
+        "subscriptionId",
+        "acceptedTargets",
+        "rejectedTargets",
+        "pendingTargets"
+      ],
+      "title": "Data"
+    }
+  }
+
+
+}
\ No newline at end of file