openapi: 3.0.3
info:
  title: SSCMFI Calculation API
  description: |
    Financial calculation API for fixed income analytics supporting multiple payment types including:
    - Periodic
    - Discount
    - IAM (Interest at Maturity)
    - Stepped
    - MultiStep
    - PIK (Payment-in-Kind)
    - Part-PIK
    
    This API performs comprehensive bond calculations including price/yield, cash flows, analytics, and risk metrics.
  version: 1.2.8
  contact:
    name: API Support

servers:
  - url: https://api.sscmfi.com
    description: Production Server

security:
  - ApiKeyAuth: []

paths:
  /api/sscmfiAPICalculate:
    post:
      summary: Calculate fixed income analytics
      description: |
        Perform bond calculations based on security definition and trade parameters.
        Returns price/yield, cash flows, analytics, and other financial metrics.
      operationId: calculateBondAnalytics
      tags:
        - Calculations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculationRequest'
            example:
              metadata:
                calculationID: "ABC987"
              securityDefinition:
                securityID: "Testsec77"
                paymentType: "Periodic"
                securityType: "CD"
                maturityDate: "3/31/2031"
                couponRate: 3.75
                redemptionValue: 100.0
                dayCountBasis: "SSCM30/360"
                eomRule: "Adjust"
                periodsPerYear: "Monthly"
                callRedemptions:
                  redemptionScheduleType: "Discrete with notification"
                  notifyMinDays: 30
                  notifyMaxDays: 60
                  notifyStart: "Settlement date"
                  notifyCalendarBusiness: "Calendar days"
                  redemptionList:
                    - date: "03/31/2027"
                      value: 101.50
                    - date: "09/30/2027"
                      value: 101.00
                    - date: "03/31/2028"
                      value: 100.50
              tradeDefinition:
                tradeDate: "7/22/2020"
                settlementDate: "7/23/2020"
                givenType: "yield"
                givenValue: 3.55
              calculationSelection:
                calcsToReturn:
                  calcPY: "Yes"
                  calcPYAnalytics: "No"
                  calcCFS: "No"
                  calcCFSAnalytics: "No"
                  calcCouponPeriod: "Yes"
                calculationsFor: "Maturity only"
              settings:
                dateScheme:
                  dateTwoOrFourYear: "FOUR"
                  dateFormat: "MDY"
                  dateCutoffYear: 2075
      responses:
        '200':
          description: Successful calculation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                success: true
                metadata:
                  calculationDate: "2026-01-27 11:59:34"
                  version:
                    calculationEngine: "1.2.7"
                    dataInputFormat: "1.2.7"
                    resultsFormat: "1.2.7"
                  securityID: "Testsec77"
                  calculationID: "ABC987"
                data:
                  summary:
                    calculationsToCount: 1
                    worstPositionInList: 1
                  calculationTo:
                    - redemptionInfo:
                        redemptionType: "Maturity"
                        redemptionDate: "03/31/2031"
                        redemptionValue: 100
                        worstIndicator: "Worst"
                      PY:
                        price: 101.77058315528
                        yield: 3.55
                        ai: 0.23958333333333
                        tradingPrice: 101.770
                      couponPeriod:
                        previousCouponDate: "06/30/2020"
                        nextCouponDate: "09/30/2020"
        '400':
          description: Invalid request (bad JSON)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemErrorResponse'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemErrorResponse'
        '405':
          description: Method not allowed - use POST
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                errorInfo:
                  error: true
                  errorNumber: 10001
                  errorMessage: "Method not allowed - use POST"
        '422':
          description: Calculation error (validation or calculation failure)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                dateError:
                  summary: Date validation error
                  value:
                    success: false
                    errorInfo:
                      error: true
                      errorNumber: 3000
                      errorParm1: 1
                      errorParm2: 2
                      errorMessage: "Settlement Date is greater than Maturity Date"
                missingRequired:
                  summary: Missing required field
                  value:
                    success: false
                    errorInfo:
                      error: true
                      errorNumber: 6001
                      errorParm1: 2
                      errorMessage: "Required value for paymentType was not provided"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/sscmfiAPIBatchCalculate:
    post:
      summary: Batch calculate bond analytics
      description: |
        Perform fixed income calculations on multiple securities in a single request.
      operationId: batchCalculateBondAnalytics
      tags:
        - Calculations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCalculationRequest'
            example:
              - metadata:
                  calculationID: "ABC987"
                securityDefinition:
                  securityID: "Testsec77"
                  paymentType: "Periodic"
                  securityType: "CD"
                  maturityDate: "3/31/2031"
                  couponRate: 3.75
                  redemptionValue: 100.0
                  dayCountBasis: "SSCM30/360"
                  eomRule: "Adjust"
                  periodsPerYear: "Monthly"
                  callRedemptions:
                    redemptionScheduleType: "Discrete with notification"
                    notifyMinDays: 30
                    notifyMaxDays: 60
                    notifyStart: "Settlement date"
                    notifyCalendarBusiness: "Calendar days"
                    redemptionList:
                      - date: "03/31/2027"
                        value: 101.50
                      - date: "09/30/2027"
                        value: 101.00
                      - date: "03/31/2028"
                        value: 100.50
                tradeDefinition:
                  tradeDate: "7/22/2020"
                  settlementDate: "7/23/2020"
                  givenType: "yield"
                  givenValue: 3.55
                calculationSelection:
                  calcsToReturn:
                    calcPY: "Yes"
                    calcPYAnalytics: "No"
                    calcCFS: "No"
                    calcCFSAnalytics: "No"
                    calcCouponPeriod: "Yes"
                  calculationsFor: "Maturity only"
                settings:
                  dateScheme:
                    dateTwoOrFourYear: "FOUR"
                    dateFormat: "MDY"
                    dateCutoffYear: 2075
              - metadata:
                  calculationID: "2131"
                  version:
                    dataInputFormat: ""
                    resultsFormat: ""
                securityDefinition:
                  securityID: "Testsec2"
                  paymentType: "stepped"
                  securityType: "corporate"
                  lastCouponDate: "3/1/2045"
                  maturityDate: "6/1/2045"
                  stepDate: "3/1/2030"
                  initialCouponRate: 0
                  stepCouponRate: 6
                  redemptionValue: 100.0
                  dayCountBasis: "SSCM30/360"
                  eomRule: "Adjust"
                  periodsPerYear: "SemiAnnual"
                  callRedemptions:
                    redemptionScheduleType: "Discrete no notification"
                    redemptionList:
                      - date: "09/1/2025"
                        value: 101.00
                      - date: "03/1/2026"
                        value: 101.25
                      - date: "09/1/2026"
                        value: 101.00
                      - date: "03/1/2027"
                        value: 100.75
                      - date: "09/1/2027"
                        value: 100.50
                      - date: "03/1/2028"
                        value: 100.25
                tradeDefinition:
                  settlementDate: "3/12/2020"
                  givenType: "Price"
                  givenValue: 99.125
                calculationSelection:
                  calcsToReturn:
                    calcPY: "Yes"
                    calcPYAnalytics: "Yes"
                    calcCFS: "No"
                    calcCFSAnalytics: "Yes"
                    calcCouponPeriod: "Yes"
                  calculationsFor: "worst and maturity"
                settings:
                  holidayList:
                    - date: "01/1/2020"
                    - date: "07/04/2023"
                  dateScheme:
                    dateTwoOrFourYear: "FOUR"
                    dateFormat: "MDY"
                    dateCutoffYear: 2075
              - metadata:
                  calculationID: "ABC123"
                  version:
                    dataInputFormat: ""
                    resultsFormat: ""
                securityDefinition:
                  securityID: "Testsec4"
                  paymentType: "Unknown"
                  securityType: "corporate"
                  issueDate: "12/1/2019"
                  firstCouponDate: "3/15/2020"
                  lastCouponDate: "3/15/2049"
                  maturityDate: "10/1/2049"
                  couponRateList:
                    - date: "12/1/2019"
                      value: 4.00
                    - date: "03/15/2024"
                      value: 5.00
                    - date: "09/15/2028"
                      value: 6.00
                    - date: "09/15/2030"
                      value: 6.50
                    - date: "09/15/2033"
                      value: 7.00
                    - date: "03/15/2049"
                      value: 8.0
                  redemptionValue: 100.0
                  dayCountBasis: "SSCM30/360"
                  eomRule: "Adjust"
                  periodsPerYear: "SemiAnnual"
                  callRedemptions:
                    redemptionScheduleType: "Continuous with notification"
                    notifyMinDays: 30
                    notifyMaxDays: 60
                    notifyStart: "Trade date"
                    notifyCalendarBusiness: "business days"
                    redemptionList:
                      - date: "03/15/2021"
                        value: 101.00
                      - date: "09/15/2025"
                        value: 102.00
                      - date: "03/15/2026"
                        value: 101.50
                      - date: "09/15/2026"
                        value: 101.00
                      - date: "03/15/2027"
                        value: 100.50
                      - date: "09/15/2027"
                        value: 100.00
                      - date: "03/15/2028"
                        value: 100.00
                tradeDefinition:
                  tradeDate: "11/1/2024"
                  settlementDate: "11/2/2024"
                  givenType: "Price"
                  givenValue: 101
                calculationSelection:
                  calcsToReturn:
                    calcPY: "Yes"
                    calcPYAnalytics: "Yes"
                    calcCFS: "Yes"
                    calcCFSAnalytics: "Yes"
                    calcCouponPeriod: "Yes"
                  calculationsFor: "all redemptions"
                settings:
                  holidayList:
                    - date: "01/1/2020"
                    - date: "07/04/2023"
                  dateScheme:
                    dateTwoOrFourYear: "FOUR"
                    dateFormat: "MDY"
                    dateCutoffYear: 2075
      responses:
        '200':
          description: Successful batch calculation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCalculationResponse'
              example:
                batchSuccess: true
                batchMetaData:
                  batchSize: 3
                  processedCount: 3
                  batchErrorCount: 1
                  calculationDate: "2026-01-27 12:35:45"
                  version:
                    calculationEngine: "1.2.7"
                    dataInputFormat: "1.2.7"
                    resultsFormat: "1.2.7"
                results:
                  - success: true
                    metadata:
                      securityID: "Testsec77"
                      calculationID: "ABC987"
                    data:
                      summary:
                        calculationsToCount: 1
                        worstPositionInList: 1
                      calculationTo:
                        - redemptionInfo:
                            redemptionType: "Maturity"
                            redemptionDate: "03/31/2031"
                            redemptionValue: 100
                            worstIndicator: "Worst"
                          PY:
                            price: 101.77058315528
                            yield: 3.55
                            ai: 0.23958333333333
                            tradingPrice: 101.770
                          couponPeriod:
                            previousCouponDate: "06/30/2020"
                            nextCouponDate: "09/30/2020"
                  - success: true
                    metadata:
                      securityID: "Testsec2"
                      calculationID: "2131"
                    data:
                      summary:
                        calculationsToCount: 2
                        worstPositionInList: 1
                      calculationTo:
                        - redemptionInfo:
                            redemptionType: "Call"
                            redemptionDate: "03/01/2028"
                            redemptionValue: 100.25
                            worstIndicator: "Worst"
                          PY:
                            price: 99.125
                            yield: 0.14165833655455
                            ai: 0
                            tradingPrice: 99.125
                          couponPeriod:
                            previousCouponDate: "03/01/2020"
                            nextCouponDate: "09/01/2020"
                          PYAnalytics:
                            approxDuration: 7.9694454520297
                            approxModDuration: 7.9638047553582
                            approxConvexity: 67.401257813743
                            pv1b: 0.078941214637489
                            yv32: 0.39586419012559
                          cashFlowAnalytics:
                            yieldSemiAnnual: 0.14165833655455
                            yieldPeriodic: 0.14165833655455
                            yieldAnnual: 0.14170850426534
                            macDuration: 15.938888888889
                            durationYears: 7.9694444444444
                            modDuration: 7.9638037484861
                            convexityInPeriods: 269.60501466752
                            convexityInYears: 67.401253666881
                            averageLifeInPeriods: 15.938888888889
                            averageLifeInYears: 7.9694444444444
                            afterTaxYield: 0.11344627674257
                            taxableEquivalentYield: 0.17684007343175
                            pvBPC: 0.078941214637489
                            totalInterestFlows: 0
                            totalPrincipalFlows: 100.25
                            totalIFPlusIOI: 0
                            totalPFPlusIOP: 100.25
                            totalIOI: 0
                            totalIOP: 0
                            totalFutureAmount: 100.25
                            totalReturn: 0.14165833655451
                            capitalGainLoss: 1.125
                            totalDollarReturn: 1.125
                        - redemptionInfo:
                            redemptionType: "Maturity"
                            redemptionDate: "06/01/2045"
                            redemptionValue: 100
                            worstIndicator: ""
                          PY:
                            price: 99.125
                            yield: 3.1118999738449
                            ai: 0
                            tradingPrice: 99.125
                          couponPeriod:
                            previousCouponDate: "03/01/2020"
                            nextCouponDate: "09/01/2020"
                          PYAnalytics:
                            approxDuration: 20.938799360655
                            approxModDuration: 20.617993690523
                            approxConvexity: 460.52855688289
                            pv1b: 0.20437586245731
                            yv32: 0.15290455352342
                          cashFlowAnalytics:
                            yieldSemiAnnual: 3.1118999738449
                            yieldPeriodic: 3.1118999738449
                            yieldAnnual: 3.136109777463
                            macDuration: 41.87756178673
                            durationYears: 20.938780893365
                            modDuration: 20.617975506173
                            convexityInPeriods: 1842.1133257649
                            convexityInYears: 460.52833144122
                            averageLifeInPeriods: 50.438888888889
                            averageLifeInYears: 25.219444444444
                            afterTaxYield: 2.0858654203656
                            taxableEquivalentYield: 4.5217140581162
                            pvBPC: 0.20437586245731
                            totalInterestFlows: 91.5
                            totalPrincipalFlows: 100
                            totalIFPlusIOI: 115.97066541975
                            totalPFPlusIOP: 100
                            totalIOI: 24.470665419754
                            totalIOP: 0
                            totalFutureAmount: 215.97066541975
                            totalReturn: 3.111899973845
                            capitalGainLoss: 0.875
                            totalDollarReturn: 116.84566541975
                  - success: false
                    metadata:
                      calculationDate: "2026-01-27 12:35:45"
                      version:
                        calculationEngine: "1.2.7"
                        dataInputFormat: "1.2.7"
                        resultsFormat: "1.2.7"
                      securityID: "Testsec4"
                      calculationID: "ABC123"
                    errorInfo:
                      error: true
                      errorNumber: 6002
                      errorParm1: 2
                      errorParm2: 0
                      errorParm3: 0
                      errorPos1: 0
                      errorPos2: 0
                      errorPos3: 0
                      errorMessage: "Provided value for paymentType is invalid."

  /api/sscmfiAPICalculatePeriodic:
    post:
      summary: Calculate Periodic Bond
      description: Specific endpoint for Periodic payment type security calculations.
      operationId: calculatePeriodic
      tags:
        - Specific Calculations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculationRequestPeriodic'
            example:
              metadata:
                calculationID: "ABC123"
                version:
                  dataInputFormat: ""
                  resultsFormat: ""
              securityDefinition:
                securityID: "Testsec1"
                paymentType: "periodic"
                securityType: "corporate"
                issueDate: "12/1/2019"
                firstCouponDate: "3/15/2020"
                lastCouponDate: "3/15/2049"
                maturityDate: "3/15/2050"
                couponRate: 5
                redemptionValue: 100.0
                dayCountBasis: "SSCM30/360"
                eomRule: "Adjust"
                periodsPerYear: "SemiAnnual"
                callRedemptions:
                  redemptionScheduleType: "Continuous with notification"
                  notifyMinDays: 30
                  notifyMaxDays: 60
                  notifyStart: "Trade date"
                  notifyCalendarBusiness: "business days"
                  redemptionList:
                    - date: "03/15/2021"
                      value: 101.00
                    - date: "12/15/2023"
                      value: 102.50
                    - date: "09/15/2025"
                      value: 102.00
                    - date: "03/15/2026"
                      value: 101.50
                    - date: "09/15/2026"
                      value: 101.00
                    - date: "03/15/2027"
                      value: 100.50
                    - date: "09/15/2027"
                      value: 100.00
                    - date: "03/15/2028"
                      value: 100.00
              tradeDefinition:
                tradeDate: "3/1/2020"
                settlementDate: "3/12/2020"
                givenType: "yield"
                givenValue: 4.0
              calculationSelection:
                calcsToReturn:
                  calcPY: "Yes"
                  calcPYAnalytics: "Yes"
                  calcCFS: "Yes"
                  calcCFSAnalytics: "Yes"
                  calcCouponPeriod: "Yes"
                calculationsFor: "worst and maturity"
              settings:
                holidayList:
                  - date: "01/1/2020"
                  - date: "07/04/2023"
                dateScheme:
                  dateTwoOrFourYear: "FOUR"
                  dateFormat: "MDY"
                  dateCutoffYear: 2075
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                success: true
                metadata:
                  calculationDate: "2026-01-26 21:08:32"
                  version:
                    calculationEngine: "1.2.7"
                    dataInputFormat: "1.2.7"
                    resultsFormat: "1.2.7"
                  securityID: "Testsec1"
                  calculationID: ""
                data:
                  summary:
                    calculationsToCount: 2
                    worstPositionInList: 1
                  calculationTo:
                    - redemptionInfo:
                        redemptionType: "Call"
                        redemptionDate: "03/15/2021"
                        redemptionValue: 101
                        worstIndicator: "Worst"
                      PY:
                        price: 101.93950281008
                        yield: 4
                        ai: 1.4027777777778
                        tradingPrice: 101.939
                      couponPeriod:
                        previousCouponDate: "12/01/2019"
                        nextCouponDate: "03/15/2020"
                      cashFlows:
                        cashFlowCount: 3
                        cashFlowDates: ["03/15/2020", "09/15/2020", "03/15/2021"]
                        cashFlows: [1.4444444444444, 2.5, 103.5]
                        interestFlows: [1.4444444444444, 2.5, 2.5]
                        principalFlows: [0, 0, 101]
                    - redemptionInfo:
                        worstIndicator: ""
                        redemptionType: "Maturity"
                        redemptionDate: "03/15/2050"
                        redemptionValue: 100
                      PY:
                        price: 117.36766497553
                        yield: 4
                        ai: 1.4027777777778
                        tradingPrice: 117.367
                      couponPeriod:
                        previousCouponDate: "12/01/2019"
                        nextCouponDate: "03/15/2020"
        '422':
          description: Calculation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/sscmfiAPICalculateDiscount:
    post:
      summary: Calculate Discount security
      description: Specific endpoint for Discount securities calculations.
      operationId: calculateDiscount
      tags:
        - Specific Calculations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculationRequestDiscount'
            example:
              metadata:
                calculationID: "ABC123"
                version:
                  dataInputFormat: ""
                  resultsFormat: ""
              securityDefinition:
                securityID: "Testsec4"
                securityType: "Treasury"
                maturityDate: "4/20/2027"
                redemptionValue: 100.0
                dayCountBasis: "Actual/360"
                eomRule: "Adjust"
              tradeDefinition:
                settlementDate: "2/21/2027"
                givenType: "yield"
                givenValue: 4.0
              calculationSelection:
                calcsToReturn:
                  calcPY: "Yes"
                  calcPYAnalytics: "Yes"
                  calcCFS: "Yes"
                  calcCFSAnalytics: "Yes"
                  calcCouponPeriod: "Yes"
                calculationsFor: "Maturity only"
              settings:
                dateScheme:
                  dateTwoOrFourYear: "FOUR"
                  dateFormat: "MDY"
                  dateCutoffYear: 2075
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseDiscount'
              example:
                success: true
                metadata:
                  calculationDate: "2026-01-26 21:31:46"
                  version:
                    calculationEngine: "1.2.7"
                    dataInputFormat: "1.2.7"
                    resultsFormat: "1.2.7"
                  securityID: "Testsec4"
                  calculationID: "ABC123"
                data:
                  summary:
                    calculationsToCount: 1
                    worstPositionInList: 1
                  calculationTo:
                    - redemptionInfo:
                        redemptionType: "Maturity"
                        redemptionDate: "04/20/2027"
                        redemptionValue: 100
                        worstIndicator: "Worst"
                      PY:
                        price: 99.359682049017
                        yield: 4
                        discountRate: 3.9743872819607
                        tradingPrice: 99.359682
                      cashFlows:
                        cashFlowCount: 1
                        cashFlowDates: ["04/20/2027"]
                        cashFlows: [100]
                        interestFlows: [0]
                        principalFlows: [100]
                      PYAnalytics:
                        approxDuration: 0.1589041097837
                        approxModDuration: 0.15572446872813
                        approxConvexity: 0.10055436172883
                        pv1b: 0.0015472733700079
                        yv32: 20.196818872311
                      cashFlowAnalytics:
                        yieldSemiAnnual: 4
                        yieldPeriodic: 4
                        yieldAnnual: 4.04
                        macDuration: 0.31871734474408
                        durationYears: 0.15935867237204
                        modDuration: 0.15623399252161
                        convexityInPeriods: 0.40396636721812
                        convexityInYears: 0.10099159180453
                        averageLifeInPeriods: 0.31868131868132
                        averageLifeInYears: 0.15934065934066
                        afterTaxYield: 3.2534222131735
                        taxableEquivalentYield: 5.0992229760419
                        pvBPC: 0.0015523359833551
                        totalInterestFlows: 0
                        totalPrincipalFlows: 100
                        totalIFPlusIOI: 0
                        totalPFPlusIOP: 100
                        totalIOI: 0
                        totalIOP: 0
                        totalFutureAmount: 100
                        totalReturn: 4.072374610318
                        capitalGainLoss: 0.64031799999999
                        totalDollarReturn: 0.64031799999999
        '422':
          description: Calculation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/sscmfiAPICalculateIAM:
    post:
      summary: Calculate IAM security
      description: Specific endpoint for Interest At Maturity (IAM) payment type calculations.
      operationId: calculateIAM
      tags:
        - Specific Calculations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculationRequestIAM'
            example:
              metadata:
                calculationID: "ABC123"
                version:
                  dataInputFormat: ""
                  resultsFormat: ""
              securityDefinition:
                securityID: "Testsec99"
                securityType: "Agency"
                issueDate: "12/1/2019"
                maturityDate: "12/1/2020"
                couponRate: 5
                redemptionValue: 100.0
                dayCountBasis: "SSCM30/360"
                eomRule: "Adjust"
              tradeDefinition:
                settlementDate: "5/17/2020"
                givenType: "yield"
                givenValue: 2.125
              calculationSelection:
                calcsToReturn:
                  calcPY: "Yes"
                  calcPYAnalytics: "Yes"
                  calcCFS: "Yes"
                  calcCFSAnalytics: "No"
                  calcCouponPeriod: "No"
                calculationsFor: "worst only"
              settings:
                dateScheme:
                  dateTwoOrFourYear: "FOUR"
                  dateFormat: "MDY"
                  dateCutoffYear: 2075
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                success: true
                metadata:
                  calculationDate: "2026-01-26 21:37:49"
                  version:
                    calculationEngine: "1.2.7"
                    dataInputFormat: "1.2.7"
                    resultsFormat: "1.2.7"
                  securityID: "Testsec99"
                  calculationID: "ABC123"
                data:
                  summary:
                    calculationsToCount: 1
                    worstPositionInList: 1
                  calculationTo:
                    - redemptionInfo:
                        redemptionType: "Maturity"
                        redemptionDate: "12/01/2020"
                        redemptionValue: 100
                        worstIndicator: "Worst"
                      PY:
                        price: 98.867826075016
                        yield: 2.125
                        discountRate: 2.1009413040941
                        tradingPrice: 98.867826
                      cashFlows:
                        cashFlowCount: 1
                        cashFlowDates: ["12/01/2020"]
                        cashFlows: [100]
                        interestFlows: [0]
                        principalFlows: [100]
                      PYAnalytics:
                        approxDuration: 0.53150685068503
                        approxModDuration: 0.52584407380594
                        approxConvexity: 0.5366327898254
                        pv1b: 0.0051989060431623
                        yv32: 6.0108799313849
        '422':
          description: Calculation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/sscmfiAPICalculateStepped:
    post:
      summary: Calculate Stepped Coupon Bond
      description: Specific endpoint for Stepped Coupon bond calculations.
      operationId: calculateStepped
      tags:
        - Specific Calculations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculationRequestStepped'
            example:
              metadata:
                calculationID: "ABC123"
                version:
                  dataInputFormat: ""
                  resultsFormat: ""
              securityDefinition:
                securityID: "Testsec2"
                securityType: "corporate"
                lastCouponDate: "3/1/2045"
                maturityDate: "6/1/2045"
                stepDate: "3/1/2030"
                initialCouponRate: 0
                stepCouponRate: 6
                redemptionValue: 100.0
                dayCountBasis: "SSCM30/360"
                eomRule: "Adjust"
                periodsPerYear: "SemiAnnual"
                callRedemptions:
                  redemptionScheduleType: "Discrete no notification"
                  redemptionList:
                    - date: "09/1/2025"
                      value: 101.00
                    - date: "03/1/2026"
                      value: 101.25
                    - date: "09/1/2026"
                      value: 101.00
                    - date: "03/1/2027"
                      value: 100.75
                    - date: "09/1/2027"
                      value: 100.50
                    - date: "03/1/2028"
                      value: 100.25
              tradeDefinition:
                settlementDate: "3/12/2020"
                givenType: "Price"
                givenValue: 99.125
              calculationSelection:
                calcsToReturn:
                  calcPY: "Yes"
                  calcPYAnalytics: "Yes"
                  calcCFS: "Yes"
                  calcCFSAnalytics: "Yes"
                  calcCouponPeriod: "Yes"
                calculationsFor: "worst and maturity"
              settings:
                holidayList:
                  - date: "01/1/2020"
                  - date: "07/04/2023"
                dateScheme:
                  dateTwoOrFourYear: "FOUR"
                  dateFormat: "MDY"
                  dateCutoffYear: 2075
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                success: true
                metadata:
                  calculationDate: "2026-01-26 21:24:19"
                  version:
                    calculationEngine: "1.2.7"
                    dataInputFormat: "1.2.7"
                    resultsFormat: "1.2.7"
                  securityID: "Testsec2"
                  calculationID: "ABC123"
                data:
                  summary:
                    calculationsToCount: 2
                    worstPositionInList: 1
                  calculationTo:
                    - redemptionInfo:
                        redemptionType: "Call"
                        redemptionDate: "03/01/2028"
                        redemptionValue: 100.25
                        worstIndicator: "Worst"
                      PY:
                        price: 99.125
                        yield: 0.14165833655455
                        ai: 0
                        tradingPrice: 99.125
                      couponPeriod:
                        previousCouponDate: "03/01/2020"
                        nextCouponDate: "09/01/2020"
                      cashFlows:
                        cashFlowCount: 1
                        cashFlowDates: ["03/01/2028"]
                        cashFlows: [100.25]
                        interestFlows: [0]
                        principalFlows: [100.25]
                      PYAnalytics:
                        approxDuration: 7.9694454520297
                        approxModDuration: 7.9638047553582
                        approxConvexity: 67.401257813743
                        pv1b: 0.078941214637489
                        yv32: 0.39586419012559
                      cashFlowAnalytics:
                        yieldSemiAnnual: 0.14165833655455
                        yieldPeriodic: 0.14165833655455
                        yieldAnnual: 0.14170850426534
                        macDuration: 15.938888888889
                        durationYears: 7.9694444444444
                        modDuration: 7.9638037484861
                        convexityInPeriods: 269.60501466752
                        convexityInYears: 67.401253666881
                        averageLifeInPeriods: 15.938888888889
                        averageLifeInYears: 7.9694444444444
                        afterTaxYield: 0.11344627674257
                        taxableEquivalentYield: 0.17684007343175
                        pvBPC: 0.078941214637489
                        totalInterestFlows: 0
                        totalPrincipalFlows: 100.25
                        totalIFPlusIOI: 0
                        totalPFPlusIOP: 100.25
                        totalIOI: 0
                        totalIOP: 0
                        totalFutureAmount: 100.25
                        totalReturn: 0.14165833655451
                        capitalGainLoss: 1.125
                        totalDollarReturn: 1.125
                    - redemptionInfo:
                        worstIndicator: ""
                        redemptionType: "Maturity"
                        redemptionDate: "06/01/2045"
                        redemptionValue: 100
                      PY:
                        price: 99.125
                        yield: 3.1118999738449
                        ai: 0
                        tradingPrice: 99.125
                      couponPeriod:
                        previousCouponDate: "03/01/2020"
                        nextCouponDate: "09/01/2020"
                      cashFlows:
                        cashFlowCount: 51
                        cashFlowDates: ["09/01/2020", "03/01/2021", "09/01/2021", "03/01/2022", "09/01/2022", "03/01/2023", "09/01/2023", "03/01/2024", "09/01/2024", "03/01/2025", "09/01/2025", "03/01/2026", "09/01/2026", "03/01/2027", "09/01/2027", "03/01/2028", "09/01/2028", "03/01/2029", "09/01/2029", "03/01/2030", "09/01/2030", "03/01/2031", "09/01/2031", "03/01/2032", "09/01/2032", "03/01/2033", "09/01/2033", "03/01/2034", "09/01/2034", "03/01/2035", "09/01/2035", "03/01/2036", "09/01/2036", "03/01/2037", "09/01/2037", "03/01/2038", "09/01/2038", "03/01/2039", "09/01/2039", "03/01/2040", "09/01/2040", "03/01/2041", "09/01/2041", "03/01/2042", "09/01/2042", "03/01/2043", "09/01/2043", "03/01/2044", "09/01/2044", "03/01/2045", "06/01/2045"]
                        cashFlows: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 101.5]
                        interestFlows: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 1.5]
                        principalFlows: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 100]
                      PYAnalytics:
                        approxDuration: 20.938799360655
                        approxModDuration: 20.617993690523
                        approxConvexity: 460.52855688289
                        pv1b: 0.20437586245731
                        yv32: 0.15290455352342
                      cashFlowAnalytics:
                        yieldSemiAnnual: 3.1118999738449
                        yieldPeriodic: 3.1118999738449
                        yieldAnnual: 3.136109777463
                        macDuration: 41.87756178673
                        durationYears: 20.938780893365
                        modDuration: 20.617975506173
                        convexityInPeriods: 1842.1133257649
                        convexityInYears: 460.52833144122
                        averageLifeInPeriods: 50.438888888889
                        averageLifeInYears: 25.219444444444
                        afterTaxYield: 2.0858654203656
                        taxableEquivalentYield: 4.5217140581162
                        pvBPC: 0.20437586245731
                        totalInterestFlows: 91.5
                        totalPrincipalFlows: 100
                        totalIFPlusIOI: 115.97066541975
                        totalPFPlusIOP: 100
                        totalIOI: 24.470665419754
                        totalIOP: 0
                        totalFutureAmount: 215.97066541975
                        totalReturn: 3.111899973845
                        capitalGainLoss: 0.875
                        totalDollarReturn: 116.84566541975
        '422':
          description: Calculation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/sscmfiAPICalculateMultistep:
    post:
      summary: Calculate Multi-Step Coupon Bond
      description: Specific endpoint for Multi-Step Coupon Bond calculations.
      operationId: calculateMultistep
      tags:
        - Specific Calculations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculationRequestMultistep'
            example:
              metatdata:
                calculationID: "ABC123"
                version:
                  dataInputFormat: ""
                  resultsFormat: ""
              securityDefinition:
                securityID: "Testsec1"
                securityType: "corporate"
                issueDate: "12/1/2019"
                firstCouponDate: "3/15/2020"
                lastCouponDate: "3/15/2049"
                maturityDate: "10/1/2049"
                couponRateList:
                  - date: "12/1/2019"
                    value: 4.00
                  - date: "03/15/2024"
                    value: 5.00
                  - date: "09/15/2028"
                    value: 6.00
                  - date: "09/15/2030"
                    value: 6.50
                  - date: "09/15/2033"
                    value: 7.00
                  - date: "03/15/2049"
                    value: 8.0
                redemptionValue: 100.0
                dayCountBasis: "SSCM30/360"
                eomRule: "Adjust"
                periodsPerYear: "SemiAnnual"
                callRedemptions:
                  redemptionScheduleType: "Continuous with notification"
                  notifyMinDays: 30
                  notifyMaxDays: 60
                  notifyStart: "Trade date"
                  notifyCalendarBusiness: "business days"
                  redemptionList:
                    - date: "03/15/2021"
                      value: 101.00
                    - date: "09/15/2025"
                      value: 102.00
                    - date: "03/15/2026"
                      value: 101.50
                    - date: "09/15/2026"
                      value: 101.00
                    - date: "03/15/2027"
                      value: 100.50
                    - date: "09/15/2027"
                      value: 100.00
                    - date: "03/15/2028"
                      value: 100.00
              tradeDefinition:
                tradeDate: "11/1/2024"
                settlementDate: "11/2/2024"
                givenType: "Price"
                givenValue: 101
              calculationSelection:
                calcsToReturn:
                  calcPY: "Yes"
                  calcPYAnalytics: "Yes"
                  calcCFS: "Yes"
                  calcCFSAnalytics: "Yes"
                  calcCouponPeriod: "Yes"
                calculationsFor: "all redemptions"
              settings:
                holidayList:
                  - date: "01/1/2020"
                  - date: "07/04/2023"
                dateScheme:
                  dateTwoOrFourYear: "FOUR"
                  dateFormat: "MDY"
                  dateCutoffYear: 2075
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                success: true
                metadata:
                  calculationDate: "2026-01-26 21:55:09"
                  version:
                    calculationEngine: "1.2.7"
                    dataInputFormat: "1.2.7"
                    resultsFormat: "1.2.7"
                  securityID: "Testsec1"
                  calculationID: ""
                data:
                  summary:
                    calculationsToCount: 8
                    worstPositionInList: 6
                  calculationTo:
                    - redemptionInfo:
                        redemptionType: "Call"
                        redemptionDate: "12/13/2024"
                        redemptionValue: 101
                        worstIndicator: ""
                      PY:
                        price: 101
                        yield: 4.9187047410848
                        ai: 0.65277777777778
                        tradingPrice: 101
                      couponPeriod:
                        previousCouponDate: "09/15/2024"
                        nextCouponDate: "12/13/2024"
                      cashFlows:
                        cashFlowCount: 1
                        cashFlowDates: ["12/13/2024"]
                        cashFlows: [102.22222222222]
                        interestFlows: [1.2222222222222]
                        principalFlows: [101]
                      PYAnalytics:
                        approxDuration: 0.11603977960342
                        approxModDuration: 0.11325445351612
                        approxConvexity: 0.025653156112544
                        pv1b: 0.0011512629795618
                        yv32: 27.144102220584
                      cashFlowAnalytics:
                        yieldSemiAnnual: 4.9187047410848
                        yieldPeriodic: 4.9187047410848
                        yieldAnnual: 4.9791888819098
                        macDuration: 0.22778965525874
                        durationYears: 0.11389482762937
                        modDuration: 0.11116098725422
                        convexityInPeriods: 0.2664100187028
                        convexityInYears: 0.066602504675701
                        averageLifeInPeriods: 0.22777777777778
                        averageLifeInYears: 0.11388888888889
                        afterTaxYield: 3.1248433451317
                        taxableEquivalentYield: 7.8957573395495
                        pvBPC: 0.0011299823147226
                        totalInterestFlows: 1.2222222222222
                        totalPrincipalFlows: 101
                        totalIFPlusIOI: 1.2222222222222
                        totalPFPlusIOP: 101
                        totalIOI: 0
                        totalIOP: 0
                        totalFutureAmount: 102.22222222222
                        totalReturn: 4.9656208115743
                        capitalGainLoss: 0
                        totalDollarReturn: 1.2222222222222
        '422':
          description: Calculation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/sscmfiAPICalculatePIK:
    post:
      summary: Calculate PIK Bond
      description: Specific endpoint for Payment-in-Kind (PIK) bond calculations.
      operationId: calculatePIK
      tags:
        - Specific Calculations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculationRequestPIK'
            example:
              metadata:
                calculationID: "Sample 17"
              securityDefinition:
                securityID: "Testsec117"
                securityType: "corporate"
                maturityDate: "6/1/2027"
                PIKCouponRate: 7.65
                redemptionValue: 100.0
                dayCountBasis: "SSCM30/360"
                eomRule: "Adjust"
                periodsPerYear: "SemiAnnual"
              tradeDefinition:
                tradeDate: "9/06/2026"
                settlementDate: "9/09/2026"
                givenType: "yield"
                givenValue: 8.0
              calculationSelection:
                calcsToReturn:
                  calcPY: "Yes"
                  calcPYAnalytics: "Yes"
                  calcCFS: "Yes"
                  calcCFSAnalytics: "Yes"
                  calcCouponPeriod: "Yes"
                calculationsFor: "worst and maturity"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                success: true
                metadata:
                  calculationDate: "2026-01-26 22:13:31"
                  version:
                    calculationEngine: "1.2.7"
                    dataInputFormat: "1.2.7"
                    resultsFormat: "1.2.7"
                  securityID: "Testsec117"
                  calculationID: "Sample 17"
                data:
                  summary:
                    calculationsToCount: 1
                    worstPositionInList: 1
                  calculationTo:
                    - redemptionInfo:
                        redemptionType: "Maturity"
                        redemptionDate: "06/01/2027"
                        redemptionValue: 100
                        worstIndicator: "Worst"
                      PY:
                        price: 101.81479892779
                        yield: 8
                        ai: 0
                        tradingPrice: 101.814
                      couponPeriod:
                        previousCouponDate: "06/01/2026"
                        nextCouponDate: "12/01/2026"
                      cashFlows:
                        cashFlowCount: 1
                        cashFlowDates: ["06/01/2027"]
                        cashFlows: [107.79630625]
                        interestFlows: [0]
                        principalFlows: [107.79630625]
                      PYAnalytics:
                        approxDuration: 0.7277777801568
                        approxModDuration: 0.69978632707385
                        approxConvexity: 0.8261366863993
                        pv1b: 0.0071248604183438
                        yv32: 4.3860508368056
                      cashFlowAnalytics:
                        yieldSemiAnnual: 8
                        yieldPeriodic: 8
                        yieldAnnual: 8.16
                        macDuration: 1.4555669772046
                        durationYears: 0.72778348860231
                        modDuration: 0.69979181596376
                        convexityInPeriods: 3.3045724642733
                        convexityInYears: 0.82614311606833
                        averageLifeInPeriods: 1.4555555555556
                        averageLifeInYears: 0.72777777777778
                        afterTaxYield: 6.4122490174384
                        taxableEquivalentYield: 9.9794726582975
                        pvBPC: 0.0071248604183438
                        totalInterestFlows: 0
                        totalPrincipalFlows: 107.79630625
                        totalIFPlusIOI: 0
                        totalPFPlusIOP: 107.79630625
                        totalIOI: 0
                        totalIOP: 0
                        totalFutureAmount: 107.79630625
                        totalReturn: 8.0011213315498
                        capitalGainLoss: 5.98230625
                        totalDollarReturn: 5.98230625
        '422':
          description: Calculation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/sscmfiAPICalculatePartPIK:
    post:
      summary: Calculate Part-PIK Bond
      description: Specific endpoint for Part-PIK Bond calculations.
      operationId: calculatePartPIK
      tags:
        - Specific Calculations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculationRequestPartPIK'
            example:
              metadata:
                calculationID: "ABC123"
                version:
                  dataInputFormat: ""
                  resultsFormat: ""
              securityDefinition:
                securityID: "Testsec21"
                securityType: "corporate"
                maturityDate: "3/15/2030"
                PIKCouponRate: 5
                PIKCashCouponRate: 2
                redemptionValue: 100.0
                dayCountBasis: "SSCM30/360"
                eomRule: "Adjust"
                periodsPerYear: "SemiAnnual"
              tradeDefinition:
                tradeDate: "1/5/2026"
                settlementDate: "1/6/2026"
                givenType: "yield"
                givenValue: 7.75
              calculationSelection:
                calcsToReturn:
                  calcPY: "Yes"
                  calcPYAnalytics: "Yes"
                  calcCFS: "Yes"
                  calcCFSAnalytics: "No"
                  calcCouponPeriod: "Yes"
              settings:
                dateScheme:
                  dateTwoOrFourYear: "FOUR"
                  dateFormat: "MDY"
                  dateCutoffYear: 2075
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                success: true
                metadata:
                  calculationDate: "2026-01-26 22:23:11"
                  version:
                    calculationEngine: "1.2.7"
                    dataInputFormat: "1.2.7"
                    resultsFormat: "1.2.7"
                  securityID: "Testsec21"
                  calculationID: "ABC123"
                data:
                  summary:
                    calculationsToCount: 1
                    worstPositionInList: 1
                  calculationTo:
                    - redemptionInfo:
                        redemptionType: "Maturity"
                        redemptionDate: "03/15/2030"
                        redemptionValue: 100
                        worstIndicator: "Worst"
                      PY:
                        price: 98.79503276173
                        yield: 7.75
                        ai: 0.63208333333333
                        tradingPrice: 98.795
                      couponPeriod:
                        previousCouponDate: "09/15/2025"
                        nextCouponDate: "03/15/2026"
                      cashFlows:
                        cashFlowCount: 9
                        cashFlowDates: ["03/15/2026", "09/15/2026", "03/15/2027", "09/15/2027", "03/15/2028", "09/15/2028", "03/15/2029", "09/15/2029", "03/15/2030"]
                        cashFlows: [1.025, 1.050625, 1.076890625, 1.103812890625, 1.1314082128906, 1.1596934182129, 1.1886857536682, 1.2184028975099, 126.13515996471]
                        interestFlows: [1.025, 1.050625, 1.076890625, 1.103812890625, 1.1314082128906, 1.1596934182129, 1.1886857536682, 1.2184028975099, 1.2488629699477]
                        principalFlows: [0, 0, 0, 0, 0, 0, 0, 0, 124.88629699477]
                      PYAnalytics:
                        approxDuration: 4.0143262506971
                        approxModDuration: 3.8645740078913
                        approxConvexity: 17.235890630283
                        pv1b: 0.038424344854057
                        yv32: 0.81328647550643
        '422':
          description: Calculation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/sscmfiPublicAPI:
    post:
      summary: Public Fixed Income Calculation API
      description: |
        Public endpoint for bond calculations. No API key required.
        Rate limited to 10 requests per minute.
      operationId: calculatePublic
      tags:
        - Public
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculationRequestPublic'
            example:
              metadata:
                calculationID: "ABC987"
              securityDefinition:
                securityID: "Testsec77"
                paymentType: "Periodic"
                securityType: "CD"
                maturityDate: "3/31/2031"
                couponRate: 3.75
                redemptionValue: 100.0
                dayCountBasis: "SSCM30/360"
                eomRule: "Adjust"
                periodsPerYear: "Monthly"
                callRedemptions:
                  redemptionScheduleType: "Discrete with notification"
                  notifyMinDays: 30
                  notifyMaxDays: 60
                  notifyStart: "Settlement date"
                  notifyCalendarBusiness: "Calendar days"
                  redemptionList:
                    - date: "03/31/2027"
                      value: 101.50
                    - date: "09/30/2027"
                      value: 101.00
                    - date: "03/31/2028"
                      value: 100.50
              tradeDefinition:
                tradeDate: "7/22/2020"
                settlementDate: "7/23/2020"
                givenType: "yield"
                givenValue: 3.55
              calculationSelection:
                calcsToReturn:
                  calcPY: "Yes"
                  calcCouponPeriod: "Yes"
                calculationsFor: "Maturity only"
              settings:
                dateScheme:
                  dateTwoOrFourYear: "FOUR"
                  dateFormat: "MDY"
                  dateCutoffYear: 2075
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                success: true
                metadata:
                  calculationDate: "2026-01-27 11:59:34"
                  version:
                    calculationEngine: "1.2.7"
                    dataInputFormat: "1.2.7"
                    resultsFormat: "1.2.7"
                  securityID: "Testsec77"
                  calculationID: "ABC987"
                data:
                  summary:
                    calculationsToCount: 1
                    worstPositionInList: 1
                  calculationTo:
                    - redemptionInfo:
                        redemptionType: "Maturity"
                        redemptionDate: "03/31/2031"
                        redemptionValue: 100
                        worstIndicator: "Worst"
                      PY:
                        price: 101.77058315528
                        yield: 3.55
                        ai: 0.23958333333333
                        tradingPrice: 101.770
                      couponPeriod:
                        previousCouponDate: "06/30/2020"
                        nextCouponDate: "09/30/2020"
        '422':
          description: Calculation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key for authentication

  schemas:
    # --- Generic Request ---
    CalculationRequest:
      type: object
      required: [securityDefinition, tradeDefinition]
      properties:
        metadata: { $ref: '#/components/schemas/Metadata' }
        securityDefinition: { $ref: '#/components/schemas/SecurityDefinition' }
        tradeDefinition: { $ref: '#/components/schemas/TradeDefinition' }
        calculationSelection: { $ref: '#/components/schemas/CalculationSelection' }
        settings: { $ref: '#/components/schemas/Settings' }

    BatchCalculationRequest:
      type: array
      items:
        $ref: '#/components/schemas/CalculationRequest'

    CalculationRequestPublic:
      type: object
      required: [securityDefinition, tradeDefinition]
      properties:
        metadata: { $ref: '#/components/schemas/Metadata' }
        securityDefinition: { $ref: '#/components/schemas/SecurityDefinition' }
        tradeDefinition: { $ref: '#/components/schemas/TradeDefinition' }
        calculationSelection: { $ref: '#/components/schemas/CalculationSelection' }
        settings: { $ref: '#/components/schemas/Settings' }

    # --- Specific Requests (Flattened) ---
    
    CalculationRequestPeriodic:
      type: object
      required: [securityDefinition, tradeDefinition]
      properties:
        metadata: { $ref: '#/components/schemas/Metadata' }
        securityDefinition: { $ref: '#/components/schemas/SecurityDefinitionPeriodic' }
        tradeDefinition: { $ref: '#/components/schemas/TradeDefinitionPeriodic' }
        calculationSelection: { $ref: '#/components/schemas/CalculationSelection' }
        settings: { $ref: '#/components/schemas/Settings' }

    CalculationRequestDiscount:
      type: object
      required: [securityDefinition, tradeDefinition]
      properties:
        metadata: { $ref: '#/components/schemas/Metadata' }
        securityDefinition: { $ref: '#/components/schemas/SecurityDefinitionDiscount' }
        tradeDefinition: { $ref: '#/components/schemas/TradeDefinition' }
        calculationSelection: { $ref: '#/components/schemas/CalculationSelection' }
        settings: { $ref: '#/components/schemas/Settings' }

    CalculationRequestIAM:
      type: object
      required: [securityDefinition, tradeDefinition]
      properties:
        metadata: { $ref: '#/components/schemas/Metadata' }
        securityDefinition: { $ref: '#/components/schemas/SecurityDefinitionIAM' }
        tradeDefinition: { $ref: '#/components/schemas/TradeDefinition' }
        calculationSelection: { $ref: '#/components/schemas/CalculationSelection' }
        settings: { $ref: '#/components/schemas/Settings' }

    CalculationRequestStepped:
      type: object
      required: [securityDefinition, tradeDefinition]
      properties:
        metadata: { $ref: '#/components/schemas/Metadata' }
        securityDefinition: { $ref: '#/components/schemas/SecurityDefinitionStepped' }
        tradeDefinition: { $ref: '#/components/schemas/TradeDefinition' }
        calculationSelection: { $ref: '#/components/schemas/CalculationSelection' }
        settings: { $ref: '#/components/schemas/Settings' }

    CalculationRequestMultistep:
      type: object
      required: [securityDefinition, tradeDefinition]
      properties:
        metadata: { $ref: '#/components/schemas/Metadata' }
        securityDefinition: { $ref: '#/components/schemas/SecurityDefinitionMultistep' }
        tradeDefinition: { $ref: '#/components/schemas/TradeDefinition' }
        calculationSelection: { $ref: '#/components/schemas/CalculationSelection' }
        settings: { $ref: '#/components/schemas/Settings' }

    CalculationRequestPIK:
      type: object
      required: [securityDefinition, tradeDefinition]
      properties:
        metadata: { $ref: '#/components/schemas/Metadata' }
        securityDefinition: { $ref: '#/components/schemas/SecurityDefinitionPIK' }
        tradeDefinition: { $ref: '#/components/schemas/TradeDefinition' }
        calculationSelection: { $ref: '#/components/schemas/CalculationSelection' }
        settings: { $ref: '#/components/schemas/Settings' }

    CalculationRequestPartPIK:
      type: object
      required: [securityDefinition, tradeDefinition]
      properties:
        metadata: { $ref: '#/components/schemas/Metadata' }
        securityDefinition: { $ref: '#/components/schemas/SecurityDefinitionPartPIK' }
        tradeDefinition: { $ref: '#/components/schemas/TradeDefinition' }
        calculationSelection: { $ref: '#/components/schemas/CalculationSelection' }
        settings: { $ref: '#/components/schemas/Settings' }


    # --- Common Components ---

    Metadata:
      type: object
      description: Optional metadata that will be returned with results
      properties:
        calculationID:
          type: string
          description: User-defined calculation identifier
          example: "ABC123"
        version:
          type: object
          description: Version information for data formats
          properties:
            dataInputFormat:
              type: string
              description: The version of the input JSON schema used
            resultsFormat:
              type: string
              description: The version of the output JSON schema returned

    # Generic Security Definition (Superset)
    SecurityDefinition:
      type: object
      description: Comprehensive definition of the security's payment and structure features
      required:
        - paymentType
        - securityType
        - maturityDate
        - dayCountBasis
        - eomRule
      properties:
        securityID:
          type: string
          description: Internal identifier or name for the security (optional)
        paymentType:
          type: string
          enum: [Discount, IAM, Periodic, Stepped, Multistep, PIK, Part-PIK]
          description: The interest payment structure of the security
        securityType:
          type: string
          enum: [Treasury, Agency, Corporate, Municipal, CD]
          description: The asset class or issuer type of the security
        issueDate:
          type: string
          description: Original date of issue for the security
        firstCouponDate:
          type: string
          description: The first date on which interest is paid to investors
        lastCouponDate:
          type: string
          description: The final coupon date before maturity
        maturityDate:
          type: string
          description: The date on which the principal balance of the security becomes due and payable
        stepDate:
          type: string
          description: The date on which the coupon rate changes (for Stepped securities)
        couponRate:
          type: number
          description: Annual stated interest rate as a percent (e.g., 3.75 represents 3.75%)
        initialCouponRate:
          type: number
          description: Initial annual interest rate before the step date as a percent
        stepCouponRate:
          type: number
          description: Annual interest rate applicable after the step date as a percent
        PIKCouponRate:
          type: number
          description: Annual Payment-In-Kind interest rate as a percent
        PIKCashCouponRate:
          type: number
          description: The cash portion of the annual coupon for Part-PIK securities as a percent
        couponRateList:
          type: array
          description: Schedule of coupon rates and dates for Multistep securities
          items:
            type: object
            properties:
              date: {type: string, description: Date the new rate becomes effective}
              value: {type: number, description: The new coupon rate as a percent}
        redemptionValue:
          type: number
          description: The price at which the security is redeemed at maturity (usually 100.0)
        dayCountBasis:
          type: string
          enum: [Actual/Actual, SSCM30/360, Actual/360, Actual/365]
          description: The method used to calculate the number of days for interest accrual
        eomRule:
          type: string
          enum: [Adjust, Do not adjust, Always 28, Always 29, Always 30]
          description: End-of-Month Rule determining how coupon dates adjust to the last day of the month
        periodsPerYear:
          type: string
          enum: [Annual, Semiannual, Quarterly, Monthly]
          description: The frequency of periodic interest payments
        callRedemptions: # Alias for legacy
           $ref: '#/components/schemas/callRedemptions'

    # --- Specific Security Definitions (Flattened) ---
    
    SecurityDefinitionPeriodic:
      type: object
      description: Definition for securities with fixed periodic coupon payments
      required: [securityType, maturityDate, couponRate, redemptionValue, dayCountBasis, eomRule, periodsPerYear]
      properties:
        securityID: { type: string, description: Internal identifier or name }
        securityType: { type: string, enum: [Treasury, Agency, Corporate, Municipal, CD], description: The asset class or issuer type }
        issueDate: { type: string, description: Original date of issue }
        firstCouponDate: { type: string, description: The first date on which interest is paid }
        lastCouponDate: { type: string, description: The final coupon date before maturity }
        maturityDate: { type: string, description: Principal due date }
        couponRate: { type: number, minimum: 0, description: Annual interest rate as a percent }
        redemptionValue: { type: number, minimum: 0, description: Redemption price at maturity (usually 100) }
        dayCountBasis: { type: string, enum: [Actual/Actual, SSCM30/360], description: Method for counting days for interest accrual }
        eomRule: { type: string, enum: [Adjust, Do not adjust, Always 28, Always 29, Always 30], description: End-of-Month adjustment rule }
        periodsPerYear: { type: string, enum: [Annual, Semiannual, Quarterly, Monthly], description: Frequency of interest payments }
        callRedemptions: { $ref: '#/components/schemas/callRedemptions' }

    SecurityDefinitionDiscount:
      type: object
      description: Definition for securities issued at a discount with no periodic interest
      required: [securityType, maturityDate, redemptionValue, dayCountBasis, eomRule]
      properties:
        securityID: { type: string, description: Internal identifier or name }
        securityType: { type: string, enum: [Treasury, Agency, Corporate, Municipal], description: The asset class or issuer type }
        issueDate: { type: string, description: Original date of issue }
        maturityDate: { type: string, description: Principal due date }
        redemptionValue: { type: number, minimum: 0, description: Redemption price at maturity (usually 100) }
        dayCountBasis: { type: string, enum: [Actual/360, Actual/365, SSCM30/360], description: Method for counting days for interest accrual }
        eomRule: { type: string, enum: [Adjust, Do not adjust, Always 28, Always 29, Always 30], description: End-of-Month adjustment rule }

    SecurityDefinitionIAM:
      type: object
      description: Definition for securities where interest is paid in a single payment at maturity
      required: [securityType, issueDate, maturityDate, couponRate, redemptionValue, dayCountBasis, eomRule]
      properties:
        securityID: { type: string, description: Internal identifier or name }
        securityType: { type: string, enum: [Agency, Corporate, Municipal, CD], description: The asset class or issuer type }
        issueDate: { type: string, description: Original date of issue }
        maturityDate: { type: string, description: Principal and interest due date }
        couponRate: { type: number, minimum: 0, description: Annual interest rate as a percent }
        redemptionValue: { type: number, minimum: 0, description: Redemption price at maturity (usually 100) }
        dayCountBasis: { type: string, enum: [SSCM30/360, Actual/360, Actual/365], description: Method for counting days for interest accrual }
        eomRule: { type: string, enum: [Adjust, Do not adjust, Always 28, Always 29, Always 30], description: End-of-Month adjustment rule }
        callRedemptions: { $ref: '#/components/schemas/callRedemptions' }

    SecurityDefinitionStepped:
      type: object
      description: Definition for securities with a single scheduled coupon rate change
      required: [securityType, maturityDate, stepDate, initialCouponRate, stepCouponRate, redemptionValue, dayCountBasis, eomRule]
      properties:
         securityID: { type: string, description: Internal identifier or name }
         securityType: { type: string, enum: [Agency, Corporate, Municipal], description: The asset class or issuer type }
         issueDate: { type: string, description: Original date of issue }
         firstCouponDate: { type: string, description: The first date on which interest is paid }
         lastCouponDate: { type: string, description: The final coupon date before maturity }
         maturityDate: { type: string, description: Principal due date }
         stepDate: { type: string, description: The date on which the coupon rate changes from initial to step rate }
         initialCouponRate: { type: number, minimum: 0, description: Annual interest rate as a percent prior to the step date }
         stepCouponRate: { type: number, minimum: 0, description: Annual interest rate as a percent after the step date }
         redemptionValue: { type: number, minimum: 0, description: Redemption price at maturity (usually 100) }
         dayCountBasis: { type: string, enum: [Actual/Actual, SSCM30/360], description: Method for counting days for interest accrual }
         eomRule: { type: string, enum: [Adjust, Do not adjust, Always 28, Always 29, Always 30], description: End-of-Month adjustment rule }
         periodsPerYear: { type: string, enum: [Annual, Semiannual, Quarterly, Monthly], description: Frequency of interest payments }
         callRedemptions: { $ref: '#/components/schemas/callRedemptions' }

    SecurityDefinitionMultistep:
      type: object
      description: Definition for securities with multiple scheduled coupon rate changes
      required: [securityType, maturityDate, couponRateList, redemptionValue, dayCountBasis, eomRule]
      properties:
         securityID: { type: string, description: Internal identifier or name }
         securityType: { type: string, enum: [Agency, Corporate, Municipal], description: The asset class or issuer type }
         issueDate: { type: string, description: Original date of issue }
         firstCouponDate: { type: string, description: The first date on which interest is paid }
         lastCouponDate: { type: string, description: The final coupon date before maturity }
         maturityDate: { type: string, description: Principal due date }
         couponRateList:
           type: array
           description: A scheduled list of effectiveness dates and new coupon rates
           items:
             type: object
             properties:
               date: {type: string, description: The date on which the new rate takes effect}
               value: {type: number, description: The new coupon rate as a percent}
         redemptionValue: { type: number, minimum: 0, description: Redemption price at maturity (usually 100) }
         dayCountBasis: { type: string, enum: [Actual/Actual, SSCM30/360], description: Method for counting days for interest accrual }
         eomRule: { type: string, enum: [Adjust, Do not adjust, Always 28, Always 29, Always 30], description: End-of-Month adjustment rule }
         periodsPerYear: { type: string, enum: [Annual, Semiannual, Quarterly, Monthly], description: Frequency of interest payments }
         callRedemptions: { $ref: '#/components/schemas/callRedemptions' }

    SecurityDefinitionPIK:
      type: object
      description: Definition for Payment-In-Kind securities where interest is added to the principal balance
      required: [securityType, maturityDate, PIKCouponRate, redemptionValue, dayCountBasis, eomRule]
      properties:
         securityID: { type: string, description: Internal identifier or name }
         securityType: { type: string, enum: [Treasury, Agency, Corporate, Municipal, CD], description: The asset class or issuer type }
         issueDate: { type: string, description: Original date of issue }
         firstCouponDate: { type: string, description: The first date on which interest is paid (added to principal) }
         lastCouponDate: { type: string, description: The final coupon date before maturity }
         maturityDate: { type: string, description: Principal (including PIK interest) due date }
         PIKCouponRate: { type: number, minimum: 0, description: Annual PIK interest rate as a percent }
         redemptionValue: { type: number, minimum: 0, description: Redemption price at maturity (usually 100) }
         dayCountBasis: { type: string, enum: [Actual/Actual, SSCM30/360], description: Method for counting days for interest accrual }
         eomRule: { type: string, enum: [Adjust, Do not adjust, Always 28, Always 29, Always 30], description: End-of-Month adjustment rule }
         periodsPerYear: { type: string, enum: [Annual, Semiannual, Quarterly, Monthly], description: Frequency of interest payments }
         callRedemptions: { $ref: '#/components/schemas/callRedemptions' }
         
    SecurityDefinitionPartPIK:
      type: object
      description: Definition for securities with both cash and Payment-In-Kind coupon components
      required: [securityType, maturityDate, PIKCouponRate, PIKCashCouponRate, redemptionValue, dayCountBasis, eomRule]
      properties:
         securityID: { type: string, description: Internal identifier or name }
         securityType: { type: string, enum: [Agency, Corporate, Municipal], description: The asset class or issuer type }
         issueDate: { type: string, description: Original date of issue }
         firstCouponDate: { type: string, description: The first date on which interest is paid }
         lastCouponDate: { type: string, description: The final coupon date before maturity }
         maturityDate: { type: string, description: Principal (including PIK interest) due date }
         PIKCouponRate: { type: number, minimum: 0, description: Annual PIK interest rate as a percent }
         PIKCashCouponRate: { type: number, minimum: 0, description: Annual cash-pay interest rate as a percent }
         redemptionValue: { type: number, minimum: 0, description: Redemption price at maturity (usually 100) }
         dayCountBasis: { type: string, enum: [Actual/Actual, SSCM30/360], description: Method for counting days for interest accrual }
         eomRule: { type: string, enum: [Adjust, Do not adjust, Always 28, Always 29, Always 30], description: End-of-Month adjustment rule }
         periodsPerYear: { type: string, enum: [Annual, Semiannual, Quarterly, Monthly], description: Frequency of interest payments }
         callRedemptions: { $ref: '#/components/schemas/callRedemptions' }


    callRedemptions:
      type: object
      description: Provisions for early redemption or call scenarios prior to maturity
      properties:
        redemptionScheduleType:
          type: string
          enum: [Discrete no notification, Discrete with notification, Continuous with notification]
          description: Specify the call schedule structure (e.g., specific dates vs. a continuously callable)
        redemptionList:
          type: array
          description: A sorted list of specific dates and prices at which the security can be called
          items:
            type: object
            properties:
              date: { type: string, description: The specific call date }
              value: { type: number, minimum: 0, description: The redemption price per $100 on this date }
        notifyStart:
          type: string
          enum: [Trade date, Trade date plus one, Settlement date, Settlement date plus one]
          description: The starting point for calculating the notification window
        notifyCalendarBusiness:
          type: string
          enum: [Calendar days, Calendar days adjusted, Business days]
          description: The calendar logic used to count notification days
        notifyMinDays:
          type: integer
          minimum: 0
          description: Minimum required notice period in days
        notifyMaxDays:
          type: integer
          minimum: 0
          description: Maximum allowed notice period in days

    TradeDefinition:
      type: object
      required:
        - settlementDate
        - givenType
        - givenValue
      properties:
        tradeDate:
          type: string
          description: Trade date
          example: "3/1/2020"
        settlementDate:
          type: string
          description: Settlement date
          example: "3/12/2020"
        givenType:
          type: string
          enum: [Price, Yield, Discount rate]
        givenValue:
          type: number
          description: The given price or yield value
          example: 4.0

    TradeDefinitionPeriodic:
      type: object
      description: Trade-specific parameters for periodic interest securities
      required: [settlementDate, givenType, givenValue]
      properties:
        tradeDate:
          type: string
          description: The date on which the trade was executed
        settlementDate:
          type: string
          description: The date on which the trade is settled and ownership is transferred
        givenType: # Subset: Price, Yield (No Discount rate)
          type: string
          enum: [Price, Yield]
          description: Specify whether the givenValue represents a clean Price or a Yield
        givenValue:
          type: number
          description: The value for the Price or Yield (e.g., 98.75 or 4.25)

    CalculationSelection:
      type: object
      description: Specify which financial metrics and redemption scenarios to perform
      properties:
        calcsToReturn:
          type: object
          description: Flags to enable specific groups of calculation results
          properties:
            calcPY:
              type: string
              enum: [Yes, No]
              default: No
              description: Return clean price, yield, and accrued interest
            calcPYAnalytics:
              type: string
              enum: [Yes, No]
              default: No
              description: Return price-based analytics (duration, convexity, PV01)
            calcCFS:
              type: string
              enum: [Yes, No]
              default: No
              description: Return detailed cash flow schedule lists
            calcCFSAnalytics:
              type: string
              enum: [Yes, No]
              default: No
              description: Return cash-flow based analytics (total returns, after-tax yield, reinvestment metrics)
            calcCouponPeriod:
              type: string
              enum: [Yes, No]
              default: No
              description: Return previous and next coupon dates relative to settlement
        calculationsFor:
          type: string
          enum: [Maturity only, Worst only, Worst and maturity, All redemptions]
          default: Worst and maturity
          description: Select which redemption scenarios to include in the output

    Settings:
      type: object
      description: Global environment and calculation settings
      properties:
        reinvestment:
          type: object
          description: Configuration for the reinvestment of periodic cash flows
          properties:
            type:
              type: string
              enum: [Periodic yield, Given rate]
              default: Periodic yield
              description: Method for determining the reinvestment rate
            rate:
              type: number
              description: Explicit reinvestment rate as a percent (required if type is 'Given rate')
        holidayList:
          type: array
          description: Optional list of dates to be treated as holidays for business day calculations
          items:
            type: object
            properties:
              date: { type: string, description: The holiday date }
        dateScheme:
          type: object
          description: Rules for parsing and formatting date strings
          properties:
            dateFormat:
              type: string
              enum: [YMD, MDY, DMY, ymd, mdy, dmy]
              default: MDY
              description: The sequence of year, month, and day components
            dateSeparator:
              type: string
              enum: ["/", "-"]
              default: "/"
              description: The character used to separate date components
            dateTwoOrFourYear:
              type: string
              enum: [Two, Four]
              default: Four
              description: Specify if years are provided as two or four digits
            dateCutoffYear:
              type: integer
              default: 75
              description: The threshold year for 2-digit year interpretation (e.g., 75 maps to 1975-2074)

    BatchCalculationResponse:
      type: object
      properties:
        batchSuccess: { type: boolean }
        batchMetaData:
          type: object
          properties:
             batchSize: { type: integer }
             processedCount: { type: integer }
             batchErrorCount: { type: integer }
             calculationDate: { type: string }
             version: { type: object }
        results:
          type: array
          items:
            $ref: '#/components/schemas/SuccessResponse'

    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        metadata:
          type: object
          properties:
            calculation_date:
              type: string
              format: date-time
            version:
              type: object
            securityID:
              type: string
            calculationID:
              type: string
        data:
          type: object
          properties:
            summary:
              type: object
              description: Summary of calculation results
              properties:
                calculationsToCount:
                  type: integer
                  description: Total number of redemption dates processed for this security
                worstPositionInList:
                  type: integer
                  description: The 1-based index in the calculationTo array representing the worst-case scenario
            calculationTo:
              type: array
              items:
                type: object
                properties:
                  redemptionInfo:
                    type: object
                    description: Information about the redemption date for these calculations
                    properties:
                      redemptionType:
                        type: string
                        enum: [Maturity, Call]
                        description: Type of redemption
                      redemptionDate:
                        type: string
                        description: The date of the redemption
                      redemptionValue:
                        type: number
                        description: The value of the redemption per $100
                      worstIndicator:
                        type: string
                        enum: [Worst, ""]
                        description: Indicates if this redemption date is the worst case scenario
                  PY:
                    type: object
                    description: Price/Yield results
                    properties:
                      price:
                        type: number
                        description: Clean price (without accrued interest)
                      yield:
                        type: number
                        description: Yield as a percent (e.g., 5.125 represents 5.125%)
                      discountRate:
                        type: number
                        description: Discount rate as a percent (only for discount securities)
                      ai:
                        type: number
                        description: Accrued interest per $100
                      tradingPrice:
                        type: number
                        description: Total price rounded or truncated per industry standard conventions
                  PYAnalytics:
                    type: object
                    description: Price/Yield analytics calculated by shifting the Price up and down
                    properties:
                      approxDuration:
                        type: number
                        description: Approximate duration
                      approxModDuration:
                        type: number
                        description: Approximate modified duration
                      approxConvexity:
                        type: number
                        description: Approximate convexity
                      pv1b:
                        type: number
                        description: Price value of one basis point
                      yv32:
                        type: number
                        description: Yield value of 1/32
                  cashFlows:
                    type: object
                    description: Scheduled cash flows for the security
                    properties:
                      cashFlowCount:
                        type: integer
                        description: Number of entries in the cash flow lists
                      cashFlowDates:
                        type: array
                        items: { type: string }
                        description: List of dates corresponding to the cash flows
                      cashFlows:
                        type: array
                        items: { type: number }
                        description: List of total cash flows per $100
                      interestFlows:
                        type: array
                        items: { type: number }
                        description: List of interest flows per $100
                      principalFlows:
                        type: array
                        items: { type: number }
                        description: List of principal flows per $100
                  couponPeriod:
                    type: object
                    properties:
                      previousCouponDate:
                        type: string
                        description: Previous coupon date from the settlement date
                      nextCouponDate:
                        type: string
                        description: Next coupon date from the settlement date
                  cashFlowAnalytics:
                    type: object
                    description: Calculated values using cash flows and price
                    properties:
                      yieldPeriodic:
                        type: number
                        description: Yield based on the securities coupon periods per year
                      yieldSemiAnnual:
                        type: number
                        description: Yield based on semi-annual compounding
                      yieldAnnual:
                        type: number
                        description: Yield based on annual compounding
                      macDuration:
                        type: number
                        description: Macaulay duration based on the securities coupon periods per year
                      durationYears:
                        type: number
                        description: Duration based on annual compounding
                      modDuration:
                        type: number
                        description: Modified duration
                      convexityInPeriods:
                        type: number
                        description: Convexity based on the securities coupon periods per year
                      convexityInYears:
                        type: number
                        description: Convexity based on annual compounding
                      averageLifeInPeriods:
                        type: number
                        description: Average life based on the securities coupon periods per year
                      averageLifeInYears:
                        type: number
                        description: Average life based on one coupon period per year
                      afterTaxYield:
                        type: number
                        description: After tax yield (tax rates default to 37% for income tax, 20% for capital gains tax)
                      taxableEquivalentYield:
                        type: number
                        description: Taxable equivalent yield (tax rates default to 37% for income tax, 20% for capital gains tax)
                      pvBPC:
                        type: number
                        description: Price value of a basis point change
                      totalInterestFlows:
                        type: number
                        description: Total of the interest flows
                      totalPrincipalFlows:
                        type: number
                        description: Total of the principal flows
                      totalIFPlusIOI:
                        type: number
                        description: Total interest on interest flows (reinvestment at yield)
                      totalPFPlusIOP:
                        type: number
                        description: Total interest on principal flows (reinvestment at yield)
                      totalIOI:
                        type: number
                        description: Total interest on interest
                      totalIOP:
                        type: number
                        description: Total interest on principal
                      totalFutureAmount:
                        type: number
                        description: Total future amount
                      totalReturn:
                        type: number
                        description: Total return as a percent
                      capitalGainLoss:
                        type: number
                        description: Capital gain or loss
                      totalDollarReturn:
                        type: number
                        description: Total dollar return

    SuccessResponseDiscount:
      type: object
      properties:
        success: { type: boolean, example: true }
        metadata:
          type: object
          properties:
            calculation_date: { type: string }
            version: { type: object }
            securityID: { type: string }
            calculationID: { type: string }
        data:
          type: object
          properties:
            summary:
              type: object
              description: Summary of calculation results
              properties:
                calculationsToCount:
                  type: integer
                  description: Total number of redemption dates processed for this security
                worstPositionInList:
                  type: integer
                  description: The 1-based index in the calculationTo array representing the worst-case scenario
            calculationTo:
              type: array
              items:
                type: object
                properties:
                  redemptionInfo:
                    type: object
                    description: Information about the redemption date for these calculations
                    properties:
                      redemptionType:
                        type: string
                        enum: [Maturity, Call]
                        description: Type of redemption
                      redemptionDate:
                        type: string
                        description: The date of the redemption
                      redemptionValue:
                        type: number
                        description: The value of the redemption per $100
                      worstIndicator:
                        type: string
                        enum: [Worst, ""]
                        description: Indicates if this redemption date is the worst case scenario
                  PY:
                    type: object
                    description: Price/Yield results
                    properties: # Discount has Discount Rate, No AI
                      price:
                        type: number
                        description: Clean price (without accrued interest)
                      yield:
                        type: number
                        description: Yield as a percent (e.g., 5.125 represents 5.125%)
                      discountRate:
                        type: number
                        description: Discount rate as a percent (only for discount securities)
                      tradingPrice:
                        type: number
                        description: Total price rounded or truncated per sector standard conventions
                  PYAnalytics:
                    type: object
                    description: Price/Yield analytics calculated by shifting the Price up and down
                    properties:
                      approxDuration:
                        type: number
                        description: Approximate duration
                      approxModDuration:
                        type: number
                        description: Approximate modified duration
                      approxConvexity:
                        type: number
                        description: Approximate convexity
                      pv1b:
                        type: number
                        description: Price value of one basis point
                      yv32:
                        type: number
                        description: Yield value of 1/32
                  cashFlows:
                    type: object
                    description: Scheduled cash flows for the security
                    properties:
                      cashFlowCount:
                        type: integer
                        description: Number of entries in the cash flow lists
                      cashFlowDates:
                        type: array
                        items: { type: string }
                        description: List of dates corresponding to the cash flows
                      cashFlows:
                        type: array
                        items: { type: number }
                        description: List of total cash flows per $100
                      interestFlows:
                        type: array
                        items: { type: number }
                        description: List of interest flows per $100
                      principalFlows:
                        type: array
                        items: { type: number }
                        description: List of principal flows per $100
                  couponPeriod:
                    type: object
                    properties:
                      previousCouponDate:
                        type: string
                        description: Previous coupon date from the settlement date
                      nextCouponDate:
                        type: string
                        description: Next coupon date from the settlement date
                  cashFlowAnalytics:
                    type: object
                    description: Calculated values using cash flows and price
                    properties:
                      yieldPeriodic:
                        type: number
                        description: Yield based on the securities coupon periods per year
                      yieldSemiAnnual:
                        type: number
                        description: Yield based on semi-annual compounding
                      yieldAnnual:
                        type: number
                        description: Yield based on annual compounding
                      macDuration:
                        type: number
                        description: Macaulay duration based on the securities coupon periods per year
                      durationYears:
                        type: number
                        description: Duration based on annual compounding
                      modDuration:
                        type: number
                        description: Modified duration
                      convexityInPeriods:
                        type: number
                        description: Convexity based on the securities coupon periods per year
                      convexityInYears:
                        type: number
                        description: Convexity based on annual compounding
                      averageLifeInPeriods:
                        type: number
                        description: Average life based on the securities coupon periods per year
                      averageLifeInYears:
                        type: number
                        description: Average life based on one coupon period per year
                      afterTaxYield:
                        type: number
                        description: After tax yield (tax rates default to 37% for income tax, 20% for capital gains tax)
                      taxableEquivalentYield:
                        type: number
                        description: Taxable equivalent yield (tax rates default to 37% for income tax, 20% for capital gains tax)
                      pvBPC:
                        type: number
                        description: Price value of a basis point change
                      totalInterestFlows:
                        type: number
                        description: Total of the interest flows
                      totalPrincipalFlows:
                        type: number
                        description: Total of the principal flows
                      totalIFPlusIOI:
                        type: number
                        description: Total interest on interest flows (reinvestment at yield)
                      totalPFPlusIOP:
                        type: number
                        description: Total interest on principal flows (reinvestment at yield)
                      totalIOI:
                        type: number
                        description: Total interest on interest
                      totalIOP:
                        type: number
                        description: Total interest on principal
                      totalFutureAmount:
                        type: number
                        description: Total future amount
                      totalReturn:
                        type: number
                        description: Total return as a percent
                      capitalGainLoss:
                        type: number
                        description: Capital gain or loss
                      totalDollarReturn:
                        type: number
                        description: Total dollar return

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        errorInfo:
          $ref: '#/components/schemas/ErrorInfo'
        metadata:
          type: object

    SystemErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string

    ErrorInfo:
      type: object
      description: |
        Error information object returned when calculation or validation errors occur.
        This error structure applies to ALL API endpoints.
        
        **Error Parameter Mappings (errorParm1/2/3):**
        
        
        
        The meaning of errorParm1/2/3 depends on the error code category:
        
        
        
        *For DATE errors (3000-5016):* errorParm values map to date field types:
        - `1` - Settlement Date
        - `2` - Maturity Date
        - `3` - Issue Date
        - `4` - First Coupon Date
        - `5` - Last Coupon Date
        - `6` - Trade Date
        - `7` - Redemption Date (for call schedules)
        - `8` - Holiday Date (for holiday lists)
        - `9` - Coupon Rate Start Date (for coupon rate lists)
        - `10` - Step Date
        
        *For PARAMETER errors (6001-6008):* errorParm values map to parameter field names:
        - `1` - securityType
        - `2` - paymentType
        - `3` - givenType
        - `4` - givenValue
        - `5` - couponRate
        - `6` - redemptionValue
        - `7` - periodsPerYear
        - `8` - dayCountBasis
        - `9` - eomRule
        - `10` - notifyCalendarBusiness
        - `11` - notifyStart
        - `12` - notifyMinDays
        - `13` - notifyMaxDays
        - `14` - redemptionScheduleType
        - `15` - calculationsFor
        - `16` - earlyRedemptions
        - `17` - couponRateList
        - `18` - PIKCashCouponRate
        - `19` - PIKCouponRate
        - `20` - initialCouponRate
        - `21` - stepCouponRate
        - `22` - dateFormat
        - `23` - dateSeparator
        - `24` - dateTwoOrFourYear
        - `25` - dateCutoffYear
        - `26` - calcsToReturn
        
        **Error Position (errorPos1/2/3):**
        Contains the 1-based position in array/list where error occurred (e.g., 3rd item in redemptionList)
        
        **Error Code Categories:**
        
        *Date Comparison Errors (3000-3006):*
        - `3000` - errorParm1 date is greater than errorParm2 date
        - `3001` - errorParm1 date is less than errorParm2 date
        - `3002` - errorParm1 date is equal to errorParm2 date
        - `3003` - errorParm1 date is greater than or equal to errorParm2 date (must be less than)
        - `3004` - errorParm1 date is less than or equal to errorParm2 date
        - `3005` - At least one errorParm1 date must be less than or equal to errorParm2 date
        - `3006` - errorParm1 date cannot be before January 1st, 1953 unless errorParm2 date is provided
        
        *Date Cycle Errors (4000-4002):*
        - `4000` - errorParm1 date must be on the same periodic cycle as errorParm2 date unless errorParm3 date is provided
        - `4001` - errorParm1 date must be on the same periodic cycle as errorParm2 when they are provided
        - `4002` - errorParm1 date must be on the same periodic cycle as errorParm2 date or errorParm3 date when provided
        
        *Date Validation Errors (5000-5016):*
        - `5000` - Missing required date (errorParm1 represents the specific date)
        - `5001` - Invalid date month (errorParm1 represents the specific date)
        - `5002` - Invalid date day (errorParm1 represents the specific date)
        - `5003` - Invalid date year - must be 1900 to 2200 (errorParm1 represents the specific date)
        - `5004` - errorParm1 date is required when errorParm2 date is provided
        - `5010` - Date string malformed
        - `5011` - Date string separator invalid (must be / or -)
        - `5012` - Invalid dateFormat specified (must be YMD, MDY, DMY, ymd, mdy, or dmy)
        - `5013` - Invalid twoOrFourYear specified (must be 4 digit year or 2 digit year provided)
        - `5014` - twoOrFourYear invalid (4 digit year specified, 2 digit year provided)
        - `5015` - Invalid yearCutOff specified (must be less than 100 and greater than or equal to 0)
        - `5016` - twoOrFourYear invalid (2 digit year specified, 4 digit year provided)
        
        *Holiday List Errors (5400-5403):*
        - `5400` - holidayCount exceeds max (cannot be more than 3000 holidays in the list)
        - `5401` - Invalid holiday (must be between January 1, 1800 and December 1, 2300)
        - `5402` - Invalid holidayList (must be in ascending order)
        - `5403` - Invalid holiday (holidays can only be weekdays)
        
        *Redemption List Errors (5500-5550):*
        - `5500` - Redemptions determined for calculations exceed maximum number allowed (must be less than 100)
        - `5501` - Invalid redemption date
        - `5502` - Invalid redemption date (must be before maturity)
        - `5503` - Invalid redemptionList (must be in date ascending order if notification is provided)
        - `5550` - Invalid redemptionList value (must be greater than 0) or missing redemptionList value
        
        *Coupon Rate List Errors (5600-5603):*
        - `5600` - Invalid couponRateList value (must be greater than or equal to 0)
        - `5601` - Missing required couponRateList value
        - `5603` - Invalid couponRateList (must be in date ascending order)
        
        *Parameter Errors (6001-6009):*
        - `6001` - Required value for x was not provided
        - `6002` - Provided value for x is invalid
        - `6003` - Provided value for x is invalid for the provided paymentType and securityType
        - `6004` - Provided value for x must be numeric
        - `6005` - Provided value for x must be numeric and greater than zero
        - `6006` - Provided value for x must be numeric and greater than or equal to zero
        - `6007` - Provided value for x is not supported for the provided paymentType and securityType
        - `6008` - At least one of x must be selected
        - `6009` - Provided value for x must be numeric and greater than 0.000001

        *Calcuated Value Errors (8900-8903):*
        - `8900` - The calculated value for price is less than or equal to zero. Cash flow analytics cannot be calculated
        - `8901` - The calculated value for price is less than or equal to zero. Risk measures cannot be calculated
        - `8902` - Cannot calculate tax equivalent yield with the data provided, The given or calculated price is out of range.
        - `8903` - Cannot calculate after tax yield with the data provided, The given or calculated price is out of range.

        *System Errors (9998-10002):*
        - `9990` - Internal formula selection error (logged)
        - `9996` - The calculated dirty price used in analytics is less than or equal to zero (logged)
        - `9997` - Cannot calculate equivalent yield with the data provided (logged)
        - `9998` - Cannot calculate yield with the data provided (logged)
        - `9999` - Unexpected error (logged)
        - `10001` - Method not allowed - use POST
        - `10002` - Internal server error (logged)
      properties:
        error:
          type: boolean
          description: Always true when errorInfo is present
          example: true
        errorNumber:
          type: integer
          description: Error code indicating the type of error that occurred
          example: 3000
        errorParm1:
          type: integer
          description: |
            First parameter involved in the error. For date errors, represents a date field (1-10).
            For parameter errors, represents a parameter type (1-25).
          example: 1
        errorPos1:
          type: integer
          description: |
            1-based position in array/list where error occurred. 
            Used for list errors (holidayList, redemptionList, couponRateList).
            0 if not applicable.
          example: 3
        errorParm2:
          type: integer
          description: |
            Second parameter involved in the error (for comparison/relationship errors).
            0 if not applicable.
          example: 2
        errorPos2:
          type: integer
          description: |
            1-based position for second parameter in array/list.
            0 if not applicable.
          example: 0
        errorParm3:
          type: integer
          description: |
            Third parameter involved in the error (for complex relationship errors).
            0 if not applicable.
          example: 0
        errorPos3:
          type: integer
          description: |
            1-based position for third parameter in array/list.
            0 if not applicable.
          example: 0
        errorMessage:
          type: string
          description: Human-readable description of the error
          example: "Settlement Date is greater than Maturity Date"
      example:
        error: true
        errorNumber: 3000
        errorParm1: 1
        errorParm2: 2
        errorParm3: 0
        errorPos1: 0
        errorPos2: 0
        errorPos3: 0
        errorMessage: "Settlement Date is greater than Maturity Date"

