Products
Rates - Fixed-Float SwapRates - Basis SwapRates - Cross-Currency SwapCredit - Credit Default SwapFX - ForwardEquity - Equity Swap (Price Return Index)Equity - Basket Portfolio SwapCommodity - Commodity Swap (Index)Exotic - FX Digital Option
Contents
Overview Key ISDA CDM Structures FpML to CDM Conversion Special Considerations

Rates - Basis Swap

Rates - Basis Swap Documentation

Overview

The IRBasisSwapCDMMapper class is responsible for mapping FpML (Financial Products Markup Language) interest rate basis swaps to the ISDA Common Domain Model (CDM) format. It extends the AbstractRateProductsCDMMapper class, inheriting common mapping functionality for interest rate products.

A basis swap involves the exchange of floating rate payments, where each leg references a different interest rate index (e.g., SOFR vs Federal Funds). This mapper handles the conversion of FpML XML elements representing basis swaps to the corresponding CDM objects.

Key ISDA CDM Structures

The following key ISDA CDM structures are important for this mapper:

  1. Trade - The top-level container for trade information

    • Contains trade date, identifiers, parties, and tradable product

  2. TradeIdentifier - Identifies the trade uniquely

    • Contains issuer, assigned identifier, and identifier type

  3. TradableProduct - Represents the tradable product in the trade

    • Contains product, trade lots, and counterparty information

  4. ContractualProduct - Describes the contractual aspects of the product

    • Contains product taxonomy and economic terms with payouts

  5. InterestRatePayout - Represents the interest rate payout terms for each leg

    • For basis swaps, there are two floating rate legs (no fixed leg)

  6. FloatingRateSpecification - Contains floating rate details for each leg

    • Includes rate option, index tenor, and spread information

  7. CalculationPeriodDates - Defines calculation periods for the legs

    • Contains effective date, termination date, and calculation period frequency

  8. PaymentDates - Defines payment schedules

    • Contains payment frequency, pay relative to, and adjustments

  9. TradeLot - Contains pricing and quantity information

    • Includes price quantities for both legs

  10. PriceQuantity - Contains pricing and notional amount details

    • Includes observable with rate option for the floating rates

FpML to CDM Mapping

Main Mapping Structures

FpML Element/StructureCDM Class/StructureContext
<trade>TradeTop-level trade container
<tradeHeader>Fields in TradeContains trade date and identifiers
<tradeDate>FieldWithMetaDate in TradeTrade execution date
<partyTradeIdentifier>TradeIdentifier list in TradeTrade identifiers
<swap>TradableProduct in TradeSwap-specific information
<swapStream> (multiple)InterestRatePayout listIndividual swap legs (both floating)
<party>Party list in TradeParty information
<productType>ProductTaxonomy listProduct classification

Detailed Element Mapping

FpML ElementCDM FieldParent CDM ClassType
<tradeDate>tradeDate.valueTradeDate
<partyTradeIdentifier>/<issuer>tradeIdentifier[].issuer.valueTradeString
<partyTradeIdentifier>/<tradeId>tradeIdentifier[].assignedIdentifier[].identifier.valueTradeString
<party>/<partyId>party[].partyId[].identifier.valueTradeString
<party>/<partyName>party[].name.valueTradeString
<party>/<businessUnit>/<n>party[].businessUnit[].nameTradeString
<payerPartyReference>payerReceiver.payerInterestRatePayoutCounterpartyRoleEnum
<receiverPartyReference>payerReceiver.receiverInterestRatePayoutCounterpartyRoleEnum
<effectiveDate>/<unadjustedDate>calculationPeriodDates.effectiveDate.adjustableDate.unadjustedDateInterestRatePayoutDate
<terminationDate>/<unadjustedDate>calculationPeriodDates.terminationDate.adjustableDate.unadjustedDateInterestRatePayoutDate
<calculationPeriodFrequency>calculationPeriodDates.calculationPeriodFrequencyInterestRatePayoutCalculationPeriodFrequency
<notionalSchedule>/<notionalStepSchedule>/<initialValue>tradeLot.priceQuantity[].quantity[].value.valueTradableProductBigDecimal
<notionalSchedule>/<notionalStepSchedule>/<currency>tradeLot.priceQuantity[].quantity[].value.unit.currency.valueTradableProductString
<floatingRateCalculation>/<floatingRateIndex>rateSpecification.floatingRate.rateOption.value.floatingRateIndex.valueInterestRatePayoutFloatingRateIndexEnum
<floatingRateCalculation>/<indexTenor>rateSpecification.floatingRate.rateOption.value.indexTenorInterestRatePayoutPeriod
<spreadSchedule>/<initialValue>rateSpecification.floatingRate.spreadSchedule.price.value.valueInterestRatePayoutBigDecimal
<dayCountFraction>dayCountFraction.valueInterestRatePayoutDayCountFractionEnum
<paymentFrequency>paymentDates.paymentFrequencyInterestRatePayoutFrequency
<resetDates>resetDatesInterestRatePayoutResetDates

Special Considerations

Enum Mappings

The mapper handles several important enum mappings between FpML and CDM:

Day Count Fraction Mapping

FpML ValueCDM Enum Value
ACT/360DayCountFractionEnum.ACT_360
ACT/365LDayCountFractionEnum.ACT_365L
ACT/364DayCountFractionEnum.ACT_364
ACT/365.FIXEDDayCountFractionEnum.ACT_365_FIXED
ACT/ACT.AFBDayCountFractionEnum.ACT_ACT_AFB
ACT/ACT.ICMADayCountFractionEnum.ACT_ACT_ICMA
ACT/ACT.ISDADayCountFractionEnum.ACT_ACT_ISDA
ACT/ACT.ISMADayCountFractionEnum.ACT_ACT_ISMA
CAL/252DayCountFractionEnum.CAL_252
1/1DayCountFractionEnum._1_1

Floating Rate Index Mapping

FpML ValueCDM Enum Value
USD-Federal Funds-H.15FloatingRateIndexEnum.USD_FEDERAL_FUNDS_H_15
USD-LIBOR-BBAFloatingRateIndexEnum.USD_LIBOR_BBA
USD-SOFR-COMPOUNDFloatingRateIndexEnum.USD_SOFR_COMPOUND
USD-LIBORFloatingRateIndexEnum.USD_LIBOR

Implementation Details

  1. Basis Swap Structure: Unlike fixed-float swaps, basis swaps involve two floating legs, each with its own floating rate index, typically with different spread values.

  2. Deterministic Keys: The mapper uses a generateDeterministicKey method to create consistent global keys for objects needing references:

    • For party references: f78b23fb for Party1, 67e3087d for Party2
    • For trade identifiers: 5d97a672
    • For trade date: 3ed88c

  3. Payer/Receiver Pattern: For basis swaps, the mapper enforces a specific pattern:

    • First leg: Party1 pays to Party2
    • Second leg: Party2 pays to Party1

  4. Reference Management: The implementation uses a comprehensive reference mechanism with document-scoped references:

    • quantity-1 and quantity-2 for the notional amounts
    • price-1 and price-2 for the spreads
    • rateOption-1 and rateOption-2 for the floating rate options

  5. Fallback Values: In cases where the required information is missing from the FpML, the mapper provides fallback values with appropriate warning logs.