Implicit-subscription template: document unavailability signalling and clarify implementation-side opt-out

[hdamker]

Problem description

The implicit-subscription API template (sample-implicit-events.yaml lines 291-312) makes sink optional on the response Resource schema. When a consumer supplies a valid sink on the create-resource request, today's only way for an implementation to signal "I created the resource but I'm not delivering events" is to omit sink from the 200/201 response body — the resource itself is still created with success status. Two gaps follow:

1. Implementation-side opt-out is undefined. The guideline doc (§2.1, line 60) says an API project's choice to offer the implicit-subscription pattern is OPTIONAL. It does not address whether a specific implementation of an API that does offer the pattern may decline event delivery for a given request.
2. Unavailability signal is undocumented. The sink-omission convention is not written down anywhere — neither in the template nor in the guideline doc.

CAMARA-API-Design-Guide.md §3.1.3 "Recommended Modeling Pattern" already provides a fitting framework: the "Nullability/presence rules" approach lets the domain-specific outcome field (here, sink echoed in the response) carry the primary signal, with optional contextCode / contextMessage for explanation. Sink-omission is therefore design-guide-compliant Limited Success on 2xx; it just isn't tied back to §3.1.3 anywhere on the implicit-subscription side.

Possible evolution

Working group decision needed: may an implementation of an implicit-subscription-offering API decline event delivery when the consumer supplies a valid sink? If yes:

1. Document the sink-omission contract explicitly in both:
   • The template's Resource.sink description (lines 306-312) — state that sink-omission in the response when sink was supplied in the request indicates event delivery is unavailable.
   • The guideline doc (§2.1) — cross-reference §3.1.3 of the Design Guide as the rationale.
2. RECOMMEND (not mandate) the optional contextCode / contextMessage fields per Design Guide §3.1.3 to explain why event delivery is unavailable. Non-breaking for clients.

A follow-up PR can land both changes after the WG decision.

Alternative solution

Forbid implementation-side opt-out: every implementation of an API offering the implicit-subscription pattern MUST deliver events when a valid sink is supplied. Then sink becomes required in the response (when present in the request), and unavailability moves to a 4xx or 5xx error path. Cleaner contract, but a step further from current implementations.

Additional context

• Related: #589 (Business-Level Outcome 2xx vs 4xx scenarios) — the Design Guide §3.1.3 framework that this issue would consume.
• Related: #612 (the implicit-subscription template that this issue refines).
• Cross-reference filed on QualityOnDemand: QualityOnDemand#556.

[PedroDiez]

From our perspective in TEF, we consider better the alternative solution. Our rationale is the following:

• sink is optional in the response, coherently with its optionality in the request (that was the principle design when this feature was modelled)
• When sink is provided in the request by API Consumer, it implicitly means that the implicit subscription model is requested (i.e., to receive event notifications).
• Then, when the sink (i.e. implicit subscription model) is not supported by an API Provider, returning an error makes clear to API Consumer the situation and ease API Developers to manage it (e.g. for instance, to make fallback for a polling solution GET /, when defined in the API)