Maintenance Iteration 18 Holistic Feedback

CDR-API-Stream commented 5 months ago

This change request has been created to simplify the raising of minor changes, such as text corrections or description clarifications, that are not really material to the standards but do have a real impact on readability and clarity.

Please raise any such suggestions that you would like included in Maintenance Iteration 18 and the DSB will review them. If a suggestion is a material change a dedicated CR will be raised.

nils-work commented 5 months ago

There is a typo in the following text in the Security Endpoints section -

Data Recipient Software Products MUST NOT reject requests including the cdr_arragement_id as a form parameter.

cdr_arragement_id should be cdr_arrangement_id

markverstege commented 4 months ago

The following Register APIs incorrectly specify a message body for 401 error responses:

Get Data Holder Brands
Get Software Statement Assertion (SSA)

The change is to remove ResponseErrorListV2 as the listed schema. These APIs conform to RFC6750 returning an oAuth error in the WWW-Authenticate response header.

nils-work commented 4 months ago

Two sentences at the start of the Participant Statuses section refer to 'Software Package'. These appear to be mistakes, and should be updated to 'Software Product' for consistency.

nils-work commented 4 months ago

The ClientRegistration schema is not referenced by any endpoints, but represents the decoded string(JWT) specified in the ClientRegistrationRequest.

To provide clarity, the ClientRegistration schema could be referenced in the description of the ClientRegistrationRequest field as follows (bold text to highlight the addition only) –

The registration request JWT to be used to register with a Data Holder. The schema of the payload section of the decoded string(JWT) is defined in ClientRegistration.

nils-work commented 4 months ago

A point under Data Holders in the Request Object section states -

Data Holders MUST require PAR for authorisation request data in accordance with [RFC9126] where "require_pushed_authorization_requests" parameter is set to "true".

while it should be clear from other statements in the Standards and the upstream spec., the last word ("true") could be changed to true to better convey that the value is expected to be a Boolean.

nils-work commented 4 months ago

The following line in the Non-normative Examples alongside HTTP Headers should be removed; it is not an Accept header like others in that block and the value appears to be mismatched with the name -

Accept-Encoding: charset=UTF-8

ACCC-CDR commented 4 months ago

Update Register API descriptions

The ACCC suggests that two Register endpoint descriptions should be updated to clarify when data holders are expected to begin appearing in responses, and what information is currently available. This is intended to address questions raised by stakeholders.

We suggest that the relevant endpoint descriptions should be updated to specify that:

Get Data Holder Brands Summary includes all data holder brands for which product reference data is available. For data holders that are active for consumer data sharing, the value disclosed is the public base uri. For brands that are not active for consumer data sharing, the value disclosed is the uri that discloses product data relevant to that brand, as provided by the relevant data holder.
Get Data Holder Brands includes all data holders that have become active for consumer data sharing and have not been archived.

We suggest that the API description in the specification be updated to ensure that users of these endpoints understand their behaviour and the differences between them.

These clarifications reflect current Register behaviour. Accordingly, we consider that this change is non-breaking change.

Area Affected

Get Data Holder Brands Endpoint Version
Get Data Holder Brands Summary Endpoint Version

Change Proposed Register APIs: To include the following information in the endpoint descriptions:

Get Data Holder Brands Summary includes all data holder brands for which product reference data is available. For data holders who are active for consumer data sharing, the value disclosed is their public base uri. For data holders who are not active for consumer data sharing, the value disclosed is the uri that discloses product data relevant to that brand.
Get Data Holder Brands includes all data holders who have become active for consumer data sharing and have not been archived.