JSON Risk instrument fields guide


adjust_accrual_periods Boolean

Instruments

Relevant for most cash flow generating instruments, i.e., bond, floater, swap, swaption, callable_bond

Meaning

If true, interest is calculated on adjusted coupon periods, i.e., from start and end of each accrual period after adjustment according to bdc and calendar attributes. Refer cash flow generation for details.


bdc String

Domain

JSON Risk recognizes unadjusted, following, modified following, preceding. For convenience, JSON Risk interprets only the first letter and ignores case. That is, for m and M, JSON Risk assumes the modified folling business day convention.

Instruments

Relevant for most cash flow generating instruments, i.e., bond, floater, swap, swaption, callable_bond

Meaning

This field determines how dates generated within schedule generation are adjusted, dependent on the field calendar. Refer cash flow generation for details.


calendar String

Domain

Contains the string target, case insensitive, or the identifier of any calendar previously registered using the library.add_calendar functionality.

Instruments

Relevant for most cash flow generating instruments, i.e., bond, floater, swap, swaption, callable_bond

Meaning

Reference to the calendar used to adjust dates generated within cash flow generation.


call_tenor Natural

Domain

Any positive integer.

Instruments

Relevant for callable_bond

Meaning

The exercise dates for the instrument type callable_bond are determined by the attribute first_exercise_date which represents the first date the bond can be called, and the attribute call_tenor. If call_tenoris not zero, the bond is callable on the date represented by first_exercise_date and every call_tenor months after that date. If call_tenoris zero, the bond is callable on the date represented by first_exercise_date only.


cap_rate

This field has no meaning in the current implementation but is reserved for representing a cap rate or cap rate schedule on the interest rate of floating rate instruments.


conditions_valid_until Date vector

Domain

Any array of dates or date strings representing the dates when conditions change.

Instruments

Relevant for many cash flow generating instruments, i.e., bond, floater, callable_bond.

Meaning

Specified the dates when conditions, e.g., fixed_rate, float_spread or interest_capitalization, change within a cashflow stream. Refer to cash flow generation for details.


currency String

Context

Only relevant in the context of vector pricing.

Domain

Any string representing any currency the conversion rate was previously registered in the parameters object for vector pricing.


dcc

Domain

JSON Risk supports the day count conventions

  • act/act according to the ISDA 2006 rules in section 4.16 (b), also recognized by JSON Risk as actual/actual or a/a
  • act/365 according to the ISDA 2006 rules in section 4.16 (d), also recognized by JSON Risk as actual/365, a/365, actual/365 (fixed) or act/365 (fixed)
  • act/360 according to the ISDA 2006 rules in section 4.16 (e), also recognized by JSON Risk as actual/360, a/360, or french
  • 30u/360 according to the ISDA 2006 rules in section 4.16 (f), also recognized by JSON Risk as 30/360, bond basis, or bond
  • 30e/360 according to the ISDA 2006 rules in section 4.16 (g), also recognized by JSON Risk as eurobond basis or eurobond
  • 30g/360 according to the ISDA 2006 rules in section 4.16 (h), also recognized by JSON Risk as 30e/360 (isda) or 30/360 german

For convenience, JSON Risk ignores case and supports all specifications mentioned above. For example, it makes no difference if 30E/360 is specified or EuRoBoNd.

Instruments

Relevant for most cash flow generating instruments, i.e., bond, floater, swap, swaption, callable_bond

Meaning

Determines how interest amounts are calculated for each accrual period generated within schedule generation.


disc_curve String

Context

Only relevant in the context of vector pricing.

Domain

Any string representing any curve previously registered in the parameters object for vector pricing.

Meaning

The curve referenced by this field is applied for discounting cash flows. For the instruments bond, floater and callable_bond, discounting is additionally affected by spread_curve as well as residual_spread.


effective_date Date

Instruments

Relevant for most cash flow generating instruments, i.e., bond, floater, swap, swaption, callable_bond

Meaning

Start date for schedule generation.


exclude_base Boolean

Instruments

Relevant for callable_bond

Meaning

If true, present value returns only the embedded option price. Defaults to false.


first_date Date

Instruments

Relevant for most cash flow generating instruments, i.e., bond, floater, swap, swaption, callable_bond

Meaning

Used fo specifying an explicit initial stub for the interest schedule. Marks the end date of the initial interest rate period within schedule generation.


first_exercise_date Date

Instruments

Relevant for swaption and callable_bond.

Meaning

For swaption instruments, this is the expiry date, i.e., the date when the swaption is exercised. The exercise dates for the instrument type callable_bond are determined by the attribute first_exercise_date which represents the first date the bond can be called, and the attribute call_tenor.


fixed_rate Number or Number vector

Instruments

Relevant for most cash flow generating instruments, i.e., bond, floater, swap, swaption, callable_bond

Meaning

Represents the fixed rate paid on a bond instrument, a callable_bond instrument or the fixed leg of a swap or swaption instrument. For a floater instrument, this must be left empty, otherwise the floater is treated as a fixed rate bond. When the field conditions_valid_until is populated with a vector of dates, fixed_rate may contain a vector of numbers of the same length and each entry in fixed_rate is considered the valid interest rate until the corresponding entry in conditions_valid_until.


fixing_first_date Date

Instruments

Relevant for all instruments paying floating rate coupons, i.e., floater, swap, swaption

Meaning

Used fo specifying an explicit initial stub for the fixing schedule. Marks the end date of the initial fixing period within schedule generation.


fixing_next_to_last_date Date

Instruments

Relevant for all instruments paying floating rate coupons, i.e., floater, swap, swaption

Meaning

Used fo specifying an explicit final stub for the fixing schedule. Marks the start date of the final fixing period within schedule generation.


fixing_stub_end Boolean

Instruments

Relevant for all instruments paying floating rate coupons, i.e., floater, swap, swaption

Meaning

Used fo specifying an implicit final stub for the fixing schedule. A value of true causes the fixing schedule to be rolled out forward within schedule generation. Ignored when fixing_next_to_last_date is populated.


fixing_stub_long Boolean

Instruments

Relevant for all instruments paying floating rate coupons, i.e., floater, swap, swaption

Meaning

If start and end dates within fixing schedule generation are not aligned with fixing_tenor, a value of true specifies a long stub to be generated instead of a short stub.


float_bdc String

Domain

JSON Risk recognizes unadjusted, following, modified following, preceding. For convenience, JSON Risk interprets only the first letter and ignores case. That is, for m and M, JSON Risk assumes the modified folling business day convention.

Instruments

Relevant for swap and swaption

Meaning

Relevant for the floating rate leg only. This field determines how dates generated within schedule generation are adjusted, dependent on the field calendar. Refer cash flow generation for details.


float_current_rate Number

Instruments

Relevant for floater, swap and swaption

Meaning

This field specifies the interest rate to be used on floating rate legs for fixing periods starting in the past.


float_dcc String

Domain

JSON Risk supports the day count conventions

  • act/act according to the ISDA 2006 rules in section 4.16 (b), also recognized by JSON Risk as actual/actual or a/a
  • act/365 according to the ISDA 2006 rules in section 4.16 (d), also recognized by JSON Risk as actual/365, a/365, actual/365 (fixed) or act/365 (fixed)
  • act/360 according to the ISDA 2006 rules in section 4.16 (e), also recognized by JSON Risk as actual/360, a/360, or french
  • 30u/360 according to the ISDA 2006 rules in section 4.16 (f), also recognized by JSON Risk as 30/360, bond basis, or bond
  • 30e/360 according to the ISDA 2006 rules in section 4.16 (g), also recognized by JSON Risk as eurobond basis or eurobond
  • 30g/360 according to the ISDA 2006 rules in section 4.16 (h), also recognized by JSON Risk as 30e/360 (isda) or 30/360 german

For convenience, JSON Risk ignores case and supports all specifications mentioned above. For example, it makes no difference if 30E/360 is specified or EuRoBoNd.

Instruments

Relevant for swap and swaption

Meaning

Relevant for the floating rate leg only. Determines how interest amounts are calculated for each accrual period generated within schedule generation.


float_spread Number or Number vector

Instruments

Relevant for floater, swap and swaption

Meaning

Relevant for the floating rate leg only. Represents a spread over the floating rate.

When the field conditions_valid_until is populated with a vector of dates, float_spread may contain a vector of numbers of the same length and each entry in float_spread is considered the valid spread over float until the corresponding entry in conditions_valid_until.


float_tenor Natural

Domain

Must be zero or positive.

Instruments

Relevant for swap and swaption

Meaning

Only relevant for the floating rate leg. A value of zero indicates interest is paid at maturity. Any other positive value is used within schedule generation for rolling out monthly dates.


floor_rate Number

This field has no meaning in the current implementation but is reserved for representing a cap rate or cap rate schedule on the interest rate of floating rate instruments.


fwd_curve String

Context

Only relevant in the context of vector pricing.

Domain

Any string representing any curve previously registered in the parameters object for vector pricing.


hull_white_volatility Number

Instruments

Only relevant for callable_bond

Meaning

Overrides the internal volatility parameter in the Hull-White model used to evaluate options with a constant value. In case this parameter is set, the automatic calibration against a basket of swaptions is skipped. This is useful for analysis purposes.


interest_capitalization Boolean or Boolean vector

Instruments

Relevant for bond, floater, callable_bond

Meaning

If true, a notional payment is generated at each interest payment date within cash flow generation. The amount of the generated notional payment is calculated by changing the sign of the interest payment.

When the field conditions_valid_until is populated with a vector of dates, interest_capitalization may contain a vector of booleans of the same length and each entry in interest_capitalization is considered valid until the corresponding entry in conditions_valid_until.


is_payer Boolean

Instruments

Relevant for swap, swaption

Meaning

A value of true marks a swapinstrument as a payer swap and marks a swaption instrument as a payer swaption. Defaults to false, implying a receiver swap or, respecitvely, a receiver swaption.


is_short Boolean

Instruments

Relevant for swaption

Meaning

A value of true marks a swaption as short, that is, the counterparty holds th eexercise right.


linear_amortization Boolean

Instruments

Relevant for bond, floater, callable_bond

Meaning

If true, the field repay_amount is overriden and the repayment amount is calculated by dividing the notional by the number of repayments implied by the repayment schedule.


market_value

This field has no meaning in the current implementation but is reserved for representing the market value or, respectively, the dirty price of a position.


maturity Date

Instruments

Relevant for all cash flow generating instruments, i.e., bond, floater, swap, swaption, callable_bond, fxterm

Meaning

The date when all remaining notionals are paid back. In case of fxterm instruments, this is the date when notional is paid, as opposed to notional_2 which is paid at maturity_2.

For all instruments except fxterm, the final payment date is subject to the business day convention in bdc, whereas the unadjusted maturity is used for schedule generation.


maturity_2 Date

Instruments

Only relevant for fxterm

Meaning

The date when notional_2 is paid, as opposed to notional which is paid at maturity.


mean_reversion Number

Instruments

Only relevant for callable_bond

Meaning

Overrides the internal default value of zero for the mean reversion parameter in the Hull-White model used to evaluate options.


next_to_last_date Date

Instruments

Relevant for most cash flow generating instruments, i.e., bond, floater, swap, swaption, callable_bond

Meaning

Used fo specifying an explicit final stub for the interest schedule. Marks the start date of the final interest accrual period within schedule generation.


notional Number

Instruments

Relevant for all cash flow generating instruments, i.e., bond, floater, swap, swaption, callable_bond, fxterm

Meaning

The notional of an instrument. In case of amortizing instruments, this is the initial notional. In case of fxterm instruments, this is the near leg notional, i.e., the notional paid at maturity as opposed to maturity_2


notional_2 Number

Instruments

Only relevant for fxterm

Meaning

Corresponds to the far leg notional of an fxterm instrument, i.e., the notional paid at maturity_2.


opportunity_spread Number

Instruments

Only relevant for callable_bond

Meaning

This field is used to model an additional spread the holder of a callable bond would have to pay if they replace the callable bond with a cheaper bond. Positive values of opportunity_spread lower the value of the call option.


quantity Number

Domain

Zero, positive and negative values accepted.

Instruments

Relevant for equity

Meaning

The number of pieces of equity held in the equity position.


repay_amount Number

Domain

Zero, positive and negative values accepted.

Instruments

Relevant for bond, floater, callable_bond

Meaning

The amount repaid at each date implied by the repayment schedule. If notional is positive, a positive value marks cash inflows. If notional is negative, a positive value marks cash outflows. A zero value switsches off amortization.

When the field conditions_valid_until is populated with a vector of dates, repay_amount may contain a vector of numbers of the same length and each entry in repay_amount is considered valid until the corresponding entry in conditions_valid_until.


repay_first_date Date

Instruments

Relevant for bond, floater, callable_bond

Meaning

Used fo specifying an explicit initial stub for the repayment schedule. Marks first date when repayments occur within schedule generation.


repay_next_to_last_date Date

Instruments

Relevant for bond, floater, callable_bond

Meaning

Used fo specifying an explicit final stub for the repayment schedule. Marks the last date before maturity where repayment occors within schedule generation.


repay_stub_end Boolean

Instruments

Relevant for bond, floater, callable_bond

Meaning

Used fo specifying an implicit final stub for the repayment schedule. A value of true causes the repayment schedule to be rolled out forward within schedule generation. Ignored when repay_next_to_last_date is populated.


repay_stub_long Boolean

Instruments

Relevant for bond, floater, callable_bond

Meaning

If start and end dates within repayment schedule generation are not aligned with repay_tenor, a value of true specifies a long stub to be generated instead of a short stub.


repay_tenor Natural

Domain

Must be zero or positive.

Instruments

Relevant for bond, floater, callable_bond

Meaning

A value of zero indicates a bullet instrument, i.e., all notional is paid back at maturity. Any other positive value is used within repayment schedule generation for rolling out monthly dates.


residual_spread Number

Instruments

Relevant for bond, floater, callable_bond

Meaning

Within discounted cash flow valuation, this number is interpreted as an additional spread with day count convention act/365 and annual compounding that is added on top of the discount curve and the spread curve.


settlement_days Natural

Domain

Must be zero or positive

Instruments

Relevant for bond, floater, callable_bond

Meaning

Within discounted cash flow valuation, this specifies a number of business days where payments are not included in the present value.


spread_curve String

Context

Only relevant in the context of vector pricing

Instruments

Relevant for bond, floater, callable_bond

Domain

Any string representing any curve previously registered in the parameters object for vector pricing.

Meaning

The curve referenced by this field is applied for discounting cash flows, in addition to the curve specified under disc_curve as well as the residual_spread.


stub_end Boolean

Instruments

Relevant for most cash flow generating instruments, i.e., bond, floater, swap, swaption, callable_bond

Meaning

Used fo specifying an implicit final stub for the interest schedule. A value of true causes the interest schedule to be rolled out forward within schedule generation. Ignored when next_to_last_date is populated.


stub_long Boolean

Instruments

Relevant for most cash flow generating instruments, i.e., bond, floater, swap, swaption, callable_bond

Meaning

If start and end dates within interest schedule generation are not aligned with tenor, a value of true specifies a long stub to be generated instead of a short stub.


surface String

Context

Only relevant in the context of vector pricing.

Instruments

Relevant for swaption and callable_bond instruments.

Domain

Any string representing any surface previously registered in the parameters object for vector pricing.

Meaning

Bachelier volatility curve object used for valuation.


tenor Natural

Domain

Must be zero or positive.

Instruments

Relevant for most cash flow generating instruments, i.e., bond, floater, swap, swaption, callable_bond

Meaning

A value of zero indicates interest is paid at maturity. Any other positive value is used within schedule generation for rolling out monthly dates.


type String

Context

Only relevant in the context of vector pricing.

Domain

Either bond, floater, swap, swaption, callable_bond or fxterm

Meaning

The vector pricing algorithm uses this field to determine

  • what internal class to use for pricing;
  • what parameters to assign and apply for pricing.

For example,

  • for a bond type instrument, a fixed_income internal object is created and a discount curve and a spread curve are assigned,
  • for a swap type instrument, a swap internal object is created and a discount curve and a forward curve are assigned,
  • for a floater type instrument, a fixed_income internal object is created and a discount curve, a spread curve and a forward curve are assigned,
  • for a callable_bond type instrument, a callable_fixed_income internal object is created and a discount curve, a forward curve, a spread curve and a surface are assigned.
  • for an equity type instrument, an equity internal object is created and a quote is assigned.

Free and open source

JSON risk is published under the MIT License.

View code on GitHub (Library)

View code on GitHub (App)

Downloads

Library

json_risk.js

Minified Library

json_risk.min.js

App (.tar.gz)

jr.tar.gz

App (.tar.bz2)

jr.tar.bz2

App (.zip)

jr.zip

This project is maintained by

www.frame-consult.de