foreign-exchange-swaps.yaml

openapi: 3.0.3
info:
  title: Bankable Assets API - FX Swaps
  version: 0.1.0
  description: >-
    # Summary

       Foreign exchange trade initiation and execution for FX swap. 

       The API is to initiate and execute foreign exchange swap transactions. 
       
       A foreign exchange swap transaction, forex swap or fx swap is a combination of a spot transaction (or forward transaction) 
       and an inverse forward transaction. An FX swap agreement is a contract in which one party borrows one currency in exchange 
       of another currency and repays at the end of the contract at the contractual rate. 

    # Use Cases

      This API covers the following use cases for **private clients** and **external asset managers**:

      1. Retrieve all available information regarding current and completed orders, including their status

      2. Request foreign exchange swap for a single client account 

      3. Request the cancellation of a not executed foreign exchange swap.

    # General Remarks

    * This API definition is inspired by the ISO 20022 standard messages
      [ForeignExchangeTradeCaptureReportV01 (fxtr.031)](https://www.iso20022.org/standardsrepository/type/fxtr.031.001.01),  
      [ForeignExchangeTradeInstructionV04 (fxtr.014)](https://www.iso20022.org/standardsrepository/type/fxtr.014.001.04) and 
      in coordination with the Bankable Assets API for Securities Orders. 

    * Schemas are generally based on datatype definitions with the same name in the
      [ISO 20022 Repository](https://www.iso20022.org/standardsrepository).
      In some cases, schemas may correspond to a restrictive version of the standard datatype definition without some
      or all optional fields.
      Any other deviations to the standard datatype definition are explicitly described below.

    * Pagination is not described in any defined
      [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#operation-object).
      A productive implementation of this API may support additional query parameters for implementing pagination
      according to the possibilities of the underlying systems.
      These additional query parameters must be optional and they must not clash with any parameter here defined.

      To allow implementing pagination and avoid clashes, this API will not use the following parameters names
      in this or future versions of the API: `limit`, `offset` and `cursor`.

    * According to the definition of
      [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#parameter-object)
      in the OpenAPI Specification:
      *If `in` is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter
      definition SHALL be ignored.* Therefore:
      * The parameter `"Accept"` will not be defined in this file at any place.
      * The parameters `"Content-Type"` and `"Authorization"` are implicitly defined by the fields `content` in
        [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#response-object)
        and `security` in
        [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#operation-object).

  contact:
    name: Open Banking Project Switzerland
    url: https://www.openbankingproject.ch
    email: info@obp.ch

servers:
  # --------------------------------------------------------------------------------------------------------------------
  # SERVERS
  # --------------------------------------------------------------------------------------------------------------------
  - url: /api1/foreign-exchange-swaps
    description: Development server

paths:
  # --------------------------------------------------------------------------------------------------------------------
  # PATHS
  # --------------------------------------------------------------------------------------------------------------------

  /orders:

    get: # OrderCollection
      tags:
        - Orders
      summary: Get all foreign exchange swap orders
      description: >-
        Get a collection of foreign exchange swap orders.
      operationId: getOrders
      parameters:
      - $ref: '#/components/parameters/Accept-Language'
      responses:
        '200':
          $ref: '#/components/responses/OK_200_OrderCollection'
        '400':
          $ref: '#/components/responses/BAD_REQUEST_400'
        '401':
          $ref: '#/components/responses/UNAUTHORIZED_401'

    post: # OrderCreation
      tags:
        - Orders
      summary: Add new foreign exchange swap order
      description: >-
        Generate new foreign exchange swap order
      operationId: postOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForeignExchangeSwap'
      responses:
        '201':
          $ref: '#/components/responses/CREATED_201_OrderCreation'
        '202':
          $ref: '#/components/responses/ACCEPTED_202_OrderCreation'
        '400':
          $ref: '#/components/responses/BAD_REQUEST_400'
        '401':
          $ref: '#/components/responses/UNAUTHORIZED_401'
        '403':
          $ref: '#/components/responses/FORBIDDEN_403_Post'
        '405':
          $ref: '#/components/responses/METHOD_NOT_ALLOWED_405_Post'

  /orders/{orderIdentification}:

    get: # Order
      tags:
        - Orders
      summary: Get foreign exchange swap order
      description: >-
        *Get foreign exchange swap order identified by `orderIdentification`*.
      operationId: getOrder
      parameters:
      - $ref: '#/components/parameters/OrderIdentification'
      - $ref: '#/components/parameters/Accept-Language'
      responses:
        '200':
          $ref: '#/components/responses/OK_200_Order'
        '400':
          $ref: '#/components/responses/BAD_REQUEST_400'
        '401':
          $ref: '#/components/responses/UNAUTHORIZED_401'
        '403':
          $ref: '#/components/responses/FORBIDDEN_403'
        '404':
          $ref: '#/components/responses/NOT_FOUND_404'

    put: # OrderModification
      tags:
      - Orders
      summary: Update foreign exchange swap order
      description: >-
        *Update foreign exchange swap order identified by `orderIdentification`.*
      operationId: putOrder
      parameters:
      - $ref: '#/components/parameters/OrderIdentification'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForeignExchangeSwap'
      responses:
        '200':
          $ref: '#/components/responses/OK_200_OrderModification'
        '202':
          $ref: '#/components/responses/ACCEPTED_202_OrderModification'
        '400':
          $ref: '#/components/responses/BAD_REQUEST_400'
        '401':
          $ref: '#/components/responses/UNAUTHORIZED_401'
        '403':
          $ref: '#/components/responses/FORBIDDEN_403'
        '404':
          $ref: '#/components/responses/NOT_FOUND_404'
        '405':
          $ref: '#/components/responses/METHOD_NOT_ALLOWED_405_Put'

    delete: # OrderCancellation
      tags:
      - Orders
      summary: Delete foreign exchange swap order
      description: >-
        *Delete foreign exchange swap order identified by `orderIdentification`.*
      operationId: deleteOrder
      parameters:
      - $ref: '#/components/parameters/OrderIdentification'
      responses:
        '200':
          $ref: '#/components/responses/OK_200_OrderCancellation'
        '202':
          $ref: '#/components/responses/ACCEPTED_202_OrderCancellation'
        '400':
          $ref: '#/components/responses/BAD_REQUEST_400'
        '401':
          $ref: '#/components/responses/UNAUTHORIZED_401'
        '403':
          $ref: '#/components/responses/FORBIDDEN_403'
        '404':
          $ref: '#/components/responses/NOT_FOUND_404'
        '405':
          $ref: '#/components/responses/METHOD_NOT_ALLOWED_405_Delete'

  
components:
  # --------------------------------------------------------------------------------------------------------------------
  # COMPONENTS
  # --------------------------------------------------------------------------------------------------------------------
  
  headers:
    # ------------------------------------------------------------------------------------------------------------------
    # COMPONENTS/HEADERS
    # ------------------------------------------------------------------------------------------------------------------

    Accept-Language:
      description: >-
        List of acceptable human languages for response.
        [RFC 7231, Section 5.3.5]
      schema:
        type: string
      example: da, en-gb;q=0.8, en;q=0.7

    Content-Language:
      description: >-
        The natural language or languages of the intended audience for the enclosed content.
        [RFC 7231, Section 3.1.3.2]
      schema:
        type: string
      example: da

    Last-Modified:
      description: >-
        Timestamp indicating the date and time at which the origin server believes the selected representation
        was last modified, as determined at the conclusion of handling the request.
        [RFC 7232, Section 2.2]
      schema:
        type: string
      example: 'Tue, 15 Nov 1994 12:45:26 GMT' # HTTP-date

    Location:
      description: >-
        Used in redirection, or when a new resource has been created.
        [RFC 7231, Section 7.1.2]
      schema:
        type: string
      example: '/pub/WWW/People.html'

    WWW-Authenticate:
      description: >-
        Indicates the authentication scheme that should be used to access the requested entity.
        [RFC 7235, Section 4.1]
      schema:
        type: string
      example: 'Basic'

  parameters:
    # ------------------------------------------------------------------------------------------------------------------
    # COMPONENTS/PARAMETERS
    # ------------------------------------------------------------------------------------------------------------------

    OrderIdentification:
      name: orderIdentification
      in: path
      description: Identification for the order as assigned by the receiving party.
      required: true
      schema:
        $ref: '#/components/schemas/Max35Text'
      
    Accept-Language:
      name: Accept-Language
      in: header
      description: List of acceptable human languages for response. [RFC 7231, Section 5.3.5]
      schema:
        type: string
      example: da, en-gb;q=0.8, en;q=0.7

  responses:
    # ------------------------------------------------------------------------------------------------------------------
    # COMPONENTS/RESPONSES
    # ------------------------------------------------------------------------------------------------------------------

    OK_200_OrderCollection:
      description: >-
        The requested collection of foreign exchange swap order orders is delivered in the response.

        *The 200 (OK) status code indicates that the request has succeeded.*
        [RFC 7231, Section 6.3.1]
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ForeignExchangeSwap'

    OK_200_Order:
      description: >-
        The requested foreign exchange swap order is delivered in the response.


        *The 200 (OK) status code indicates that the request has succeeded.*
        [RFC 7231, Section 6.3.1]
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        Last-Modified:
          $ref: '#/components/headers/Last-Modified'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForeignExchangeSwap'

    OK_200_OrderModification:
      description: >-
        The foreign exchange swap order has been modified.


        *The 200 (OK) status code indicates that the request has succeeded.*
        [RFC 7231, Section 6.3.1]

    OK_200_OrderCancellation:
      description: >-
        The foreign exchange swap order has been cancelled.


        *The 200 (OK) status code indicates that the request has succeeded.*
        [RFC 7231, Section 6.3.1]

    CREATED_201_OrderCreation:
      description: >-
        The foreign exchange swap order has been accepted, processed and it is now available at the
        URI delivered in the Location header field of this response.


        *The 201 (Created) status code indicates that the request has been
        fulfilled and has resulted in one resource being
        created.  The resource created by the request is identified
        by a Location header field in the response.*
        [RFC7231, Section 6.3.2]
      headers:
        Location:
          $ref: '#/components/headers/Location'

    ACCEPTED_202_OrderCreation:
      description: >-
        The foreign exchange swap order has been accepted and will be processed asynchronously.


        *The 202 (Accepted) status code indicates that the request has been
        accepted for processing, but the processing has not been completed.
        The request might or might not eventually be acted upon, as it might
        be disallowed when processing actually takes place.  There is no
        facility in HTTP for re-sending a status code from an asynchronous
        operation.*
        [RFC 7231, Section 6.3.3]

    ACCEPTED_202_OrderModification:
      description: >-
        The order modification has been requested and the foreign exchange swap order is now waiting for the broker to accept
        or reject the modification.


        *The 202 (Accepted) status code indicates that the request has been
        accepted for processing, but the processing has not been completed.
        The request might or might not eventually be acted upon, as it might
        be disallowed when processing actually takes place.  There is no
        facility in HTTP for re-sending a status code from an asynchronous
        operation.*
        [RFC 7231, Section 6.3.3]

    ACCEPTED_202_OrderCancellation:
      description: >-
        The order cancellation has been requested and the foreign exchange swap order is now waiting for the broker to accept
        or reject the cancellation.


        *The 202 (Accepted) status code indicates that the request has been
        accepted for processing, but the processing has not been completed.
        The request might or might not eventually be acted upon, as it might
        be disallowed when processing actually takes place.  There is no
        facility in HTTP for re-sending a status code from an asynchronous
        operation.*
        [RFC 7231, Section 6.3.3]

    BAD_REQUEST_400:
      description: >-
        The request indicates that the server was unable to process the request sent by the client due to invalid syntax. 


        *The 400 (Bad Request) status code indicates that the server cannot or
        will not process the request due to something that is perceived to be
        a client error (e.g., malformed request syntax, invalid request
        message framing, or deceptive request routing).*
        [RFC 7231, Section 6.5.1]
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string

    UNAUTHORIZED_401:
      description: >-
        The request has no authentication credentials for the target resource or the authentication credentials
        are not valid.


        *The 401 (Unauthorized) status code indicates that the request has not
        been applied because it lacks valid authentication credentials for
        the target resource.  The server generating a 401 response MUST send
        a WWW-Authenticate header field (Section 4.1) containing at least one
        challenge applicable to the target resource.*
        [RFC 7235, Section 3.1]
      headers:
        WWW-Authenticate:
          $ref: '#/components/headers/WWW-Authenticate'

    FORBIDDEN_403:
      description: >-
        The request has valid authentication credentials but they are not sufficient for the server to grant access
        to the target resource.
        In case that the server wants to hide the fact that the target resource even exists it may send a
        404 (Not Found) status code instead of this 403 (Forbidden) status code.


        *The 403 (Forbidden) status code indicates that the server understood
        the request but refuses to authorize it.  A server that wishes to
        make public why the request has been forbidden can describe that
        reason in the response payload (if any).*
        [RFC 7231, Section 6.5.3]

    FORBIDDEN_403_Post:
      description: >-
        The request has valid authentication credentials but they are not sufficient for the server to allow the
        creation of the target resource.


        *The 403 (Forbidden) status code indicates that the server understood
        the request but refuses to authorize it.  A server that wishes to
        make public why the request has been forbidden can describe that
        reason in the response payload (if any).*
        [RFC 7231, Section 6.5.3]

    NOT_FOUND_404:
      description: >-
        The target resource could not be found or the authentication credentials are not sufficient for the server
        to grant access to it.


        *The 404 (Not Found) status code indicates that the origin server did
        not find a current representation for the target resource or is not
        willing to disclose that one exists.  A 404 status code does not
        indicate whether this lack of representation is temporary or
        permanent.*
        [RFC 7231, Section 6.5.4]

    METHOD_NOT_ALLOWED_405_Post:
      description: >-
        The creation of the target resource is not possible at this time.


        *The 405 (Method Not Allowed) status code indicates that the method
        received in the request-line is known by the origin server but not
        supported by the target resource.  The origin server MUST generate an
        Allow header field in a 405 response containing a list of the target
        resource's currently supported methods.*
        [RFC 7231, Section 6.5.5]

    METHOD_NOT_ALLOWED_405_Put:
      description: >-
        The modification of the target resource is not possible at this time.


        *The 405 (Method Not Allowed) status code indicates that the method
        received in the request-line is known by the origin server but not
        supported by the target resource.  The origin server MUST generate an
        Allow header field in a 405 response containing a list of the target
        resource's currently supported methods.*
        [RFC 7231, Section 6.5.5]

    METHOD_NOT_ALLOWED_405_Delete:
      description: >-
        The deletion of the target resource is not possible at this time.


        *The 405 (Method Not Allowed) status code indicates that the method
        received in the request-line is known by the origin server but not
        supported by the target resource.  The origin server MUST generate an
        Allow header field in a 405 response containing a list of the target
        resource's currently supported methods.*
        [RFC 7231, Section 6.5.5]

  schemas:
    # ------------------------------------------------------------------------------------------------------------------
    # COMPONENTS/SCHEMAS
    # ------------------------------------------------------------------------------------------------------------------

    AccountIdentification4Choice:
      description: Specifies the unique identification of an account as assigned by the account servicer.
      oneOf:
      - title: IBAN
        type: object
        description: >-
          International Bank Account Number (IBAN) - identifier used internationally by financial institutions to
          uniquely identify the account of a customer. Further specifications of the format and content of the IBAN
          can be found in the standard ISO 13616 "Banking and related financial services - International Bank Account
          Number (IBAN)" version 1997-10-01, or later revisions.
        properties:
          iban:
            $ref: '#/components/schemas/IBAN2007Identifier'
        required:
        - iban
      - title: Other
        type: object
        description: >-
          Unique identification of an account, as assigned by the account servicer, using an identification scheme.
        properties:
          other:
            $ref: '#/components/schemas/GenericAccountIdentification1'
        required:
        - other

    AccountSchemeName1Choice:
      description: Sets of elements to identify a name of the identification scheme.
      oneOf:
      - type: object
        title: Code
        description: Name of the identification scheme, in a coded form as published in an external list.
        properties:
          code:
            $ref: '#/components/schemas/ExternalAccountIdentification1Code'
        required:
        - code
      - type: object
        title: Proprietary
        description: Name of the identification scheme, in a free tex.
        properties:
          proprietary:
            $ref: '#/components/schemas/Max35Text'
        required:
        - proprietary

    ActiveCurrencyAndAmount:
      type: object
      description: >-
        A number of monetary units specified in an active currency where the unit of currency is explicit
        and compliant with ISO 4217.
      properties:
        currency:
          $ref: '#/components/schemas/ActiveCurrencyCode'
        amount:
          $ref: '#/components/schemas/ImpliedCurrencyAndAmount'
      required:
      - currency
      - amount

    ActiveCurrencyCode:
      type: string
      description: >-
        A code allocated to a currency by a Maintenance Agency under an international identification scheme,
        as described in the latest edition of the international standard ISO 4217 "Codes for the representation
        of currencies and funds".


        Validation Rules:

        * ActiveCurrency: The currency code must be a valid active currency code, not yet withdrawn on the day
          the message containing the currency is exchanged. Valid active currency codes are registered with the
          ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and are not yet withdrawn on the
          day the message containing the Currency is exchanged.
      pattern: '^[A-Z]{3}$'
      minLength: 3
      maxLength: 3

    ActiveOrHistoricCurrencyAndAmount:
      type: object
      description: >-
        A number of monetary units specified in an active or a historic currency where the unit of currency
        is explicit and compliant with ISO 4217.
      properties:
        currency:
          $ref: '#/components/schemas/ActiveOrHistoricCurrencyCode'
        amount:
          $ref: '#/components/schemas/ImpliedCurrencyAndAmount'
      required:
      - currency
      - amount

    ActiveOrHistoricCurrencyCode:
      type: string
      description: >-
        A code allocated to a currency by a Maintenance Agency under an international identification scheme,
        as described in the latest edition of the international standard ISO 4217 "Codes for the representation
        of currencies and funds".

        Validation Rules:
        * ActiveOrHistoricCurrency: The Currency Code must be registered, or have already been registered.
          Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency,
          consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing
          the Currency is exchanged.
      pattern: '^[A-Z]{3}$'
      minLength: 3
      maxLength: 3

    CashAccount38:
      type: object
      description: >-
        Unique and unambiguous identification for the cash account between the account owner
        and the account servicer.
      properties:
        identification:
          $ref: '#/components/schemas/AccountIdentification4Choice'
      required:
      - identification

    DecimalNumber:
      type: string
      description: >-
        Number of objects represented as a decimal number, for example 0.75 or 45.6.

        * Total number of digits: 18

        * Number of digits in fractional part: 17
      pattern: '^-?[0-9]{1,18}(\.[0-9]{1,17})?$'
      minLength: 1
      maxLength: 20

    Exact4AlphaNumericText:
      type: string
      description: Specifies an alphanumeric string with a length of 4 characters.
      pattern: '^[a-zA-Z0-9]{4}$'
      minLength: 4
      maxLength: 4

    ExternalAccountIdentification1Code:
      type: string
      description: >-
        Specifies the external account identification scheme name code in the format of character string with a
        maximum length of 4 characters. The list of valid codes is an external code list published separately.
        External code sets can be downloaded from www.iso20022.org.
      minLength: 1
      maxLength: 4
    
    GenericAccountIdentification1:
      type: object
      properties:
        identification:
          description: Identification assigned by an institution.
          allOf:
          - $ref: '#/components/schemas/Max34Text'
        schemeName:
          description: Name of the identification scheme.
          allOf:
          - $ref: '#/components/schemas/AccountSchemeName1Choice'
        issuer:
          description: Entity that assigns the identification.
          allOf:
          - $ref: '#/components/schemas/Max35Text'
      required:
      - identification

    IBAN2007Identifier:
      type: string
      description: >-
        An identifier used internationally by financial institutions to uniquely identify the account of a customer
        at a financial institution, as described in the latest edition of the international standard ISO 13616:
        2007 - "Banking and related financial services - International Bank Account Number (IBAN)".


        Validation Rules:

        * IBAN: A valid IBAN consists of all three of the following components: Country Code, check digits and BBAN.
      pattern: '^[A-Z]{2}[0-9]{2}[a-zA-Z0-9]{1,30}$'
      minLength: 5
      maxLength: 34

    ImpliedCurrencyAndAmount:
      type: string
      description: >-
        Number of monetary units specified in a currency where the unit of currency is implied by the context and
        compliant with ISO 4217. The decimal separator is a dot.  
        Note: a zero amount is considered a positive amount.

        * Total number of digits: 18

        * Number of digits in fractional part: 5

        * minInclusive: 0
      pattern: '^[0-9]{1,18}(\.[0-9]{1,5})?$'
      minLength: 1
      maxLength: 19

    InvestmentAccount58:
      type: object
      properties:
        accountIdentification:
          description: >-
            Unique and unambiguous identification for the account between the account owner and the account servicer.
          allOf:
          - $ref: '#/components/schemas/Max35Text'
      required:
      - accountIdentification

    GenericIdentification38:
      type: object
      description: Identification expressed as a proprietary type and narrative description.
      properties:
        identification:
          description: Proprietary information, often a code, issued by the data source scheme issuer.
          allOf:
          - $ref: '#/components/schemas/Exact4AlphaNumericText'
        issuer:
          description: Entity that assigns the identification.
          allOf:
          - $ref: '#/components/schemas/Max35Text'
        schemeName:
          description: Short textual description of the scheme.
          allOf:
          - $ref: '#/components/schemas/Max35Text'
      required:
      - identification
      - issuer

    OrderStatusAndReason:
      # Not part of the ISO 20022 Repository.
      type: object
      description: Specifies the current status of the order including a reason if applicable.
      properties:
        status:
          $ref: '#/components/schemas/OrderStatusChoice'
        reason:
          $ref: '#/components/schemas/OrderStatusReasonChoice'
        description:
          description: Additional information regarding the current status of the order, in free text form.
          allOf:
          - $ref: '#/components/schemas/Max35Text'
      required:
      - status

    OrderStatusChoice:
      # Not part of the ISO 20022 Repository.
      description: Choice of format for the order status.
      oneOf:
      - title: Code
        type: object
        description: Order status expressed as an ISO 20022 code.
        properties:
          code:
            $ref: '#/components/schemas/OrderStatusCode'
        required:
        - code
      - title: Proprietary
        type: object
        description: Order status expressed as a proprietary code.
        properties:
          proprietary:
            $ref: '#/components/schemas/GenericIdentification38'
        required:
        - proprietary      

    OrderStatusCode:
      type: string
      description: Specifies the current status of the order.
      enum:
      - NEWW # New
      - PENN # PendingNew
      - DONE # Done
      - CANP # PendingCancel      
      - CANC # Cancelled
      - REJT # Rejected
      - EXPI # Expired
      - SETT # Settled

    OrderStatusReasonChoice:
      description: >-
        Choice of format for the order status reason.
        Note: Not part of the ISO 20022 Repository.
      oneOf:
      - title: Code
        type: object
        description: Order status reason expressed as an ISO 20022 code.
        properties:
          code:
            $ref: '#/components/schemas/OrderStatusReasonCode'
        required:
        - code
      - title: Proprietary
        type: object
        description: Order status reason expressed as a proprietary code.
        properties:
          proprietary:
            $ref: '#/components/schemas/GenericIdentification38'
        required:
        - proprietary

    OrderStatusReasonCode:
      type: string
      description: >-
        Specifies the reason for the current status of the order.
        Note: This is a combination of the ISO 20022 defitions CancelledStatusReasonV2Code and
        RejectedStatusReasonCode. 
      enum:
      # Cancellation
      - CANI # CancelledByYourself
      - CANS # CancelledBySystem
      - CSUB # CancelledByAgent
      - CANH # CancelledByHub
      - CANP # CancelledByInstructingParty
      - CANO # CancelledByOther
      - CNTA # CancelledByTransferAgent
      - CNCL # CancelledByClient
      - CNIN # CancelledByIntermediary
      - CANT # CancelledDueToTransformation
      - CANZ # CancelledSplitPartialSettlement
      - CORP # CancelledDueToCorporateAction
      - CREG # CancelledByIssuerRegistrar
      - CTHP # CancelledByThirdParty
      - BYIY # CancelledDueToBuyIn
      - SCEX # SecuritiesNoLongerEligible
      - CXLR # EndOfLife
      - NARR # NarrativeReason
      - OTHR # Other
      # Rejection
      - DDAT # SettlementDate
      - IAQD # AcquisitionDate
      - POIN # DifferentValuationPoints
      - ICAG # DeliveringAgent
      - IDDB # DirectDebit
      - INTE # Intermediary
      - SAFE # InvestmentAccount
      - IPAY # PaymentCard
      - ICTR # InvalidCreditTransfer
      - DEPT # SettlementPlace
      - IVAG # ReceivingAgent
      - ISAF # SafekeepingPlace
      - DFOR # InvalidSecurityForm
      - DSEC # FinancialInstrumentIdentification
      - BLCA # AccountBlockedForCorporateAction
      - BLTR # AccountBlockedForTransfer
      - DOCC # AccountBlockedMissingDocuments
      - MONY # NotEnoughCash
      - SECU # NotEnoughFinancialInstrument
      - IDNA # FinancialInstrumentIdentificationAndName
      - UWAI # UnacceptedCommissionWaiving
      - UDCY # UnacceptedDealCurrency
      - UNAV # UnacceptedNAVCurrency
      - UPAY # UnacceptedPaymentMethod
      - URSC # UnacceptedRequestedSettlementCurrency
      - SHIG # TooHighUnitsOrAmountToSubscribe
      - SLOW # TooLowUnitsOrAmountToSubscribe
      - ULNK # UnknownLinkagesReference
      - DLVY # PhysicalDeliveryImpossible
      - ORRF # DuplicateOrderReference
      - IPAC # InstructingPartyNotAllowedForAccount
      - IOTP # InvalidOrderType
      - NSLA # NotCompliantWithSLA
      - CUTO # CutOffTime
      - REFE # InvalidOrUnrecognisedReference
      - NALO # NotAllowedRequest
      - COSE # AlreadyExecuted
      - NALC # NotAllowedToCancel
      - LEGL # LegallyImpossible
      - OTHR # Other
      - DQUA # FinancialInstrumentQuantity
      - ICTN # CertificateNumber
      - ISTP # SettlementParties
      - LATE # TooLate
      - ADEA # AfterDeadline
      - DTRD # TradeDate
      - FEEE # FeeOrCommission
      - IEXE # SubscriberOrRedeemer
      - NCRR # SettlementAmountCurrency
      - PHYS # PhysicalSettlement
      - PLCE # PlaceOfTrade
      - SETR # SettlementTransaction
      - RTGS # RTGSSystem
      - NRGM # NoCancellationMatch
      - INUK # InvestorNameAddressUnknown
      - INID # InsufficientInvestorData
      - INAC # InvalidAccountServicer
      - INNA # InvalidNomineeAccount
      - INPM # InvalidNewPlanManager
      - CYPA # CurrentYearPartial
      - PTNS # PartialNotSupported
      - FTAX # FinancialInstrumentTaxYear
      - ISAT # InvalidISAType
      - CASH # InvalidCashAccount
      - TREF # DuplicateTransferReference
      - DMON # InvalidSettlementAmount
      - ORDR # InvalidOrderedAmount
      - BMIN # BelowMinimumInitialInvestmentAmount
      - BMTO # BelowMinimumTopUpAmount
      - INSU # InsufficientCapacity
      - PRCT # PercentageHoldingBreach
      - BMRA # BelowMinimumRedemptionAmount
      - BMRV # BelowMinimumRetainedAmount
      - LOCK # LockUp
      - ILLI # AssetsIlliquid
      - DINV # DataInvalid
      - CLOS # FundClosed
      - UNSC # UnacceptableSwitchCombination
      - NCON # NotConvertable
      - ACLO # AssetClosed
      - NQTY # QuantityBelowMinimum
      - NASS # AssetNotSupported

    ISODate:
      type: string
      description: >-
        A particular point in the progression of time in a calendar year expressed in the YYYY-MM-DD format. This
        representation is defined in "XML Schema Part 2: Datatypes Second Edition - W3C Recommendation 28 October
        2004" which is aligned with ISO 8601.
      format: date

    ISODateTime:
      type: string
      description: >-
        A particular point in the progression of time defined by a mandatory date and a mandatory time component, 
        expressed in either UTC time format (YYYY-MM-DDThh:mm:ss.sssZ), local time with UTC offset format (YYYY-MM-DDThh:mm:ss.sss+/-hh:mm), 
        or local time format (YYYY-MM-DDThh:mm:ss.sss). These representations are defined in "XML Schema Part 2: Datatypes Second Edition - W3C Recommendation 28 October 2004" which is aligned with ISO 8601.
        Beginning / end of calendar day:
        00:00:00 = the beginning of a calendar day
        24:00:00 = the end of a calendar day
        Fractions of second in time format: Decimal fractions of seconds may be included. In this case, the involved parties shall agree 
        on the maximum number of digits that are allowed.
    
    Max34Text:
      type: string
      description: Specifies a character string with a maximum length of 34 characters.
      minLength: 1
      maxLength: 34
    
    Max35Text:
      type: string
      description: Specifies a character string with a maximum length of 35 characters.
      minLength: 1
      maxLength: 35

    Side1Code:
      type: string
      description: Side1Code (BUYI,SELL), View from Instructing Party, buy/sell the trading currency/amount.
      minLength: 4
      maxLength: 4
      enum:
      - BUYI # Buy
      - SELL # Sell

    UnderlyingProductIdentifier1Code:
      type: string
      description: Indicates the underlying product type for reporting to trade repositories. These product codes must be in line with the ISDA Product Taxonomy.
      minLength: 4
      maxLength: 4
      enum:
      - SWAP # ForeignExchangeSwap  
    
    BaseOneRate:
      type: string
      description: The value of one currency expressed in relation to another currency. ExchangeRate expresses the ratio between UnitCurrency and QuotedCurrency (ExchangeRate = UnitCurrency/QuotedCurrency).
      pattern: '^-?[0-9]{1,11}(\.[0-9]{1,10})?$'
      minLength: 1
      maxLength: 11

    AgreedRate3:
      type: object
      description: Information needed to process a currency exchange or conversion.
      properties:
        exchangeRate: 
          $ref: '#/components/schemas/BaseOneRate' 
        unitCurrency: 
          description: Currency in which the rate of exchange is expressed in a currency exchange. In the example 1GBP = xxxCUR, the unit currency is GBP.
          allOf:
          - $ref: '#/components/schemas/ActiveCurrencyCode'
        quotedCurrency:
          description: Currency into which the base currency is converted, in a currency exchange.
          allOf:
          - $ref: '#/components/schemas/ActiveCurrencyCode'  
      required:
      - exchangeRate
      - unitCurrency
      - quotedCurrency             

    AmountsAndValueDate1:
      type: object
      description: Amounts of the trade. View as initiated by instructing party
      properties:
        buyAmount:
          $ref: '#/components/schemas/ActiveOrHistoricCurrencyAndAmount'
        sellAmount:
          $ref: '#/components/schemas/ActiveOrHistoricCurrencyAndAmount'
      required:
      - buyAmount
      - sellAmount
                
    Trade1:
      type: object
      description: Details of the foreign trade captured
      properties:
        side:
          description: Side1Code (BUYI,SELL), View from Instructing Party for the near leg, buy/sell the trading currency/amount 
          allOf:
          - $ref: '#/components/schemas/Side1Code'
        foreignExchangeTradeProduct:
          description: Indicates the underlying product type for reporting to trade repositories. These product codes must be in line with the ISDA Product Taxonomy (SWAP).
          allOf:
          - $ref: '#/components/schemas/UnderlyingProductIdentifier1Code'
        tradeTade: 
          description: Date on which the trading parties agreed on the trade.
          allOf:
          - $ref: '#/components/schemas/ISODate'
        tradeCurrency: 
          description: Specifies the ISO code of the trade currency which is bought or sold depending  in Side identifier.
          allOf:
          - $ref: '#/components/schemas/ActiveCurrencyCode'
        settlementCurrency:
          description: Settlement currency of the trade, agreed by both sides of the trade.
          allOf:
          - $ref: '#/components/schemas/ActiveCurrencyCode'          
        transactionTime:
          description: Date and time at which the trade was executed.
          allOf:
          - $ref: '#/components/schemas/ISODateTime'
          readOnly: true      
        swapNearLeg:
          $ref: '#/components/schemas/Trade3' 
        swapFarLeg:
          $ref: '#/components/schemas/Trade3'                   
      required:
      - side
      - foreignExchangeTradeProduct
      - tradeCurrency
      - settlementCurrency
      - swapNearLeg
      - swapFarLeg

    Trade3:
      type: object
      description: Details of the foreign exchange trade
      properties:
        orderAmount:
           $ref: '#/components/schemas/ActiveCurrencyAndAmount' 
        settlementDate:
          description: Date on which the trade is settled, ie, the amounts are due.
          allOf:
          - $ref: '#/components/schemas/ISODate'       
        agreedRate:
          $ref: '#/components/schemas/AgreedRate3'
        forwardPoints:
          $ref: '#/components/schemas/DecimalNumber'
      required:
      - orderAmount
      - settlementDate

    ForeignExchangeSwap:
      # Not part of the ISO 20022 Repository
      type: object
      description: >-
         A foreign exchange swap transaction
        
      properties:
        # ORDER DETAILS
        orderIdentification:
          description: Unique and unambiguous identifier for the order, as assigned by the receiving party.
          allOf:
          - $ref: '#/components/schemas/Max35Text'
          readOnly: true
        # ACCOUNT DETAILS
        clientOrderReference:
          description: Unique and unambiguous identifier for the order, as assigned by the instructing party.
          allOf:
          - $ref: '#/components/schemas/Max35Text'
        investmentAccountDetails:
          $ref: '#/components/schemas/InvestmentAccount58'
        tradingCashAccountDetails:
          $ref: '#/components/schemas/CashAccount38'
        settlementCashAccountDetails:
          $ref: '#/components/schemas/CashAccount38'   
        #TRADE DETAILS
        tradeDetail:
          description: Details of the foreign exchange trade captured
          allOf:
          - $ref: '#/components/schemas/Trade1'
        # ORDER STATUS
        orderStatus:
          allOf:
          - $ref: '#/components/schemas/OrderStatusAndReason'
          readOnly: true
        # TRADE AMOUNTS
        swapNearLegTradeAmounts:
          description: Amounts of the near leg trade. View as initiated by instructing party
          allOf:
          - $ref: '#/components/schemas/AmountsAndValueDate1'       
          readOnly: true         
        swapFarLegTradeAmounts:
          description: Amounts of the far leg trade. View as initiated by instructing party
          allOf:
          - $ref: '#/components/schemas/AmountsAndValueDate1'       
          readOnly: true                       
      required:
      - orderIdentification
      - investmentAccountDetails
      - tradeDetail

  securitySchemes:
    # ------------------------------------------------------------------------------------------------------------------
    # COMPONENTS/SECURITY SCHEMES
    # In this file it is only described the basic security element to transport the bearer token of an OAuth2 process.
    # The bearer token must be included in the HTTP header.
    #
    # WARNING:
    # If you want to use this file for a productive implementation, it is recommended to adjust the security schemes
    # according to your system environments and security policies.
    # ------------------------------------------------------------------------------------------------------------------
    bearerAuth:
      description: OAuth 2.0 Bearer Token [RFC 6750].
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  # --------------------------------------------------------------------------------------------------------------------
  # SECURITY
  # In this file it is only described the basic security element to transport the bearer token of an OAuth2 process.
  # The bearer token must be included in the HTTP header.
  #
  # WARNING:
  # If you want to use this file for a productive implementation, it is recommended to adjust the security schemes
  # according to your system environments and security policies.
  # --------------------------------------------------------------------------------------------------------------------
  - {}
  - bearerAuth: []

tags:
  # --------------------------------------------------------------------------------------------------------------------
  # TAGS
  #---------------------------------------------------------------------------------------------------------------------
- name: Orders
  description: Get, add, modify and delete foreign exchange swap orders