sinkCredential in response schemas contradicts Event Guide §2.2.3

[hdamker]

Problem description

Commonalities#633 ("Fix issue #619 - Simplify usage of PrivateKeyJwtCredentials for event notification", merged 2026-05-19, included in r4.3) introduces a partial-disclosure model for sinkCredential (public client-configuration fields exchanged via request and response; secret fields kept out of responses via writeOnly: true). Per the PR description, adding sinkCredential to the response shapes is part of the design, not a side effect; the same applies to the matching changes in two sample artifacts (added on review request in the PR thread).

The new model is described in §4.3.1 "Pre-requisites for using credential type PRIVATE_KEY_JWT" of the Event Subscription and Notification Guide:

This information could be shared out of band (manual exchange, contract data, via the Operate API, etc.) or as properties of sinkCredential object in subscription request/response.

The earlier (pre-#633) blanket rule in §2.2.3 "Subscriptions Data Model", sinkCredential row in the table, was not updated:

The sinkCredential MUST NOT be present in POST and GET responses.

The two statements now contradict each other inside the same document. The §2.2.3 wording predates the writeOnly-based granular model and reads as stale.

Sample artifacts changed in the same PR to align with the new §4.3.1 model:

• artifacts/api-templates/sample-service-subscriptions.yaml — added sinkCredential to the Subscription schema (POST /subscriptions 201 response, GET single, GET list).
• artifacts/api-templates/sample-implicit-events.yaml — added sinkCredential to the Resource schema (POST + GET response). The new property sits directly below the existing sink: description that reads "sinkCredential is deliberately not echoed in responses." — that description was written under the old §2.2.3 rule and is now stale too.

The contradiction was caught when the new validation framework rule check-sinkcredential-not-in-response (introduced by tooling#295) was run against the r4.3 samples in camaraproject/ReleaseTest. Commonalities CI does not run the validation framework against artifacts/api-templates/, so the contradiction surfaced only on downstream consumption.

Expected behavior

1. Align §2.2.3 with the §4.3.1 model: replace the blanket "sinkCredential MUST NOT be present in responses" rule with one that reflects the writeOnly mechanism — secret credential fields (e.g. accessToken, accessTokenType) are writeOnly and therefore excluded from responses by OAS semantics; non-secret client-configuration fields (e.g. PRIVATE_KEY_JWT's clientId, tokenUri, jwksUri) may appear in responses.
2. Update the sample-implicit-events.yaml inline description to match — the "deliberately not echoed in responses" sentence in the sink: description of the Resource schema is now incorrect.
3. Update validation framework rule check-sinkcredential-not-in-response (P-016 in tooling) to match the new contract — a separate filing in camaraproject/tooling once §2.2.3 is settled. The current rule fires on any sinkCredential property in a 2xx response schema and needs to be relaxed (or replaced with a per-field writeOnly check).

Alternative solution

If the WG decides instead that the §2.2.3 blanket prohibition was correct and §4.3.1's partial-disclosure design should be reverted: amend §4.3.1's "request/response" wording, and remove sinkCredential from the Subscription and Resource schemas in the two sample artifacts (matching the r4.2 shape). In that case the validation rule in tooling stays as-is.

Additional context

• PR that introduced the new model: Commonalities#633
• Validation framework rule: check-sinkcredential-not-in-response, metadata at validation/rules/python-rules.yaml, applicability api_pattern: [explicit-subscription].
• Until this is reconciled, the validation rule check-sinkcredential-not-in-response (P-016) will be muted in camaraproject/tooling — same interim-mute pattern used for S-314/S-316 vs Commonalities#615. The samples in camaraproject/ReleaseTest will remain as Commonalities r4.3 ships them.

[rartych]

The contradiction of the latest changes with current general rule is obvious.

The changes in artifacts use the readOnly and writeOnly keywords to block sending credentials in resposes.
readOnly properties are included in responses but not in requests, and writeOnly properties may be sent in requests but not in responses.
CAMARA_event_common.yaml #L307-L366

The simplest approach is to update the sentence describing sinkCredential in table in §2.2.3 :

The sinkCredential MUST NOT be present in POST and GET responses.

BTW, sinkCredential attributes tables §2.1 and §2.2.3 can be updated to include PRIVATE_KEY_JWT's attributes clientId, tokenUri, jwksUri