Clarify sink behaviour in implicit subscription model

artifacts/api-templates/sample-implicit-events.yaml

@@ -114,6 +114,11 @@
         includes the `sink` (and optionally `sinkCredential`) property, the API
         provider will deliver event notifications related to this resource to
         the supplied sink for as long as the resource exists.
+
+        If `sink` is provided but the API provider does not support notification
+        delivery, the request MUST be rejected with `422 EVENT_NOTIFICATIONS_NOT_SUPPORTED`
+        and the resource MUST NOT be created. The consumer can then retry without
+        `sink` (e.g. fall back to polling via `GET /resources/{resourceId}`).
       operationId: createResource
       parameters:
         - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator"
@@ -359,6 +364,7 @@
                       - UNSUPPORTED_IDENTIFIER
                       - UNNECESSARY_IDENTIFIER
                       - PRIVATE_KEY_JWT_NOT_CONFIGURED
+                      - EVENT_NOTIFICATIONS_NOT_SUPPORTED
           examples:
             GENERIC_422_SERVICE_NOT_APPLICABLE:
               $ref: "../common/CAMARA_common.yaml#/components/examples/GENERIC_422_SERVICE_NOT_APPLICABLE"
@@ -370,6 +376,8 @@
               $ref: "../common/CAMARA_common.yaml#/components/examples/GENERIC_422_UNNECESSARY_IDENTIFIER_DEVICE"
             GENERIC_422_PRIVATE_KEY_JWT_NOT_CONFIGURED:
               $ref: "../common/CAMARA_event_common.yaml#/components/examples/GENERIC_422_PRIVATE_KEY_JWT_NOT_CONFIGURED"
+            GENERIC_422_EVENT_NOTIFICATIONS_NOT_SUPPORTED:
+              $ref: "../common/CAMARA_event_common.yaml#/components/examples/GENERIC_422_EVENT_NOTIFICATIONS_NOT_SUPPORTED"
 
   schemas:
 
@@ -397,10 +405,10 @@
       required:
         - name
       properties:
         name:
           type: string
           maxLength: 128
           description: Human-readable name for the resource
         device:
           $ref: "../common/CAMARA_common.yaml#/components/schemas/Device"
         sink:
@@ -408,6 +416,11 @@
             The HTTPS URL where event notifications for this resource will be
             delivered. Omit this field (and `sinkCredential`) to create the
             resource without event notifications.
+
+            If provided, the API provider SHOULD support event delivery. If
+            notification delivery is not supported, the request MUST be rejected
+            with `422 EVENT_NOTIFICATIONS_NOT_SUPPORTED` and the resource MUST NOT
+            be created.
           allOf:
             - $ref: "../common/CAMARA_event_common.yaml#/components/schemas/Sink"
         sinkCredential:
@@ -422,15 +435,16 @@
       properties:
         resourceId:
           $ref: "#/components/schemas/ResourceId"
         name:
           type: string
           maxLength: 128
           description: Human-readable name for the resource
         device:
           $ref: "../common/CAMARA_common.yaml#/components/schemas/Device"
         sink:
           description: |
             The sink URL registered for notifications on this resource, if any.
+            Present in the response whenever `sink` was provided in the creation request.
             `sinkCredential` may be returned in responses, but limited to non-secret metadata only (e.g., `credentialType`).
           allOf:
             - $ref: "../common/CAMARA_event_common.yaml#/components/schemas/Sink"

artifacts/common/CAMARA_event_common.yaml

@@ -49,19 +49,19 @@
         - type
         - time
       properties:
         id:
           type: string
           maxLength: 256
           description: Identifier of this event, unique within the source context.
         source:
           $ref: "#/components/schemas/Source"
         type:
           type: string
           maxLength: 512
           description: |
             Identifies the event type. CAMARA APIs use reverse-DNS notation:
             `org.camaraproject.<api-name>.<event-version>.<event-name>`
             The api-name segment makes each type globally unique across API groups.
         specversion:
           type: string
           description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version)
@@ -856,3 +856,13 @@
         status: 422
         code: PRIVATE_KEY_JWT_NOT_CONFIGURED
         message: No JWK Set configured for PRIVATE_KEY_JWT authentication.
+    # Responses: Local CreateResourceUnprocessableEntity422 in APIs that define it (reference sample-implicit-events.yaml)
+    # Examples: the generic 422 examples (CAMARA_common.yaml) plus
+    #   GENERIC_422_PRIVATE_KEY_JWT_NOT_CONFIGURED (aforementioned defined),
+    #   GENERIC_422_EVENT_NOTIFICATIONS_NOT_SUPPORTED
+    GENERIC_422_EVENT_NOTIFICATIONS_NOT_SUPPORTED:
+      description: The API provider does not support event notification delivery for this resource
+      value:
+        status: 422
+        code: EVENT_NOTIFICATIONS_NOT_SUPPORTED
+        message: Notification delivery is not supported by this API provider. Retry the request without the sink field.

artifacts/testing/sample-implicit-events-template.feature

@@ -25,6 +25,14 @@ Feature: CAMARA Template Artifact - Test scenarios for sample-implicit-events.ya
 
 ############################ Happy Path Scenarios #############################################
 
+  # Test applicable for the related createResource operationId
+  @{feature_identifier}_{operationId}_xx_sink_echoed
+  Scenario: Sink is returned in the creation "<Resource>" response when event delivery is accepted
+    Given the request body includes property "$.sink" with a valid value
+    When the request "{operationId}" is sent
+    Then the response status code is 2<xx>
+    And the response property "$.sink" has same value as the request body property "$.sink"
+
   # Replace ... in the lastest sentence by any type of applicable validation for the property
   @{feature_identifier}_{operationId}_xx_event_notification
   Scenario: Event is received if the sink was provided and "<Resource>" lifecycle faces an update
@@ -71,3 +79,19 @@ Feature: CAMARA Template Artifact - Test scenarios for sample-implicit-events.ya
     And the response property "$.status" is 400
     And the response property "$.code" is "INVALID_TOKEN" OR "INVALID_ARGUMENT"
     And the response property "$.message" contains a user friendly text
+
+  # Service Error scenarios
+
+  # Event notifications capability not supported scenario
+  # Only applicable if the API defines the error 422 EVENT_NOTIFICATIONS_NOT_SUPPORTED
+  @{feature_identifier}_{operationId}_422.01_event_notifications_not_supported
+  Scenario: Event notifications capability not supported
+    Given the request body includes property "$.sink" with a valid value
+    And the API provider does not implement event notifications delivery for the operation "{operationId}"
+    When the request "{operationId}" is sent
+    Then the response status code is 422
+    And the response header "x-correlator" has same value as the request header "x-correlator"
+    And the response header "Content-Type" is "application/json"
+    And the response property "$.status" is 422
+    And the response property "$.code" is "EVENT_NOTIFICATIONS_NOT_SUPPORTED"
+    And the response property "$.message" contains a user friendly text

documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md

@@ -59,13 +59,15 @@ The subscription terminates with the managed entity.
 
 Providing this capability is OPTIONAL for any CAMARA API depending on UC requirements.
 
-If this capability is present in CAMARA API, the following attributes MUST be used in the POST request :
+If this capability is present in CAMARA API, the following attribute names MUST be used in the POST request:
 
 | attribute name | type   | attribute description                                                                                                                                                                                                                                                                                       | cardinality |
 |----------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
-| sink           | string | https callback address where the notification must be POST-ed, `format: uri` SHOULD be used to require a string that is compliant with [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986).  The [security considerations](#43-notifications-security-considerations) SHOULD be followed.                | mandatory   |
+| sink           | string | https callback address where the notification must be POST-ed, `format: uri` SHOULD be used to require a string that is compliant with [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986).  The [security considerations](#43-notifications-security-considerations) SHOULD be followed.                | optional   |
 | sinkCredential | object | Sink credential provides authentication or authorization information necessary to enable delivery of events to a target. In order to be updated in future this object is polymorphic. See detail below. It is RECOMMENDED for subscription consumer to provide credential to protect notification endpoint. | optional    |
 
+**NOTE**: To request the Implicit Subscription mode, `sink` attribute MUST be provided within the API request body.
+
 Several types of `sinkCredential` could be available in the future, but for now only access token and private key JWT credentials are managed.
 
 ``sinkCredential`` attributes table:
@@ -80,6 +82,20 @@ Several types of `sinkCredential` could be available in the future, but for now
 | tokenUri             | string           | The URI where to request an access token using `PRIVATE_KEY_JWT`. Applicable for `PRIVATE_KEY_JWT` credentialType. Optional in the request. Not returned in the response  | optional    |
 | jwksUri              | string           | The URI used to request the public key to verify that the JWT assertion was signed by `PRIVATE_KEY_JWT`. Applicable for `PRIVATE_KEY_JWT` credentialType. Not needed in the request. Optional in the response  | optional    |
 
+**Sink delivery behaviour**
+
+When `sink` is provided in the POST request, the following rules apply:
+- API providers SHOULD implement event delivery support. If a request includes `sink` and the API provider does not support notification delivery (i.e. the implicit subscription feature is not implemented by this API provider), the request MUST be rejected with 422 EVENT_NOTIFICATIONS_NOT_SUPPORTED and the resource MUST NOT be created.
+- When event delivery is accepted, `sink` MUST be echoed in the response.
+- The implementation MUST NOT silently create the resource while ignoring the requested `sink`. If event delivery is unavailable, the consumer MUST be informed via the error response, so they can retry without `sink` (e.g. fall back to a polling pattern via `GET /<resource>`).
+
+These rules apply to CAMARA APIs targeting Commonalities r4.4 and later. APIs targeting earlier Commonalities versions are unaffected.
+
+- An API newly adopting the implicit subscription model MUST follow the behaviour described above.
+- For an API that already offers the implicit subscription model, whether to document `422 EVENT_NOTIFICATIONS_NOT_SUPPORTED` is that API's own decision:
+  - An API that allows implementations without notification delivery adds the error code to its API definition. This is a breaking change per [Section 7.4. Backward and Forward Compatibility](/documentation/CAMARA-API-Design-Guide.md#74-backward-and-forward-compatibility) of the CAMARA API Design Guide, so a new major version is required.
+  - An API that expects every implementation to deliver event notifications adds nothing and stays as it is. Implementations of such an API MUST deliver event notifications when `sink` is provided.
+
 A sample OpenAPI template for the implicit-subscription pattern is available in [Commonalities/artifacts/api-templates](/artifacts/api-templates/) directory (`sample-implicit-events.yaml`), with common event schemas in [Commonalities/artifacts/common](/artifacts/common/) (`CAMARA_event_common.yaml`).
 
 #### 2.1.1. Instance-based (Implicit) Subscription Example