{ "openapi": "3.1.0", "info": { "title": "Dhanwise public retirement calculation", "version": "1.0.0", "description": "Stateless educational calculation with nominal INR, annual returns, year-end contributions and year-start withdrawals. All ten numeric fields required. No personal records, persistence or automatic ChatGPT integration. Best-effort per-worker limits, currently a shared 60-request/minute bucket; see /api-docs." }, "servers": [ { "url": "https://green-field-06308a200.2.azurestaticapps.net" } ], "paths": { "/api/retirement/calculate": { "post": { "operationId": "calculateRetirement", "summary": "Calculate corpus, constant monthly saving and annual projections", "description": "JSON body only, maximum 8192 bytes, no query parameters or compression. retirementAge >= age and lifeExpectancy > retirementAge. Do not submit private plans or identifiers. Projections follow supplied savings, not the minimum calculated contribution.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculationInput" }, "example": { "age": 35, "retirementAge": 60, "lifeExpectancy": 90, "monthlyExpense": 50000, "currentSavings": 1000000, "monthlySavings": 20000, "inflation": 6, "preReturn": 10, "postReturn": 6, "withdrawalTaxPercent": 5 } } } }, "responses": { "200": { "description": "Illustrative result; application sends Cache-Control: no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculationResult" }, "example": { "contractVersion": "1", "currency": "INR", "target": 81319655.74250817, "requiredCorpus": 81319655.74250817, "projected": 34438000.20752052, "gap": 46881655.53498765, "monthlyTarget": 59724.68, "requiredMonthlySIP": 59724.68, "retirementExpense": 2575122.431846093, "readiness": 42.34892522979382, "years": 25, "yearlyProjections": [ { "age": 35, "year": 0, "phase": "accumulation", "openingBalance": 1000000, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 100000, "closingBalance": 1340000 }, { "age": 36, "year": 1, "phase": "accumulation", "openingBalance": 1340000, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 134000, "closingBalance": 1714000.0000000002 }, { "age": 37, "year": 2, "phase": "accumulation", "openingBalance": 1714000.0000000002, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 171400.00000000003, "closingBalance": 2125400.0000000005 }, { "age": 38, "year": 3, "phase": "accumulation", "openingBalance": 2125400.0000000005, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 212540.00000000006, "closingBalance": 2577940.000000001 }, { "age": 39, "year": 4, "phase": "accumulation", "openingBalance": 2577940.000000001, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 257794.00000000012, "closingBalance": 3075734.0000000014 }, { "age": 40, "year": 5, "phase": "accumulation", "openingBalance": 3075734.0000000014, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 307573.40000000014, "closingBalance": 3623307.400000002 }, { "age": 41, "year": 6, "phase": "accumulation", "openingBalance": 3623307.400000002, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 362330.7400000002, "closingBalance": 4225638.140000002 }, { "age": 42, "year": 7, "phase": "accumulation", "openingBalance": 4225638.140000002, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 422563.81400000025, "closingBalance": 4888201.954000003 }, { "age": 43, "year": 8, "phase": "accumulation", "openingBalance": 4888201.954000003, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 488820.1954000003, "closingBalance": 5617022.149400003 }, { "age": 44, "year": 9, "phase": "accumulation", "openingBalance": 5617022.149400003, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 561702.2149400003, "closingBalance": 6418724.3643400045 }, { "age": 45, "year": 10, "phase": "accumulation", "openingBalance": 6418724.3643400045, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 641872.4364340005, "closingBalance": 7300596.800774005 }, { "age": 46, "year": 11, "phase": "accumulation", "openingBalance": 7300596.800774005, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 730059.6800774005, "closingBalance": 8270656.480851406 }, { "age": 47, "year": 12, "phase": "accumulation", "openingBalance": 8270656.480851406, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 827065.6480851406, "closingBalance": 9337722.128936548 }, { "age": 48, "year": 13, "phase": "accumulation", "openingBalance": 9337722.128936548, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 933772.2128936548, "closingBalance": 10511494.341830203 }, { "age": 49, "year": 14, "phase": "accumulation", "openingBalance": 10511494.341830203, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 1051149.4341830204, "closingBalance": 11802643.776013225 }, { "age": 50, "year": 15, "phase": "accumulation", "openingBalance": 11802643.776013225, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 1180264.3776013225, "closingBalance": 13222908.153614549 }, { "age": 51, "year": 16, "phase": "accumulation", "openingBalance": 13222908.153614549, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 1322290.815361455, "closingBalance": 14785198.968976006 }, { "age": 52, "year": 17, "phase": "accumulation", "openingBalance": 14785198.968976006, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 1478519.8968976007, "closingBalance": 16503718.865873609 }, { "age": 53, "year": 18, "phase": "accumulation", "openingBalance": 16503718.865873609, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 1650371.8865873609, "closingBalance": 18394090.75246097 }, { "age": 54, "year": 19, "phase": "accumulation", "openingBalance": 18394090.75246097, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 1839409.0752460973, "closingBalance": 20473499.82770707 }, { "age": 55, "year": 20, "phase": "accumulation", "openingBalance": 20473499.82770707, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 2047349.9827707072, "closingBalance": 22760849.81047778 }, { "age": 56, "year": 21, "phase": "accumulation", "openingBalance": 22760849.81047778, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 2276084.981047778, "closingBalance": 25276934.791525558 }, { "age": 57, "year": 22, "phase": "accumulation", "openingBalance": 25276934.791525558, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 2527693.479152556, "closingBalance": 28044628.270678114 }, { "age": 58, "year": 23, "phase": "accumulation", "openingBalance": 28044628.270678114, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 2804462.8270678115, "closingBalance": 31089091.09774593 }, { "age": 59, "year": 24, "phase": "accumulation", "openingBalance": 31089091.09774593, "contribution": 240000, "expense": 0, "requiredWithdrawal": 0, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 0, "investmentReturn": 3108909.1097745933, "closingBalance": 34438000.20752052 }, { "age": 60, "year": 25, "phase": "retirement", "openingBalance": 34438000.20752052, "contribution": 0, "expense": 2575122.431846093, "requiredWithdrawal": 2710655.19141694, "withdrawal": 2710655.19141694, "withdrawalTax": 135532.759570847, "netSpending": 2575122.431846093, "shortfall": 0, "investmentReturn": 1903640.7009662166, "closingBalance": 33630985.7170698 }, { "age": 61, "year": 26, "phase": "retirement", "openingBalance": 33630985.7170698, "contribution": 0, "expense": 2729629.7777568586, "requiredWithdrawal": 2873294.5029019564, "withdrawal": 2873294.5029019564, "withdrawalTax": 143664.72514509782, "netSpending": 2729629.7777568586, "shortfall": 0, "investmentReturn": 1845461.4728500731, "closingBalance": 32603152.687017914 }, { "age": 62, "year": 27, "phase": "retirement", "openingBalance": 32603152.687017914, "contribution": 0, "expense": 2893407.5644222703, "requiredWithdrawal": 3045692.173076074, "withdrawal": 3045692.173076074, "withdrawalTax": 152284.6086538037, "netSpending": 2893407.5644222703, "shortfall": 0, "investmentReturn": 1773447.630836513, "closingBalance": 31330908.144778352 }, { "age": 63, "year": 28, "phase": "retirement", "openingBalance": 31330908.144778352, "contribution": 0, "expense": 3067012.018287607, "requiredWithdrawal": 3228433.703460639, "withdrawal": 3228433.703460639, "withdrawalTax": 161421.68517303196, "netSpending": 3067012.018287607, "shortfall": 0, "investmentReturn": 1686148.466479063, "closingBalance": 29788622.907796778 }, { "age": 64, "year": 29, "phase": "retirement", "openingBalance": 29788622.907796778, "contribution": 0, "expense": 3251032.7393848635, "requiredWithdrawal": 3422139.7256682776, "withdrawal": 3422139.7256682776, "withdrawalTax": 171106.9862834139, "netSpending": 3251032.7393848635, "shortfall": 0, "investmentReturn": 1581988.9909277111, "closingBalance": 27948472.17305621 }, { "age": 65, "year": 30, "phase": "retirement", "openingBalance": 27948472.17305621, "contribution": 0, "expense": 3446094.703747955, "requiredWithdrawal": 3627468.109208374, "withdrawal": 3627468.109208374, "withdrawalTax": 181373.4054604187, "netSpending": 3446094.703747955, "shortfall": 0, "investmentReturn": 1459260.2438308708, "closingBalance": 25780264.307678707 }, { "age": 66, "year": 31, "phase": "retirement", "openingBalance": 25780264.307678707, "contribution": 0, "expense": 3652860.3859728323, "requiredWithdrawal": 3845116.1957608764, "withdrawal": 3845116.1957608764, "withdrawalTax": 192255.80978804384, "netSpending": 3652860.3859728323, "shortfall": 0, "investmentReturn": 1316108.8867150694, "closingBalance": 23251256.9986329 }, { "age": 67, "year": 32, "phase": "retirement", "openingBalance": 23251256.9986329, "contribution": 0, "expense": 3872032.009131203, "requiredWithdrawal": 4075823.1675065295, "withdrawal": 4075823.1675065295, "withdrawalTax": 203791.1583753265, "netSpending": 3872032.009131203, "shortfall": 0, "investmentReturn": 1150526.029867582, "closingBalance": 20325959.86099395 }, { "age": 68, "year": 33, "phase": "retirement", "openingBalance": 20325959.86099395, "contribution": 0, "expense": 4104353.9296790753, "requiredWithdrawal": 4320372.557556922, "withdrawal": 4320372.557556922, "withdrawalTax": 216018.6278778461, "netSpending": 4104353.9296790753, "shortfall": 0, "investmentReturn": 960335.2382062208, "closingBalance": 16965922.54164325 }, { "age": 69, "year": 34, "phase": "retirement", "openingBalance": 16965922.54164325, "contribution": 0, "expense": 4350615.16545982, "requiredWithdrawal": 4579594.911010337, "withdrawal": 4579594.911010337, "withdrawalTax": 228979.74555051688, "netSpending": 4350615.16545982, "shortfall": 0, "investmentReturn": 743179.6578379758, "closingBalance": 13129507.28847089 }, { "age": 70, "year": 35, "phase": "retirement", "openingBalance": 13129507.28847089, "contribution": 0, "expense": 4611652.07538741, "requiredWithdrawal": 4854370.605670958, "withdrawal": 4854370.605670958, "withdrawalTax": 242718.5302835479, "netSpending": 4611652.07538741, "shortfall": 0, "investmentReturn": 496508.2009679964, "closingBalance": 8771644.883767929 }, { "age": 71, "year": 36, "phase": "retirement", "openingBalance": 8771644.883767929, "contribution": 0, "expense": 4888351.199910655, "requiredWithdrawal": 5145632.842011216, "withdrawal": 5145632.842011216, "withdrawalTax": 257281.64210056083, "netSpending": 4888351.199910655, "shortfall": 0, "investmentReturn": 217560.72250540275, "closingBalance": 3843572.7642621156 }, { "age": 72, "year": 37, "phase": "retirement", "openingBalance": 3843572.7642621156, "contribution": 0, "expense": 5181652.271905294, "requiredWithdrawal": 5454370.8125318885, "withdrawal": 3843572.7642621156, "withdrawalTax": 192178.6382131058, "netSpending": 3651394.1260490096, "shortfall": 1530258.145856284, "investmentReturn": 0, "closingBalance": 0 }, { "age": 73, "year": 38, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 5492551.408219611, "requiredWithdrawal": 5781633.061283802, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 5492551.408219611, "investmentReturn": 0, "closingBalance": 0 }, { "age": 74, "year": 39, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 5822104.492712788, "requiredWithdrawal": 6128531.04496083, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 5822104.492712788, "investmentReturn": 0, "closingBalance": 0 }, { "age": 75, "year": 40, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 6171430.762275556, "requiredWithdrawal": 6496242.90765848, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 6171430.762275556, "investmentReturn": 0, "closingBalance": 0 }, { "age": 76, "year": 41, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 6541716.60801209, "requiredWithdrawal": 6886017.48211799, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 6541716.60801209, "investmentReturn": 0, "closingBalance": 0 }, { "age": 77, "year": 42, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 6934219.604492816, "requiredWithdrawal": 7299178.53104507, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 6934219.604492816, "investmentReturn": 0, "closingBalance": 0 }, { "age": 78, "year": 43, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 7350272.780762386, "requiredWithdrawal": 7737129.242907775, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 7350272.780762386, "investmentReturn": 0, "closingBalance": 0 }, { "age": 79, "year": 44, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 7791289.147608129, "requiredWithdrawal": 8201356.997482242, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 7791289.147608129, "investmentReturn": 0, "closingBalance": 0 }, { "age": 80, "year": 45, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 8258766.496464617, "requiredWithdrawal": 8693438.417331176, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 8258766.496464617, "investmentReturn": 0, "closingBalance": 0 }, { "age": 81, "year": 46, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 8754292.486252494, "requiredWithdrawal": 9215044.722371047, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 8754292.486252494, "investmentReturn": 0, "closingBalance": 0 }, { "age": 82, "year": 47, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 9279550.035427645, "requiredWithdrawal": 9767947.40571331, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 9279550.035427645, "investmentReturn": 0, "closingBalance": 0 }, { "age": 83, "year": 48, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 9836323.037553303, "requiredWithdrawal": 10354024.250056108, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 9836323.037553303, "investmentReturn": 0, "closingBalance": 0 }, { "age": 84, "year": 49, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 10426502.419806503, "requiredWithdrawal": 10975265.705059476, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 10426502.419806503, "investmentReturn": 0, "closingBalance": 0 }, { "age": 85, "year": 50, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 11052092.564994892, "requiredWithdrawal": 11633781.647363044, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 11052092.564994892, "investmentReturn": 0, "closingBalance": 0 }, { "age": 86, "year": 51, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 11715218.118894586, "requiredWithdrawal": 12331808.546204828, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 11715218.118894586, "investmentReturn": 0, "closingBalance": 0 }, { "age": 87, "year": 52, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 12418131.206028262, "requiredWithdrawal": 13071717.058977118, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 12418131.206028262, "investmentReturn": 0, "closingBalance": 0 }, { "age": 88, "year": 53, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 13163219.078389958, "requiredWithdrawal": 13856020.082515746, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 13163219.078389958, "investmentReturn": 0, "closingBalance": 0 }, { "age": 89, "year": 54, "phase": "retirement", "openingBalance": 0, "contribution": 0, "expense": 13953012.223093357, "requiredWithdrawal": 14687381.287466692, "withdrawal": 0, "withdrawalTax": 0, "netSpending": 0, "shortfall": 13953012.223093357, "investmentReturn": 0, "closingBalance": 0 } ], "assumptions": { "monetaryBasis": "nominal-INR", "rateUnit": "annual-percentage", "inflationPercent": 6, "preRetirementReturnPercent": 10, "postRetirementReturnPercent": 6, "effectiveWithdrawalTaxPercent": 5, "returnsNetOfFeesAndInvestmentTaxes": true, "contributionTiming": "year-end", "contributionGrowthPercent": 0, "contributionAggregation": "monthly-amount-times-12", "retirementSpendingTiming": "year-start", "horizonEndAgeExclusive": 90, "projectionBasis": "supplied-current-savings-and-monthly-savings", "requiredMonthlySIPMeaning": "total-constant-monthly-equivalent-not-monthly-compounding", "requiredMonthlySIPRounding": "up-to-0.01-INR" }, "limitations": [ { "code": "ILLUSTRATIVE_ONLY", "message": "Educational deterministic estimate, not investment or tax advice; returns and inflation are assumptions, not forecasts." }, { "code": "NO_MONTHLY_COMPOUNDING", "message": "requiredMonthlySIP aliases monthlyTarget: twelve monthly amounts are contributed at each year end, not invested monthly." }, { "code": "NO_MARKET_RISK_MODEL", "message": "No volatility, sequence-of-returns simulation or probability of success; readiness is a capped funding ratio." }, { "code": "SIMPLIFIED_TAX_AND_ACCESS", "message": "Withdrawal tax is an illustrative effective gross-up, not statutory taxation; no scheme-specific access or liquidity rules." }, { "code": "EXCLUDED_CASH_FLOWS", "message": "No pension income, individual accounts, family events, salary growth, spending changes or borrowing." }, { "code": "IMMEDIATE_RETIREMENT", "message": "When retiring now, monthlyTarget and requiredMonthlySIP are zero; gap is the immediate capital shortfall." } ] } } } }, "400": { "description": "Invalid JSON, inputs, query or Content-Length.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Only POST is accepted; Allow: POST.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 8192 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported Content-Type, charset or compression.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Best-effort per-worker rate limit. Honour Retry-After.", "headers": { "Retry-After": { "description": "Seconds until the fixed window resets.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected application error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "CalculationInput": { "type": "object", "additionalProperties": false, "required": [ "age", "retirementAge", "lifeExpectancy", "monthlyExpense", "currentSavings", "monthlySavings", "inflation", "preReturn", "postReturn", "withdrawalTaxPercent" ], "properties": { "age": { "type": "integer", "minimum": 18, "maximum": 100, "description": "Current age: years. Required; no service default.", "examples": [ 35 ] }, "retirementAge": { "type": "integer", "minimum": 18, "maximum": 110, "description": "Retirement age: years. Required; no service default.", "examples": [ 60 ] }, "lifeExpectancy": { "type": "integer", "minimum": 19, "maximum": 120, "description": "Plan until age: years, exclusive. Required; no service default.", "examples": [ 90 ] }, "monthlyExpense": { "type": "integer", "minimum": 1, "maximum": 10000000, "description": "Monthly household spending: INR today. Required; no service default.", "examples": [ 50000 ] }, "currentSavings": { "type": "integer", "minimum": 0, "maximum": 10000000000, "description": "Total retirement savings: INR today; count each balance once. Required; no service default.", "examples": [ 1000000 ] }, "monthlySavings": { "type": "integer", "minimum": 0, "maximum": 10000000, "description": "Total monthly saving: INR; constant, including account contributions. Required; no service default.", "examples": [ 20000 ] }, "inflation": { "type": "number", "minimum": 0, "maximum": 15, "description": "Annual spending inflation: %; assumption, not a forecast. Required; no service default.", "examples": [ 6 ] }, "preReturn": { "type": "number", "minimum": -20, "maximum": 30, "description": "Return before retirement: % nominal per year, net of fees and investment taxes. Required; no service default.", "examples": [ 10 ] }, "postReturn": { "type": "number", "minimum": -20, "maximum": 20, "description": "Return after retirement: % nominal per year, net of fees and investment taxes. Required; no service default.", "examples": [ 6 ] }, "withdrawalTaxPercent": { "type": "number", "minimum": 0, "maximum": 60, "description": "Effective withdrawal tax: % of gross withdrawals; illustrative, not a statutory rate. Required; no service default.", "examples": [ 5 ] } } }, "CalculationResult": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "currency", "target", "requiredCorpus", "projected", "gap", "monthlyTarget", "requiredMonthlySIP", "retirementExpense", "readiness", "years", "yearlyProjections", "assumptions", "limitations" ], "properties": { "contractVersion": { "type": "string", "const": "1" }, "currency": { "type": "string", "const": "INR" }, "target": { "type": "number" }, "requiredCorpus": { "type": "number" }, "projected": { "type": "number" }, "gap": { "type": "number" }, "monthlyTarget": { "type": "number" }, "requiredMonthlySIP": { "type": "number", "description": "Total monthly equivalent, rounded up to INR 0.01. Twelve payments are aggregated at year end, NOT compounded monthly. Zero for immediate retirement: check gap." }, "retirementExpense": { "type": "number", "description": "Annual nominal spending in the first retirement year, before withdrawal-tax gross-up." }, "readiness": { "type": "number" }, "years": { "type": "number" }, "yearlyProjections": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "age", "year", "phase", "openingBalance", "contribution", "expense", "requiredWithdrawal", "withdrawal", "withdrawalTax", "netSpending", "shortfall", "investmentReturn", "closingBalance" ], "properties": { "age": { "type": "integer" }, "year": { "type": "integer", "minimum": 0 }, "phase": { "type": "string", "enum": [ "accumulation", "retirement" ] }, "openingBalance": { "type": "number" }, "contribution": { "type": "number" }, "expense": { "type": "number" }, "requiredWithdrawal": { "type": "number" }, "withdrawal": { "type": "number" }, "withdrawalTax": { "type": "number" }, "netSpending": { "type": "number" }, "shortfall": { "type": "number" }, "investmentReturn": { "type": "number" }, "closingBalance": { "type": "number" } } }, "description": "Annual rows based on supplied currentSavings and monthlySavings; year is a zero-based offset, not calendar year." }, "assumptions": { "type": "object", "additionalProperties": false, "required": [ "monetaryBasis", "rateUnit", "inflationPercent", "preRetirementReturnPercent", "postRetirementReturnPercent", "effectiveWithdrawalTaxPercent", "returnsNetOfFeesAndInvestmentTaxes", "contributionTiming", "contributionGrowthPercent", "contributionAggregation", "retirementSpendingTiming", "horizonEndAgeExclusive", "projectionBasis", "requiredMonthlySIPMeaning", "requiredMonthlySIPRounding" ], "properties": { "monetaryBasis": { "type": "string" }, "rateUnit": { "type": "string" }, "inflationPercent": { "type": "number" }, "preRetirementReturnPercent": { "type": "number" }, "postRetirementReturnPercent": { "type": "number" }, "effectiveWithdrawalTaxPercent": { "type": "number" }, "returnsNetOfFeesAndInvestmentTaxes": { "type": "boolean" }, "contributionTiming": { "type": "string" }, "contributionGrowthPercent": { "type": "number" }, "contributionAggregation": { "type": "string" }, "retirementSpendingTiming": { "type": "string" }, "horizonEndAgeExclusive": { "type": "number" }, "projectionBasis": { "type": "string" }, "requiredMonthlySIPMeaning": { "type": "string" }, "requiredMonthlySIPRounding": { "type": "string" } } }, "limitations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "Error": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "error" ], "properties": { "contractVersion": { "type": "string", "const": "1" }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "documentation" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "documentation": { "type": "string", "const": "/api-docs" } } } } } } } }