Decision Proposal 70 - May 2019 Draft API Standards Feedback Cycle 1

[JamesMBligh]

This thread has been created to accept feedback on the May 2019 working draft. Specifically this thread is for feedback on the overall standards, API URIs and payloads.

We will also receive written submissions on this update on the basis that such submissions will be published subsequently. In accordance with our normal transparency policy all submissions will be made public. Written submissions should be submitted via the CDR email address: [email protected].

Where participants believe they have sensitive information to convey we will consider those discussions and give guidance on our preferred disclosure approach prior to meeting to discuss such issues. To discuss such issues please email us at the CDR email address: [email protected].

We will written submissions and feedback on this thread until Friday 21st June.

For feedback on the Information Security Profile please refer to the separate thread at #71.

[anzbankau]

Hi James,

Re: BankingProductDiscount.amount like BankingProductFee.amount

(Copied from #67 post just in case it wasn't logged before you moved to this thread.)

Thanks for making BankingProductFee.amount Conditional to reflect that fees can be expressed in terms of amount, balanceRate, transactionRate or accruedRate as per 3rd item in your response. Could you please do the same for BankingProductDiscount in the same way. amount is Mandatory and has Description 'Value of the discount' when following properties include 'One of amount, balanceRate, transactionRate, accruedRate and feeRate is mandatory.'.
Thanks.

[anzbankau]

Hi James,

Copied across from #67 (comment)

Product API header values
Could it please be clarified that the following header fields would not be expected for product API calls:

Request

• x-fapi-auth-date
• x-fapi-customer-ip-address
• x-fapi-interaction-id

Response

• x-Correlation-Id
• x-fapi-interaction-id

Unless the intention is otherwise?

Additionally we notice that x-Correlation-Id is specified in the response header, but not in the request header documentation.

Thanks.

[anzbankau]

Re: Eligibility OTHER 'Use of additionalValue Field' = 'NA' but still optional

Hi James/Brian,

For all our OTHER eligibility type cases we have descriptive text for additionalInfo but don't have a discrete value for additionalValue. However, the 'Use of additionalValue Field' column in the enums table has 'Value relevant to the criteria' rather than 'NA', meaning it's mandatory. These cases fit the OTHER enum Description of 'Another eligibility criteria exists as described in the additionalInfo field (if this option is specified then the additionalInfo field is mandatory)'.

This also fits the pattern throughout the standards where additionalValue is for a discrete value (often numeric) and additionalInfo is for descriptive information. The schema Description for additionalValue confuses this with 'Generic field containing additional information relevant to the eligibilityType specified'.

We propose that the Eligibility enums table entry for 'OTHER' has a 'Use of additionalValue Field' value of 'NA'. Could you please confirm that this still permits us to provide a value if required i.e. it should not be interpreted as 'must not be provided'. The inclusion of 'Mandatory if the eligibilityType field is set to OTHER' in the additionalInfo schema Description enforces the obvious intention that 'OTHER' is meaningless and therefore requires additional information - even if a discrete additionalValue does not make sense for these cases.

Clearly we can repeat the descriptive text in additionalInfo in additionalValue (as there are not brief and long versions of the description) but I doubt that's what you intended or what data consumers would expect.

Thanks

[commbankoss]

Commonwealth Bank welcomes the opportunity to provide feedback on version 0.9.3 of the Draft API Standards.
Commonwealth Bank acknowledge the work the Data Standards Body has undertaken to address feedback from the community. The Standards identify a number of areas where further feedback is specifically requested before a decision will be made, and Commonwealth Bank has addressed those issues in our submission on proposal 71. Outlined below are a number of issues and recommendations specific to proposal 70.
Commonwealth Bank note that the Australian Competition and Consumer Commission (ACCC) have begun consultation on the design of the CDR Registry. The design of the Registry is critical to the secure operation of the regime. We note that there will be required amendments or additions to the standards once the design and function of the Registry become clear. Specifically, it is expected that future iterations of the Standards will include details regarding end points related to Data Recipient registration, certificate revocation, Data Recipient discovery, and Data Holder discovery. At this time Commonwealth Bank are unable to comment on those issues without additional information.
API.pdf

[WestpacOpenBanking]

Versioning

The documentation versioning strategy is currently incompatible with the end point versioning strategy. This is because breaking changes are not always negotiated. To illustrate this, consider the following sequence:

• A breaking modification is made to the security standard. The standards version is incremented to 1.2.0.
• A new version of an endpoint is released, incrementing the standards version to 1.3.0 and the endpoint version from v2 to v3.
• A data holder updates to version 1.3.0 but retains support for endpoint v2 as well as v3.
• A client which has not been updated sends a request to the endpoint supporting a minimum version of 1 and a maximum version of 2.

In this example, there is currently no mechanism for the client and server to negotiate which version of the security standard is to be used. Presumably, the client would assume that v1.2.0 was to be used, and the server would use v1.3.0. Even though the Data Holder’s server has implemented endpoint versioning correctly the Data Recipient might be unable to communicate in this instance.

We suggest two possible solutions to these problems. Both solutions require:

• Breaking changes to require a change in base URI
• Data Consumers would use the register discovery API to determine which base-URI-changing versions are available.
• Versioning and release management strategies to outline behaviour with respect to consents between versions. For example, can an old consent be used with new data?
• Timeframes for depreciation of old versions with breaking changes.

Sunset headers and/or some other form of depreciation notification may also be useful for Data Consumers.

A breaking change is a change which is not backwards-compatible. Backwards-compatible changes include:

• Addition of a new endpoint
• Addition of optional request parameters
• Addition of additional fields to existing endpoints

The definition of a breaking change should be included in the standard.

Solution 1 – Block Versioning without endpoint versioning

We support this solution. The standards would be block versioned without endpoint versioning. This should allow, and stipulate, that any changes made to endpoints within the block version MUST be backward-compatible otherwise the block version number is incremented. This would be split by industry into authenticated endpoints, unauthenticated endpoints and (as was the case until recently) into the infosec profile.

This approach is already being used in practice by all of Data61’s streams in the lead up to the release of version one. Artefacts using this strategy include:

• The technical standard itself (currently at 0.9.3). Here we are including the swagger, but also the parts of the standard not encoded into the swagger.
• The infosec standard (which was version 0.1.1 before being merged into the technical standard)
• The engineering stream deliverables, including cds-conformance, cds-codegen, cds-client-java and cds-models

This approach supports Principle 4 (APIs provide a good developer experience) because it:

• Resolves the unsolved issues surrounding swagger’s compatibility with endpoint negotiation. This simplifies the use of automated code generation (either swagger-codegen or cds-codegen), quality assurance tools, dev-ops tools, API gateways and many other activities.
• Frequently allows support for different versions to be maintained and deployed through different forks of a codebase rather than within the code itself.
• Simplifies the use of client or server side HTTP caches which are frequently unaware of request headers.

Additionally, we believe that this approach may be the most pragmatic if there are large differences in the standards between industries.

Solution 2 – Minor version changes are always non-breaking

Minor version changes would be non-breaking in this standard. This would allow a data recipient to mix and match endpoint versions using the header negotiation method.

We do not support this solution. It does not provide a good developer experience because:

• It is difficult to use standard swagger based tools without modifications.
• Support for multiple versions needs to maintained within code rather than as forks of a codebase.
• Use of standard HTTP caching solutions is more difficult.

Reauthorisation

It is difficult to comment on the reauthorisation flow until a decision is made on the authorisation flow. This is because we believe the two decisions are interlinked. Noting that few customers will have a need to reauthorise on February 2020, our recommendation also depends on the timeframe with which reauthorisation must be implemented. If reauthorisation must be implemented for February 2020, our recommendation is that the reauthorisation flow should follow the same approach as the authorisation flow. If it need not be implemented for February 2020, then the decision should be deferred until the authorisation flow approach is clear.

Customer Endpoint

• lastUpdateTime should be optional in both CommonPerson and CommonOrganisation – this is frequently unavailable for us.

[anzbankau]

Error object

Currently in the payload conventions:

https://consumerdatastandardsaustralia.github.io/standards/#payload-conventions

It is stated that: If the response is unsuccessful (not 200 OK) the root object: MUST contain an errors object

As per our discussion this payload isn't required for all non-200 responses - only for specific scenarios.

NFRs

With regards to the NFR document which threshold does get account balance and the scheduled payments fall in?

We are assuming the low threshold, if so could this be reflected in the document?

[NationalAustraliaBank]

HTTP Headers
https://consumerdatastandardsaustralia.github.io/standards/#http-headers
NAB requests the following changes to the CDS for HTTP Headers:

• Inclusion of the original user agent of the customer device, as a request header, if the customer is currently logged in. This information is important to Data Holder's risk based decisioning and fraud data correlation, and must be mandatory for customer attended traffic. Refer to Decision Proposal 010 - Standard HTTP Headers #10 and https://github.com/ConsumerDataStandardsAustralia/open-banking/files/2419915/Decision.010.-.Standard.HTTP.Headers.pdf on previous consideration of this attribute.
• Inclusion of x-fapi-customer-id request header which must be mandatory for customer attended traffic. This information is important to Data Holder's risk based decisioning and fraud data correlation. Refer to Decision Proposal 021 - Non-functional Requirements #21 (comment) for our previous feedback.
• x-fapi-auth-date request header to be made mandatory, even for unattended traffic. This information is important to Data Holder's risk based decisioning and fraud data correlation.
• Standardising optionality table layout across request and response headers. Refer to Decision Proposal 021 - Non-functional Requirements #21 (comment) for our previous feedback and Decision Proposal 021 - Non-functional Requirements #21 (comment) for consideration.

Authorisation scopes
https://consumerdatastandardsaustralia.github.io/standards/#authorisation-scopes
Security authorisation scopes on Transaction endpoints is too broad. Standards must introduce different security scopes based on the level of data shared in each Transaction endpoint, as NAB has previously recommended. I.e. basic, detailed, sensitive.
Alternatively, fine-grained permissions supported through a Consent API (or similar capability) can be used to align to the CDS CX recommended permission language for Transactions, without changing the authorisation scope.
With respect to supporting fine-grained permissions, the CDS CX Phase 1 report also recommends applying the data minimization principle to the data time frame in the future and the past - third party providers should only request the time frame they require to provide the service, e.g. 1 year prior and post consent for an accounting tool. This principle can be addressed through the introduction of a Consent API (or similar capability) into the CDS. Please refer to NAB's response to #71 regarding the Consent API.

Account creation date
https://consumerdatastandardsaustralia.github.io/standards/#tocSresponsebankingaccountlist
As mentioned previously, #52 (comment), NAB requests a clear definition and interpretation of what the creationDate field represents and how it can be used. Using the account creation date and time to infer the relationship length between the customer and the Data Holder is misleading when taking into consideration the CDR data extents and the way accounts could be closed and then opened. Scenarios such as lost & stolen card replacement process, or product swap scenarios which involve a new contract date that is different the underlying account creation date. The account creation date and time is valid data and it could be misleading under certain use cases.

isPreferred flag for phoneNumbersand emailAddresses objects
https://consumerdatastandardsaustralia.github.io/standards/#tocScommonphonenumber (conditional)
https://consumerdatastandardsaustralia.github.io/standards/#tocScommonemailaddress (mandatory)
Previous feedback to make both fields conditional for structural consistency and alignment to the field's description has not yet been incorporated or has regressed, see #59 (comment)

Get Metrics API alignment to Decision 21
https://consumerdatastandardsaustralia.github.io/standards/#tocSresponsemetricslist
Get Metrics endpoint has peak and average TPS. Approved NFR decision from #21 has peak and current TPS. If Data Holders should be reporting current TPS, then no historical data is required in the API structure.

paymentSet in Scheduled Payments type
https://consumerdatastandardsaustralia.github.io/standards/#tocSbankingscheduledpayment
paymentSet object should be of type [BankingScheduledPaymentSet] (array).

Description of amount in Scheduled Payments
https://consumerdatastandardsaustralia.github.io/standards/#tocSbankingscheduledpaymentset
The description of the amount field is duplicated from isAmountCalculated.

[CDR-API-Stream]

Hi All, this is the new persona for the CDR API Stream that will be used for posting by the Data Standards Body. You can expect to see more interactions from this profile as we continue to progress.

Thank you all for the contributions to date for this consultation. The consultation period is now complete and this thread will be closed for further posting. The submissions provided via email will be added here, however.

A new thread for holistic (API and InfoSec) feedback will be opened shortly for ongoing feedback.

[CDR-API-Stream]

Please find attached the feedback submission received from the Australian Banking Association
ABA Standards Submission - FINAL.pdf

[CDR-API-Stream]

Please find attached the feedback submission received from AGL
AGL submission - Consumer Data Standards - 21 June 2019.pdf

[CDR-API-Stream]

Please find below the feedback submission received from ARCA (excerpt of email received)

Here’s our feedback on the data standards:

• The draft Rules (in 1.3 of Schedule 2) lists specific types of information that are (one of) customer data, account data, transaction data and product specific data. It then provides that “any other information that is specified in the data standards as being customer data/account data/transaction data/product specific data” is also captured. Therefore, unless a type of data is specifically listed in 1.3, it must be designated as being customer data/account data/transaction data/product specific data in the data standards. At this point, we don’t see a statement in the draft standards that clearly defines particular elements of the payloads as being one of those specified data types. For example, ‘occupation code’ arguably does not come within any of the specific forms of ‘customer data’ listed in 1.3. For the Rules to require a data holder to share occupation code, the data standards need to state that it is customer data. How will this be done in the Standards? (Noting that this appears to require a form of ‘legal drafting’ rather than the technical drafting of the Standards).
• Product reference data: We note the approach to PRD allows more latitude for data holders to interpret the requirements (where conventions will be implemented to improve consistency). This data is likely to be used by data recipients to provide financial product related advice, comparisons and recommendations. On that basis, we recommend that Data61 engage with ASIC to work through some of the implications that may arise out of the approach taken (e.g. whether there is a higher likelihood that the advice, comparisons and recommendations may be incorrect; whether ASIC has particular expectations on the conventions adopted; whether warnings to consumers are necessary when giving the advice, comparison and recommendations etc).

[CDR-API-Stream]

Please find attached the feedback submission received from BPAY
BPAY_StandardsFeedback-June_2019.pdf

[CDR-API-Stream]

Please find attached the feedback submission received from ID Exchange
API_idexchange_digi.me 210619.pdf

[CDR-API-Stream]

Please find attached the feedback submission received from FinTech Australia
Fintech Australia_ Open Data - Consumer Data Standard submission May Final.docx.pdf

[CDR-API-Stream]

Please find attached the feedback submission received from Visa
Visa_CDR Data61 submission June 2019.pdf

[CDR-API-Stream]

Please find attached a summary of the feedback received for the May draft across API standards and InfoSec streams. This document has been used to help focus discussions amongst participants and to assist the Chair in making the decisions arising from the consultation process.

This document has also been provided to the Advisory Committee for review and discussion in the July 10th meeting.

Draft Standards Feedback Summary - v0.9.3 May 2019.pdf

[CDR-API-Stream]

Please find attached the approved decision document responding to the majority of the feedback in response to the May 2019 draft standards. Note that decisions for Consent and Authorisation Flow will be published separately.
Decision 070-071 - May Draft Consultation Response.pdf

(note: minor wording update to the attached document made 10:17am 15th July)