Clarification needed: Interpretation of the Data Model for the ExtensionList element

[elnyry-sam-k]

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

___

This section contains basic information regarding the change request.

1.1 Change Request Information

Requested By	Change Request Status	Approved/Rejected Date
Sam Kummary, ModusBox	In review ☒ / Approved ☐ / Rejected ☐

1.2 Document Version Information

Version	Date	Author	Change Description
1.0	2020-02-20	Sam Kummary	Initial version. Discussed with CCB on 11Feb2020

2. Problem Description

___

2.1 Background

This is regarding the interpretation of the extensionList element's Data Model, from sections 7.4.4 of the API Definition v1.0. This element is present in several complex data structures used for quotes, transfers, error information and such others.

2.2 Current Behaviour

For ease of reference, here's the data model for extensionList (Section 7.4.4), taken from the API Definition v1.0 document.

ExtensionList

Table 72 contains the data model for the complex type ExtensionList.

Table 72

| Name | Cardinality | Format | Description |
| --- | --- | --- | --- |
| extension | 1..16 | Extension | Number of Extension elements. |

A representation of this in a Open API / Swagger looks like below:

extensionList:
{
  extension:
  [ 
    { 
      “key”: “item1”, 
      “value”: “Description for item1” 
    }, 
    { 
      “key”: “item2”, 
      “value”: “Description for item2” 
    }
  ]
}

This is how the current v1.0 Swagger (a supporting file of the Specification document set) represents the extensionList element, as can be seen here.

However, some of the examples given in the Specification document set indicate either a different interpretation of the data model definition or an error, which is making this ambiguous.

1. Here's an example from the API Definition:
   https://github.com/mojaloop/mojaloop-specification/blob/master/documents/API%20Definition%20v1.0.md#listing-5

{
    "errorInformation": {
        "errorCode": "3001",
        "errorDescription": "The Client requested an unsupported version, see exten-
sion list for supported version(s).",
        "extensionList": [
            { "key": "1", "value": "0"},
            { "key": "2", "value": "1"},
            { "key": "4", "value": "2"},
        ]
    }
}

2. Here's another example from the Encryption document:
   https://github.com/mojaloop/mojaloop-specification/blob/master/documents/Encryption.md#41-encryption-example

"extensionList": [
        { "value": "value1", "key": "key1"},
        { "value": "value2", "key": "key2"},
        { "value": "value3", "key": "key3" }
    ]

2.3 Requested Behaviour

There seems to be a need to clarify the data model so that it eliminates ambiguity. This may be done by providing examples of each type, one each for Simple, Complex types and some others so that they can be representative of how the data model definitions are to be interpreted.

It may also be moved to the proposed "Implementation Guide" document. However, the example already present in the Specification documents will need to be updated if they're found to be incorrect.

3. Proposed Solution Options

___

This may or may not need a change directly to the data model, but I think having a consensus regarding the interpretation and adding examples for the data structures representing each type would eliminate scope for misinterpretation. As mentioned above, the existing examples need to be reviewed for accuracy.

[henrka]

The given examples in the specification documents (Listing 5 in API Definition and the one in Encryption) are incorrect as per the defined data model and should be updated. The Swagger version is correct.

[elnyry-sam-k]

Thanks Henrik.

[henrka]

Sam, it looks like this issue has been fixed in the version 1.1 document (I have only checked API Definition as of now), should this not be in the #52 issue?

[elnyry-sam-k]

hi Henrik, it is included as item #5. Thank you..

[henrka]

@elnyry-sam-k, the document set for v1.1 (https://github.com/mojaloop/mojaloop-specification/tree/master/fspiop-api/documents/v1.1-document-set) does not contain the Encryption document v1.1. As this bug with incorrect representation for the extensionlist in the documents was also present in that document, it should also have been updated for v1.1. Have this been updated but not just added to the document set folder?

[elnyry-sam-k]

Thanks Henrik @ehenrka , you're right, Encryption was missing from the v1.1 doc set.

If this version looks good to you, I'll upload it (sections 1.2, 4.1, 4.1.3 have changed):
Encryption_v1.1.pdf

[henrka]

Thanks @elnyry-sam-k, just a tiny little styling comment.. The quotation marks around extension are not of the exact same style as the other quotation marks. Compare with for example the extensionList above. Can you please fix before upload?

[elnyry-sam-k]

Thanks Henrik, will fix it and upload :-)

[elnyry-sam-k]

Fixed and uploaded here: https://github.com/mojaloop/mojaloop-specification/tree/master/fspiop-api/documents/v1.1-document-set.

@ehenrka I think we can close this now

[henrka]

Yes, it should be fixed now in every document where it was present.