Raw schema
{
"type": "object",
"properties": {
"current_age": {
"type": "integer",
"description": "Current age of the primary person."
},
"retirement_age": {
"type": "integer",
"description": "Age work income stops. Defaults to current age."
},
"life_expectancy": {
"type": "integer",
"description": "Age the plan must last until. Default 92."
},
"annual_spending": {
"type": "number",
"description": "Planned yearly spending in today's dollars, after tax: what the household keeps. The engine withdraws enough each year to fund this plus that year's federal, state, Medicare-surcharge and penalty tax."
},
"monthly_contribution": {
"type": "number",
"description": "Monthly savings until retirement. Default 0."
},
"social_security": {
"type": "number",
"description": "Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden."
},
"ss_start_age": {
"type": "integer",
"description": "Age Social Security starts. Default 67."
},
"pension": {
"type": "number",
"description": "Yearly pension income. Default 0."
},
"pension_start_age": {
"type": "integer",
"description": "Age the pension starts. Default 65."
},
"inflation_rate": {
"type": "number",
"description": "Annual inflation as a percent, e.g. 2.5. Default 2.5."
},
"allocations": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 5,
"maxItems": 5,
"description": "Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0]."
},
"returns_source": {
"type": "string",
"description": "Which published return set to use (see list_return_assumption_sources). Default jpmorgan."
},
"traditional_balance": {
"type": "number",
"description": "Pre-tax retirement accounts today (traditional IRA, 401(k), 403(b)), in dollars. 0 if none."
},
"roth_balance": {
"type": "number",
"description": "Roth IRA and Roth 401(k) balance today, in dollars. 0 if none."
},
"taxable_balance": {
"type": "number",
"description": "Taxable brokerage and savings today, in dollars. 0 if none. The three balances together are the portfolio."
},
"filing_status": {
"type": "string",
"enum": [
"single",
"mfj",
"mfs",
"hoh"
],
"description": "Federal filing status: single, married filing jointly (mfj), married filing separately (mfs) or head of household (hoh)."
},
"state": {
"type": "string",
"description": "Two-letter state of residence (or DC) for state income tax with that state's retirement-income rules. When absent the result states that no state tax was modelled."
},
"cost_basis_ratio": {
"type": "number",
"description": "Percentage of the taxable account that is cost basis, 0-100. Default 40, and the result says so when it is assumed."
},
"spouse_age": {
"type": "integer",
"description": "Spouse's current age, for married filing jointly: sets the second aged deduction and Medicare surcharge. Default: the same as current_age, stated in the result."
},
"medicare_start_age": {
"type": "integer",
"description": "Age Medicare (and its IRMAA income surcharges) begins. Default 65. The year it begins is charged only for the months from the birthday month."
},
"birth_year": {
"type": "integer",
"description": "Year of birth, optional. Must match current_age: 2026 minus current_age, or 2025 minus current_age when this year's birthday is still to come (then every tax rule uses the age reached in each calendar year). Sets the RMD start age (73 if born 1951-1959, 75 if born 1960 or later). Default: 2026 minus current_age, stated in the result."
},
"birth_month": {
"type": "integer",
"description": "Month of birth, 1-12, optional. Times the half-year rules: the early-withdrawal penalty ends at 59 and a half, charitable distributions start at 70 and a half, Medicare starts in the birthday month. Default: not given, stated in the result."
},
"annual_qcd": {
"type": "number",
"description": "Yearly qualified charitable distribution from the traditional account, in today's dollars, counted against required minimum distributions. Default 0."
},
"roth_conversion": {
"type": "object",
"description": "The household's own Roth-conversion plan: a fixed amount per year between two ages. When given, the engine applies it on every path and searches withdrawal orders around it instead of searching its own conversion programmes.",
"properties": {
"annual_amount": {
"type": "number",
"description": "Dollars converted per year, today's dollars."
},
"start_age": {
"type": "integer"
},
"end_age": {
"type": "integer"
}
},
"required": [
"annual_amount",
"start_age",
"end_age"
]
},
"tax_exempt_interest": {
"type": "number",
"description": "Yearly municipal-bond interest, which counts toward Social Security taxability and IRMAA income but is not itself taxed. Default 0."
}
},
"required": [
"current_age",
"annual_spending",
"traditional_balance",
"roth_balance",
"taxable_balance",
"filing_status"
]
}