Clarify `sink` behaviour in implicit subscription model by PedroDiez · Pull Request #680 · camaraproject/Commonalities

PedroDiez · 2026-07-24T14:48:38Z

What type of PR is this?

enhancement/feature

What this PR does / why we need it:

Formalises the behaviour for sink handling in the implicit-subscription model: when a consumer provides a sink in the request, the API provider must either deliver events or reject the request with an error — silently creating the resource without notifications is no longer permitted.

Changes

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

Added a Sink delivery paragraph to §2.1 stating:
- Implementations SHOULD support event delivery when sink is provided.
- If delivery is not supported, the request MUST be rejected with 422 EVENT_NOTIFICATIONS_NOT_SUPPORTED and the resource MUST NOT be created.
- Consumers can retry without sink (e.g. fall back to polling).

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

Updated POST /resources description to document the 422 EVENT_NOTIFICATIONS_NOT_SUPPORTED error path.
Updated CreateResource.sink description to clarify that omitting sink skips notifications, and that providing an unsupported sink returns an error.
Updated Resource.sink description to reflect that sink is echoed only when delivery is accepted and active.
Added EVENT_NOTIFICATIONS_NOT_SUPPORTED to the 422 response enum and added a corresponding example with an actionable error message

Which issue(s) this PR fixes:

Fixes #628

Does this PR introduce a breaking change?

Yes
No
Not clear behaviour so far so both allowing the resorce creation without notifications delivery as well as generating an error would be acceptable
This PR unifies behaviour and introduces a new Error Code 422 EVENT_NOTIFICATIONS_NOT_SUPPORTED, so backwards compatibility is not kept

Special notes for reviewers:

Changelog input

 clarify `sink` behaviour in implicit subscription model

Additional documentation

This section can be blank.

docs

bigludo7

LGTM

rartych · 2026-07-27T11:47:03Z

Additional test case in sample-implicit-events-template.feature can be considered to check the error response when event delivery is not supported.

PedroDiez · 2026-07-27T14:31:21Z

Additional test case in sample-implicit-events-template.feature can be considered to check the error response when event delivery is not supported.

Thanks @rartych! Good point

Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com>

…uide.md Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com>

bigludo7

LGTM
Thanks @PedroDiez for the reminder

hdamker

See a few suggestions below.

Two small things in the PR description, since it feeds the release notes:

The Changes list doesn't mention the added test scenario in artifacts/testing/sample-implicit-events-template.feature.
"providing an unsupported sink returns an error" (in the CreateResource.sink bullet) sounds like the existing 400 INVALID_SINK / INVALID_PROTOCOL / INVALID_CREDENTIAL cases, which this PR doesn't change. The new code is for a different case: the provider doesn't support notification delivery at all.

On the breaking change I agree, and I think the PR should say who has to act on it. Today an implementation may accept sink, create the resource, and simply not send events; nothing forbids it. After this PR that is no longer allowed. Whether to document the new 422 is then each API's own decision: an API that wants to allow implementations without notification delivery adds it — a breaking change per §7.4 of the Design Guide, so a major version — while an API that expects every implementation to deliver events adds nothing and stays as it is (camaraproject/QualityOnDemand#556 tracks that decision for QoD). Worth saying so in §2.1, so the new text isn't read as requiring the error in every API offering the pattern.

hdamker · 2026-07-28T14:37:42Z

                status: 422
                code: PRIVATE_KEY_JWT_NOT_CONFIGURED
                message: Private key JWT credential type cannot be used because no configuration was pre-shared.
+            GENERIC_422_NOTIFICATIONS_NOT_SUPPORTED:


Example key aligned with the code:

Suggested change

GENERIC_422_NOTIFICATIONS_NOT_SUPPORTED:

GENERIC_422_EVENT_NOTIFICATIONS_NOT_SUPPORTED:

hdamker · 2026-07-28T14:41:22Z


 | 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   |


The attribute sink must be optional to not contradict the described behavior and the definition within artifacts (this inconsistency wasn't introduced by the PR, it pre-existed):

Suggested change

| 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 |

hdamker · 2026-07-28T14:45:14Z

+            Present in the response when `sink` was provided in the creation
+            request and event delivery is supported and active.


Under the new contract, if delivery isn't supported the resource is not created — so every existing resource whose creation carried sink had delivery accepted, and the guide says sink MUST be echoed.

Suggested change

Present in the response when `sink` was provided in the creation

request and event delivery is supported and active.

Present in the response whenever `sink` was provided in the creation request.

hdamker · 2026-07-28T14:49:50Z

+**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 provider instance), the request MUST be rejected with 422 EVENT_NOTIFICATIONS_NOT_SUPPORTED and the resource MUST NOT be created.


Vocabulary ... we haven't used "provider instance" yet in the document:

Suggested change

- 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 provider instance), the request MUST be rejected with 422 EVENT_NOTIFICATIONS_NOT_SUPPORTED and the resource MUST NOT be created.

- 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.

hdamker · 2026-07-28T16:47:51Z

    And the response property "$.code" is "INVALID_TOKEN" OR "INVALID_ARGUMENT"
    And the response property "$.message" contains a user friendly text
+
+  # Event notifications capability not supported scenario


The file inherits # Syntax Error scenarios from line 44, so this 422 currently sits in the syntax group. sample-service-template.feature splits the two — adding the second header keeps that structure:

Suggested change

# Event notifications capability not supported scenario

# Service Error scenarios

# Event notifications capability not supported scenario

hdamker · 2026-07-28T16:57:26Z

    And the event header "Content-Type" is set to "application/cloudevents+json"
    And the event body complies with the OAS schema at "#/components/schemas/ApiNotificationEvent"
    # Additionally any event body has to comply with some constraints beyond the schema compliance
    And the event body property "$.<property>" is ...


§2.1 now also states that sink MUST be echoed in the response when event delivery is accepted, and no scenario covers that yet — this one verifies the notification arrives, and its When acts on an already-created resource. A compact scenario for the creation response could look like:

@{feature_identifier}_{operationId}_xx_sink_echoed Scenario: Sink is returned in the creation 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"

Clarify sink behaviour in implicit subscription model

1fe7e82

PedroDiez requested review from bigludo7, eric-murray, jlurien and rartych as code owners July 24, 2026 14:48

PedroDiez self-assigned this Jul 24, 2026

PedroDiez requested a review from hdamker July 24, 2026 14:49

bigludo7 previously approved these changes Jul 24, 2026

View reviewed changes

rartych reviewed Jul 27, 2026

View reviewed changes

Comment thread artifacts/api-templates/sample-implicit-events.yaml Outdated

rartych reviewed Jul 27, 2026

View reviewed changes

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

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

4443491

Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com>

PedroDiez dismissed bigludo7’s stale review via 4443491 July 27, 2026 14:31

PedroDiez and others added 2 commits July 27, 2026 16:32

Update documentation/CAMARA-API-Event-Subscription-and-Notification-G…

92da74b

…uide.md Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com>

add_test_case_for_event_notifications_delivery_not_supported

f6ba3f5

PedroDiez requested review from bigludo7 and rartych July 27, 2026 14:46

bigludo7 approved these changes Jul 28, 2026

View reviewed changes

hdamker reviewed Jul 28, 2026

View reviewed changes

rartych mentioned this pull request Jul 28, 2026

Normalize artifact line endings and Gherkin formatting #678

Open

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Clarify `sink` behaviour in implicit subscription model - #680

Clarify `sink` behaviour in implicit subscription model#680
PedroDiez wants to merge 4 commits into
camaraproject:mainfrom
PedroDiez:clarify_sink_behaviour_in_implicit_subscription_model

PedroDiez commented Jul 24, 2026

Uh oh!

bigludo7 left a comment

Uh oh!

rartych commented Jul 27, 2026

Uh oh!

Uh oh!

Uh oh!

PedroDiez commented Jul 27, 2026

Uh oh!

bigludo7 left a comment

Uh oh!

hdamker left a comment •

edited

Loading

Uh oh!

hdamker Jul 28, 2026

Uh oh!

hdamker Jul 28, 2026

Uh oh!

hdamker Jul 28, 2026

Uh oh!

hdamker Jul 28, 2026

Uh oh!

hdamker Jul 28, 2026

Uh oh!

hdamker Jul 28, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	GENERIC_422_NOTIFICATIONS_NOT_SUPPORTED:
	GENERIC_422_EVENT_NOTIFICATIONS_NOT_SUPPORTED:


	\| 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 \|

		Present in the response when `sink` was provided in the creation
		request and event delivery is supported and active.

	Present in the response when `sink` was provided in the creation
	request and event delivery is supported and active.
	Present in the response whenever `sink` was provided in the creation request.

	- 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 provider instance), the request MUST be rejected with 422 EVENT_NOTIFICATIONS_NOT_SUPPORTED and the resource MUST NOT be created.
	- 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.

Uh oh!

Conversation

PedroDiez commented Jul 24, 2026

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Does this PR introduce a breaking change?

Special notes for reviewers:

Changelog input

Additional documentation

Uh oh!

bigludo7 left a comment

Choose a reason for hiding this comment

Uh oh!

rartych commented Jul 27, 2026

Uh oh!

Uh oh!

Uh oh!

PedroDiez commented Jul 27, 2026

Uh oh!

bigludo7 left a comment

Choose a reason for hiding this comment

Uh oh!

hdamker left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hdamker Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

hdamker Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

hdamker Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

hdamker Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

hdamker Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

hdamker Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hdamker left a comment •

edited

Loading

hdamker Jul 28, 2026 •

edited

Loading