Change Request: Adding ExtensionList fields to existing data structures

[MichaelJBRichards]

Open API for FSP Interoperability - Change Request

Table of Contents

• 1. Preface
  • 1.1 Change Request Information
  • 1.2 Document Version Information
• 2. Problem Description
  • 2.1 Background
  • 2.2 Current Behaviour
  • 2.3 Requested Behaviour
• 3. Proposed Solution Options

1. Preface

---

Additional data is required for some existing data items in order to meet the particular requirements of individual implementations.

• When registrations are made using the /participants resource, DFSPs need to be able to specify the transaction account to which transfers to the new ID will be credited, and in the case of Merchant IDs the Tax Identification Number (TIN) for the merchant. This requires the addition of an ExtensionList field to the PartyIdInfo data structure.

• When information is returned from a call to the /parties resource, and when it is included in a request sent to the /quotes resource, additional information about the party needs to be included. This includes identifying what TransactionInitiatorType the party belongs to, and whether the party's account is a bank account or a wallet. This requires the addition of an optional ExtensionList field to the Party data structure.

1.1 Change Request Information

| Requested By | Michael Richards, ModusBox |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date | |

1.2 Document Version Information

Version	Date	Author	Change Description
1.0	2019-02-04	Michael Richards	Initial version of template. Sent out for review.

2. Problem Description

The implementation of the Open API in TIPS has revealed the need for additional data to be passed between participants in the system. The normal pattern for adding implementation-specific details to calls in the Open API is via the use of an ExtensionList field(see Open API Specification, Section 7.4.4) However, some data items as defined in the specification do not contain ExtensionList fields, and these data items cannot therefore have additional information added.

2.1 Background

Specific instances where data structures in the existing Open API definition need to have specialised data associated with them are:

• When registrations are made using the /participants resource, DFSPs need to be able to specify the transaction account to which transfers to the new ID will be credited, and in the case of Merchant IDs the Tax Identification Number (TIN) for the merchant. This requires the addition of an ExtensionList field to the PartyIdInfo data structure.

• When information is returned from a call to the /parties resource, and when it is included in a request sent to the /quotes resource, additional information about the party needs to be included. This includes identifying what TransactionInitiatorType the party belongs to, and whether the party's account is a bank account or a wallet. This requires the addition of an optional ExtensionList field to the Party data structure.

2.2 Current Behaviour

It is not possible to add implementation-specific information to the Party data structure or the PartyIdInfo data structure.

2.3 Requested Behaviour

Allow the addition of implementation-specific information to the Party data structure and the PartyIdInfo data structure.

3. Proposed Solution Options

Add an Extensionlist data structure to the Party data structure and the PartyIdInfo data structure.

[henrka]

Sounds good! The proposal would mean though that the Party data model would then contain two extension lists, one directly on the Party and one under the partyIdInfo element, which I do not really like as it would be hard to know which one of them to use. Would it be enough to have only an extension list on the PartyIdInfo, as you would be able to add the extensions in the Party anyway?

To make the proposal complete, an extension list should also be added to the POST /participants/<Type>/<ID> and POST /participants/<Type>/<ID>/<SubId> requests as well. Those requests are used for adding single participant information, compared to the POST /participants request which is used for bulk add of participant information (where the partyIdInfo is used).

[MichaelJBRichards]

I agree that it would mean that the Party data model would then contain two extension lists; however, I thought it would be less confusing to have the extension list attached to the Party object, since it would be used for passing information about the party rather than the FSP.

With respect to adding a list to the participants resource, I shied away from that because it would have meant adding a message body where none currently exists. TIPS are happy with preventing use of the resources without content and insisting that the PartyIdInfo structure is used to pass the information.

However, I'm not unhappy with your suggestions in both cases

[henrka]

I agree that it would mean that the Party data model would then contain two extension lists; however, I thought it would be less confusing to have the extension list attached to the Party object, since it would be used for passing information about the party rather than the FSP.

The partyIdInfo is not for FSP information only. It is for information regarding how the party (or a specific account under a party) is identified, where one of the elements is for saying in which FSP the party is located in. The party could also be for example identified by its Tax Identification Number (TIN), or Merchant ID (from the background of the change request). If the change request is not for identifying a party (or a specific account under a party), then this information should not really be registered in the Account Lookup System using POST /participants/, it should rather be retrieved from the FSP using GET /parties, if the ALS should continue to be a light weight ALS.

With respect to adding a list to the participants resource, I shied away from that because it would have meant adding a message body where none currently exists.

There is already message body in POST /participants/<Type>/<ID>? Please see Section 6.2.2.3 in API Definition. Are you talking about another service?

[mjbrichards]

I'm not sure why we want to legislate about how people ought to use the API. My feeling is that we should probably allow an extension list somewhere on every resource, so that people who want to include additional information in it can do so, provided that they all agree how it should be done. For me, it's not a question of "(knowing) which to use," but simply of providing facilities.

[henrka]

I'm not against having extension lists on every resource, but at the same time I would like to limit the use of extensions as they are very hard to maintain in code that should be reused between schemes, and it makes interoperability between schemes more difficult as they might require different extensions.

My suggestion as earlier is to add the extension list to the PartyIdInfo, which will allow it to be used in POST /participants/. For consistency it should also be added in the POST /participants/<Type>/<ID> and POST /participants/<Type>/<ID>/<SubId>. This should be sufficient for the first bullet in the background information.

Regarding the second bullet in the background information:

• The type of the Party is already part of Adding detail to transaction type definition #25.
• For the type of account (wallet or bank account), you should be able to set that in the PartyIdInfo extension list. Another alternative would be to add the proposed Account data type from Consolidated Change Proposal #22, and set a type of account in that.

[henrka]

This does not seem to be part of the API version 1.1 document ("API Definition_v1.1-draft_Updated-2020-04-07.docx"). Though there is a "Hold me" text added in Section 6.2.3.3..

[elnyry-sam-k]

Hi Henrik, Table-92 under Section 7.4.13 - PartyIdInfo has been updated to include the optional ExtensionList element.

[henrka]

Yes, but for consistency it also needs to be added to Table 9 in Section 6.2.3.3 for the POST /participants/<Type>/<ID> and POST /participants/<Type>/<ID>/<SubId>, where the "Hold me" text is currently located (see my earlier comment #30 (comment)).

[henrka]

Another issue is that all resources using the PartyIdInfo element in some way should be updated to new minor version (1.1) to reflect the changes in what data that can be expected. That should include all the resources except /authorizations and /transactions, as the rest uses either PartyIdInfo directly or through the Party element.

[elnyry-sam-k]

Thanks Henrik.

How does this version look with the above suggested changes included -
API Definition_v1.1-draft_Updated-2020-04-14.docx

[henrka]

Thanks Sam, please find some comments on the new version below:

• Typo in Table 7 ("ExtensioinList"):

The data model is updated to add an optional ExtensioinList element ..

• The text "Hold me" is still present after Table 9, just before Section 6.2.3.4

• Please update Table 6 to the latest version per resource. See /transfers in Table 6 as an example.

• Table 17 (and 21 and 36), version 1.1, does not need to mention the POST /participants stuff as it has nothing to do with the /parties resource (same for /transactionRequests and /bulkQuotes resources).

• /transfers and /bulkTransfers are also affected by the change in the Party element, through the Transaction complex type which is in the ILP Packet of these two resources. /transfers is already at version 1.1, but this change should also be mentioned there. /bulkTransfers is only at version 1.0 in the document, as such it needs to be updated to version 1.1.

[elnyry-sam-k]

Thanks again, Henrik.

Here's the updated draft - API Definition_v1.1-draft_Updated-2020-04-15.docx

[henrka]

Thanks Sam, Your changes looks great!

Just a tiny layout comment regarding Table 6, the table is split so that only the header is on page 79 and the rest of the table is on page 80. Select the entire paragraph including the text just above (starting with "Table 6 contains the version for each resource that ...") and click on "Keep with next" so that it is ticked.

[elnyry-sam-k]

Alright, thank you.

Here's the updated draft: API Definition_v1.1-draft_Updated-2020-04-16.docx

[henrka]

Hi @elnyry-sam-k, I think this issue can be closed as this was updated in v1.1?

[elnyry-sam-k]

Thanks Henrik; Yes, as we discussed today