Maintenance Iteration 17 Holistic Feedback

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

nils-work commented 9 months ago

Item from MI 16 holistic feedback - https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/599#issuecomment-1676191553

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

perlboy commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

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

nils-work commented 9 months ago

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 commented 9 months ago

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

CDR-Engagement-Stream commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

Hi @nils-work,

As part of these corrections (earlier https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/612#issuecomment-1724733931):

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 commented 9 months ago

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 commented 7 months ago

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 commented 7 months ago

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