Maintenance Iteration 17 Holistic Feedback

[CDR-API-Stream]

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 17 and the DSB will review them. If a suggestion is a material change a dedicated CR will be raised.

[nils-work]

Item from MI 16 holistic feedback - #599 (comment)

The endpoint versioning schedule is incorrect for the CDR Arrangement Revocation End Point.

[perlboy]

Non Normative example for Discovery document seems to use a string for the code_challenge_methods when it is a JSON array. For example:
... "code_challenge_methods_supported": "S256", ...

I don't believe singletons are supported for this attribute. Also, RFC7636 isn't in the Normative References list.

[nils-work]

There is a typo in the description of the kid property in the JWK section of Register APIs.
Proposing the following changes for clarity (insert 'to be', delete 'to'):

The "kid" (key ID) parameter is partially used to match a specific key. Note the "kid" parameter is not guaranteed to be unique and additional parameters should be used to progressively to identify a key within a set

[nils-work]

The maturityInstructions property has three enumerated values defined in the BankingTermDepositAccount schema, but only the most recently added value HOLD_ON_MATURITY has a detailed description in the Product & Account Components section.

A link to the supporting information could be added to the maturityInstructions description in the schema, and the missing values added to the table.

New row detail for consideration -

Value	Description	Use of additionalValue Field
PAID_OUT_AT_MATURITY	Funds are to be paid out at maturity	NA
ROLLED_OVER	Funds are to be rolled over at maturity	NA

[nils-work]

There are references to three incorrect field labels in the property descriptions of BankingProductRateTierV3.

These changes are required -

• tierValueMinimum should refer to minimumValue
• tierValueMaximum should refer to maximumValue
• tierUnitOfMeasure should refer to unitOfMeasure

[nils-work]

There are a few minor differences in the naming of Register endpoints in the documentation.
These could be aligned:

[nils-work]

The text:

Refer also to Future Dated obligations

in the Amending Authorisation Standards section can be removed as the obligation date for these requirements has passed.

[nils-work]

Add a link to the Obligation Dates Schedule from the Future Dated Obligations section.

[CDR-Engagement-Stream]

Request for update to the Consumer Experience Guidelines link in the CDS.

From here: https://consumerdatastandardsaustralia.github.io/standards/#consumer-experience

Change the link to direct reference to the CX Guidelines.

Change from:
<a href="https://consumerdatastandards.gov.au/guidelines-and-conventions/consumer-experience-guidelines/">

To:
<a href="https://cx.cds.gov.au/">

Link to line: https://github.com/ConsumerDataStandardsAustralia/standards/blob/877417aaff0a44a195c6893c630d4340e757d7d6/docs/includes/cx#L6C2-L6C2

Edit: formatting.

[nils-work]

To reflect the changes in the error reporting structure from Get Metrics v3, to v4 and v5 -

Update the Description of the errors property of ResponseMetricsListV4 and ResponseMetricsListV5:

- Number of calls resulting in error due to server execution over time
+ Number of calls resulting in error, over time

Update the italic introductory text under the heading of ErrorMetricsV2 (in Get Metrics v4 and v5):

- Number of calls resulting in error due to server execution over time
+ Number of calls resulting in error, over time

Update the following property descriptions in ErrorMetricsV2 (in Get Metrics v4 and v5):

- Number of calls resulting in error due to server execution over time for unauthenticated endpoints
+ Number of calls resulting in error for unauthenticated endpoints

- Number of calls resulting in error due to server execution over time for authenticated endpoints
+ Number of calls resulting in error for authenticated endpoints

[anzbankau]

Hi @nils-work,

As part of these corrections (earlier #612 (comment)):

There are references to three incorrect field labels in the property descriptions of BankingProductRateTierV3.

These changes are required -

• tierValueMinimum should refer to minimumValue
• tierValueMaximum should refer to maximumValue
• tierUnitOfMeasure should refer to unitOfMeasure

Could you please correct the minimumValue and maximumValue descriptions that still refer to tierUnitOfMeasure when the referenced property was subsequently renamed to unitOfMeasure.

[anzbankau]

Hi @nils-work,

As mentioned in our comment CP614 - Definition of PERCENT in BankingProductRateTierV3:

(While the Number data type has the Description "A standard floating point number. Can be positive, negative or zero", the examples include the integer 10, so perhaps the description needs to be expanded.)

Assuming there hasn't been guidance to ignore the example of 10 for Number, we suggest the following description:

• An integer or decimal number. Can be positive, negative or zero.

Note: Since JSON is representational rather than for storage, 'decimal' should be used in the description rather than 'floating point'.

If Number was not intended to include integers, perhaps a review (only) of the data type hierarchy for numeric data would be timely. We're not suggesting changes as there would be significant implementation impacts. The traditional hierarchy:

• Number:
  • Integer:
    • 0
    • PositiveInteger
    • NegativeInteger
  • Decimal: [0.0, PositiveDecimal, NegativeDecimal]

... has been extended in Common Field Types with the useful union:

• NaturalNumber: [ 0 | PositiveInteger ]

... but there's also this interesting modification (for which an alternative name would be hard to provide):

• NegativeInteger: [ 0 | NegativeInteger ]

Thanks.

[nils-work]

Thanks for raising this @perlboy, the first part was resolved in v1.27.0 -

Non Normative example for Discovery document seems to use a string for the code_challenge_methods when it is a JSON array. For example: ... "code_challenge_methods_supported": "S256", ...

and RFC7636 is linked from the [PKCE] entry, but not by itself with the other RFC entries -

I don't believe singletons are supported for this attribute. Also, RFC7636 isn't in the Normative References list.

[CDR-Engagement-Stream]

Update link to the Data Standards Body (DSB) under Introduction.

Current link goes to: https://www.directory.gov.au/portfolios/treasury/data-standards-body (404 - Access denied)

I think the original page has been deprecated. Now there is no new or replacement.

Proposed new link: https://www.legislation.gov.au/Details/F2021N00038

Edit: changed proposed link

[kirkycdr]

There are references to three incorrect field labels in the property descriptions of BankingProductRateTierV3.

These changes are required -

• tierValueMinimum should refer to minimumValue
• tierValueMaximum should refer to maximumValue
• tierUnitOfMeasure should refer to unitOfMeasure

This has been staged for review:
ConsumerDataStandardsAustralia/standards-staging@89314f9

ConsumerDataStandardsAustralia/standards-staging@349180a

[kirkycdr]

Request for update to the Consumer Experience Guidelines link in the CDS.

From here: https://consumerdatastandardsaustralia.github.io/standards/#consumer-experience

Change the link to direct reference to the CX Guidelines.

Change from: <a href="https://consumerdatastandards.gov.au/guidelines-and-conventions/consumer-experience-guidelines/">

To: <a href="https://cx.cds.gov.au/">

Link to line: https://github.com/ConsumerDataStandardsAustralia/standards/blob/877417aaff0a44a195c6893c630d4340e757d7d6/docs/includes/cx#L6C2-L6C2

Edit: formatting.

This has been staged for review:
ConsumerDataStandardsAustralia/standards-staging@0156249

[kirkycdr]

The text:

Refer also to Future Dated obligations

in the Amending Authorisation Standards section can be removed as the obligation date for these requirements has passed.

This has been staged for review:
ConsumerDataStandardsAustralia/standards-staging@25d7069

[kirkycdr]

Thanks for raising this @perlboy, the first part was resolved in v1.27.0 -

Non Normative example for Discovery document seems to use a string for the code_challenge_methods when it is a JSON array. For example: ... "code_challenge_methods_supported": "S256", ...

and RFC7636 is linked from the [PKCE] entry, but not by itself with the other RFC entries -

I don't believe singletons are supported for this attribute. Also, RFC7636 isn't in the Normative References list.

This has been staged for review:
ConsumerDataStandardsAustralia/standards-staging@71734da

[kirkycdr]

Update link to the Data Standards Body (DSB) under Introduction.

Current link goes to: https://www.directory.gov.au/portfolios/treasury/data-standards-body (404 - Access denied)

I think the original page has been deprecated. Now there is no new or replacement.

Proposed new link: https://www.legislation.gov.au/Details/F2021N00038

Edit: changed proposed link

This has been staged for review:
ConsumerDataStandardsAustralia/standards-staging@3381935

[kirkycdr]

There are a few minor differences in the naming of Register endpoints in the documentation. These could be aligned:

This has been staged for review:
ConsumerDataStandardsAustralia/standards-staging@6565dfe

[kirkycdr]

Add a link to the Obligation Dates Schedule from the Future Dated Obligations section.

This has been staged for review:
ConsumerDataStandardsAustralia/standards-staging@1e61195

[kirkycdr]

The maturityInstructions property has three enumerated values defined in the BankingTermDepositAccount schema, but only the most recently added value HOLD_ON_MATURITY has a detailed description in the Product & Account Components section.

A link to the supporting information could be added to the maturityInstructions description in the schema, and the missing values added to the table.

New row detail for consideration -

Value Description Use of additionalValue Field
PAID_OUT_AT_MATURITY Funds are to be paid out at maturity NA
ROLLED_OVER Funds are to be rolled over at maturity NA

This has been staged for review :
ConsumerDataStandardsAustralia/standards-staging@061bf45

[kirkycdr]

Hi @nils-work,

As mentioned in our comment CP614 - Definition of PERCENT in BankingProductRateTierV3:

(While the Number data type has the Description "A standard floating point number. Can be positive, negative or zero", the examples include the integer 10, so perhaps the description needs to be expanded.)

Assuming there hasn't been guidance to ignore the example of 10 for Number, we suggest the following description:

• An integer or decimal number. Can be positive, negative or zero.

Note: Since JSON is representational rather than for storage, 'decimal' should be used in the description rather than 'floating point'.

If Number was not intended to include integers, perhaps a review (only) of the data type hierarchy for numeric data would be timely. We're not suggesting changes as there would be significant implementation impacts. The traditional hierarchy:

• Number:

  • Integer:

    • 0
    • PositiveInteger
    • NegativeInteger

  • Decimal: [0.0, PositiveDecimal, NegativeDecimal]

... has been extended in Common Field Types with the useful union:

• NaturalNumber: [ 0 | PositiveInteger ]

... but there's also this interesting modification (for which an alternative name would be hard to provide):

• NegativeInteger: [ 0 | NegativeInteger ]

Thanks.

This has been staged for review:

ConsumerDataStandardsAustralia/standards-staging@1cdef9f

[kirkycdr]

To reflect the changes in the error reporting structure from Get Metrics v3, to v4 and v5 -

Update the Description of the errors property of ResponseMetricsListV4 and ResponseMetricsListV5:

- Number of calls resulting in error due to server execution over time
+ Number of calls resulting in error, over time

Update the italic introductory text under the heading of ErrorMetricsV2 (in Get Metrics v4 and v5):

- Number of calls resulting in error due to server execution over time
+ Number of calls resulting in error, over time

Update the following property descriptions in ErrorMetricsV2 (in Get Metrics v4 and v5):

- Number of calls resulting in error due to server execution over time for unauthenticated endpoints
+ Number of calls resulting in error for unauthenticated endpoints

- Number of calls resulting in error due to server execution over time for authenticated endpoints
+ Number of calls resulting in error for authenticated endpoints

This has been staged for review:

ConsumerDataStandardsAustralia/standards-staging@eff33a6

[CDR-API-Stream]

Standards version 1.29.0 was published on 21/12/2023 incorporating changes from MI17.