Change Request: Identifying message formats in headers

[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

___

This section contains basic information regarding the change request.

1.1 Change Request Information

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

1.2 Document Version Information

Version	Date	Author	Change Description
1.0	2024-10-17	Michael Richards	Initial version of issue. Sent out for review.

2. Problem Description

___

2.1 Background

At present, the Accept parameter in the message header represents the API version that the sender of a message would like to use. This enables version negotiation between participants, and is currently defined here.

The Accept parameter is structured in the following way:

• An application type The application type is always application/vnd.interoperability.{resource}, where {resource} is the actual resource (for example, participants or quotes).
• A data exchange format. The only data exchange format currently supported is json.
• A version number.
  • If a client can use any minor version of a major version, only the major version should be sent; for example, version=1 or version=2.
  • If a client would like to use a specific minor version, this should be indicated by using the specific major.minor version; for example, version=1.2 or version=2.8. The use of a specific major.minor version in the request should generally be avoided, as minor versions should be backwards-compatible.

For example: Accept: application/vnd.interoperability.transfers+json;version=1

When we consider the implementation of message content based on ISO 20022 alongside one based on FSPIOP, we shall need to consider whether the structure of the Accept parameter needs to be changed to specify the structure of the message content; and, if so, how this should be done.

2.2 Current Behaviour

The current structure of the Accept parameter does not allow for distinctions of message structure.

Since the resource type is currently used to allow participants to support different versions of individual resources (for instance, it would allow a DFSP to support version 1.1 of PISP and version 2 of transfers), using this part of the parameter to define the structure of the message content would remove this flexibility.

2.3 Requested Behaviour

There are basically two approaches:

1. Leave the Accept parameter as it is, and allow the structure of the message content (ISO 20022 or FSPIOP) to be implicit as regards the header.
2. Modify the Accept parameter to include the structure of the message content. Given the constraints described above, this would mean adding a new field to the Accept parameter.

Changing the structure of the Accept parameter would require changes to the ways in which DFSPs and the switch evaluate the validity of a message.

3. Proposed Solution Options

The proposed solution is to modify the Accept and Content-Type parameters to define explicitly the content format used in the body of the message. The new definition of the syntax of the Accept and Content-Type parameters will be:

• An application type The application type is always application/vnd.interoperability.{messagetype}.{resource}, where {messagetype} is the format used for the message (for example, fspiop or iso20022), and {resource} is the actual resource (for example, participants or quotes).
• A data exchange format. The only data exchange format currently supported is json.
• A version number.
  • If a client can use any minor version of a major version, only the major version should be sent; for example, version=1 or version=2.
  • If a client would like to use a specific minor version, this should be indicated by using the specific major.minor version; for example, version=1.2 or version=2.8. The use of a specific major.minor version in the request should generally be avoided, as minor versions should be backwards-compatible.

For example: Accept: application/vnd.interoperability.iso20022.transfers+json;version=1

If no message type is given in the Accept and Content-Type parameters, then a recipient of the message should assume that the message format being used is fspiop. If one of the Accept and Content-Type parameters specifies a message format and the other does not, then a recipient of the message should assume that the message format being used is the one explicitly specified. If the Accept parameter and the Content-Type parameter specify different message formats, then a recipient of the message should report an error.

---

[bushjames]

@PaulGregoryBaker would you mind outlining your proposed solution here so we can discuss at the next available opportunity. Many thanks.