Decision Proposal 003 - Extensibility Model

[JamesMBligh]

This decision proposal outlines a recommendation for how the standards can be extended to incorporate provider specific fields, end points or API categories. The detail for the proposal is in the attached PDF.

This proposal is closely aligned to the proposal for the URI parameters so substantial change to that proposal will impact this one. For this reason the feedback dates have been aligned. If this timing creates a problem please indicate such in your feedback.

Feedback is now open for this proposal. Feedback is planned to be closed on the 17th August.
Decision Proposal 003 - Extensibility Model.pdf

[ggotti]

I agree with "Option 2 - In Place Extension" being the better of the two approaches, but I have some concerns with the details.

• I'm not sure that we should be enforcing any kind of provider identifier. The line "agreement on the prefix would be made between the provider and the data standards body" seems like additional maintenance overhead, with little reward.
• I'd prefer that you provide some kind of "generic" prefix, like 'x-' if providers want to add additional endpoints. That way there is never the possibility of naming collisions. So instead of:
  <base path>/account/{account ID}/<PID>-balancemovement
  You could have
  <base path>/account/{account ID}/x-balancemovement
• Obviously pointing back to the discussion in Decision Proposal 002 - URI Structure #2, provider's should return relationship links within the primary response, so that their extensions can be identified. We don't want to discourage providers from adding additional data, and we want to be able to surface that additional data quickly if it's available.

[perlboy]

As I understand it Option 1 involves having a common "generic" data model interface + a URI path that is potentially versions/implementation specific. This would imply a master data model that is extended but only scoped once the implementation specific path is hit? Option 2 would imply that the data model can be extended from an end point at any point in time but would discount custom modifications?

I think there's two separate components here:

1. Defining whether a data model's extension (ie. "GenericAUDAccount" versus "SuperSaverAUDAccount" extending "GenericAUDAccount") can occur with/without scoping.

I'll point out here that scoping doesn't implicitly need to be solved in the URI path because the SAML/OAUTH/Swagger layer provides a scoping capability that is probably preferable given the potential data flow.

2. Is this initiative focused just on the generic URI naming? If so are we intending to allow bank specific customisation for things that aren't currently defined?

I personally would say that this should primarily be focused on that generic namespace but that there is a facilitation to allow custom methods with the idea being that they may eventually be adopted into the generic namespace if applicable.

That could start out as easily as saying:

1. Stick to /< PID >-[functionname] when setting up a bank specific process.
2. If adopted as generic, performing API side aliasing in the future isn't a particularly challenging technical impost.
3. If it's some new fandangled bank specific product requirement there may be some sort of "You must supply all the generic methods for this bank account type as well" so external parties can degrade gracefully. I guess enforcing that is outside the scope of this definition.

RE: x-[functionname] or /[functionname] aside, that's a style guide thing.

OpenBankingUK (and most of OBP) uses /[functionname]. Not sure I agree with it entirely (locks you in) but it's what is there now?

[speedyps]

I think the preferred Option 2 is the more workable solution.

I agree with @perlboy that an implementer must still provide the generic methods relating to the entity they are extending (ie a specific Bank account product). There may be cases where the response they want to provide is not one that falls under an existing one, but the established pattern would need to be followed.

With regards to extending within an existing payload, would we consider a grouping of the implementer specific data.

eg
"Accounts": [ { "AccountId": "1000000001", "Currency": "AUD", "AccountType": "Business", "AccountSubType": "CurrentAccount", "Description": "Online Current Account", "Nickname": "Business A Current Account", "Account": [ { "SchemeName": "BSBAccountNumber (AU/NZ)", "Identification": "99999912345678", "Name": "BUS ONLINE CURRENT ACCOUNT" } ], "<PID>": { "SpecialField1": "Value 1", "SpecialField2": "Value 2" } }

[JamesMBligh]

The key piece of feedback seems to relate to the "-" concept versus "x-". The reason that I introduced the concept of the three letter acronym that is provider specific for extension is that most customers will be multi-banked. In many scenarios a client will be calling multiple providers to obtain data on the same customer.

It is possible that there will be many scenarios where the same APIs, with extension data, are obtained from multi-providers. In these scenarios, some form of name spacing would definitely assist with the client implementations, especially if the data is being persisted.

For example, I can imagine a situation where an array of account data is held from multiple Banks that creates a full view of a customer financial position and each entry in the array has different extension fields based on who the provider is. That was the key driver for the PID concept.

I do acknowledge the management overhead it would entail if the string for each provider needed to be registered. We could manage it without that requirement I guess. This could also be decided later as it doesn't technically change the standard.

Any additional feedback is welcome.

-JB-

[TKCOBA]

COBA supports Data61’s proposed introduction of a Provider Identifier (PID) to distinguish proprietary extensions and that the PID should be prefixed to proprietary end-points and fields.

However, COBA suggests that the PID should also be prefixed to proprietary API paths, not as proposed as part of a standardised URI, but as part of a dynamic discovery document structure.

[JamesMBligh]

I have now closed consultation on this decision. A recommendation incorporating feedback will be made to the Chair in due course.

-JB-

[JamesMBligh]

The finalised decision for this topic has been endorsed. Please refer to the attached document.
Decision 003 - Extensibility Model.pdf

-JB-