From 36d220c27643abd9431aef3ddd41b0a658d730b1 Mon Sep 17 00:00:00 2001 From: Ivan Hosgood Date: Mon, 16 May 2022 16:00:22 +1000 Subject: [PATCH 01/13] Added requirement for data holders to ignore unsupported authorisation scopes --- slate/source/includes/introduction/_fdo.md | 5 +++++ .../includes/releasenotes/releasenotes.1.17.0.html.md | 1 + slate/source/includes/security/_client_registration.md.erb | 6 ++++++ 3 files changed, 12 insertions(+) diff --git a/slate/source/includes/introduction/_fdo.md b/slate/source/includes/introduction/_fdo.md index c1926f3f..87c794ef 100644 --- a/slate/source/includes/introduction/_fdo.md +++ b/slate/source/includes/introduction/_fdo.md @@ -1,5 +1,9 @@ ## Future Dated Obligations +```diff ++ Added Registration Validation obligation for November 15th 2022 +``` + The standards, as published from time to time, may include specific statements indicating that a specific section of the standards will not take effect until a future date or may cease to have effect on some future date. The table below highlights these areas of the standards. @@ -32,6 +36,7 @@ The table below highlights these areas of the standards. |[Information Security profile](#security-profile) | FAPI 1.0 adoption is introduced across three phases.
Phase 2: FAPI 1.0 Final (Baseline & Advanced) includes, amongst other changes: | September 16th 2022 | |[Get Metrics V3](#get-metrics)|Version 3 of this end point must be made available by affected data holders by October 1st 2022|October 1st 2022| |[Standard Error Codes](#error-codes) | Data Holders MAY retire application-specific error codes in favour of standard error codes from November 1st 2022 | November 1st 2022 | +|[Registration Validation](#registration-validation) | Data Holders **MUST** ignore unsupported authorisation scopes presented in the SSA for the creation and update of client registrations from November 15th 2022 | November 15th 2022 | |[Get Account Detail V2](#get-account-detail)|Version 2 of this end point must be made available by affected data holders by November 30th 2022|November 30th 2022| |[Get Customer Detail V2](#get-customer-detail)|Version 2 of this end point must be made available by affected data holders by November 30th 2022|November 30th 2022| |[Get Product Detail V4](#get-product-detail)|Version 4 of this end point must be made available by affected data holders by November 30th 2022|November 30th 2022| diff --git a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md index 228feba0..49b6b700 100644 --- a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md +++ b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md @@ -52,6 +52,7 @@ This release addresses the following Decision Proposals published on [Standards] | CDR Arrangement Revocation End Point | [Standards Maintenance Issue 503](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/503): Corrected the documentation to include CDR Arrangement Form Parameter and CDR Arrangement JWT methods. Previous versions did not include this documentation correctly. | [CDR Arrangement Revocation End Point](../../#cdr-arrangement-revocation-end-point) | Self-signed JWT Client Authentication non-normative example | [**Standards Maintenance #482**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/482): Updated self-signed JWT client authentication non-normative example `alg` field from HS256 to PS256 | [Client Authentication](../../index.html#client-authentication) | | CDR Arrangement Revocation End Point non-normative example | [**Standards Maintenance #482**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/482): Updated data recipient hosted CDR Arrangement Revocation End Point non-normative example `alg` field from HS256 to PS256 | [Security Endpoints](../../index.html#security-endpoints) | +| Registration Validation | [**Standards Maintenance #488**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/488): Added requirement for data holders to ignore unsupported authorisation scopes | [Registration Validation](../../index.html#registration-validation) | ## Consumer Experience diff --git a/slate/source/includes/security/_client_registration.md.erb b/slate/source/includes/security/_client_registration.md.erb index f05aa7d1..6499908b 100644 --- a/slate/source/includes/security/_client_registration.md.erb +++ b/slate/source/includes/security/_client_registration.md.erb @@ -214,6 +214,11 @@ Participants **MUST** support, at a minimum, the following ID Token algorithms: ### Registration Validation + +```diff ++ Added requirement for data holders to ignore unsupported authorisation scopes +``` + Validation and use of the JWT and the claims described above **MUST** be performed in accordance with **[[JWT]](#nref-JWT)**. SSA JWT signatures **MUST** be verified against the associated JWK published at the CDR Register [JWKS endpoint](#get-jwks). @@ -222,6 +227,7 @@ The registration request JWT **MUST** be verified against the associated JWK pub Data Holders **MUST NOT** allow multiple active registrations for the same `software_id`. +Data Holders **MUST** ignore unsupported authorisation scopes presented in the SSA for the creation and update of client registrations. Data Holders **MUST** adhere to the [NFR performance requirements](#performance-requirements) when validating and responding to registration requests. Additional validation processes (such as outbound white-listing of data recipient endpoints) **MUST NOT** prevent specified response times being met. From 36109a1530066d3bd0d3e3236284d3f4181064fe Mon Sep 17 00:00:00 2001 From: Hemang Rathod Date: Mon, 16 May 2022 17:04:20 +1000 Subject: [PATCH 02/13] Standards Maintenance Issue #476: Updated EnergyConcession model to cater for variable concessions. Changed RateString to represent generic percentages. --- slate/source/includes/_energy_apis.md.erb | 12 +++++ slate/source/includes/_standards.md.erb | 4 ++ .../releasenotes/releasenotes.1.17.0.html.md | 2 + slate/source/includes/standards/_types.md | 2 +- swagger-gen/api/cds_energy.json | 52 +++++++++++++------ 5 files changed, 54 insertions(+), 18 deletions(-) diff --git a/slate/source/includes/_energy_apis.md.erb b/slate/source/includes/_energy_apis.md.erb index 8bf96594..53403117 100644 --- a/slate/source/includes/_energy_apis.md.erb +++ b/slate/source/includes/_energy_apis.md.erb @@ -17,6 +17,18 @@ The following objects were added to EnergyBillingOtherTransaction model + adjustments The `EnergyServicePointDetail.meters.registers.registerSuffix` field has been made optional + +The following changes were made to EnergyConcession model +* Made additionalInfo field conditional ++ type ++ discountFrequency ++ amount ++ percentage ++ appliedTo +- dailyDiscount +- monthlyDiscount +- yearlyDiscount +- percentageDiscount ``` <%= partial "includes/cds_energy.md" %> diff --git a/slate/source/includes/_standards.md.erb b/slate/source/includes/_standards.md.erb index 05d254d1..9039d411 100644 --- a/slate/source/includes/_standards.md.erb +++ b/slate/source/includes/_standards.md.erb @@ -2,6 +2,10 @@ This section contains components of the standards that are foundational and generally applicable. +```diff +Changed RateString type to represent generic percentages +``` + <%= partial "includes/standards/principles.md" %> <%= partial "includes/standards/versioning.md" %> <%= partial "includes/standards/uri.md" %> diff --git a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md index 228feba0..e005759e 100644 --- a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md +++ b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md @@ -22,6 +22,7 @@ This release addresses the following change requests raised on [Standards Mainte - [Standards Maintenance Issue 438: Representing adjustment transactions within the Billing Payload for C&I customers](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/438) - [Standards Maintenance Issue 457: Energy - Get Service Point Detail register suffix should be optional](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/457) - [Standards Maintenance Issue 482: JWT signing non-normative examples use unsupported signing algorithm)](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/482) +- [Standards Maintenance Issue 476: Modify Energy concessions structure to allow non-fixed (e.g. daily, monthly etc.) concessions](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/476) ### Decision Proposals @@ -44,6 +45,7 @@ This release addresses the following Decision Proposals published on [Standards] |Change|Description|Link| |------|-----------|----| | Energy schema | [**Standards Maintenance #457**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/457) Made EnergyServicePointDetail.meters.registers.registerSuffix field optional | [Energy Schema](../../#energy-apis) | +| Energy schema | [**Standards Maintenance #476**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/476) | [Energy Schema](../../#energy-apis) | ## Information Security Profile diff --git a/slate/source/includes/standards/_types.md b/slate/source/includes/standards/_types.md index ce9fcd77..eb5c3227 100644 --- a/slate/source/includes/standards/_types.md +++ b/slate/source/includes/standards/_types.md @@ -18,7 +18,7 @@ DateTimeString | Combined Date and Time string as per **[[RFC3339]](#nref-RFC333 DateString | Date string as per **[[RFC3339]](#nref-RFC3339)** (labelled full-date in the RFC) | “2007-05-01”
“2012-12-25” TimeString | Time string as per **[[RFC3339]](#nref-RFC3339)** (labelled full-time in the RFC). As specified in **[[RFC3339]](#nref-RFC3339)** times should be offset relative to UTC | “15:43:00.12345Z”
“15:43:00-12:00” CurrencyString | Standard 3 character currency codes as per ISO-4217 | “AUD”
“USD”
“GBP” -RateString | A string representing an interest rate. A rate of 100% would be represented by the value 1.0 and a rate of -100% by -1.0
- At least 1 and up to a total of 16 significant digits before decimal point
- Up to 16 digits following the decimal point
- No formatting, eg thousand separating commas | “0.05”
“-0.05”
“12.3456789”
“-99.123456789123” +RateString | A string representing a percentage (e.g. an interest rate). A rate of 100% would be represented by the value 1.0 and a rate of -100% by -1.0
- At least 1 and up to a total of 16 significant digits before decimal point
- Up to 16 digits following the decimal point
- No formatting, eg thousand separating commas | “0.05”
“-0.05”
“12.3456789”
“-99.123456789123” AmountString | A string representing an amount of currency.
- A positive, zero or negative number
- Negative numbers identified with a ‘-‘
- No currency symbols should be supplied
- At least 1 and up to a total of 16 significant digits before decimal point
- Minimum 2 digits following a decimal point (more digits allowable but only if required)
- No additional formatting, eg thousand separating commas | “0.01”
“10.00”
“1234567.89”
“-1001.23”
“1.999” MaskedPANString | Masked credit card number. Lower case ‘x’ should be used to mask numbers and only the last four digits should be exposed to facilitate identification. This type is expected to be used for display so the format should be logical for this context | "xxxx xxxx xxxx 1234" MaskedAccountString | Masked bank account number genericised for a variety of account types. Should be represented as the full account number would normally be represented for display (including formatting) but with all digits except the last four replaced with a lowercase x. This type is expected to be used for display so the format should be logical for this context | "xxxx xxxx xxxx 1234"
"xxx-xxx xxxxx1234" diff --git a/swagger-gen/api/cds_energy.json b/swagger-gen/api/cds_energy.json index b084c684..bf1ba347 100644 --- a/swagger-gen/api/cds_energy.json +++ b/swagger-gen/api/cds_energy.json @@ -2830,21 +2830,31 @@ "EnergyConcession": { "type": "object", "required": [ + "type", "displayName" ], "x-conditional": [ - "dailyDiscount", - "monthlyDiscount", - "yearlyDiscount", - "percentageDiscount" + "additionalInfo", + "discountFrequency", + "amount", + "percentage" ], "properties": { + "type": { + "description": "Indicator of the method of concession calculation", + "type": "string", + "enum": [ + "FIXED_AMOUNT", + "FIXED_PERCENTAGE", + "VARIABLE" + ] + }, "displayName": { "description": "The display name of the concession", "type": "string" }, "additionalInfo": { - "description": "Display text providing more information on the concession", + "description": "Display text providing more information on the concession. Mandatory if type is VARIABLE", "type": "string" }, "additionalInfoUri": { @@ -2862,25 +2872,33 @@ "type": "string", "x-cds-type": "DateString" }, - "dailyDiscount": { - "description": "Daily discount value due to the concession. At least one dailyDiscount, monthlyDiscount, yearlyDiscount and percentageDiscount must be provided", + "discountFrequency": { + "description": "Conditional attribute for frequency at which a concession is applied. Required if type is FIXED_AMOUNT or FIXED_PERCENTAGE. Formatted according to [ISO 8601 Durations](https://en.wikipedia.org/wiki/ISO_8601#Durations) (excludes recurrence syntax)", "type": "string", - "x-cds-type": "AmountString" + "x-cds-type": "ExternalRef" }, - "monthlyDiscount": { - "description": "Monthly discount value due to the concession. At least one dailyDiscount, monthlyDiscount, yearlyDiscount and percentageDiscount must be provided", - "type": "string", - "x-cds-type": "AmountString" - }, - "yearlyDiscount": { - "description": "Annual discount value due to the concession. At least one dailyDiscount, monthlyDiscount, yearlyDiscount and percentageDiscount must be provided", + "amount": { + "description": "Conditional attribute for the amount of discount for the concession- required if type is FIXED_AMOUNT", "type": "string", "x-cds-type": "AmountString" }, - "percentageDiscount": { - "description": "Percentage of each invoice to be discounted due to the concession. At least one dailyDiscount, monthlyDiscount, yearlyDiscount and percentageDiscount must be provided", + "percentage": { + "description": "Conditional attribute for the percentage of discount of concession - required if type is FIXED_PERCENTAGE", "type": "string", "x-cds-type": "RateString" + }, + "appliedTo": { + "description": "Array of ENUM's to specify what the concession applies to. Multiple ENUM values can be provided. If absent, USAGE is assumed", + "type": "array", + "items": { + "type": "string", + "enum": [ + "INVOICE", + "USAGE", + "SERVICE_CHARGE", + "CONTROLLED_LOAD" + ] + } } } }, From b8810b4e243b162989792c7988938f44a6e03622 Mon Sep 17 00:00:00 2001 From: Hemang Rathod Date: Mon, 16 May 2022 17:25:20 +1000 Subject: [PATCH 03/13] Standards Maintenance Issue #476: Moved RateString change description to High Level Standards in Release Notes. Move RateString diff in High Level Standards --- slate/source/includes/releasenotes/releasenotes.1.17.0.html.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md index e005759e..fa9ce398 100644 --- a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md +++ b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md @@ -39,13 +39,14 @@ This release addresses the following Decision Proposals published on [Standards] | Obligation date highlighting | Highlighting based on a date pickers has been added for the Endpoint versioning schedule to enhance documentation functionality. This feature allows users to select a target date and determine what obligations apply at that date. | [Endpoint versioning schedule](../../includes/endpoint-version-schedule/) | Obligation Dates Table | A series of fixed obligation milestones were agreed in Maintenance Iteration 10. This set of milestones will be used to pin breaking changes to a deterministic series of possible obligation dates. | [Obligation Dates]() | | Scrollable diffs and examples | Added previous and next buttons to support easy scrolling between all diffs and non-normative examples. This feature is context dependent on the tab being viewed | N/A | +| RateString description | [**Standards Maintenance #476**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/476): Changed RateString type to represent generic percentages. | [Common Field Types](../../#common-field-types) ## API End Points |Change|Description|Link| |------|-----------|----| | Energy schema | [**Standards Maintenance #457**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/457) Made EnergyServicePointDetail.meters.registers.registerSuffix field optional | [Energy Schema](../../#energy-apis) | -| Energy schema | [**Standards Maintenance #476**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/476)
  • Updated EnergyConcession model to allow representation of concessions that are calculated based on variable parameters.
  • Changed RateString type to represent generic percentages.
| [Energy Schema](../../#energy-apis) | +| Energy schema | [**Standards Maintenance #476**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/476): Updated EnergyConcession model to allow representation of concessions that are calculated based on variable parameters | [Energy Schema](../../#energy-apis) | ## Information Security Profile From d19351773bf7f640659841c953ad98954bac3b66 Mon Sep 17 00:00:00 2001 From: Hemang Rathod Date: Mon, 16 May 2022 17:30:49 +1000 Subject: [PATCH 04/13] Moved change description to API Endpoints sections in Release Notes --- slate/source/includes/releasenotes/releasenotes.1.17.0.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md index 228feba0..0a0605b1 100644 --- a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md +++ b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md @@ -34,7 +34,6 @@ This release addresses the following Decision Proposals published on [Standards] |Change|Description|Link| |------|-----------|----| -| Energy schema | [**Standards Maintenance #438**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/438) Added 'calculationFactors' and 'adjustments' objects to ['EnergyBillingOtherTransaction'](../../#tocSenergybillingothertransaction) model to allow consistent representation of any calculation factors (i.e. DLF or MLF) used for deriving other charges and any adjustments arising from other types of charges such as environmental charge. | [Energy Schema](../../#energy-apis) | | Obligation date highlighting | Highlighting based on a date pickers has been added for the Endpoint versioning schedule to enhance documentation functionality. This feature allows users to select a target date and determine what obligations apply at that date. | [Endpoint versioning schedule](../../includes/endpoint-version-schedule/) | Obligation Dates Table | A series of fixed obligation milestones were agreed in Maintenance Iteration 10. This set of milestones will be used to pin breaking changes to a deterministic series of possible obligation dates. | [Obligation Dates]() | | Scrollable diffs and examples | Added previous and next buttons to support easy scrolling between all diffs and non-normative examples. This feature is context dependent on the tab being viewed | N/A | @@ -43,6 +42,7 @@ This release addresses the following Decision Proposals published on [Standards] |Change|Description|Link| |------|-----------|----| +| Energy schema | [**Standards Maintenance #438**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/438): Added 'calculationFactors' and 'adjustments' objects to ['EnergyBillingOtherTransaction'](../../#tocSenergybillingothertransaction) model to allow consistent representation of any calculation factors (i.e. DLF or MLF) used for deriving other charges and any adjustments arising from other types of charges such as environmental charge. | [Energy Schema](../../#energy-apis) | | Energy schema | [**Standards Maintenance #457**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/457) Made EnergyServicePointDetail.meters.registers.registerSuffix field optional | [Energy Schema](../../#energy-apis) | ## Information Security Profile From 5714c51e63bee9ee00a274b840c780e5f6c7efe9 Mon Sep 17 00:00:00 2001 From: Ivan Hosgood Date: Tue, 17 May 2022 11:15:21 +1000 Subject: [PATCH 05/13] Set retirement dates for outstanding deprecated Register APIs --- .../includes/_register.md | 25 ++++++++----------- .../releasenotes/releasenotes.1.17.0.html.md | 2 ++ 2 files changed, 13 insertions(+), 14 deletions(-) diff --git a/slate/source/includes/endpoint-version-schedule/includes/_register.md b/slate/source/includes/endpoint-version-schedule/includes/_register.md index 2d0ffc39..28f8a2cb 100644 --- a/slate/source/includes/endpoint-version-schedule/includes/_register.md +++ b/slate/source/includes/endpoint-version-schedule/includes/_register.md @@ -9,20 +9,17 @@ |----------------------|-------------------------------------------|----------------------------------------------------------|--------|---------|----------------|-----------------|--------------------|---------------------| | CDR Register APIs | Get OpenId Provider Config | ``/.well-known/openid-configuration`` | GET | None | 2021-10-29† | N/A | 2021-10-29, V1.14.0† | N/A | | CDR Register APIs | Get JWKS | ``/jwks`` | GET | None | 2021-10-29† | N/A | 2021-10-29, V1.14.0† | N/A | -| CDR Register APIs | Get Data Holder Brands | ``/{industry}/data-holders/brands`` | GET | V1 | 2021-10-29† | N/A | 2021-10-29, V1.14.0† | 2021-12-23, V1.15.0 | -| CDR Register APIs | Get Data Holder Brands | ``/{industry}/data-holders/brands`` | GET | V2 | 2022-08-30‡ | N/A | 2021-12-23, V1.15.0* | N/A | -| CDR Register APIs | Get Software Statement Assertion (SSA) | ``/{industry}/data-recipients/``
``brands/{dataRecipientBrandId}/``
``software-products/{softwareProductId}/ssa`` | GET | V2 | 2021-10-29† | N/A | 2021-10-29, V1.14.0† | 2021-12-23, V1.15.0 | -| CDR Register APIs | Get Software Statement Assertion (SSA) | ``/{industry}/data-recipients/``
``brands/{dataRecipientBrandId}/``
``software-products/{softwareProductId}/ssa`` | GET | V3 | 2022-08-30‡ | N/A | 2021-12-23, V1.15.0 | N/A | -| CDR Register APIs | Get Software Products Statuses | ``/{industry}/data-recipients/``
``brands/software-products/status`` | GET | V1 | 2021-10-29† | N/A | 2021-10-29, V1.14.0† | 2021-12-23, V1.15.0 | -| CDR Register APIs | Get Software Products Statuses | ``/{industry}/data-recipients/``
``brands/software-products/status`` | GET | V2 | 2022-08-30‡ | N/A | 2021-12-23, V1.15.0 | N/A | -| CDR Register APIs | Get Data Recipient Statuses | ``/{industry}/data-recipients/status`` | GET | V1 | 2021-10-29† | N/A | 2021-10-29, V1.14.0† | 2021-12-23, V1.15.0 | -| CDR Register APIs | Get Data Recipient Statuses | ``/{industry}/data-recipients/status`` | GET | V2 | 2022-08-30‡ | N/A | 2021-12-23, V1.15.0 | N/A | -| CDR Register APIs | Get Data Recipients | ``/{industry}/data-recipients`` | GET | V2 | 2021-10-29† | N/A | 2021-10-29, V1.14.0† | 2021-12-23, V1.15.0 | -| CDR Register APIs | Get Data Recipients | ``/{industry}/data-recipients`` | GET | V3 | 2022-08-30‡ | N/A | 2021-12-23, V1.15.0 | N/A | -| CDR Register APIs | Get Data Holder Statuses | ``/{industry}/data-holders/status`` | GET | V1 | 2022-08-30‡ | N/A | 2021-12-23, V1.15.0 | N/A | +| CDR Register APIs | Get Data Holder Brands | ``/{industry}/data-holders/brands`` | GET | V1 | 2021-10-29† | 2023-04-07 | 2021-10-29, V1.14.0† | 2021-12-23, V1.15.0 | +| CDR Register APIs | Get Data Holder Brands | ``/{industry}/data-holders/brands`` | GET | V2 | 2022-11-15 | N/A | 2021-12-23, V1.15.0* | N/A | +| CDR Register APIs | Get Software Statement Assertion (SSA) | ``/{industry}/data-recipients/``
``brands/{dataRecipientBrandId}/``
``software-products/{softwareProductId}/ssa`` | GET | V2 | 2021-10-29† | 2023-04-07 | 2021-10-29, V1.14.0† | 2021-12-23, V1.15.0 | +| CDR Register APIs | Get Software Statement Assertion (SSA) | ``/{industry}/data-recipients/``
``brands/{dataRecipientBrandId}/``
``software-products/{softwareProductId}/ssa`` | GET | V3 | 2022-11-15 | N/A | 2021-12-23, V1.15.0 | N/A | +| CDR Register APIs | Get Software Products Statuses | ``/{industry}/data-recipients/``
``brands/software-products/status`` | GET | V1 | 2021-10-29† | 2023-04-07 | 2021-10-29, V1.14.0† | 2021-12-23, V1.15.0 | +| CDR Register APIs | Get Software Products Statuses | ``/{industry}/data-recipients/``
``brands/software-products/status`` | GET | V2 | 2022-11-15 | N/A | 2021-12-23, V1.15.0 | N/A | +| CDR Register APIs | Get Data Recipient Statuses | ``/{industry}/data-recipients/status`` | GET | V1 | 2021-10-29† | 2023-04-07 | 2021-10-29, V1.14.0† | 2021-12-23, V1.15.0 | +| CDR Register APIs | Get Data Recipient Statuses | ``/{industry}/data-recipients/status`` | GET | V2 | 2022-11-15 | N/A | 2021-12-23, V1.15.0 | N/A | +| CDR Register APIs | Get Data Recipients | ``/{industry}/data-recipients`` | GET | V2 | 2021-10-29† | 2023-04-07 | 2021-10-29, V1.14.0† | 2021-12-23, V1.15.0 | +| CDR Register APIs | Get Data Recipients | ``/{industry}/data-recipients`` | GET | V3 | 2022-11-15 | N/A | 2021-12-23, V1.15.0 | N/A | +| CDR Register APIs | Get Data Holder Statuses | ``/{industry}/data-holders/status`` | GET | V1 | 2022-11-15 | N/A | 2021-12-23, V1.15.0 | N/A | **†NOTE:** The CDR Register standards were introduced into the Consumer Data Standards in v1.14.0. Prior to this the CDR Register specifications were hosted by the ACCC. -**‡NOTE:** This date has been defined to give certainty to Data Recipient and Data Holder participants but it is yet to be confirmed by the ACCC. - -**\*NOTE:** Data Holder Brands V2 definition is still subject to change diff --git a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md index 228feba0..ce296e91 100644 --- a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md +++ b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md @@ -22,6 +22,7 @@ This release addresses the following change requests raised on [Standards Mainte - [Standards Maintenance Issue 438: Representing adjustment transactions within the Billing Payload for C&I customers](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/438) - [Standards Maintenance Issue 457: Energy - Get Service Point Detail register suffix should be optional](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/457) - [Standards Maintenance Issue 482: JWT signing non-normative examples use unsupported signing algorithm)](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/482) +- [Standards Maintenance Issue 452: Deprecation and retirement dates for CDR Register superseded endpoint versions needs to be defined](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/452) ### Decision Proposals @@ -44,6 +45,7 @@ This release addresses the following Decision Proposals published on [Standards] |Change|Description|Link| |------|-----------|----| | Energy schema | [**Standards Maintenance #457**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/457) Made EnergyServicePointDetail.meters.registers.registerSuffix field optional | [Energy Schema](../../#energy-apis) | +| CDR Register APIs Endpoint Version Schedule | [**Standards Maintenance #452**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/452) Set retirement dates for outstanding deprecated Register APIs| [Endpoint Version Schedule](../endpoint-version-schedule/index.html#cdr-register-apis) | ## Information Security Profile From ce3cc31c8246283790b8ff173b868037dc42107b Mon Sep 17 00:00:00 2001 From: Ivan Hosgood Date: Tue, 17 May 2022 11:22:03 +1000 Subject: [PATCH 06/13] Added standards maintenance issue reference to release notes --- slate/source/includes/releasenotes/releasenotes.1.17.0.html.md | 1 + 1 file changed, 1 insertion(+) diff --git a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md index 49b6b700..b0eb52be 100644 --- a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md +++ b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md @@ -22,6 +22,7 @@ This release addresses the following change requests raised on [Standards Mainte - [Standards Maintenance Issue 438: Representing adjustment transactions within the Billing Payload for C&I customers](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/438) - [Standards Maintenance Issue 457: Energy - Get Service Point Detail register suffix should be optional](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/457) - [Standards Maintenance Issue 482: JWT signing non-normative examples use unsupported signing algorithm)](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/482) +- [Standards Maintenance Issue 488: Data holder behaviour clarification required when receiving registrations with unsupported authorisation scopes](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/488) ### Decision Proposals From 53cfe1a960dcdf13aabd5e4879cef4bbcc2eb52f Mon Sep 17 00:00:00 2001 From: Ivan Hosgood Date: Tue, 17 May 2022 12:07:27 +1000 Subject: [PATCH 07/13] New authenticated endpoints only require cdr-register:read as the authorisation scope --- slate/source/includes/releasenotes/releasenotes.1.17.0.html.md | 2 ++ swagger-gen/api/cds_register.json | 2 -- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md index 228feba0..1ac0bae7 100644 --- a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md +++ b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md @@ -22,6 +22,7 @@ This release addresses the following change requests raised on [Standards Mainte - [Standards Maintenance Issue 438: Representing adjustment transactions within the Billing Payload for C&I customers](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/438) - [Standards Maintenance Issue 457: Energy - Get Service Point Detail register suffix should be optional](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/457) - [Standards Maintenance Issue 482: JWT signing non-normative examples use unsupported signing algorithm)](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/482) +- [Standards Maintenance Issue 498: New Register Authenticated APIs versions require multiple authorisation scopes](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/498) ### Decision Proposals @@ -44,6 +45,7 @@ This release addresses the following Decision Proposals published on [Standards] |Change|Description|Link| |------|-----------|----| | Energy schema | [**Standards Maintenance #457**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/457) Made EnergyServicePointDetail.meters.registers.registerSuffix field optional | [Energy Schema](../../#energy-apis) | +| Register APIs | [**Standards Maintenance #498**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/498) New authenticated endpoints only require `cdr-register:read` as the authorisation scope | [Register APIs](../../#register-apis) | ## Information Security Profile diff --git a/swagger-gen/api/cds_register.json b/swagger-gen/api/cds_register.json index b13988a4..e6c2e677 100644 --- a/swagger-gen/api/cds_register.json +++ b/swagger-gen/api/cds_register.json @@ -185,7 +185,6 @@ }, "x-version": "2", "x-scopes": [ - "cdr-register:bank:read", "cdr-register:read" ] } @@ -341,7 +340,6 @@ }, "x-version": "3", "x-scopes": [ - "cdr-register:bank:read", "cdr-register:read" ] } From 1ab2f0a539023f870081420a567d02760bb7359a Mon Sep 17 00:00:00 2001 From: Ivan Hosgood Date: Tue, 17 May 2022 14:54:08 +1000 Subject: [PATCH 08/13] Added clarification that when statuses are not received or recognised from the CDR Register, the ACCC can inform Data Holders of statuses to trust using an alternative mechanism --- .../includes/releasenotes/releasenotes.1.17.0.html.md | 2 ++ .../source/includes/security/_participant_statuses.md.erb | 7 ++++++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md index 228feba0..754e520a 100644 --- a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md +++ b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md @@ -22,6 +22,7 @@ This release addresses the following change requests raised on [Standards Mainte - [Standards Maintenance Issue 438: Representing adjustment transactions within the Billing Payload for C&I customers](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/438) - [Standards Maintenance Issue 457: Energy - Get Service Point Detail register suffix should be optional](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/457) - [Standards Maintenance Issue 482: JWT signing non-normative examples use unsupported signing algorithm)](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/482) +- [Standards Maintenance Issue 453: Consider an upper bound on trusting entity statuses when they go missing](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/453) ### Decision Proposals @@ -52,6 +53,7 @@ This release addresses the following Decision Proposals published on [Standards] | CDR Arrangement Revocation End Point | [Standards Maintenance Issue 503](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/503): Corrected the documentation to include CDR Arrangement Form Parameter and CDR Arrangement JWT methods. Previous versions did not include this documentation correctly. | [CDR Arrangement Revocation End Point](../../#cdr-arrangement-revocation-end-point) | Self-signed JWT Client Authentication non-normative example | [**Standards Maintenance #482**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/482): Updated self-signed JWT client authentication non-normative example `alg` field from HS256 to PS256 | [Client Authentication](../../index.html#client-authentication) | | CDR Arrangement Revocation End Point non-normative example | [**Standards Maintenance #482**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/482): Updated data recipient hosted CDR Arrangement Revocation End Point non-normative example `alg` field from HS256 to PS256 | [Security Endpoints](../../index.html#security-endpoints) | +| Data Holder Responsibilities | [**Standards Maintenance #453**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/453): Added clarification that when statuses are not received or recognised from the CDR Register, the ACCC can inform Data Holders of statuses to trust using an alternative mechanism. There is **no** upper bound for how long previous status values should remain trusted. | [Data Holder Responsibilities](../../index.html#participant-statuses) | ## Consumer Experience diff --git a/slate/source/includes/security/_participant_statuses.md.erb b/slate/source/includes/security/_participant_statuses.md.erb index 8cadd497..17727a0c 100644 --- a/slate/source/includes/security/_participant_statuses.md.erb +++ b/slate/source/includes/security/_participant_statuses.md.erb @@ -56,6 +56,10 @@ The table below outlines the end state for each Register entry type: ### Data Holder Responsibilities +```diff ++ Added clarification that when statuses are not received or recognised from the CDR Register, the ACCC can inform Data Holders of statuses to trust using an alternative mechanism. There is no upper bound for how long previous status values should remain trusted. +``` + The CDR Registrar has the ability to change the status of a Software Product independently of the Data Recipient's accreditation status. Therefore, both the Data Recipient and Software Product statuses **SHOULD** be referenced, to determine the Data Holder's responsibilities for data disclosure, consent and registration management. |**Data Recipient
Status**|**Software Product
Status**|**Disclose of CDR Data**|**Facilitate Consent Authorisation**|**Facilitate Consent Withdrawal**|**Invalidate Consents**|**Cleanup Registration**| @@ -75,7 +79,8 @@ The CDR Registrar has the ability to change the status of a Software Product ind * When a Data Recipient status is Suspended, Revoked or Surrendered the Software Product status cannot be Active * Invalidation of consents and cleanup of registrations are bulk operations. It is reasonable to execute these as batch tasks performed overnight * The CDR Register MUST NOT provide an undefined status for Data Recipient or Data Recipient Software Product Statuses -* If Data Holders do not receive a status for a Data Recipient or Data Recipient Software Product, or receives a status that is not recognised, Data Holders SHOULD ignore the value and use the previous status value retrieved from the CDR Register +* If Data Holders do not receive a status for a Data Recipient or Data Recipient Software Product, or receives a status that is not recognised, Data Holders SHOULD ignore the value and use the previous status value retrieved from the CDR Register. Data Holders SHOULD continue to use the previous status value until a valid value is returned by the CDR Register **or** the ACCC informs the Data Holder using an alternative mechanism. There is **no** upper bound for how long previous status values should remain trusted. + ### Metadata Cache Management Data Holders **MUST** react to Data Recipient and associated Software Statuses changes within **5 minutes** of the change occurring on the CDR Register. From 82804a647e6dd703c89bc413778eb4491b5c89ae Mon Sep 17 00:00:00 2001 From: Ivan Hosgood Date: Wed, 18 May 2022 11:58:06 +1000 Subject: [PATCH 09/13] Added GetDataHolderBrandsSummary API to expose public details of Data Holder Brands from the CDR Register to public clients --- slate/source/includes/_register.md.erb | 5 + slate/source/includes/cds_register.md | 200 +++++++++++++++++ .../releasenotes/releasenotes.1.17.0.html.md | 2 + swagger-gen/api/cds_register.json | 208 ++++++++++++++++++ 4 files changed, 415 insertions(+) diff --git a/slate/source/includes/_register.md.erb b/slate/source/includes/_register.md.erb index 646613d6..698c3bd2 100644 --- a/slate/source/includes/_register.md.erb +++ b/slate/source/includes/_register.md.erb @@ -37,6 +37,11 @@ These endpoints are exposed by the Register and consumed by Data Holders and Dat |**Production mTLS**|https://secure.api.cdr.gov.au| +```diff +Below are the changes to the Register APIs section of the +standards. ++ Added GetDataHolderBrandsSummary API to expose public details of Data Holder Brands from the CDR Register to public clients +``` <%= partial "includes/cds_register.md" %> diff --git a/slate/source/includes/cds_register.md b/slate/source/includes/cds_register.md index af9d8dc4..6e227cae 100644 --- a/slate/source/includes/cds_register.md +++ b/slate/source/includes/cds_register.md @@ -322,6 +322,123 @@ cdr-register:read +## Get Data Holder Brands Summary + + + +> Code samples + +```http +GET https:///cdr-register/v1/{industry}/data-holders/brands/summary HTTP/1.1 + +Accept: application/json +x-v: string +x-min-v: string +If-None-Match: string + +``` + +```javascript +var headers = { + 'Accept':'application/json', + 'x-v':'string', + 'x-min-v':'string', + 'If-None-Match':'string' + +}; + +$.ajax({ + url: 'https:///cdr-register/v1/{industry}/data-holders/brands/summary', + method: 'get', + + headers: headers, + success: function(data) { + console.log(JSON.stringify(data)); + } +}) + +``` + +`GET /cdr-register/v1/{industry}/data-holders/brands/summary` + +Endpoint used by participants to discover public details of Data Holder Brands from the CDR Register + +###Endpoint Version +| | | +|---|--| +|Version|**1** + +

Parameters

+ +|Name|In|Type|Required|Description| +|---|---|---|---|---| +|industry|path|string|mandatory|The industry the participant is retrieving data for (Banking, etc)| +|x-v|header|string|optional|The version of the API end point requested by the client. Must be set to a positive integer.| +|x-min-v|header|string|optional|The [minimum version](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) of the API end point requested by the client. Must be set to a positive integer if provided.| +|If-None-Match|header|string|optional|Makes the request method conditional on a recipient cache or origin server not having any current representation of the target resource with an entity-tag that does not match any of those listed in the field-value.| + +#### Enumerated Values + +|Parameter|Value| +|---|---| +|industry|banking| +|industry|energy| +|industry|telco| +|industry|all| + +> Example responses + +> 200 Response + +```json +{ + "data": [ + { + "dataHolderBrandId": "string", + "interimId": "string", + "brandName": "string", + "publicBaseUri": "string", + "logoUri": "string", + "industries": [ + "banking" + ], + "lastUpdated": "2019-08-24T14:15:22Z", + "abn": "string", + "acn": "string", + "arbn": "string" + } + ], + "links": { + "self": "string" + }, + "meta": {} +} +``` + +

Responses

+ +|Status|Meaning|Description|Schema| +|---|---|---|---| +|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|[ResponseDataHoldersBrandSummaryList](#schemacdr-participant-discovery-apiresponsedataholdersbrandsummarylist)| +|304|[Not Modified](https://tools.ietf.org/html/rfc7232#section-4.1)|Not Modified - The current representation of the target resource matches with the entity-tag provided in the If-None-Match request header|None| +|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Missing Required Header / Invalid Version / Invalid Path Parameter|[ResponseErrorListV2](#schemacdr-participant-discovery-apiresponseerrorlistv2)| +|406|[Not Acceptable](https://tools.ietf.org/html/rfc7231#section-6.5.6)|Unsupported Version|[ResponseErrorListV2](#schemacdr-participant-discovery-apiresponseerrorlistv2)| + +### Response Headers + +|Status|Header|Type|Format|Description| +|---|---|---|---|---| +|200|x-v|string||The version of the API end point that the CDR Register has responded with.| +|200|Etag|string||Entity tag that uniquely represents the requested resource.| +|304|Etag|string||Entity tag that uniquely represents the requested resource.| + + + + + + ## Get Software Statement Assertion (SSA) @@ -1150,6 +1267,89 @@ This operation does not require authentication |status|INACTIVE| |status|REMOVED| +

ResponseDataHoldersBrandSummaryList

+ + + +```json +{ + "data": [ + { + "dataHolderBrandId": "string", + "interimId": "string", + "brandName": "string", + "publicBaseUri": "string", + "logoUri": "string", + "industries": [ + "banking" + ], + "lastUpdated": "2019-08-24T14:15:22Z", + "abn": "string", + "acn": "string", + "arbn": "string" + } + ], + "links": { + "self": "string" + }, + "meta": {} +} + +``` + +### Properties + +|Name|Type|Required|Description| +|---|---|---|---| +|data|[[DataHolderBrandSummary](#schemacdr-participant-discovery-apidataholderbrandsummary)]|mandatory|Response data for the query| +|links|[Links](#schemacdr-participant-discovery-apilinks)|mandatory|none| +|meta|[Meta](#schemacdr-participant-discovery-apimeta)|mandatory|none| + +

DataHolderBrandSummary

+ + + +```json +{ + "dataHolderBrandId": "string", + "interimId": "string", + "brandName": "string", + "publicBaseUri": "string", + "logoUri": "string", + "industries": [ + "banking" + ], + "lastUpdated": "2019-08-24T14:15:22Z", + "abn": "string", + "acn": "string", + "arbn": "string" +} + +``` + +### Properties + +|Name|Type|Required|Description| +|---|---|---|---| +|dataHolderBrandId|string|optional|Unique id of the Data Holder Brand issued by the CDR Register| +|interimId|string|optional|Interim id of the Data Holder Brand issued by the CDR Register. This is to be used to uniquely identify the record when dataHolderBrandId is not populated and is not to be reused| +|brandName|string|mandatory|The name of Data Holder Brand| +|publicBaseUri|[URIString](#common-field-types)|mandatory|Base URI for the Data Holder's Consumer Data Standard public endpoints| +|logoUri|[URIString](#common-field-types)|mandatory|Brand logo URI| +|industries|[string]|mandatory|The industries the Data Holder Brand belongs to. Please note that the CDR Register entity model is constrained to one industry per brand which is planned to be relaxed in the future.| +|lastUpdated|[DateTimeString](#common-field-types)|mandatory|The date/time that the Data Holder Brand data was last updated in the Register| +|abn|string|optional|Australian Business Number for the organisation| +|acn|string|optional|Australian Company Number for the organisation| +|arbn|string|optional|Australian Registered Body Number. ARBNs are issued to registrable Australian bodies and foreign companies| + +#### Enumerated Values + +|Property|Value| +|---|---| +|industries|banking| +|industries|energy| +|industries|telco| +

DataHoldersStatusList

diff --git a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md index 228feba0..165a6452 100644 --- a/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md +++ b/slate/source/includes/releasenotes/releasenotes.1.17.0.html.md @@ -22,6 +22,7 @@ This release addresses the following change requests raised on [Standards Mainte - [Standards Maintenance Issue 438: Representing adjustment transactions within the Billing Payload for C&I customers](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/438) - [Standards Maintenance Issue 457: Energy - Get Service Point Detail register suffix should be optional](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/457) - [Standards Maintenance Issue 482: JWT signing non-normative examples use unsupported signing algorithm)](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/482) +- [Standards Maintenance Issue 444: Add an unauthenticated GetDataHolderBrands endpoint exposed as a public API](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/444) ### Decision Proposals @@ -44,6 +45,7 @@ This release addresses the following Decision Proposals published on [Standards] |Change|Description|Link| |------|-----------|----| | Energy schema | [**Standards Maintenance #457**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/457) Made EnergyServicePointDetail.meters.registers.registerSuffix field optional | [Energy Schema](../../#energy-apis) | +| Register APIs | [**Standards Maintenance #444**](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/444) Added GetDataHolderBrandsSummary API to expose public details of Data Holder Brands from the CDR Register to public clients | [Register APIs](../../#register-apis) | ## Information Security Profile diff --git a/swagger-gen/api/cds_register.json b/swagger-gen/api/cds_register.json index b13988a4..e8ca8664 100644 --- a/swagger-gen/api/cds_register.json +++ b/swagger-gen/api/cds_register.json @@ -190,6 +190,115 @@ ] } }, + "/cdr-register/v1/{industry}/data-holders/brands/summary": { + "get": { + "tags": [ + "Register" + ], + "summary": "Get Data Holder Brands Summary", + "description": "Endpoint used by participants to discover public details of Data Holder Brands from the CDR Register", + "operationId": "GetDataHolderBrandsSummary", + "parameters": [ + { + "name": "industry", + "in": "path", + "description": "The industry the participant is retrieving data for (Banking, etc)", + "required": true, + "schema": { + "type": "string", + "enum": [ + "banking", + "energy", + "telco", + "all" + ] + } + }, + { + "name": "x-v", + "in": "header", + "description": "The version of the API end point requested by the client. Must be set to a positive integer.", + "schema": { + "type": "string" + } + }, + { + "name": "x-min-v", + "in": "header", + "description": "The [minimum version](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) of the API end point requested by the client. Must be set to a positive integer if provided.", + "schema": { + "type": "string" + } + }, + { + "name": "If-None-Match", + "in": "header", + "description": "Makes the request method conditional on a recipient cache or origin server not having any current representation of the target resource with an entity-tag that does not match any of those listed in the field-value.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "headers": { + "x-v": { + "description": "The version of the API end point that the CDR Register has responded with.", + "schema": { + "type": "string" + } + }, + "Etag": { + "description": "Entity tag that uniquely represents the requested resource.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResponseDataHoldersBrandSummaryList" + } + } + } + }, + "304": { + "description": "Not Modified - The current representation of the target resource matches with the entity-tag provided in the If-None-Match request header", + "headers": { + "Etag": { + "description": "Entity tag that uniquely represents the requested resource.", + "schema": { + "type": "string" + } + } + } + }, + "400": { + "description": "Missing Required Header / Invalid Version / Invalid Path Parameter", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResponseErrorListV2" + } + } + } + }, + "406": { + "description": "Unsupported Version", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResponseErrorListV2" + } + } + } + } + }, + "x-version": "1" + } + }, "/cdr-register/v1/{industry}/data-recipients/brands/{dataRecipientBrandId}/software-products/{softwareProductId}/ssa": { "get": { "tags": [ @@ -1043,6 +1152,105 @@ } } }, + "ResponseDataHoldersBrandSummaryList": { + "required": [ + "data", + "links", + "meta" + ], + "type": "object", + "properties": { + "data": { + "uniqueItems": true, + "type": "array", + "description": "Response data for the query", + "items": { + "$ref": "#/components/schemas/DataHolderBrandSummary" + } + }, + "links": { + "$ref": "#/components/schemas/Links" + }, + "meta": { + "$ref": "#/components/schemas/Meta" + } + } + }, + "DataHolderBrandSummary": { + "required": [ + "brandName", + "publicBaseUri", + "logoUri", + "industries", + "lastUpdated" + ], + "type": "object", + "properties": { + "dataHolderBrandId": { + "maxLength": 36, + "type": "string", + "x-conditional": true, + "description": "Unique id of the Data Holder Brand issued by the CDR Register" + }, + "interimId": { + "maxLength": 36, + "type": "string", + "x-conditional": true, + "description": "Interim id of the Data Holder Brand issued by the CDR Register. This is to be used to uniquely identify the record when dataHolderBrandId is not populated and is not to be reused" + }, + "brandName": { + "maxLength": 200, + "type": "string", + "description": "The name of Data Holder Brand" + }, + "publicBaseUri": { + "maxLength": 1000, + "type": "string", + "description": "Base URI for the Data Holder's Consumer Data Standard public endpoints", + "x-cds-type": "URIString" + }, + "logoUri": { + "maxLength": 1000, + "type": "string", + "description": "Brand logo URI", + "x-cds-type": "URIString" + }, + "industries": { + "uniqueItems": true, + "type": "array", + "description": "The industries the Data Holder Brand belongs to. Please note that the CDR Register entity model is constrained to one industry per brand which is planned to be relaxed in the future.", + "items": { + "type": "string", + "enum": [ + "banking", + "energy", + "telco" + ] + } + }, + "lastUpdated": { + "type": "string", + "description": "The date/time that the Data Holder Brand data was last updated in the Register", + "format": "date-time", + "x-cds-type": "DateTimeString" + }, + "abn": { + "maxLength": 11, + "type": "string", + "description": "Australian Business Number for the organisation" + }, + "acn": { + "maxLength": 9, + "type": "string", + "description": "Australian Company Number for the organisation" + }, + "arbn": { + "maxLength": 9, + "type": "string", + "description": "Australian Registered Body Number. ARBNs are issued to registrable Australian bodies and foreign companies" + } + } + }, "DataHoldersStatusList": { "required": [ "data", From cca53a801b32dd9d934b382f6c84fcc0a991051d Mon Sep 17 00:00:00 2001 From: Ivan Hosgood Date: Thu, 19 May 2022 14:38:43 +1000 Subject: [PATCH 10/13] Documented scopes usage for the authenticated Register endpoint versions --- slate/source/includes/_scopes.md.erb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/slate/source/includes/_scopes.md.erb b/slate/source/includes/_scopes.md.erb index 816b5c4d..cc30ce0f 100644 --- a/slate/source/includes/_scopes.md.erb +++ b/slate/source/includes/_scopes.md.erb @@ -47,6 +47,6 @@ Scope Name | Scope ID |Description -----------|----------|----------- **Basic Admin Metrics Data** | admin:metrics.basic:read | Metrics data accessible ONLY to the CDR Register. If the Data Holder uses Private Key JWT Client Authentication to authenticate the CDR Register, this scope is required.

Includes access to basic Metrics data. **Admin Metadata Update Data** | admin:metadata:update | Update notification accessible ONLY to the CDR Register. If the Data Holder uses Private Key JWT Client Authentication to authenticate the CDR Register, this scope is required.

Includes permission to notify Data Holders of changes to Data Recipient metadata held by the CDR Register. -**Bank Participant Data** | cdr-register:bank:read | This scope would allow Data Recipients and Data Holders access to participant metadata in the banking sector, held by the CDR Register. -**Participant Data** | cdr-register:read | This scope would allow Data Recipients and Data Holders access to participant metadata held by the CDR Register. +**Bank Participant Data** | cdr-register:bank:read | This scope would allow Data Recipients and Data Holders access to participant metadata in the banking sector, held by the CDR Register.
This scope is valid for the following endpoint versions:
  • GetDataHolderBrands [**V1**](includes/obsolete/get-data-holder-brands-v1.html#get-data-holder-brands-v1)
  • GetSoftwareStatementAssertion [**V2**](includes/obsolete/get-software-statement-assertion-v2.html#get-software-statement-assertion-ssa-v2)
This scope is replaced by `cdr-register:read` for newer versions of these endpoints. +**Participant Data** | cdr-register:read | This scope would allow Data Recipients and Data Holders access to participant metadata held by the CDR Register.
Replaces `cdr-register:bank:read` for the following endpoint versions:
  • GetDataHolderBrands [**V2**](#get-data-holder-brands)
  • GetSoftwareStatementAssertion [**V3**](#get-software-statement-assertion-ssa)
**Register Client** | cdr:registration | This scope would allow a Data Recipient to register or manage a software product client with a Data Holder. From 5bfea5a1c2112d2309cd103927e22f8fa55a36dc Mon Sep 17 00:00:00 2001 From: Ivan Hosgood Date: Fri, 20 May 2022 08:46:54 +1000 Subject: [PATCH 11/13] XV header is a required field --- swagger-gen/api/cds_register.json | 1 + 1 file changed, 1 insertion(+) diff --git a/swagger-gen/api/cds_register.json b/swagger-gen/api/cds_register.json index e8ca8664..08989dc7 100644 --- a/swagger-gen/api/cds_register.json +++ b/swagger-gen/api/cds_register.json @@ -218,6 +218,7 @@ "name": "x-v", "in": "header", "description": "The version of the API end point requested by the client. Must be set to a positive integer.", + "required": true, "schema": { "type": "string" } From 403a27b35280fa244b02710f776c177113ccef85 Mon Sep 17 00:00:00 2001 From: Ivan Hosgood Date: Fri, 20 May 2022 09:41:00 +1000 Subject: [PATCH 12/13] Made SHOULD requirement bold --- slate/source/includes/security/_participant_statuses.md.erb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/slate/source/includes/security/_participant_statuses.md.erb b/slate/source/includes/security/_participant_statuses.md.erb index 17727a0c..3672f89f 100644 --- a/slate/source/includes/security/_participant_statuses.md.erb +++ b/slate/source/includes/security/_participant_statuses.md.erb @@ -78,8 +78,8 @@ The CDR Registrar has the ability to change the status of a Software Product ind * The status of a Data Recipient Brand does not impact Data Holder responsibilities due to the cascade rules outlined above * When a Data Recipient status is Suspended, Revoked or Surrendered the Software Product status cannot be Active * Invalidation of consents and cleanup of registrations are bulk operations. It is reasonable to execute these as batch tasks performed overnight -* The CDR Register MUST NOT provide an undefined status for Data Recipient or Data Recipient Software Product Statuses -* If Data Holders do not receive a status for a Data Recipient or Data Recipient Software Product, or receives a status that is not recognised, Data Holders SHOULD ignore the value and use the previous status value retrieved from the CDR Register. Data Holders SHOULD continue to use the previous status value until a valid value is returned by the CDR Register **or** the ACCC informs the Data Holder using an alternative mechanism. There is **no** upper bound for how long previous status values should remain trusted. +* The CDR Register **MUST NOT** provide an undefined status for Data Recipient or Data Recipient Software Product Statuses +* If Data Holders do not receive a status for a Data Recipient or Data Recipient Software Product, or receives a status that is not recognised, Data Holders **SHOULD** ignore the value and use the previous status value retrieved from the CDR Register. Data Holders **SHOULD** continue to use the previous status value until a valid value is returned by the CDR Register or the ACCC informs the Data Holder using an alternative mechanism. There is **no** upper bound for how long previous status values should remain trusted. ### Metadata Cache Management From c7b65b159feedda4307d8416fcd46349be4033b9 Mon Sep 17 00:00:00 2001 From: Ivan Hosgood Date: Fri, 20 May 2022 09:56:52 +1000 Subject: [PATCH 13/13] Added version-deltas for register scope usage --- slate/source/includes/_scopes.md.erb | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/slate/source/includes/_scopes.md.erb b/slate/source/includes/_scopes.md.erb index cc30ce0f..a2f143b6 100644 --- a/slate/source/includes/_scopes.md.erb +++ b/slate/source/includes/_scopes.md.erb @@ -40,6 +40,11 @@ Scope Name | Scope ID |Description **Detailed Customer Data** | common:customer.detail:read | The scope would allow the third party to access more detailed information about the customer. Includes the data available with the Basic Customer Data scope plus contact details.

Includes basic data plus phone, email and address information. ## Admin & Registration + +```diff ++ Added endpoint versions that cdr-register:bank:read and cdr-register:read apply to. +``` + The following scopes are used for administrative interactions. These scopes MUST never be included in the same access token as a CDR Data scope.