Change Request: no additional properties should be allowed at requests and responses other than those defined at FSPIOP API

[gibaros]

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

___

No additional properties should be allowed at requests and responses other than those defined at FSPIOP API.

1.1 Change Request Information

| Requested By | Juan Correa, Mojaloop |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date | |

1.2 Document Version Information

Version	Date	Author	Change Description
1.0	2022-05-17	Juan Correa	Initial version. Sent out for review.

2. Problem Description

___

2.1 Background

The FSPIOP API Specification Swagger at:

https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/fspiop-v1.1-openapi3.yaml

should be the ultimate source of truth and as such it should explicitly specify what fields are allowed on a request/response.

Currently, it uses OpenAPI mechanisms to signal which fields are required. Which allows for specifying which fields are mandatory and which are optional.

However, it leaves the door open for fields not defined at the FSPIOP API Swagger to be allowed on requests/responses. In terms of impact at a minimum these extra fields are adding to the payload size of requests and responses, but there could be additional unwated side effects, for example:

https://apisecurity.io/encyclopedia/content/oasv3/datavalidation/schema/v3-schema-object-additionalproperties-true.htm

2.2 Current Behaviour

Additional properties others than those defined at the Swagger are allowed at requests and responses.

By default, if left unspecified, additionalProperties is set to true.

2.3 Requested Behaviour

No additional properties should be allowed at requests and responses other than those defined at FSPIOP API Swagger.

3. Proposed Solution Options

___

Possibly, per https://swagger.io/specification/#schema-object and http://json-schema.org/understanding-json-schema/reference/object.html#additional-properties the additionalProperties could be be employed and set to false to not allow additional properties at requests and responses.

[henrka]

Thanks @gibaros, I agree that additionalProperties should be set to false to deny additional properties. I failed to find in the API Definition now that we have explicitly documented that it should be like that, but that has been my intention at least.. If it's not documented there, then we should also update the API Definition to be more clear about this. I will have another look in the documentation.

[henrka]

Sorry for not getting back earlier regarding this change request. It seems like we need to update the API Definition document as well, I have failed to find any mention of this. My suggestion is to document it as part of the Section Data Exchange Format in a subsection like the below:

Additional Parameters
Only the documented mandatory and optional parameters as part of the data model for each respective API service are allowed to be sent in a request or callback. Any additional parameters that are not documented in the data model are not allowed to be sent.