Giters

mojaloop / mojaloop-specification

This repo contains the specification document set of the Open API for FSP Interoperability

Home Page:https://docs.mojaloop.io/api

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

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

elnyry-sam-k opened this issue · comments

commented

Open API for FSP Interoperability - Change Request

Table of Contents

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"},
        ]
    }
}
  1. 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.

commented

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.

commented

Thanks Henrik.

commented

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?

commented

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

commented

@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?

commented

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

commented

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?
image

commented

Thanks Henrik, will fix it and upload :-)

commented

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