{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://quantcalc.app/docs/state-tax-api/state-tax-api-schema.json", "title": "QuantCalc state income tax API", "description": "POST /api/state-tax: validate a request against #/$defs/request; a 200 body has the shape of #/$defs/response and a 400 body that of #/$defs/error. Generated from the request parser's field table. Keys are matched case-insensitively by the API; this schema lists the documented spellings. Checks that relate two fields (for example earlyDistributions at most iraDistributions plus employerPlanDistributions) are listed under x-errors with the exact 400 message. Reference: https://quantcalc.app/docs/state-tax-api/", "engineVersion": "1.16.9", "taxYear": 2026, "$defs": { "request": { "type": "object", "properties": { "state": { "type": "string", "pattern": "^(?:[aA][kK]|[fF][lL]|[nN][vV]|[nN][hH]|[sS][dD]|[tT][nN]|[tT][xX]|[wW][aA]|[wW][yY]|[aA][zZ]|[cC][oO]|[iI][dD]|[iI][lL]|[iI][nN]|[kK][yY]|[mM][aA]|[mM][iI]|[nN][cC]|[pP][aA]|[uU][tT]|[aA][lL]|[aA][rR]|[cC][aA]|[cC][tT]|[dD][eE]|[gG][aA]|[hH][iI]|[iI][aA]|[kK][sS]|[lL][aA]|[mM][eE]|[mM][dD]|[mM][nN]|[mM][sS]|[mM][oO]|[mM][tT]|[nN][eE]|[nN][jJ]|[nN][mM]|[nN][yY]|[nN][dD]|[oO][hH]|[oO][kK]|[oO][rR]|[rR][iI]|[sS][cC]|[vV][tT]|[vV][aA]|[wW][vV]|[wW][iI]|[dD][cC]|[nN][oO][nN][eE])$", "description": "Two-letter code, or DC (case-insensitive).", "x-whenAbsent": "(none: 400)", "x-relation": "Required; not an amount.", "x-limits": "One of the 50 state codes or DC, any case (the sentinel NONE, no state tax, is also accepted). Absent, empty or not a string: 400 \"state is required\"; any other value: 400 \"state is not one we carry\"." }, "state_code": { "type": "string", "pattern": "^(?:[aA][kK]|[fF][lL]|[nN][vV]|[nN][hH]|[sS][dD]|[tT][nN]|[tT][xX]|[wW][aA]|[wW][yY]|[aA][zZ]|[cC][oO]|[iI][dD]|[iI][lL]|[iI][nN]|[kK][yY]|[mM][aA]|[mM][iI]|[nN][cC]|[pP][aA]|[uU][tT]|[aA][lL]|[aA][rR]|[cC][aA]|[cC][tT]|[dD][eE]|[gG][aA]|[hH][iI]|[iI][aA]|[kK][sS]|[lL][aA]|[mM][eE]|[mM][dD]|[mM][nN]|[mM][sS]|[mM][oO]|[mM][tT]|[nN][eE]|[nN][jJ]|[nN][mM]|[nN][yY]|[nN][dD]|[oO][hH]|[oO][kK]|[oO][rR]|[rR][iI]|[sS][cC]|[vV][tT]|[vV][aA]|[wW][vV]|[wW][iI]|[dD][cC]|[nN][oO][nN][eE])$", "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(none: 400)", "x-relation": "Required; not an amount.", "x-limits": "One of the 50 state codes or DC, any case (the sentinel NONE, no state tax, is also accepted). Absent, empty or not a string: 400 \"state is required\"; any other value: 400 \"state is not one we carry\"." }, "filingStatus": { "type": [ "string", "null" ], "pattern": "^(?:[sS][iI][nN][gG][lL][eE]|[mM][fF][jJ]|[mM][aA][rR][rR][iI][eE][dD]_[fF][iI][lL][iI][nN][gG]_[jJ][oO][iI][nN][tT][lL][yY]|[mM][fF][sS]|[mM][aA][rR][rR][iI][eE][dD]_[fF][iI][lL][iI][nN][gG]_[sS][eE][pP][aA][rR][aA][tT][eE][lL][yY]|[hH][oO][hH]|[hH][eE][aA][dD]_[oO][fF]_[hH][oO][uU][sS][eE][hH][oO][lL][dD]|[qQ][sS][sS]|[qQ][uU][aA][lL][iI][fF][yY][iI][nN][gG]_[sS][uU][rR][vV][iI][vV][iI][nN][gG]_[sS][pP][oO][uU][sS][eE])$", "examples": [ "single", "mfj", "married_filing_jointly", "mfs", "married_filing_separately", "hoh", "head_of_household", "qss", "qualifying_surviving_spouse" ], "description": "single, mfj or married_filing_jointly, mfs or married_filing_separately, hoh or head_of_household, qss or qualifying_surviving_spouse (case-insensitive). A qualifying surviving spouse is one person on the return (no spouse object) and gets the state's own treatment of the status: the joint schedule, deduction or limits, the head-of-household return, or the single return, as each state page says. Anything else, including a non-string, is refused with 400.", "x-whenAbsent": "single", "x-relation": "Not an amount.", "x-limits": "One of the nine strings, any case; null = absent. Anything else: 400 naming the field." }, "filing_status": { "type": [ "string", "null" ], "pattern": "^(?:[sS][iI][nN][gG][lL][eE]|[mM][fF][jJ]|[mM][aA][rR][rR][iI][eE][dD]_[fF][iI][lL][iI][nN][gG]_[jJ][oO][iI][nN][tT][lL][yY]|[mM][fF][sS]|[mM][aA][rR][rR][iI][eE][dD]_[fF][iI][lL][iI][nN][gG]_[sS][eE][pP][aA][rR][aA][tT][eE][lL][yY]|[hH][oO][hH]|[hH][eE][aA][dD]_[oO][fF]_[hH][oO][uU][sS][eE][hH][oO][lL][dD]|[qQ][sS][sS]|[qQ][uU][aA][lL][iI][fF][yY][iI][nN][gG]_[sS][uU][rR][vV][iI][vV][iI][nN][gG]_[sS][pP][oO][uU][sS][eE])$", "examples": [ "single", "mfj", "married_filing_jointly", "mfs", "married_filing_separately", "hoh", "head_of_household", "qss", "qualifying_surviving_spouse" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "single", "x-relation": "Not an amount.", "x-limits": "One of the nine strings, any case; null = absent. Anything else: 400 naming the field." }, "age": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 120, "description": "The primary filer's age, a whole number from 0 to 120. A non-number or a fraction is refused with 400 (engine 1.5.0).", "x-whenAbsent": "0", "x-relation": "The primary filer's age (the household's without spouse). Every age test reads it.", "x-limits": "Whole number 0 to 120; null = absent (0). A fraction or non-number: 400." }, "ordinaryIncome": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Ordinary income not in another field: interest, non-qualified dividends and so on. Not negative. A non-number is refused with 400 (engine 1.5.0).", "x-whenAbsent": "0", "x-relation": "Component: a separate amount, added to income once. Does not contain wages, qualifiedDividends, shortTermGains or any retirement field.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "ordinary_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component: a separate amount, added to income once. Does not contain wages, qualifiedDividends, shortTermGains or any retirement field.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "socialSecurity": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The federally taxable part of Social Security benefits, not gross benefits. Not negative. A non-number is refused with 400 (engine 1.5.0).", "x-whenAbsent": "0", "x-relation": "Component (the taxable part); a household total. It is part of socialSecurityGross.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "social_security": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component (the taxable part); a household total. It is part of socialSecurityGross.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "capitalGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Net long-term capital gain. Not negative. A non-number is refused with 400 (engine 1.5.0).", "x-whenAbsent": "0", "x-relation": "Component; a household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "capital_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component; a household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "wages": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Earned income: W-2 wages and, without computeFederal, net self-employment income as it reaches federal AGI (the net profit less the deduction for half the self-employment tax). With computeFederal it is the person's W-2 wages only (one employer: boxes 1, 3 and 5 alike) and a business's net profit goes in selfEmploymentIncome.", "x-whenAbsent": "not supplied", "x-relation": "Component. With spouse: the primary filer's own amount (spouse.wages is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "iraDistributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Traditional IRA distributions, excluding conversions. 401(k), 403(b) and 457(b) distributions go in employerPlanDistributions.", "x-whenAbsent": "not supplied", "x-relation": "Component, disjoint from employerPlanDistributions and rothConversion. With spouse: the primary filer's own amount (spouse.iraDistributions is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "ira_distributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied", "x-relation": "Component, disjoint from employerPlanDistributions and rothConversion. With spouse: the primary filer's own amount (spouse.iraDistributions is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pensionPrivate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Private-employer pension or annuity.", "x-whenAbsent": "not supplied", "x-relation": "Component, disjoint from disabilityIncome. With spouse: the primary filer's own amount (spouse.pensionPrivate is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pension_private": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied", "x-relation": "Component, disjoint from disabilityIncome. With spouse: the primary filer's own amount (spouse.pensionPrivate is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pensionPublic": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Government or public-employer pension.", "x-whenAbsent": "not supplied", "x-relation": "Component, disjoint from pensionFederalCivilService and pensionMilitary. With spouse: the primary filer's own amount (spouse.pensionPublic is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pension_public": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied", "x-relation": "Component, disjoint from pensionFederalCivilService and pensionMilitary. With spouse: the primary filer's own amount (spouse.pensionPublic is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pensionMilitary": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Military retirement pay.", "x-whenAbsent": "not supplied", "x-relation": "Component. With spouse: the primary filer's own amount (spouse.pensionMilitary is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pension_military": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied", "x-relation": "Component. With spouse: the primary filer's own amount (spouse.pensionMilitary is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "rothConversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Traditional-to-Roth conversion amount.", "x-whenAbsent": "not supplied", "x-relation": "Component, not part of iraDistributions. With spouse: the primary filer's own amount (spouse.rothConversion is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "roth_conversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied", "x-relation": "Component, not part of iraDistributions. With spouse: the primary filer's own amount (spouse.rothConversion is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pensionFederalCivilService": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "A federal civil service annuity (CSRS or FERS), counted as a public pension and read by the states' civil service rules. Do not also include it in pensionPublic.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from pensionPublic. With spouse: the primary filer's own amount (spouse.pensionFederalCivilService is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pension_federal_civil_service": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from pensionPublic. With spouse: the primary filer's own amount (spouse.pensionFederalCivilService is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "disabilityIncome": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Taxable disability pay of a person retired on disability (reported federally as wages before the minimum retirement age, or as a pension), counted as pension income and read by the states' disability-pay exclusions. Do not also include it in pensionPrivate.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from pensionPrivate. With spouse: the primary filer's own amount (spouse.disabilityIncome is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "disability_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from pensionPrivate. With spouse: the primary filer's own amount (spouse.disabilityIncome is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "earlyDistributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The part of iraDistributions and employerPlanDistributions taken before age 59½.", "x-whenAbsent": "every IRA and employer-plan dollar of a person under 59", "x-relation": "Part of the same person's iraDistributions plus employerPlanDistributions; not added to income again.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. At most iraDistributions plus employerPlanDistributions (same person), else 400." }, "early_distributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "every IRA and employer-plan dollar of a person under 59", "x-relation": "Part of the same person's iraDistributions plus employerPlanDistributions; not added to income again.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. At most iraDistributions plus employerPlanDistributions (same person), else 400." }, "iraBasis": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "After-tax IRA contributions not yet recovered (a state that taxes an early distribution only above them reads it).", "x-whenAbsent": "0", "x-relation": "Not income: the after-tax basis read with earlyDistributions; adds nothing to income.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "ira_basis": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Not income: the after-tax basis read with earlyDistributions; adds nothing to income.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "railroadRetirementTier2": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Railroad Retirement Tier 2 and supplemental annuities (the taxable amount on RRB-1099-R). Never taxed by a state; counted in the income tests and, where the state says so, against a retirement cap.", "x-whenAbsent": "not supplied (none)", "x-relation": "Component. With spouse: the primary filer's own amount (spouse.railroadRetirementTier2 is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "railroad_retirement_tier2": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (none)", "x-relation": "Component. With spouse: the primary filer's own amount (spouse.railroadRetirementTier2 is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "railroadRetirementTier1": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The Railroad Retirement Tier 1 part of socialSecurityGross (needs it, at most it). Its share of the taxable benefits is kept out of every state's Social Security rules.", "x-whenAbsent": "not supplied (none)", "x-relation": "Part of socialSecurityGross; a household total even with spouse (spouse.railroadRetirementTier1 is the spouse's part of it). Not added to income again.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Needs socialSecurityGross and at most it, else 400." }, "railroad_retirement_tier1": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (none)", "x-relation": "Part of socialSecurityGross; a household total even with spouse (spouse.railroadRetirementTier1 is the spouse's part of it). Not added to income again.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Needs socialSecurityGross and at most it, else 400." }, "employerPlanDistributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "401(k), 403(b) and 457(b) distributions, excluding conversions. Taxed like IRA distributions except where the state's pension rule covers employer plans (Maryland, Rhode Island).", "x-whenAbsent": "not supplied", "x-relation": "Component, disjoint from iraDistributions. With spouse: the primary filer's own amount (spouse.employerPlanDistributions is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "employer_plan_distributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied", "x-relation": "Component, disjoint from iraDistributions. With spouse: the primary filer's own amount (spouse.employerPlanDistributions is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "selfEmploymentIncome": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Net profit from self-employment (Schedule C line 31, or a partner's Schedule K-1 box 14 code A), at least 0. Needs computeFederal: true. The federal engine prices it on the person's Schedule SE and Schedule 1, and the state engine receives it as earned income less half the person's self-employment tax (the business income as it reaches federal AGI), together with the person's wages. Without computeFederal an amount other than 0 is refused with 400: send the state earned income as wages instead.", "x-whenAbsent": "not supplied (none)", "x-relation": "Component, disjoint from wages. With spouse: the primary filer's own amount (spouse.selfEmploymentIncome is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Not 0 without computeFederal: true, else 400." }, "self_employment_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (none)", "x-relation": "Component, disjoint from wages. With spouse: the primary filer's own amount (spouse.selfEmploymentIncome is the spouse's); without: the household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Not 0 without computeFederal: true, else 400." }, "qualifiedTips": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Qualified tips received as an employee (26 U.S.C. 224(c): tips in an occupation that customarily received tips, reported on the W-2), a part of wages. A state that allows the federal tips deduction subtracts the federal amount (NY, IN for 2026, HI, DC); Georgia excludes a person's cash tips up to its per-person amount. Tips received in the person's own business are not taken.", "x-whenAbsent": "not supplied (none)", "x-relation": "A part of wages (with qualifiedOvertime, at most wages). With spouse: the primary filer's own amount (spouse.qualifiedTips is the spouse's); without: the household total, read as the filer's for a per-person limit.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. With qualifiedOvertime more than wages: 400. Refused with residency." }, "qualified_tips": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (none)", "x-relation": "A part of wages (with qualifiedOvertime, at most wages). With spouse: the primary filer's own amount (spouse.qualifiedTips is the spouse's); without: the household total, read as the filer's for a per-person limit.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. With qualifiedOvertime more than wages: 400. Refused with residency." }, "qualifiedOvertime": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Qualified overtime compensation (26 U.S.C. 225(c)): the overtime premium above the regular rate that section 7 of the Fair Labor Standards Act requires (W-2 box 12 code TT), a part of wages. A state that allows the federal overtime deduction subtracts the federal amount (IN for 2026, DC); Georgia (a full-time hourly employee's) and Alabama deduct it up to their per-person amounts, 2026-2028.", "x-whenAbsent": "not supplied (none)", "x-relation": "A part of wages. With spouse: the primary filer's own amount; without: the household total, read as the filer's for a per-person limit.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. With qualifiedTips more than wages: 400. Refused with residency." }, "qualified_overtime": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (none)", "x-relation": "A part of wages. With spouse: the primary filer's own amount; without: the household total, read as the filer's for a per-person limit.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. With qualifiedTips more than wages: 400. Refused with residency." }, "shortTermGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Net short-term capital gain.", "x-whenAbsent": "not supplied", "x-relation": "Component; a household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "short_term_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied", "x-relation": "Component; a household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "socialSecurityGross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Gross benefits (Social Security and Railroad Retirement Tier 1 received), for the rules that run on gross benefits. At least socialSecurity.", "x-whenAbsent": "not supplied (the engine estimates where a rule needs it)", "x-relation": "Contains socialSecurity (and railroadRetirementTier1); a household total. Not added to income: the rules that run on gross benefits read it.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. When given and above 0, at least socialSecurity, else 400." }, "social_security_gross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (the engine estimates where a rule needs it)", "x-relation": "Contains socialSecurity (and railroadRetirementTier1); a household total. Not added to income: the rules that run on gross benefits read it.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. When given and above 0, at least socialSecurity, else 400." }, "federalTax": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The year's federal income tax after the nonrefundable credits (Form 1040 line 22), without the net investment income tax (that goes in federalNiit) or the other Schedule 2 taxes. Read by five states: Alabama deducts it with federalNiit, less federalRefundableCredits (its worksheet subtracts the refundable credits); Missouri deducts a percentage of it and Oregon deducts it up to its cap; Nebraska caps its tax at the federal tax before credits and Oklahoma's child credit is limited by it, so those two read federalTaxBeforeCredits when it is given (without it Nebraska takes no cap, and Oklahoma reads a positive federalTax as the whole nonrefundable credit allowed and 0 as none of it). Every other state ignores it.", "x-whenAbsent": "not supplied (no federal-tax deduction)", "x-relation": "Not income: a federal figure some states deduct or compare with; a household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. With federalTaxBeforeCredits, at most that figure (else 400)." }, "federal_tax": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (no federal-tax deduction)", "x-relation": "Not income: a federal figure some states deduct or compare with; a household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. With federalTaxBeforeCredits, at most that figure (else 400)." }, "federalNiit": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The year's federal net investment income tax.", "x-whenAbsent": "not supplied", "x-relation": "Not income: read with federalTax.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "federal_niit": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied", "x-relation": "Not income: read with federalTax.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "federalTaxBeforeCredits": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The year's federal tax before credits (Form 1040 line 16 plus Schedule 2 lines 2 and 8), which Nebraska caps its tax at and which limits the nonrefundable part of the federal child tax credit Oklahoma takes a share of. At least federalTax.", "x-whenAbsent": "not supplied (NE: no federal-tax cap when only federalTax is given; OK: the nonrefundable child credit limit is read from federalTax)", "x-relation": "Not income: a federal figure, at least federalTax (the tax after the nonrefundable credits); a household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field; 400 when federalTax is larger." }, "federal_tax_before_credits": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (NE: no federal-tax cap when only federalTax is given; OK: the nonrefundable child credit limit is read from federalTax)", "x-relation": "Not income: a federal figure, at least federalTax (the tax after the nonrefundable credits); a household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field; 400 when federalTax is larger." }, "federalRefundableCredits": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The year's federal refundable credits (Form 1040 lines 27a, 28, 29 and 30, and Schedule 3 line 13a), which Alabama's federal income tax deduction subtracts.", "x-whenAbsent": "not supplied (none)", "x-relation": "Not income: a federal figure read with federalTax; a household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "federal_refundable_credits": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (none)", "x-relation": "Not income: a federal figure read with federalTax; a household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "qualifiedDividends": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Qualified dividends, in addition to ordinaryIncome (do not count them twice). Ordinary income except where the state treats them apart (North Dakota's exclusion; Georgia's and Delaware's retirement pools).", "x-whenAbsent": "not supplied (none)", "x-relation": "Component, disjoint from ordinaryIncome: add it, do not include it there too.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "qualified_dividends": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (none)", "x-relation": "Component, disjoint from ordinaryIncome: add it, do not include it there too.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "capitalLoss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The year's net capital loss as a positive amount: capital losses in excess of capital gains (federal Schedule D line 16), including any carryover brought into the year. What the state deducts is its own rule: the federal {{CA:config.cap_loss_limit|money}} ({{CA:config.cap_loss_limit_mfs|money}} married filing separately) where it follows the federal return, Massachusetts {{MA:config.cap_loss_limit|money}} against interest and dividends only, Alabama the whole in-year loss, Pennsylvania and New Jersey nothing.", "x-whenAbsent": "not supplied (none)", "x-relation": "A net loss excludes a net gain: capitalGains and shortTermGains must be 0 with it; a household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field; 400 with capitalGains or shortTermGains above 0." }, "capital_loss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (none)", "x-relation": "A net loss excludes a net gain: capitalGains and shortTermGains must be 0 with it; a household total.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field; 400 with capitalGains or shortTermGains above 0." }, "capitalLossCarryover": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The part of capitalLoss carried into the year from earlier years (Schedule D lines 6 and 14). Only Alabama reads it (no carryover there: it deducts the rest). Where a state keeps its own carryover (Massachusetts, Wisconsin) give that state's figure in both fields.", "x-whenAbsent": "not supplied (none)", "x-relation": "A part of capitalLoss.", "x-limits": "Finite, from 0 to $100 billion, at most capitalLoss; null = absent. Otherwise 400 naming the field." }, "capital_loss_carryover": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (none)", "x-relation": "A part of capitalLoss.", "x-limits": "Finite, from 0 to $100 billion, at most capitalLoss; null = absent. Otherwise 400 naming the field." }, "rentalNetIncome": { "type": [ "number", "null" ], "minimum": -100000000000, "maximum": 100000000000, "description": "Rental real estate, signed: the federal Schedule E line 26 amount (Schedule 1 line 5), net rental income or the loss the federal return allows after the passive-activity limit (Form 8582). A profit is other ordinary income (and joins Georgia's and Delaware's retirement-income exclusions, which name net rental income); a loss reduces the state's income where the state starts from federal AGI or follows the federal schedule, and offsets no other income in Pennsylvania and New Jersey.", "x-whenAbsent": "not supplied (none)", "x-relation": "A household total; not part of ordinaryIncome. With computeFederal the federal return takes it as Schedule E line 26 as given.", "x-limits": "Finite, from -$100 billion to $100 billion; null = absent. Refused with residency and for a part-year resident of a locality." }, "rental_net_income": { "type": [ "number", "null" ], "minimum": -100000000000, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (none)", "x-relation": "A household total; not part of ordinaryIncome. With computeFederal the federal return takes it as Schedule E line 26 as given.", "x-limits": "Finite, from -$100 billion to $100 billion; null = absent. Refused with residency and for a part-year resident of a locality." }, "qualifiedCarLoanInterest": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Qualified passenger vehicle loan interest paid in the year (26 U.S.C. 163(h)(4)(B): a loan taken after 2024 for a new vehicle assembled in the United States). A state that allows the federal deduction subtracts the federal amount (IN for 2026, DC).", "x-whenAbsent": "not supplied (none)", "x-relation": "A household amount, not income.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Refused with residency and with computeFederal (the federal engine has no Schedule 1-A Part IV)." }, "qualified_car_loan_interest": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (none)", "x-relation": "A household amount, not income.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Refused with residency and with computeFederal (the federal engine has no Schedule 1-A Part IV)." }, "charityCash": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Cash gifts in the year to public charities (26 U.S.C. 170(b)(1)(A)) other than a supporting organization or a donor-advised fund: the amount the federal non-itemizer deduction (170(p)) counts. A state that allows that deduction takes the federal amount (HI). With computeFederal the federal return takes it too.", "x-whenAbsent": "not supplied (none)", "x-relation": "A household amount, not income.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Refused with residency." }, "charity_cash": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not supplied (none)", "x-relation": "A household amount, not income.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Refused with residency." }, "localTaxRate": { "type": [ "number", "null" ], "minimum": 0.005, "maximum": 0.033, "description": "Indiana and Maryland only: the filer's county income tax rate as a fraction, within the state's lowest and highest official county rate. Elsewhere, or out of range, refused with 400.", "x-whenAbsent": "the population-weighted average of the county rates", "x-relation": "Not an amount: a rate (fraction) replacing the average county rate.", "x-limits": "Indiana and Maryland only, within that state's lowest and highest official county rate (config.local_tax_rate_min and local_tax_rate_max on GET /api/state-tax/rules; the schema's range covers both states). Any other state, or out of range: 400. null = absent." }, "local_tax_rate": { "type": [ "number", "null" ], "minimum": 0.005, "maximum": 0.033, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "the population-weighted average of the county rates", "x-relation": "Not an amount: a rate (fraction) replacing the average county rate.", "x-limits": "Indiana and Maryland only, within that state's lowest and highest official county rate (config.local_tax_rate_min and local_tax_rate_max on GET /api/state-tax/rules; the schema's range covers both states). Any other state, or out of range: 400. null = absent." }, "otherLocalTaxCredit": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "A resident's credit for local income tax paid to another locality, as the residence's ordinance allows it (each municipality sets its own; the engine never computes it, except between two Pennsylvania Act 32 jurisdictions, whose statutory credit it applies itself). Applied against the separate resident local returns, in the order given, at most each one's tax.", "x-whenAbsent": "0", "x-relation": "An amount the caller computed from the ordinance.", "x-limits": "Non-negative; needs a residence in localities that files a separate local return, else 400." }, "other_local_tax_credit": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "An amount the caller computed from the ordinance.", "x-limits": "Non-negative; needs a residence in localities that files a separate local return, else 400." }, "localUnearnedIncome": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Philadelphia residents: the income its School Income Tax reaches (dividends, interest other than bank-deposit and government-bond interest, gains on assets held six months or less, annuities not from an employer plan, rents not under the Net Profits Tax); pensions and Social Security are not in it. Never derived from the other amounts.", "x-whenAbsent": "0", "x-relation": "Overlaps ordinaryIncome, shortTermGains and qualifiedDividends; it is a separate base, not added income.", "x-limits": "Non-negative; needs localities [\"PA-PSD-510101\"], else 400." }, "local_unearned_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Overlaps ordinaryIncome, shortTermGains and qualifiedDividends; it is a separate base, not added income.", "x-limits": "Non-negative; needs localities [\"PA-PSD-510101\"], else 400." }, "localities": { "type": [ "array", "null" ], "maxItems": 6, "items": { "oneOf": [ { "type": "string", "pattern": "^[A-Za-z]{2}-[A-Za-z0-9-]+$" }, { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z]{2}-[A-Za-z0-9-]+$", "description": "The jurisdiction's code (MD-0300, IN-49, IA-01-0018, OH-SD-0203, OH-MU-00142, PA-PSD-010101, MI-DETROIT, NY-NYC, KY-LOUISVILLE, MO-KANSAS-CITY, OR-METRO, DE-WILMINGTON, ...), any case.", "x-whenAbsent": "required", "x-relation": "Which jurisdiction.", "x-limits": "Required in an object; must be one of the listed codes of the request's state." }, "role": { "type": [ "string", "null" ], "pattern": "^(?:[rR][eE][sS][iI][dD][eE][nN][tT]|[wW][oO][rR][kK])$", "examples": [ "resident", "work" ], "description": "\"resident\" (the household lives there) or \"work\" (a nonresident's workplace: its nonresident rate on the wages given).", "x-whenAbsent": "resident", "x-relation": "Residence or workplace.", "x-limits": "resident or work; anything else: 400." }, "wages": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "A workplace's wages: what the household earned there.", "x-whenAbsent": "0", "x-relation": "A subset of the household's wages.", "x-limits": "A workplace only; non-negative; all workplaces together at most the household's wages." }, "residentFrom": { "type": [ "string", "null" ], "pattern": "^2026-[0-9]{2}-[0-9]{2}$", "description": "Engine 1.13.0: the first day lived in this resident locality, YYYY-MM-DD in 2026: a part-year resident of it (NYC and Yonkers IT-360.1, a PA EIT subdivision's Local Worksheet, an Ohio earned-income-base school district). Not for a county or Iowa school district (they follow one day of residence) or a workplace.", "x-whenAbsent": "the whole year (or a part-year return's resident period)", "x-relation": "The period lived there.", "x-limits": "With residentTo; inside a part-year return's resident period; the localities without a settled part-year rule refuse it: 400." }, "resident_from": { "type": [ "string", "null" ], "pattern": "^2026-[0-9]{2}-[0-9]{2}$", "description": "The same field under its snake_case spelling.", "x-whenAbsent": "the whole year (or a part-year return's resident period)", "x-relation": "The period lived there.", "x-limits": "With residentTo; inside a part-year return's resident period; the localities without a settled part-year rule refuse it: 400." }, "residentTo": { "type": [ "string", "null" ], "pattern": "^2026-[0-9]{2}-[0-9]{2}$", "description": "Engine 1.13.0: the last day lived in this resident locality, YYYY-MM-DD in 2026.", "x-whenAbsent": "the whole year (or a part-year return's resident period)", "x-relation": "The period lived there.", "x-limits": "With residentFrom: 400 otherwise." }, "resident_to": { "type": [ "string", "null" ], "pattern": "^2026-[0-9]{2}-[0-9]{2}$", "description": "The same field under its snake_case spelling.", "x-whenAbsent": "the whole year (or a part-year return's resident period)", "x-relation": "The period lived there.", "x-limits": "With residentFrom: 400 otherwise." }, "residentIncome": { "type": [ "object", "null" ], "properties": { "wages": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The wages received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's wages.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "ordinaryIncome": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The ordinaryIncome received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's ordinaryIncome.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "ordinary_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's ordinaryIncome.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "shortTermGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The shortTermGains received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's shortTermGains.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "short_term_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's shortTermGains.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "capitalGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The capitalGains received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's capitalGains.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "capital_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's capitalGains.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "capitalLoss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The capitalLoss received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's capitalLoss.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "capital_loss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's capitalLoss.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "iraDistributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The iraDistributions received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's iraDistributions.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "ira_distributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's iraDistributions.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "pensionPrivate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The pensionPrivate received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's pensionPrivate.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "pension_private": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's pensionPrivate.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "pensionPublic": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The pensionPublic received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's pensionPublic.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "pension_public": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's pensionPublic.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "rothConversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The rothConversion received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's rothConversion.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "roth_conversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's rothConversion.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "socialSecurity": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The socialSecurity received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's socialSecurity.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "social_security": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's socialSecurity.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "socialSecurityGross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The socialSecurityGross received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's socialSecurityGross.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "social_security_gross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's socialSecurityGross.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." } }, "additionalProperties": false, "description": "Engine 1.13.0: the income received while living there, under the keys of residency.stateIncome (IT-360.1 Columns B and C; SD 100 lines 29-32).", "x-whenAbsent": "none (needed for a part-year resident of NYC, Yonkers, Philadelphia, an Ohio municipality or earned-income-base district, Lexington, Metro or Multnomah)", "x-relation": "Each a part of the year's amount.", "x-limits": "A part-year resident of those localities only (a PA EIT subdivision, an Ohio traditional-base district and Kansas City / St. Louis take the period instead); each amount at most the year's: 400." }, "resident_income": { "type": [ "object", "null" ], "properties": { "wages": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The wages received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's wages.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "ordinaryIncome": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The ordinaryIncome received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's ordinaryIncome.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "ordinary_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's ordinaryIncome.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "shortTermGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The shortTermGains received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's shortTermGains.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "short_term_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's shortTermGains.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "capitalGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The capitalGains received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's capitalGains.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "capital_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's capitalGains.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "capitalLoss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The capitalLoss received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's capitalLoss.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "capital_loss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's capitalLoss.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "iraDistributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The iraDistributions received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's iraDistributions.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "ira_distributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's iraDistributions.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "pensionPrivate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The pensionPrivate received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's pensionPrivate.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "pension_private": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's pensionPrivate.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "pensionPublic": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The pensionPublic received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's pensionPublic.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "pension_public": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's pensionPublic.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "rothConversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The rothConversion received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's rothConversion.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "roth_conversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's rothConversion.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "socialSecurity": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The socialSecurity received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's socialSecurity.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "social_security": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's socialSecurity.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "socialSecurityGross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The socialSecurityGross received while living in the locality.", "x-whenAbsent": "0", "x-relation": "A part of the year's socialSecurityGross.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." }, "social_security_gross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the year's socialSecurityGross.", "x-limits": "A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent." } }, "additionalProperties": false, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "none (needed for a part-year resident of NYC, Yonkers, Philadelphia, an Ohio municipality or earned-income-base district, Lexington, Metro or Multnomah)", "x-relation": "Each a part of the year's amount.", "x-limits": "A part-year resident of those localities only (a PA EIT subdivision, an Ohio traditional-base district and Kansas City / St. Louis take the period instead); each amount at most the year's: 400." }, "daysOutside": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 365, "description": "Engine 1.14.0: the days the city's non-residency deduction formula deducts for a part-year resident: Kansas City (Form RD-109NR line 2) the days worked outside the city while not living in it (\"You may not deduct days lived in the City\"); St. Louis (Form E-1) the days lived or worked outside the City. The deduction is the year's wages x daysOutside / the work days, at the city's rate.", "x-whenAbsent": "none (needed for a part-year resident of Kansas City or St. Louis)", "x-relation": "At most the work days.", "x-limits": "A whole number 0 to 365, only on a part-year Kansas City or St. Louis residence (with residentFrom / residentTo), at most the work days: 400." }, "days_outside": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 365, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "none (needed for a part-year resident of Kansas City or St. Louis)", "x-relation": "At most the work days.", "x-limits": "A whole number 0 to 365, only on a part-year Kansas City or St. Louis residence (with residentFrom / residentTo), at most the work days: 400." }, "workDays": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 365, "description": "Engine 1.14.0: St. Louis Form E-1 line 1, total work days (\"standard work year is 260 days\"); Kansas City's RD-109NR line 1 is always 260 (\"Enter 260 for days worked everywhere\"), so it is refused there.", "x-whenAbsent": "260 (both cities' standard work year)", "x-relation": "The formula's denominator.", "x-limits": "A whole number 1 to 365, only on a part-year St. Louis residence: 400." }, "work_days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 365, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "260 (both cities' standard work year)", "x-relation": "The formula's denominator.", "x-limits": "A whole number 1 to 365, only on a part-year St. Louis residence: 400." } }, "required": [ "code" ], "additionalProperties": false } ] }, "description": "The local income-tax jurisdictions of the household, by official code (GET /api/state-tax/localities?state=XX lists them; never guessed from a zip code): the residence's county, city, school district or municipality, and (role \"work\") a workplace with the wages earned there. Each is taxed on its own base: NYC, Yonkers and Iowa school districts on the state return (in tax), the others on separate local returns (in totalTax). Engine 1.13.0: with residency, a county or Iowa school district on a part-year return, a nonresident's workplaces, and (residentFrom / residentTo / residentIncome) a part-year resident of NYC, Yonkers, a PA EIT subdivision or an Ohio earned-income-base district; the localities whose part-year rules are not settled are refused with the reason.", "x-whenAbsent": "none (Indiana and Maryland: the average county rate)", "x-relation": "Facts about where the household lives and works.", "x-limits": "At most 6 entries, each a code string or {code, role, wages}; a code of another state, an unknown or unmodelled one, two residences of one kind, a workplace for a tax on residents only, wages on a residence, or workplace wages above the household's wages: 400. null = absent." }, "propertyTaxPaid": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The year's property tax on the principal residence (a married filer on a separate return: their share). The states' property-tax credits and NJ's deduction read it.", "x-whenAbsent": "0", "x-relation": "A fact for the credits, not income.", "x-limits": "Non-negative; null = absent." }, "property_tax_paid": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A fact for the credits, not income.", "x-limits": "Non-negative; null = absent." }, "rentPaid": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The year's rent for the principal residence. The renter's credits and the rent share of the property-tax credits read it.", "x-whenAbsent": "0", "x-relation": "A fact for the credits, not income.", "x-limits": "Non-negative; null = absent." }, "rent_paid": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A fact for the credits, not income.", "x-limits": "Non-negative; null = absent." }, "rentIncludesHeat": { "type": [ "boolean", "null" ], "description": "The rent includes heat or utilities (NY's real property tax credit then counts a reduced share of it).", "x-whenAbsent": "false", "x-relation": "A fact about rentPaid.", "x-limits": "true or false; needs rentPaid, else 400." }, "rent_includes_heat": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "false", "x-relation": "A fact about rentPaid.", "x-limits": "true or false; needs rentPaid, else 400." }, "homeValue": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The home's value: the assessed value (MA Senior Circuit Breaker limit) or full value (NY real property tax credit limit).", "x-whenAbsent": "not said (no value limit applied)", "x-relation": "A fact for the credits.", "x-limits": "Non-negative; null = absent." }, "home_value": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not said (no value limit applied)", "x-relation": "A fact for the credits.", "x-limits": "Non-negative; null = absent." }, "taxExemptInterest": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Federally tax-exempt interest (Form 1040 line 2a): counted in the household-income measures of the property-tax and senior credits, and with computeFederal in the federal return's provisional income (Social Security) and its other line 2a measures. The parts the states treat apart are inStateMunicipalInterest and outOfStateMunicipalInterest; what is left of it (for example interest on U.S. territory bonds) is added by no state. When it is absent and a part is given, it is the sum of the parts.", "x-whenAbsent": "0", "x-relation": "Not in ordinaryIncome. Taxed by a state only through its parts inStateMunicipalInterest and outOfStateMunicipalInterest.", "x-limits": "Non-negative; null = absent." }, "tax_exempt_interest": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Not in ordinaryIncome. Taxed by a state only through its parts inStateMunicipalInterest and outOfStateMunicipalInterest.", "x-limits": "Non-negative; null = absent." }, "medicalExpenses": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The household's unreimbursed medical care expenses for the year (filer, spouse and dependents), insurance premiums included as IRC 213 counts them: New Jersey's medical expense deduction and New Mexico's medical care exemption and credit for a filer or spouse 65 or older.", "x-whenAbsent": "0", "x-relation": "A fact for those rules.", "x-limits": "Non-negative; null = absent." }, "medical_expenses": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A fact for those rules.", "x-limits": "Non-negative; null = absent." }, "inStateMunicipalInterest": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The part of taxExemptInterest that is interest on obligations of the return's own state and its political subdivisions (its state and municipal bonds, and the in-state share of a municipal bond fund's exempt-interest dividends). Most states exempt it; the states that tax their own obligations add it (each state page's interest rules).", "x-whenAbsent": "0", "x-relation": "A part of taxExemptInterest (with the other part, at most it).", "x-limits": "Non-negative; null = absent; together with the other part at most taxExemptInterest when that is given (400). Refused with residency." }, "in_state_municipal_interest": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of taxExemptInterest (with the other part, at most it).", "x-limits": "Non-negative; null = absent; together with the other part at most taxExemptInterest when that is given (400). Refused with residency." }, "outOfStateMunicipalInterest": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The part of taxExemptInterest that is interest on obligations of OTHER states and their political subdivisions (including the out-of-state share of a municipal bond fund's exempt-interest dividends). Most states tax it: their addition line adds it to the state's income. Interest on U.S. territory bonds (Puerto Rico, Guam, the Virgin Islands and others) is in neither part.", "x-whenAbsent": "0", "x-relation": "A part of taxExemptInterest (with the other part, at most it).", "x-limits": "Non-negative; null = absent; together with the other part at most taxExemptInterest when that is given (400). Refused with residency." }, "out_of_state_municipal_interest": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of taxExemptInterest (with the other part, at most it).", "x-limits": "Non-negative; null = absent; together with the other part at most taxExemptInterest when that is given (400). Refused with residency." }, "usObligationInterest": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The part of ordinaryIncome that is interest on direct obligations of the United States (Treasury bills, notes and bonds, U.S. savings bonds), which no state may tax (31 U.S.C. 3124): the states subtract it on their own line. Interest on obligations of federal agencies that are not U.S. obligations (for example Ginnie Mae, Fannie Mae and Freddie Mac securities) does not belong here.", "x-whenAbsent": "0", "x-relation": "A part of ordinaryIncome (federally taxable interest).", "x-limits": "Non-negative; null = absent; at most ordinaryIncome (400). Refused with residency." }, "us_obligation_interest": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of ordinaryIncome (federally taxable interest).", "x-limits": "Non-negative; null = absent; at most ordinaryIncome (400). Refused with residency." }, "militaryServiceYears": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 60, "description": "The person's years of service in the uniformed services (top level, and spouse.militaryServiceYears on a joint return). North Carolina deducts military retirement pay only for a retiree with at least 20 years of service or a medical retirement (Schedule S line 21); fewer years without militaryMedicalRetirement make the pay an ordinary, taxable pension there.", "x-whenAbsent": "not said: the service test taken as met", "x-relation": "A fact about pensionMilitary; read by North Carolina.", "x-limits": "A whole number 1-60; null = absent. Refused with residency." }, "military_service_years": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 60, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not said: the service test taken as met", "x-relation": "A fact about pensionMilitary; read by North Carolina.", "x-limits": "A whole number 1-60; null = absent. Refused with residency." }, "militaryMedicalRetirement": { "type": [ "boolean", "null" ], "description": "The person was medically retired from the uniformed services: North Carolina's military retirement deduction then applies whatever the years of service.", "x-whenAbsent": "false", "x-relation": "A fact about pensionMilitary; read with militaryServiceYears.", "x-limits": "true or false; null = absent. Refused with residency." }, "military_medical_retirement": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "false", "x-relation": "A fact about pensionMilitary; read with militaryServiceYears.", "x-limits": "true or false; null = absent. Refused with residency." }, "veteran": { "type": [ "boolean", "null" ], "description": "The person is a veteran honorably discharged or released under honorable circumstances from active duty: New Jersey's veteran exemption (NJ-1040 line 9), with or without military retired pay; false: no exemption for that person.", "x-whenAbsent": "not said: a person with military retired pay of their own is read as a veteran", "x-relation": "A person fact.", "x-limits": "true or false; null = absent. Refused with residency." }, "retirementIncomeBefore59Half": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "In the year the person reaches 59 1/2, the part of their IRA, employer-plan and private pension income received before that date: New York's pension and annuity exclusion (IT-201 line 29) takes only what is received after it, so this part is taxed.", "x-whenAbsent": "0", "x-relation": "A part of the person's iraDistributions, employerPlanDistributions and pensionPrivate.", "x-limits": "Non-negative; at most those amounts; only with an age of 59 or 60 (400). Refused with residency." }, "retirement_income_before_59_half": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the person's iraDistributions, employerPlanDistributions and pensionPrivate.", "x-limits": "Non-negative; at most those amounts; only with an age of 59 or 60 (400). Refused with residency." }, "federalEarnedIncomeCredits": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "Form 1040 lines 27a and 29: the federal earned income credit and the refundable American opportunity credit. Missouri figures its federal tax deduction on federalTax less them (MO-1040 line 9). With computeFederal the federal return's earned income credit fills it.", "x-whenAbsent": "0", "x-relation": "A federal figure, like federalRefundableCredits.", "x-limits": "Non-negative; null = absent. Refused with computeFederal (it computes it) and with residency." }, "federal_earned_income_credits": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A federal figure, like federalRefundableCredits.", "x-limits": "Non-negative; null = absent. Refused with computeFederal (it computes it) and with residency." }, "residency": { "type": [ "object", "null" ], "properties": { "status": { "type": "string", "pattern": "^(?:[rR][eE][sS][iI][dD][eE][nN][tT]|[pP][aA][rR][tT][yY][eE][aA][rR]|[nN][oO][nN][rR][eE][sS][iI][dD][eE][nN][tT])$", "examples": [ "resident", "partYear", "nonresident" ], "description": "resident (the full-year return), partYear or nonresident (case-insensitive). With residency.spouse: the primary's own.", "x-whenAbsent": "(required inside residency)", "x-relation": "Not an amount.", "x-limits": "Required inside residency; anything else: 400." }, "residentFrom": { "type": [ "string", "null" ], "pattern": "^2026-[0-9]{2}-[0-9]{2}$", "description": "The first day of the resident period, YYYY-MM-DD in 2026.", "x-whenAbsent": "(required for partYear)", "x-relation": "The resident period of a part-year return (the days and months the state counts).", "x-limits": "A date of 2026 written YYYY-MM-DD, at most residentTo; required with residentTo for partYear, refused otherwise: 400." }, "resident_from": { "type": [ "string", "null" ], "pattern": "^2026-[0-9]{2}-[0-9]{2}$", "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(required for partYear)", "x-relation": "The resident period of a part-year return (the days and months the state counts).", "x-limits": "A date of 2026 written YYYY-MM-DD, at most residentTo; required with residentTo for partYear, refused otherwise: 400." }, "residentTo": { "type": [ "string", "null" ], "pattern": "^2026-[0-9]{2}-[0-9]{2}$", "description": "The last day of the resident period, YYYY-MM-DD in 2026.", "x-whenAbsent": "(required for partYear)", "x-relation": "The resident period of a part-year return.", "x-limits": "A date of 2026 written YYYY-MM-DD; required with residentFrom for partYear: 400." }, "resident_to": { "type": [ "string", "null" ], "pattern": "^2026-[0-9]{2}-[0-9]{2}$", "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(required for partYear)", "x-relation": "The resident period of a part-year return.", "x-limits": "A date of 2026 written YYYY-MM-DD; required with residentFrom for partYear: 400." }, "stateIncome": { "type": [ "object", "null" ], "properties": { "wages": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The wages earned in the state or while a resident.", "x-whenAbsent": "0", "x-relation": "A part of the top-level wages.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "ordinaryIncome": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The interest, dividends and other income received while a resident (a nonresident: from a business or property in the state).", "x-whenAbsent": "0", "x-relation": "A part of the top-level ordinaryIncome.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "ordinary_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level ordinaryIncome.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "shortTermGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The net short-term gains taxed by the state.", "x-whenAbsent": "0", "x-relation": "A part of the top-level shortTermGains.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "short_term_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level shortTermGains.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "capitalGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The net long-term gains taxed by the state.", "x-whenAbsent": "0", "x-relation": "A part of the top-level capitalGains.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "capital_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level capitalGains.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "capitalLoss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The the part of the net capital loss the state's column carries.", "x-whenAbsent": "0", "x-relation": "A part of the top-level capitalLoss.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "capital_loss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level capitalLoss.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "iraDistributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The IRA distributions received while a resident (a nonresident: 0, 4 U.S.C. §114).", "x-whenAbsent": "0", "x-relation": "A part of the top-level iraDistributions.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "ira_distributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level iraDistributions.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "pensionPrivate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The private pensions received while a resident (a nonresident: 0).", "x-whenAbsent": "0", "x-relation": "A part of the top-level pensionPrivate.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "pension_private": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level pensionPrivate.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "pensionPublic": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The public pensions received while a resident (a nonresident: 0).", "x-whenAbsent": "0", "x-relation": "A part of the top-level pensionPublic.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "pension_public": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level pensionPublic.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "rothConversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The Roth conversions made while a resident (a nonresident: 0).", "x-whenAbsent": "0", "x-relation": "A part of the top-level rothConversion.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "roth_conversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level rothConversion.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "socialSecurity": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The the taxable Social Security received while a resident (a nonresident: 0).", "x-whenAbsent": "0", "x-relation": "A part of the top-level socialSecurity.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "social_security": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level socialSecurity.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "socialSecurityGross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The the gross Social Security received while a resident (a nonresident: 0).", "x-whenAbsent": "0", "x-relation": "A part of the top-level socialSecurityGross.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "social_security_gross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level socialSecurityGross.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." } }, "additionalProperties": false, "description": "The amounts the state taxes: everything received while a resident plus the state-source income while a nonresident, under the same keys as the top level.", "x-whenAbsent": "every amount 0 (no income from the state)", "x-relation": "Each a part of the top-level amount of the same key.", "x-limits": "An object of the amount keys listed here only (any other key: 400); a full-year resident gives none (400)." }, "state_income": { "type": [ "object", "null" ], "properties": { "wages": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The wages earned in the state or while a resident.", "x-whenAbsent": "0", "x-relation": "A part of the top-level wages.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "ordinaryIncome": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The interest, dividends and other income received while a resident (a nonresident: from a business or property in the state).", "x-whenAbsent": "0", "x-relation": "A part of the top-level ordinaryIncome.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "ordinary_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level ordinaryIncome.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "shortTermGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The net short-term gains taxed by the state.", "x-whenAbsent": "0", "x-relation": "A part of the top-level shortTermGains.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "short_term_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level shortTermGains.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "capitalGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The net long-term gains taxed by the state.", "x-whenAbsent": "0", "x-relation": "A part of the top-level capitalGains.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "capital_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level capitalGains.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "capitalLoss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The the part of the net capital loss the state's column carries.", "x-whenAbsent": "0", "x-relation": "A part of the top-level capitalLoss.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "capital_loss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level capitalLoss.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent." }, "iraDistributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The IRA distributions received while a resident (a nonresident: 0, 4 U.S.C. §114).", "x-whenAbsent": "0", "x-relation": "A part of the top-level iraDistributions.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "ira_distributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level iraDistributions.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "pensionPrivate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The private pensions received while a resident (a nonresident: 0).", "x-whenAbsent": "0", "x-relation": "A part of the top-level pensionPrivate.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "pension_private": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level pensionPrivate.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "pensionPublic": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The public pensions received while a resident (a nonresident: 0).", "x-whenAbsent": "0", "x-relation": "A part of the top-level pensionPublic.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "pension_public": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level pensionPublic.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "rothConversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The Roth conversions made while a resident (a nonresident: 0).", "x-whenAbsent": "0", "x-relation": "A part of the top-level rothConversion.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "roth_conversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level rothConversion.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "socialSecurity": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The the taxable Social Security received while a resident (a nonresident: 0).", "x-whenAbsent": "0", "x-relation": "A part of the top-level socialSecurity.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "social_security": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level socialSecurity.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "socialSecurityGross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The the gross Social Security received while a resident (a nonresident: 0).", "x-whenAbsent": "0", "x-relation": "A part of the top-level socialSecurityGross.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." }, "social_security_gross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the top-level socialSecurityGross.", "x-limits": "A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400." } }, "additionalProperties": false, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "every amount 0 (no income from the state)", "x-relation": "Each a part of the top-level amount of the same key.", "x-limits": "An object of the amount keys listed here only (any other key: 400); a full-year resident gives none (400)." }, "spouse": { "type": [ "object", "null" ], "properties": { "status": { "type": "string", "pattern": "^(?:[rR][eE][sS][iI][dD][eE][nN][tT]|[pP][aA][rR][tT][yY][eE][aA][rR]|[nN][oO][nN][rR][eE][sS][iI][dD][eE][nN][tT])$", "examples": [ "resident", "partYear", "nonresident" ], "description": "The spouse's own residency: resident, partYear or nonresident (case-insensitive).", "x-whenAbsent": "(required inside residency.spouse)", "x-relation": "Not an amount.", "x-limits": "Required inside residency.spouse; anything else: 400." }, "residentFrom": { "type": [ "string", "null" ], "pattern": "^2026-[0-9]{2}-[0-9]{2}$", "description": "The first day of the spouse's own resident period, YYYY-MM-DD in 2026.", "x-whenAbsent": "(required for a partYear spouse)", "x-relation": "The spouse's resident period.", "x-limits": "A date of 2026 written YYYY-MM-DD, at most residentTo; required with residentTo for partYear, refused otherwise: 400." }, "resident_from": { "type": [ "string", "null" ], "pattern": "^2026-[0-9]{2}-[0-9]{2}$", "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(required for a partYear spouse)", "x-relation": "The spouse's resident period.", "x-limits": "A date of 2026 written YYYY-MM-DD, at most residentTo; required with residentTo for partYear, refused otherwise: 400." }, "residentTo": { "type": [ "string", "null" ], "pattern": "^2026-[0-9]{2}-[0-9]{2}$", "description": "The last day of the spouse's own resident period, YYYY-MM-DD in 2026.", "x-whenAbsent": "(required for a partYear spouse)", "x-relation": "The spouse's resident period.", "x-limits": "A date of 2026 written YYYY-MM-DD; required with residentFrom for partYear: 400." }, "resident_to": { "type": [ "string", "null" ], "pattern": "^2026-[0-9]{2}-[0-9]{2}$", "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(required for a partYear spouse)", "x-relation": "The spouse's resident period.", "x-limits": "A date of 2026 written YYYY-MM-DD; required with residentFrom for partYear: 400." }, "stateIncome": { "type": [ "object", "null" ], "properties": { "wages": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own wages the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own wages.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "ordinaryIncome": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own ordinaryIncome the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own ordinaryIncome.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "ordinary_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own ordinaryIncome.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "shortTermGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own shortTermGains the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own shortTermGains.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "short_term_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own shortTermGains.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "capitalGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own capitalGains the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own capitalGains.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "capital_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own capitalGains.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "capitalLoss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own capitalLoss the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own capitalLoss.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "capital_loss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own capitalLoss.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "iraDistributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own iraDistributions the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own iraDistributions.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "ira_distributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own iraDistributions.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "pensionPrivate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own pensionPrivate the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own pensionPrivate.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "pension_private": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own pensionPrivate.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "pensionPublic": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own pensionPublic the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own pensionPublic.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "pension_public": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own pensionPublic.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "rothConversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own rothConversion the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own rothConversion.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "roth_conversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own rothConversion.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "socialSecurity": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own socialSecurity the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own socialSecurity.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "social_security": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own socialSecurity.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "socialSecurityGross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own socialSecurityGross the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own socialSecurityGross.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "social_security_gross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own socialSecurityGross.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." } }, "additionalProperties": false, "description": "The spouse's own amounts the state taxes: everything the spouse received while a resident plus the spouse's state-source income while a nonresident (a full-year resident spouse gives none: all of the spouse's income is the state's).", "x-whenAbsent": "every amount 0 (no income from the state)", "x-relation": "Each a part of the spouse's own amount.", "x-limits": "The keys of residency.stateIncome; each at most the spouse's own amount: 400." }, "state_income": { "type": [ "object", "null" ], "properties": { "wages": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own wages the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own wages.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "ordinaryIncome": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own ordinaryIncome the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own ordinaryIncome.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "ordinary_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own ordinaryIncome.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "shortTermGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own shortTermGains the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own shortTermGains.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "short_term_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own shortTermGains.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "capitalGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own capitalGains the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own capitalGains.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "capital_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own capitalGains.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "capitalLoss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own capitalLoss the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own capitalLoss.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "capital_loss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own capitalLoss.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "iraDistributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own iraDistributions the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own iraDistributions.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "ira_distributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own iraDistributions.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "pensionPrivate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own pensionPrivate the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own pensionPrivate.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "pension_private": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own pensionPrivate.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "pensionPublic": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own pensionPublic the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own pensionPublic.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "pension_public": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own pensionPublic.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "rothConversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own rothConversion the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own rothConversion.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "roth_conversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own rothConversion.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "socialSecurity": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own socialSecurity the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own socialSecurity.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "social_security": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own socialSecurity.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "socialSecurityGross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own socialSecurityGross the state taxes.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own socialSecurityGross.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." }, "social_security_gross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the spouse's own socialSecurityGross.", "x-limits": "A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent." } }, "additionalProperties": false, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "every amount 0 (no income from the state)", "x-relation": "Each a part of the spouse's own amount.", "x-limits": "The keys of residency.stateIncome; each at most the spouse's own amount: 400." } }, "required": [ "status" ], "additionalProperties": false, "description": "Engine 1.13.0: the spouse's own residency on a joint (mfj) request with the spouse object, when the two differ (one moves first): {\"status\", \"residentFrom\", \"residentTo\", \"stateIncome\"} with the same meaning as residency's own keys. With it, residency's own keys are the primary's, each stateIncome is that spouse's own part (each spouse's own amounts: the person amounts of the top level or spouse object, and their part of the household amounts per residency.spouseShare), and the state's own rule for the couple decides the returns (residency.couple in the response).", "x-whenAbsent": "none: the top-level residency is the household's (both spouses the same)", "x-relation": "Not an amount.", "x-limits": "An object with status and only these keys; it needs filingStatus \"mfj\" and the spouse object: 400 otherwise." }, "spouseShare": { "type": [ "object", "null" ], "properties": { "ordinaryIncome": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's part of the household ordinaryIncome.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level ordinaryIncome.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "ordinary_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level ordinaryIncome.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "shortTermGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's part of the household shortTermGains.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level shortTermGains.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "short_term_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level shortTermGains.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "capitalGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's part of the household capitalGains.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level capitalGains.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "capital_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level capitalGains.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "capitalLoss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's part of the household capitalLoss.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level capitalLoss.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "capital_loss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level capitalLoss.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "capitalLossCarryover": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's part of the household capitalLossCarryover.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level capitalLossCarryover.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "capital_loss_carryover": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level capitalLossCarryover.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "socialSecurity": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's part of the household socialSecurity.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level socialSecurity.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "social_security": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level socialSecurity.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." } }, "additionalProperties": false, "description": "Engine 1.13.0: the spouse's part of the household amounts (ordinaryIncome, shortTermGains, capitalGains, capitalLoss, capitalLossCarryover, socialSecurity) when the spouses' residency differs; the primary's part is the rest. Each spouse's own amounts decide what the state taxes and each separate return.", "x-whenAbsent": "none (needed for each household amount that is not 0)", "x-relation": "A split of the top-level household amounts.", "x-limits": "Only with residency.spouse; each key needed when its household amount is not 0, at most it: 400." }, "spouse_share": { "type": [ "object", "null" ], "properties": { "ordinaryIncome": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's part of the household ordinaryIncome.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level ordinaryIncome.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "ordinary_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level ordinaryIncome.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "shortTermGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's part of the household shortTermGains.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level shortTermGains.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "short_term_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level shortTermGains.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "capitalGains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's part of the household capitalGains.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level capitalGains.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "capital_gains": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level capitalGains.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "capitalLoss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's part of the household capitalLoss.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level capitalLoss.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "capital_loss": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level capitalLoss.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "capitalLossCarryover": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's part of the household capitalLossCarryover.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level capitalLossCarryover.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "capital_loss_carryover": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level capitalLossCarryover.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "socialSecurity": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's part of the household socialSecurity.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level socialSecurity.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." }, "social_security": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "(needed when the household amount is not 0)", "x-relation": "A part of the top-level socialSecurity.", "x-limits": "A finite number from 0 to the household amount (at most $100 billion): 400. null = absent." } }, "additionalProperties": false, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "none (needed for each household amount that is not 0)", "x-relation": "A split of the top-level household amounts.", "x-limits": "Only with residency.spouse; each key needed when its household amount is not 0, at most it: 400." }, "election": { "type": [ "string", "null" ], "pattern": "^(?:[jJ][oO][iI][nN][tT]|[sS][eE][pP][aA][rR][aA][tT][eE]|[jJ][oO][iI][nN][tT][aA][sS][rR][eE][sS][iI][dD][eE][nN][tT][sS])$", "examples": [ "joint", "separate", "jointAsResidents" ], "description": "Engine 1.13.0: which of the treatments the state allows the couple applies to tax: \"joint\" (one joint part-year / nonresident return), \"separate\" (each spouse's own return) or \"jointAsResidents\" (a joint resident return, both taxed as full-year residents). Every allowed treatment is computed and reported either way (residency.couple.options).", "x-whenAbsent": "none: the state's required or default treatment, else (a free choice) the joint return the request's mfj names", "x-relation": "Not an amount.", "x-limits": "Only with residency.spouse; one the state allows for the couple: 400 otherwise." } }, "required": [ "status" ], "additionalProperties": false, "description": "A part-year resident's or nonresident's return (engine 1.12.0): {\"status\": \"partYear\", \"residentFrom\": \"2026-07-01\", \"residentTo\": \"2026-12-31\", \"stateIncome\": {...}} or {\"status\": \"nonresident\", \"stateIncome\": {...}}. The top-level amounts stay the whole year's (the forms compute as if a full-year resident, then apportion); stateIncome holds the part the state taxes. Each state's own method (ratio, prorated items, rounding) is on its page; the response's residency block shows the computation.", "x-whenAbsent": "none: a full-year resident (every result before engine 1.12.0)", "x-relation": "Not an amount; the whole year's amounts stay at the top level.", "x-limits": "An object with status and only the keys listed here; with residency, dependents, the credit facts, and military, civil service, disability, employer-plan, self-employment, railroad or qualified-dividend amounts or the person facts are a 400 (not modelled with residency); a spouse split needs residency.spouse (engine 1.13.0); localities: see localities[] (engine 1.13.0)." }, "pensionPublicSsCovered": { "type": [ "boolean", "null" ], "description": "Was the pensionPublic service covered by Social Security? false unlocks the rules for non-covered pensions (each state page's public-pension section says which apply); true or absent gives none. It covers both spouses' pensionPublic.", "x-whenAbsent": "unknown", "x-relation": "A fact about pensionPublic (both spouses').", "x-limits": "true or false; null = absent (unknown). Anything else: 400." }, "pension_public_ss_covered": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "unknown", "x-relation": "A fact about pensionPublic (both spouses').", "x-limits": "true or false; null = absent (unknown). Anything else: 400." }, "blind": { "type": [ "boolean", "null" ], "description": "The primary filer is blind (the federal test: corrected vision no better than 20/200 in the better eye, or a field of 20 degrees or less). Each state's blind amounts apply as its page lists; true or false, null means false.", "x-whenAbsent": "false", "x-relation": "A fact about the primary filer.", "x-limits": "true or false; null = false. Anything else: 400." }, "disabled": { "type": [ "boolean", "null" ], "description": "The primary filer is totally and permanently disabled. Read only by the disability rules each state page lists; true or false, null means false.", "x-whenAbsent": "false", "x-relation": "A fact about the primary filer.", "x-limits": "true or false; null = false. Anything else: 400." }, "dependents": { "type": [ "array", "null" ], "maxItems": 20, "items": { "type": "object", "properties": { "age": { "type": "integer", "minimum": 0, "maximum": 120, "description": "Whole number, 0 to 120: the age at the end of the year (0 for a child born in the year).", "x-whenAbsent": "required", "x-relation": "A dependent's age.", "x-limits": "Required: whole number 0 to 120, else 400." }, "student": { "type": [ "boolean", "null" ], "description": "A full-time student (the five-month test).", "x-whenAbsent": "false", "x-relation": "A fact about the dependent.", "x-limits": "true or false; null = false. Anything else: 400." }, "disabled": { "type": [ "boolean", "null" ], "description": "Permanently and totally disabled.", "x-whenAbsent": "false", "x-relation": "A fact about the dependent.", "x-limits": "true or false; null = false. Anything else: 400." } }, "required": [ "age" ], "additionalProperties": false }, "description": "The household's dependents (people claimed as dependents on the federal return), each `{age, student, disabled}`; a head of household lists the qualifying person when that person is a dependent. The states' dependent exemptions, deductions and credits read it.", "x-whenAbsent": "none", "x-relation": "Facts about the household's dependents.", "x-limits": "An array of at most 20 objects with only age, student and disabled; [] = none; null = absent. Otherwise 400 naming the element." }, "earlyDistributionException": { "type": [ "string", "null" ], "pattern": "^(?:[nN][oO][nN][eE]|[sS][eE][pP][pP]|[dD][eE][aA][tT][hH]|[dD][iI][sS][aA][bB][iI][lL][iI][tT][yY]|[oO][tT][hH][eE][rR])$", "examples": [ "none", "sepp", "death", "disability", "other" ], "description": "The federal early-withdrawal exception for earlyDistributions: none, sepp (equal periodic payments), death (paid to a beneficiary), disability or other.", "x-whenAbsent": "none (death for survivor benefits, disability for a disabled person)", "x-relation": "A fact about earlyDistributions.", "x-limits": "none, sepp, death, disability or other, any case; null = absent. Anything else: 400." }, "early_distribution_exception": { "type": [ "string", "null" ], "pattern": "^(?:[nN][oO][nN][eE]|[sS][eE][pP][pP]|[dD][eE][aA][tT][hH]|[dD][iI][sS][aA][bB][iI][lL][iI][tT][yY]|[oO][tT][hH][eE][rR])$", "examples": [ "none", "sepp", "death", "disability", "other" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "none (death for survivor benefits, disability for a disabled person)", "x-relation": "A fact about earlyDistributions.", "x-limits": "none, sepp, death, disability or other, any case; null = absent. Anything else: 400." }, "survivorBenefits": { "type": [ "boolean", "null" ], "description": "The person's pension and IRA income is received as a beneficiary of someone who died.", "x-whenAbsent": "false", "x-relation": "A fact about the person's pension and IRA income.", "x-limits": "true or false; null = false. Anything else: 400." }, "survivor_benefits": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "false", "x-relation": "A fact about the person's pension and IRA income.", "x-limits": "true or false; null = false. Anything else: 400." }, "socialSecurityDisability": { "type": [ "boolean", "null" ], "description": "The person's Social Security is disability benefits for the whole year; false says it is not (a state that exempts only older recipients then taxes a younger one's share).", "x-whenAbsent": "not said", "x-relation": "A fact about the person's Social Security.", "x-limits": "true or false; null = not said. Anything else: 400." }, "social_security_disability": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not said", "x-relation": "A fact about the person's Social Security.", "x-limits": "true or false; null = not said. Anything else: 400." }, "priorHohQualifyingPersonDied": { "type": [ "boolean", "null" ], "description": "The filer was a head of household in one of the two previous years for a qualifying person who died in one of those years.", "x-whenAbsent": "false", "x-relation": "A fact about the filer.", "x-limits": "true or false; null = false. Anything else: 400." }, "prior_hoh_qualifying_person_died": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "false", "x-relation": "A fact about the filer.", "x-limits": "true or false; null = false. Anything else: 400." }, "planMinimumRetirementAge": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 120, "description": "The minimum retirement age of the plan paying the person's disabilityIncome: from that age the pay is a pension (IRS Pub. 525). Connecticut then subtracts it as a pension (line 48b), Maine counts it as pension income from that age (in place of 55), and Ohio stops deducting it on line 42 from that age (in place of 65). Every other state ignores it.", "x-whenAbsent": "not said (Connecticut reads disability pay as wages, Maine as pension income from 55, Ohio deducts it until 65)", "x-relation": "A fact about the person's disabilityIncome. With spouse: the primary filer's (spouse.planMinimumRetirementAge is the spouse's); without: the household's.", "x-limits": "Whole number 1 to 120; null = absent. Otherwise 400 naming the field. Needs disabilityIncome at the same level (else 400)." }, "plan_minimum_retirement_age": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 120, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not said (Connecticut reads disability pay as wages, Maine as pension income from 55, Ohio deducts it until 65)", "x-relation": "A fact about the person's disabilityIncome. With spouse: the primary filer's (spouse.planMinimumRetirementAge is the spouse's); without: the household's.", "x-limits": "Whole number 1 to 120; null = absent. Otherwise 400 naming the field. Needs disabilityIncome at the same level (else 400)." }, "deceasedSpouseAge": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 120, "description": "For a surviving spouse (survivorBenefits: true): the age the deceased spouse would have reached by the end of the year had they lived. South Carolina's surviving-spouse deduction (SC1040 line p-3) is {{SC:config.survivor_spouse_deduction_older|money}} instead of {{SC:config.survivor_spouse_deduction|money}} when that age is {{SC:config.survivor_spouse_older_age|int}} or more. Every other state ignores it.", "x-whenAbsent": "not said (South Carolina's lower amount)", "x-relation": "A fact about the person's survivor income. With spouse: the primary filer's (spouse.deceasedSpouseAge is the spouse's); without: the household's.", "x-limits": "Whole number 1 to 120; null = absent. Otherwise 400 naming the field. Needs survivorBenefits: true at the same level (else 400)." }, "deceased_spouse_age": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 120, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not said (South Carolina's lower amount)", "x-relation": "A fact about the person's survivor income. With spouse: the primary filer's (spouse.deceasedSpouseAge is the spouse's); without: the household's.", "x-limits": "Whole number 1 to 120; null = absent. Otherwise 400 naming the field. Needs survivorBenefits: true at the same level (else 400)." }, "socialSecuritySurvivor": { "type": [ "boolean", "null" ], "description": "The person's Social Security benefits are survivor benefits (paid because of the death of the person entitled to them). Colorado's death-benefit subtraction for a person under {{CO:config.survivor_young_below_age|int}} then also covers the person's taxable Social Security, within its one {{CO:config.survivor_young_cap|money}} limit. Every other state ignores it.", "x-whenAbsent": "false", "x-relation": "A fact about the person's Social Security. With spouse: the primary filer's (the spouse's own benefits are spouse.socialSecurityGross's share); without: the household's.", "x-limits": "true or false; null = false. Anything else: 400." }, "social_security_survivor": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "false", "x-relation": "A fact about the person's Social Security. With spouse: the primary filer's (the spouse's own benefits are spouse.socialSecurityGross's share); without: the household's.", "x-limits": "true or false; null = false. Anything else: 400." }, "domicileYears": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 120, "description": "The whole years the person has been domiciled in the state at the end of the year. Delaware, from tax year 2027: a person 60 or older takes no pension exclusion before 3 years (5 for a person domiciled from 2027); for 2026 it changes nothing (the act applies to tax years after January 1, 2027). Every other state ignores it.", "x-whenAbsent": "not said (no domicile test)", "x-relation": "A fact about the person. With spouse: the primary filer's (spouse.domicileYears is the spouse's); without spouse on a joint return, the test applies to the return only when both are said to fail.", "x-limits": "Whole number 0 to 120; null = absent. Otherwise 400 naming the field." }, "domicile_years": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 120, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not said (no domicile test)", "x-relation": "A fact about the person. With spouse: the primary filer's (spouse.domicileYears is the spouse's); without spouse on a joint return, the test applies to the return only when both are said to fail.", "x-limits": "Whole number 0 to 120; null = absent. Otherwise 400 naming the field." }, "includeSources": { "type": [ "boolean", "null" ], "description": "false leaves rules.sources and rules.unsourced out of the response, for callers that do not need the citations (a smaller, faster response); the tax and every other field are the same.", "x-whenAbsent": "true", "x-relation": "Not an engine input: shapes the response only.", "x-limits": "true or false; null = true. Anything else: 400." }, "include_sources": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "true", "x-relation": "Not an engine input: shapes the response only.", "x-limits": "true or false; null = true. Anything else: 400." }, "includeInputsNotSupplied": { "type": [ "boolean", "null" ], "description": "false leaves inputsNotSupplied out of the response and runs none of its probes (engine 1.10.0). The tax is the same either way.", "x-whenAbsent": "true", "x-relation": "Response shaping; not an amount.", "x-limits": "true or false; null = true. Anything else: 400 naming the field." }, "include_inputs_not_supplied": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "true", "x-relation": "Response shaping; not an amount.", "x-limits": "true or false; null = true. Anything else: 400 naming the field." }, "includeNotModelled": { "type": [ "boolean", "null" ], "description": "false leaves notModelled out of the response (engine 1.12.0). The tax is the same either way.", "x-whenAbsent": "true", "x-relation": "Response shaping; not an amount.", "x-limits": "true or false; null = true. Anything else: 400 naming the field." }, "include_not_modelled": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "true", "x-relation": "Response shaping; not an amount.", "x-limits": "true or false; null = true. Anything else: 400 naming the field." }, "strict": { "type": [ "boolean", "null" ], "description": "true: a top-level key the API does not read is refused with a 400 that names it (up to five, then a count), checked before anything else (engine 1.10.0). Keys match as the API matches them: any case, either spelling.", "x-whenAbsent": "false (unknown top-level keys are ignored)", "x-relation": "Request checking; not an amount.", "x-limits": "true or false; null = false. Anything else: 400 naming the field." }, "taxYear": { "type": [ "integer", "null" ], "minimum": 2026, "maximum": 2026, "description": "The tax year the request is for (state engine 1.16.8). This build carries the rules year only: the rules year is accepted and answered exactly as without the key; any other year is refused with a 400 rather than answered with the rules year's law. A later year is an estimate through projection.", "x-whenAbsent": "the rules year (2026)", "x-relation": "Request checking; not an amount.", "x-limits": "The rules year (2026); null = absent. Another whole number: 400 (the year is not carried). A string, fraction or other type: 400 naming the field." }, "tax_year": { "type": [ "integer", "null" ], "minimum": 2026, "maximum": 2026, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "the rules year (2026)", "x-relation": "Request checking; not an amount.", "x-limits": "The rules year (2026); null = absent. Another whole number: 400 (the year is not carried). A string, fraction or other type: 400 naming the field." }, "projection": { "type": [ "object", "null" ], "properties": { "year": { "type": "integer", "minimum": 2026, "maximum": 2100, "description": "The tax year to estimate.", "x-whenAbsent": "(required inside projection)", "x-relation": "Not an amount.", "x-limits": "Required inside projection; a whole number from 2026 (the rules year) to 2100. Otherwise 400." }, "inflation": { "type": [ "number", "null" ], "minimum": -0.1, "maximum": 0.25, "description": "The annual CPI assumption; the cumulative factor is (1 + inflation) to the power of (year - 2026).", "x-whenAbsent": "none (then cpiFactor)", "x-relation": "Not an amount; exactly one of inflation and cpiFactor.", "x-limits": "From -0.10 to 0.25; not together with cpiFactor. Otherwise 400." }, "cpiFactor": { "type": [ "number", "null" ], "minimum": 0.01, "maximum": 100, "description": "Your own cumulative CPI factor from 2026 to year (for example 1.44).", "x-whenAbsent": "none (then inflation)", "x-relation": "Not an amount; exactly one of inflation and cpiFactor.", "x-limits": "From 0.01 to 100, and 1 when year is 2026; not together with inflation. Otherwise 400." }, "cpi_factor": { "type": [ "number", "null" ], "minimum": 0.01, "maximum": 100, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "none (then inflation)", "x-relation": "Not an amount; exactly one of inflation and cpiFactor.", "x-limits": "From 0.01 to 100, and 1 when year is 2026; not together with inflation. Otherwise 400." }, "indexing": { "type": [ "string", "null" ], "pattern": "^(?:[lL][aA][wW]|[iI][nN][fF][lL][aA][tT][iI][oO][nN])$", "examples": [ "law", "inflation" ], "description": "How the dollar amounts move: \"law\" (the default) moves each the way its state's law moves it; \"inflation\" multiplies every amount QuantCalc's planner scaled before engine 1.10.0 by the factor, unrounded, and holds the rest (schedules and derived amounts not applied; the result is not refused for an unsettled amount). Birth-year age cutoffs move one year per year either way.", "x-whenAbsent": "law", "x-relation": "Not an amount.", "x-limits": "\"law\" or \"inflation\", any case; null means law. Otherwise 400." } }, "required": [ "year" ], "additionalProperties": false, "description": "Estimate a later tax year (engine 1.10.0): {\"year\": 2040, \"inflation\": 0.025} or {\"year\": 2040, \"cpiFactor\": 1.44}. Every dollar amount and birth-year age cutoff of the state's rules moves the way the state's law moves it (see /docs/state-tax/indexing/), or, with indexing \"inflation\", as QuantCalc's planner moved them before engine 1.10.0; the amounts in the request are taken as that year's. The response says projected: true and carries a projection block. With computeFederal the federal return is projected to the same year with the same factor and indexing (federal engine 2.0: see /docs/federal-tax/indexing/).", "x-whenAbsent": "none: the rules year (2026)", "x-relation": "Not an amount.", "x-limits": "An object with year and exactly one of inflation or cpiFactor, and no other key; otherwise 400 naming the problem." }, "spouse": { "type": [ "object", "null" ], "properties": { "wages": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own wages (with computeFederal: the spouse's W-2 wages).", "x-whenAbsent": "0", "x-relation": "Component. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "iraDistributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own IRA distributions.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from employerPlanDistributions and rothConversion. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "ira_distributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from employerPlanDistributions and rothConversion. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pensionPrivate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own private pension.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from disabilityIncome. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pension_private": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from disabilityIncome. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pensionPublic": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own public pension.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from pensionFederalCivilService and pensionMilitary. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pension_public": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from pensionFederalCivilService and pensionMilitary. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pensionMilitary": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own military retirement pay.", "x-whenAbsent": "0", "x-relation": "Component. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pension_military": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "rothConversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own conversion.", "x-whenAbsent": "0", "x-relation": "Component, not part of iraDistributions. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "roth_conversion": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component, not part of iraDistributions. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pensionFederalCivilService": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own pensionFederalCivilService (joint returns).", "x-whenAbsent": "0", "x-relation": "Component, disjoint from pensionPublic. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "pension_federal_civil_service": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from pensionPublic. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "disabilityIncome": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own disabilityIncome (joint returns).", "x-whenAbsent": "0", "x-relation": "Component, disjoint from pensionPrivate. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "disability_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from pensionPrivate. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "earlyDistributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own earlyDistributions (joint returns).", "x-whenAbsent": "every IRA and employer-plan dollar of a person under 59", "x-relation": "Part of the spouse's own iraDistributions plus employerPlanDistributions; not added to income again.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. At most spouse.iraDistributions plus spouse.employerPlanDistributions, else 400." }, "early_distributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "every IRA and employer-plan dollar of a person under 59", "x-relation": "Part of the spouse's own iraDistributions plus employerPlanDistributions; not added to income again.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. At most spouse.iraDistributions plus spouse.employerPlanDistributions, else 400." }, "iraBasis": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own iraBasis (joint returns).", "x-whenAbsent": "0", "x-relation": "Not income: the after-tax basis read with earlyDistributions; adds nothing to income.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "ira_basis": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Not income: the after-tax basis read with earlyDistributions; adds nothing to income.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "railroadRetirementTier2": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own Railroad Retirement Tier 2 and supplemental annuities.", "x-whenAbsent": "0", "x-relation": "Component. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "railroad_retirement_tier2": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "railroadRetirementTier1": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own part of railroadRetirementTier1 (needs it, at most it, and at most spouse.socialSecurityGross when that is given).", "x-whenAbsent": "none of the household's Tier 1", "x-relation": "Part of railroadRetirementTier1 and of spouse.socialSecurityGross.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Needs railroadRetirementTier1 and at most it (and at most spouse.socialSecurityGross when given), else 400." }, "railroad_retirement_tier1": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "none of the household's Tier 1", "x-relation": "Part of railroadRetirementTier1 and of spouse.socialSecurityGross.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Needs railroadRetirementTier1 and at most it (and at most spouse.socialSecurityGross when given), else 400." }, "employerPlanDistributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own 401(k), 403(b) and 457(b) distributions.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from iraDistributions. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "employer_plan_distributions": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from iraDistributions. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field." }, "selfEmploymentIncome": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own net profit from self-employment (joint returns; needs computeFederal: true).", "x-whenAbsent": "0", "x-relation": "Component, disjoint from spouse.wages. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Not 0 without computeFederal: true, else 400." }, "self_employment_income": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "Component, disjoint from spouse.wages. The spouse's own amount (joint returns).", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Not 0 without computeFederal: true, else 400." }, "qualifiedTips": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own qualified tips (joint returns).", "x-whenAbsent": "0", "x-relation": "A part of spouse.wages.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. With spouse.qualifiedOvertime more than spouse.wages: 400; refused on a separate return." }, "qualified_tips": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of spouse.wages.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. With spouse.qualifiedOvertime more than spouse.wages: 400; refused on a separate return." }, "qualifiedOvertime": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own qualified overtime compensation (joint returns).", "x-whenAbsent": "0", "x-relation": "A part of spouse.wages.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. With spouse.qualifiedTips more than spouse.wages: 400; refused on a separate return." }, "qualified_overtime": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of spouse.wages.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. With spouse.qualifiedTips more than spouse.wages: 400; refused on a separate return." }, "militaryServiceYears": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 60, "description": "The spouse's own militaryServiceYears on a joint return (as the top-level one for the filer).", "x-whenAbsent": "not said: the service test taken as met", "x-relation": "A fact about pensionMilitary; read by North Carolina.", "x-limits": "A whole number 1-60; null = absent. Refused with residency." }, "military_service_years": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 60, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not said: the service test taken as met", "x-relation": "A fact about pensionMilitary; read by North Carolina.", "x-limits": "A whole number 1-60; null = absent. Refused with residency." }, "militaryMedicalRetirement": { "type": [ "boolean", "null" ], "description": "The spouse's own militaryMedicalRetirement on a joint return (as the top-level one for the filer).", "x-whenAbsent": "false", "x-relation": "A fact about pensionMilitary; read with militaryServiceYears.", "x-limits": "true or false; null = absent. Refused with residency." }, "military_medical_retirement": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "false", "x-relation": "A fact about pensionMilitary; read with militaryServiceYears.", "x-limits": "true or false; null = absent. Refused with residency." }, "veteran": { "type": [ "boolean", "null" ], "description": "The spouse's own veteran on a joint return (as the top-level one for the filer).", "x-whenAbsent": "not said: a person with military retired pay of their own is read as a veteran", "x-relation": "A person fact.", "x-limits": "true or false; null = absent. Refused with residency." }, "retirementIncomeBefore59Half": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own retirementIncomeBefore59Half on a joint return (as the top-level one for the filer).", "x-whenAbsent": "0", "x-relation": "A part of the person's iraDistributions, employerPlanDistributions and pensionPrivate.", "x-limits": "Non-negative; at most those amounts; only with an age of 59 or 60 (400). Refused with residency." }, "retirement_income_before_59_half": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "0", "x-relation": "A part of the person's iraDistributions, employerPlanDistributions and pensionPrivate.", "x-limits": "Non-negative; at most those amounts; only with an age of 59 or 60 (400). Refused with residency." }, "blind": { "type": [ "boolean", "null" ], "description": "The spouse is blind (joint returns; on a separate return, the other spouse).", "x-whenAbsent": "false", "x-relation": "A fact about the spouse.", "x-limits": "true or false; null = false. Anything else: 400." }, "disabled": { "type": [ "boolean", "null" ], "description": "The spouse is totally and permanently disabled (joint returns).", "x-whenAbsent": "false", "x-relation": "A fact about the spouse.", "x-limits": "true or false; null = false. Anything else: 400." }, "earlyDistributionException": { "type": [ "string", "null" ], "pattern": "^(?:[nN][oO][nN][eE]|[sS][eE][pP][pP]|[dD][eE][aA][tT][hH]|[dD][iI][sS][aA][bB][iI][lL][iI][tT][yY]|[oO][tT][hH][eE][rR])$", "examples": [ "none", "sepp", "death", "disability", "other" ], "description": "The spouse's own earlyDistributionException (joint returns).", "x-whenAbsent": "none (death for survivor benefits, disability for a disabled person)", "x-relation": "A fact about earlyDistributions.", "x-limits": "none, sepp, death, disability or other, any case; null = absent. Anything else: 400." }, "early_distribution_exception": { "type": [ "string", "null" ], "pattern": "^(?:[nN][oO][nN][eE]|[sS][eE][pP][pP]|[dD][eE][aA][tT][hH]|[dD][iI][sS][aA][bB][iI][lL][iI][tT][yY]|[oO][tT][hH][eE][rR])$", "examples": [ "none", "sepp", "death", "disability", "other" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "none (death for survivor benefits, disability for a disabled person)", "x-relation": "A fact about earlyDistributions.", "x-limits": "none, sepp, death, disability or other, any case; null = absent. Anything else: 400." }, "survivorBenefits": { "type": [ "boolean", "null" ], "description": "The spouse's own survivorBenefits (joint returns).", "x-whenAbsent": "false", "x-relation": "A fact about the spouse's pension and IRA income.", "x-limits": "true or false; null = false. Anything else: 400." }, "survivor_benefits": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "false", "x-relation": "A fact about the spouse's pension and IRA income.", "x-limits": "true or false; null = false. Anything else: 400." }, "socialSecurityDisability": { "type": [ "boolean", "null" ], "description": "The spouse's own socialSecurityDisability (joint returns).", "x-whenAbsent": "not said", "x-relation": "A fact about the spouse's Social Security.", "x-limits": "true or false; null = not said. Anything else: 400." }, "social_security_disability": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not said", "x-relation": "A fact about the spouse's Social Security.", "x-limits": "true or false; null = not said. Anything else: 400." }, "planMinimumRetirementAge": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 120, "description": "The spouse's own planMinimumRetirementAge (joint returns): the minimum retirement age of the plan paying spouse.disabilityIncome.", "x-whenAbsent": "not said", "x-relation": "A fact about the spouse's disabilityIncome.", "x-limits": "Whole number 1 to 120; null = absent. Otherwise 400 naming the field. Needs spouse.disabilityIncome (else 400); refused on a separate return." }, "plan_minimum_retirement_age": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 120, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not said", "x-relation": "A fact about the spouse's disabilityIncome.", "x-limits": "Whole number 1 to 120; null = absent. Otherwise 400 naming the field. Needs spouse.disabilityIncome (else 400); refused on a separate return." }, "deceasedSpouseAge": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 120, "description": "The spouse's own deceasedSpouseAge (joint returns): the age the spouse's deceased former spouse would have reached.", "x-whenAbsent": "not said", "x-relation": "A fact about the spouse's survivor income.", "x-limits": "Whole number 1 to 120; null = absent. Otherwise 400 naming the field. Needs spouse.survivorBenefits: true (else 400); refused on a separate return." }, "deceased_spouse_age": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 120, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not said", "x-relation": "A fact about the spouse's survivor income.", "x-limits": "Whole number 1 to 120; null = absent. Otherwise 400 naming the field. Needs spouse.survivorBenefits: true (else 400); refused on a separate return." }, "socialSecuritySurvivor": { "type": [ "boolean", "null" ], "description": "The spouse's own socialSecuritySurvivor (joint returns): the spouse's Social Security benefits are survivor benefits.", "x-whenAbsent": "false", "x-relation": "A fact about the spouse's Social Security.", "x-limits": "true or false; null = false. Anything else: 400; refused on a separate return." }, "social_security_survivor": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "false", "x-relation": "A fact about the spouse's Social Security.", "x-limits": "true or false; null = false. Anything else: 400; refused on a separate return." }, "domicileYears": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 120, "description": "The spouse's own years of domicile in the state (joint returns).", "x-whenAbsent": "not said", "x-relation": "A fact about the spouse.", "x-limits": "Whole number 0 to 120; null = absent. Otherwise 400 naming the field; refused on a separate return." }, "domicile_years": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 120, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "not said", "x-relation": "A fact about the spouse.", "x-limits": "Whole number 0 to 120; null = absent. Otherwise 400 naming the field; refused on a separate return." }, "age": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 120, "description": "Whole number, 1 to 120 (on a separate return: the other spouse's age).", "x-whenAbsent": "the primary filer's age", "x-relation": "The spouse's age.", "x-limits": "Whole number 1 to 120, else 400." }, "socialSecurityGross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The spouse's own gross Social Security (with their Tier 1 railroad benefits), part of socialSecurityGross (which must be given and at least as large). It divides the benefits between the spouses for the per-spouse rules (Colorado, Maine, Maryland, Rhode Island and the other rules that read each spouse's benefits).", "x-whenAbsent": "half the household figure", "x-relation": "Part of socialSecurityGross (the household total); not added to income.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Needs socialSecurityGross and at most it, else 400." }, "social_security_gross": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000000, "description": "The same field under its snake_case spelling.", "x-whenAbsent": "half the household figure", "x-relation": "Part of socialSecurityGross (the household total); not added to income.", "x-limits": "Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Needs socialSecurityGross and at most it, else 400." } }, "additionalProperties": false, "description": "Joint returns: the spouse's own amounts, age and facts; with it, the top-level person fields are the primary filer's own amounts. Married filing separately: only the other spouse's age and blind.", "x-whenAbsent": "none (household totals)", "x-relation": "Joint returns: makes the top-level person fields the primary's own. Separate returns: the other spouse's age and blind only.", "x-limits": "An object with only the spouse keys listed here (any other key: 400); only with filingStatus mfj, or mfs with age and blind only, else 400." }, "computeFederal": { "type": [ "boolean", "null" ], "description": "true: the federal inputs come from QuantCalc's federal engine instead of from the request. It builds one federal return from this request (wages, self-employment income, IRA and employer-plan distributions, pensions including Railroad Retirement Tier 2, Roth conversions, gains, gross Social Security, the ages) and hands the state engine what the planner hands it: socialSecurity (the taxable part), federalTax and federalTaxBeforeCredits (the income tax without the NIIT; the federal engine models no credits), federalNiit, federalRefundableCredits 0, and federal taxable income for the states whose base starts from it. The response gains a `federal` object with the federal return. blind (the filer, and the spouse on a joint return) adds the federal §63(f) amount for blindness, and filingStatus qss is priced on the federal joint tables for a qualifying surviving spouse. ordinaryIncome goes on federal Form 1040 line 2b (interest and non-qualified dividends) and qualifiedDividends on lines 3a and 3b, and taxExemptInterest (or the sum of inStateMunicipalInterest and outOfStateMunicipalInterest) on line 2a, in the provisional income of the Social Security worksheet (state engine 1.16; before it this path left line 2a at 0), with their share of the NIIT and the capital-gains worksheet. Each person's wages are one W-2 from one employer (boxes 1, 3 and 5 the same, box 3 at most the social security wage base) with the employer's social security and Medicare withholding, including the additional Medicare withholding (federal engine 2.0); selfEmploymentIncome is the person's Schedule C net profit (Schedule SE, the deduction for half the self-employment tax, the qualified business income deduction), and the state engine receives each person's wages plus that profit less half the person's self-employment tax. The self-employment tax and the Additional Medicare Tax are not income tax: federalTax stays the income tax without them. A request with anything the federal engine does not model (disabilityIncome, earlyDistributions or earlyDistributionException, iraBasis, disabled, dependents, a separate filer's spouse.blind), or with its own socialSecurity or federal figures, is refused with 400. The embeddable library answers it the same way from library 1.6 (its default build carries the federal engine); a state-only build of the library ignores it. Federal engine reference: /docs/federal-tax/. With projection, the federal return is the federal engine's projection of the same year, with the same factor and indexing (federal engine 2.0), and the `federal` object carries rulesYear, projectedYear, projected and the federal projection block. The federal return's deduction (Form 1040 line 12e, and on an itemized return the state income tax inside Schedule A line 5e) reaches the states that read it: Colorado's line 4 add-back at high income, the Colorado and Montana add-back of the state income tax a federal itemizer deducted, and Utah's taxpayer credit base (2026-10-12). The federal return itemizes only with federalItemized.", "x-whenAbsent": "false (the caller's own federal figures, or none)", "x-relation": "Not an amount: chooses where federalTax, federalNiit, federalTaxBeforeCredits, federalRefundableCredits and socialSecurity come from. Needs age, and spouse.age on a joint return.", "x-limits": "true or false; null = false. Anything else: 400." }, "compute_federal": { "type": [ "boolean", "null" ], "description": "The same field under its snake_case spelling.", "x-whenAbsent": "false (the caller's own federal figures, or none)", "x-relation": "Not an amount: chooses where federalTax, federalNiit, federalTaxBeforeCredits, federalRefundableCredits and socialSecurity come from. Needs age, and spouse.age on a joint return.", "x-limits": "true or false; null = false. Anything else: 400." }, "federalItemized": { "type": [ "object", "null" ], "description": "With computeFederal: true, the federal return's Schedule A, in POST /api/federal-tax's names: saltIncomeOrSalesTax (line 5a, the state and local income tax paid in the year), saltRealEstateTax (5b), saltPersonalPropertyTax (5c), mortgageInterest (8a-8c, the deductible amount), charityCash (11), medicalExpenses (1, before the AGI floor). The federal return itemizes when that is the lower tax, as POST /api/federal-tax does with itemizeMode auto, and the `federal` object echoes the amounts under inputs.federalItemized and reports schedules.scheduleA. These are federal amounts only: the state's own facts are propertyTaxPaid and medicalExpenses.", "x-whenAbsent": "none (the federal return takes the standard deduction)", "x-relation": "Not part of the state return's amounts: it shapes the federal return computeFederal builds (its taxable income, which Colorado, Iowa, Montana and North Dakota start from).", "x-limits": "An object of the six keys, each a number from 0 to $1 trillion; any other key, a wrong type or a negative: 400. Without computeFederal: true: 400.", "properties": { "saltIncomeOrSalesTax": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "saltRealEstateTax": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "saltPersonalPropertyTax": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "mortgageInterest": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "charityCash": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "medicalExpenses": { "type": "number", "minimum": 0, "maximum": 1000000000000 } }, "additionalProperties": false } }, "required": [ "state" ], "additionalProperties": true, "description": "The request body. All amounts are annual US dollars. Unknown top-level keys are ignored unless strict is true (then refused, named); unknown keys inside spouse, a dependent or projection are refused.", "x-errors": [ { "message": "Invalid JSON body", "when": "The body is not JSON (or is empty)." }, { "message": "{1} must be a string, one of: single, mfj, married_filing_jointly, mfs, married_filing_separately, hoh, head_of_household, qss, qualifying_surviving_spouse", "when": "filingStatus is present and not a string. {1} = filingStatus or filing_status, as sent." }, { "message": "{1} \"{2}\" is not recognised — use one of: single, mfj, married_filing_jointly, mfs, married_filing_separately, hoh, head_of_household, qss, qualifying_surviving_spouse", "when": "filingStatus is a string that is not one of the nine. {2} = the first 40 characters sent." }, { "message": "{1} must be a number (annual dollars)", "when": "An amount added in 1.1.0 (top level or in spouse) is not a number. {1} = its name, e.g. wages or spouse.pensionPublic. Since engine 1.5.0 this covers ordinaryIncome, socialSecurity and capitalGains too." }, { "message": "pensionPublicSsCovered must be true or false (was the pensionPublic service covered by Social Security?)", "when": "pensionPublicSsCovered is present, not null and not a boolean." }, { "message": "{1} must be true or false ({2})", "when": "blind, disabled, spouse.blind or spouse.disabled is present, not null and not a boolean. {1} = the field; {2} = what it asks." }, { "message": "spouse must be an object", "when": "spouse is present, not null and not an object." }, { "message": "spouse.age must be a whole number between 1 and 120", "when": "spouse.age is not a whole number from 1 to 120." }, { "message": "state is required — a two-letter code such as \"CA\", or \"DC\"", "when": "state (and state_code) absent, empty or not a string." }, { "message": "state is not one we carry — expected a US state code or \"DC\"", "when": "state is not a code the engine carries." }, { "message": "income components cannot be negative", "when": "ordinaryIncome, socialSecurity or capitalGains is negative." }, { "message": "age must be a whole number between 0 and 120", "when": "age is present, not null and not a number, or has a fraction (engine 1.5.0)." }, { "message": "age must be between 0 and 120", "when": "age is a whole number outside 0 to 120." }, { "message": "{1} must be a finite number", "when": "Any amount other than ordinaryIncome, socialSecurity and capitalGains (top level or in spouse) is not finite. {1} = its name." }, { "message": "{1} cannot be negative", "when": "Any amount other than ordinaryIncome, socialSecurity and capitalGains (top level or in spouse) is negative. {1} = its name." }, { "message": "{1} is larger than the engine accepts ($100 billion)", "when": "Any amount other than ordinaryIncome, socialSecurity and capitalGains (top level or in spouse) exceeds {{src:STJ_MAX_AMOUNT|money}}. {1} = its name. The three household totals have no upper limit." }, { "message": "socialSecurityGross must be at least socialSecurity (the federally-taxable part of the benefits)", "when": "Both are given and gross is positive but below the taxable amount." }, { "message": "out of memory", "when": "The evaluation could not allocate memory (returned as 400)." }, { "message": "bad request", "when": "Fallback when an evaluation fails without a message (not reached by the checks above)." }, { "message": "{1} must be one of: none, sepp, death, disability, other (the federal early-withdrawal exception for earlyDistributions)", "when": "earlyDistributionException (top level or spouse) is not one of the five strings. {1} = the field." }, { "message": "dependents must be an array of objects such as [{\"age\": 10}] (the people claimed as dependents; [] for none)", "when": "dependents is present and not an array." }, { "message": "dependents can list at most 20 people", "when": "dependents has more elements than the engine carries." }, { "message": "{1} must be an object such as {\"age\": 10}", "when": "An element of dependents is not an object. {1} = dependents[i]." }, { "message": "{1}.{2} is not a dependent field — allowed: age, student, disabled", "when": "A dependent carries another key. {1} = dependents[i], {2} = the key." }, { "message": "{1}.age is required: a whole number between 0 and 120 (age at the end of the year)", "when": "A dependent's age is missing, not a whole number or out of range. {1} = dependents[i]." }, { "message": "spouse.{1} is not a spouse field (the spouse's own amounts and facts only; ordinaryIncome, gains and socialSecurity are household totals at the top level)", "when": "spouse carries a key that is not a spouse field. {1} = the key." }, { "message": "on a married-filing-separately return spouse may carry only age and blind (the spouse's income is on their own return)", "when": "spouse on an mfs return carries an amount or another fact." }, { "message": "spouse is only valid with filingStatus \"mfj\" (married filing jointly), or with \"mfs\" for the spouse's age and blindness", "when": "spouse is sent with single or head of household." }, { "message": "spouse.earlyDistributions cannot exceed spouse.iraDistributions (it is the part of them taken before age 59½)", "when": "The spouse's early part is larger than the spouse's IRA distributions (no spouse.employerPlanDistributions given)." }, { "message": "spouse.socialSecurityGross is the spouse's part of socialSecurityGross, so it needs socialSecurityGross (the household total) and cannot exceed it", "when": "spouse.socialSecurityGross without the household figure, or larger than it." }, { "message": "earlyDistributions cannot exceed iraDistributions (it is the part of them taken before age 59½)", "when": "The early part is larger than the IRA distributions (no employerPlanDistributions given)." }, { "message": "spouse.earlyDistributions cannot exceed spouse.iraDistributions plus spouse.employerPlanDistributions (it is the part of them taken before age 59½)", "when": "The spouse's early part is larger than the spouse's IRA and employer-plan distributions together (spouse.employerPlanDistributions given)." }, { "message": "earlyDistributions cannot exceed iraDistributions plus employerPlanDistributions (it is the part of them taken before age 59½)", "when": "The early part is larger than the IRA and employer-plan distributions together (employerPlanDistributions given)." }, { "message": "railroadRetirementTier1 is the Tier 1 part of socialSecurityGross (Social Security and Tier 1 benefits received), so it needs socialSecurityGross and cannot exceed it", "when": "railroadRetirementTier1 without socialSecurityGross, or larger than it." }, { "message": "spouse.railroadRetirementTier1 is the spouse's part of railroadRetirementTier1 (the household total), so it needs it and cannot exceed it, nor the spouse's own socialSecurityGross", "when": "spouse.railroadRetirementTier1 without railroadRetirementTier1, larger than it, larger than spouse.socialSecurityGross, or leaving the primary filer more Tier 1 than the primary's own gross benefits." }, { "message": "localTaxRate applies only where the engine includes a county income tax (Indiana and Maryland)", "when": "localTaxRate is given for any other state." }, { "message": "localTaxRate must be a fraction between %.4f and %.4f (the lowest and highest {1} county rate, e.g. 0.0202 for 2.02%%)", "when": "localTaxRate is not finite or is outside the state's range (the two figures are the state's lowest and highest rate). {1} = the state's name." }, { "message": "federalTax (after the nonrefundable credits) cannot exceed federalTaxBeforeCredits", "when": "Both are given and federalTax is more than federalTaxBeforeCredits." }, { "message": "{1} must be a whole number between {2} and {3} ({4})", "when": "planMinimumRetirementAge or deceasedSpouseAge (top level or spouse) is present and not a whole number from 1 to 120. {1} = the field as spouse.x or x; {2}, {3} = 1, 120; {4} = what the field means." }, { "message": "{1}planMinimumRetirementAge is the minimum retirement age of the plan paying {2}disabilityIncome, so it needs {3}disabilityIncome", "when": "planMinimumRetirementAge is given without disabilityIncome at the same level. {1}-{3} = \"\" or \"spouse.\"." }, { "message": "{1}deceasedSpouseAge is the age a surviving spouse's deceased spouse would have reached, so it needs {2}survivorBenefits: true", "when": "deceasedSpouseAge is given without survivorBenefits: true at the same level. {1}, {2} = \"\" or \"spouse.\"." }, { "message": "computeFederal must be true or false (should the federal engine supply the federal inputs?)", "when": "computeFederal is present and not a boolean." }, { "message": "federalItemized needs computeFederal: true (it is the federal return's Schedule A; without computeFederal send the federal amounts themselves)", "when": "federalItemized is present (not null) and computeFederal is not true." }, { "message": "federalItemized must be an object of federal Schedule A amounts", "when": "federalItemized is present and not an object." }, { "message": "federalItemized.{1} is not a key: send saltIncomeOrSalesTax, saltRealEstateTax, saltPersonalPropertyTax, mortgageInterest, charityCash, medicalExpenses", "when": "federalItemized has another key. {1} = the key." }, { "message": "federalItemized.{1} must be a number of dollars >= 0", "when": "A federalItemized amount is not a number from 0 to 1 trillion. {1} = the key." }, { "message": "{1}selfEmploymentIncome needs computeFederal: true (the state's earned income is the net profit less half the self-employment tax, which only the federal return computes); without computeFederal, send the state earned income as wages", "when": "selfEmploymentIncome (or spouse.selfEmploymentIncome) is not 0 and computeFederal is not true. {1} = empty for the filer, spouse. for the spouse." }, { "message": "computeFederal: {1} is not modelled by the federal engine ({2}) yet: {3}. Leave computeFederal out and send federalTax, federalNiit, federalTaxBeforeCredits and federalRefundableCredits yourself.", "when": "computeFederal: true with a field the federal engine does not model. {1} = the field, {2} = the federal engine version, {3} = what it would need." }, { "message": "computeFederal needs age (the filer's age at the end of the year: the federal §72(t) additional tax, §63(f) aged amount and senior deduction read it)", "when": "computeFederal: true without age." }, { "message": "computeFederal with filingStatus mfj needs spouse.age (the spouse's §63(f) aged amount and senior deduction depend on it)", "when": "computeFederal: true on a joint return without spouse.age." }, { "message": "computeFederal computes federalTax, federalNiit, federalTaxBeforeCredits and federalRefundableCredits: leave them out, or leave computeFederal out", "when": "computeFederal: true with any of the four federal figures." }, { "message": "computeFederal computes socialSecurity (the federally taxable part) from socialSecurityGross: send the gross benefits as socialSecurityGross and leave socialSecurity out", "when": "computeFederal: true with a socialSecurity amount other than zero." }, { "message": "computeFederal: the spouse's iraDistributions or employerPlanDistributions are taxed at the spouse's own age for the §72(t) additional tax, and the spouses are on different sides of 59½; the federal engine ({1}) applies it at one age. Leave computeFederal out and send federalTax, federalNiit, federalTaxBeforeCredits and federalRefundableCredits yourself.", "when": "computeFederal: true, the spouse has IRA or plan distributions, and one spouse is under 60 at the end of the year while the other is not. {1} = the federal engine version." }, { "message": "capitalLoss is the year's net capital loss, so capitalGains and shortTermGains must be 0 with it (net the gains against the losses first)", "when": "capitalLoss above 0 with capitalGains or shortTermGains above 0." }, { "message": "capitalLossCarryover is the part of capitalLoss carried in from earlier years, so it cannot exceed capitalLoss", "when": "capitalLossCarryover above capitalLoss (including without capitalLoss)." }, { "message": "strict: not a field of this API: {1} (check the spelling, or leave strict out to ignore unknown keys)", "when": "strict is true and the request has top-level keys the API does not read. {1} = up to five of them, quoted, then \" and N more\"." }, { "message": "{1} must be a year, a whole number such as {2} (the tax year of the return)", "when": "taxYear (or tax_year) is present, not null, and not a whole number from 1 to 9999 (a string, a fraction, a boolean). {1} = taxYear, or tax_year when the request uses that spelling; {2} = 2026." }, { "message": "{1} {2} is not carried by this build (it encodes tax year {3}; later years are estimates through projection, e.g. \"projection\": {\"year\": 2040, \"inflation\": 0.025})", "when": "taxYear (or tax_year) is a whole number other than 2026, the rules year. {1} = taxYear, or tax_year when the request uses that spelling; {2} = the year; {3} = 2026. The embeddable library returns QCST_ERR_UNSUPPORTED with this message." }, { "message": "projection must be an object such as {\"year\": 2040, \"inflation\": 0.025} (the tax year to estimate and the inflation to assume)", "when": "projection is present and not an object (null means absent)." }, { "message": "projection.{1} is not a projection field — allowed: year, inflation, cpiFactor, indexing", "when": "projection carries another key. {1} = the key." }, { "message": "projection.year is required: a whole number, the tax year to estimate ({1} to {2})", "when": "projection has no year, or year is not a whole number. {1} = 2026, {2} = 2100." }, { "message": "projection needs exactly one of inflation (the annual CPI assumption, e.g. 0.025) or cpiFactor (your own cumulative CPI factor from {1} to projection.year)", "when": "projection has neither inflation nor cpiFactor, or both. {1} = 2026." }, { "message": "projection.indexing must be \"law\" (the default: each state amount the way its law moves it) or \"inflation\" (every amount QuantCalc's planner scaled before engine 1.10.0 rises with inflation)", "when": "projection.indexing is present, not null, and not \"law\" or \"inflation\" (any case)." }, { "message": "projection.year must be a whole number from {1} (the rules year) to {2}", "when": "projection.year is before 2026 or after 2100. {1} = 2026, {2} = 2100." }, { "message": "projection.inflation must be an annual rate between -0.10 and 0.25 (0.025 is 2.5 percent a year)", "when": "projection.inflation is outside -0.10 to 0.25." }, { "message": "projection.cpiFactor must be a number between 0.01 and 100 (the cumulative CPI factor from {1} to projection.year, e.g. 1.44)", "when": "projection.cpiFactor is outside 0.01 to 100. {1} = 2026." }, { "message": "projection.cpiFactor must be 1 when projection.year is {1} (the rules year itself)", "when": "projection.year is 2026 and cpiFactor is not 1. {1} = 2026." }, { "message": "projection refused: this result depends on {1}'s {2}, and how the law moves it after {3} is not established from an official source (leave projection out for {4})", "when": "A projection past 2026 whose result depends on an amount the indexing registry marks not established. {1} = the state, {2} = the engine field, {3} and {4} = 2026 (indexing \"law\" only)." }, { "message": "localities must be an array of jurisdiction codes such as [\"NY-NYC\"] (GET /api/state-tax/localities?state=XX lists them)", "when": "localities is present and not an array." }, { "message": "localities can list at most {1} jurisdictions", "when": "More than 6 entries." }, { "message": "localities[{1}].role must be \"resident\" (the household lives there) or \"work\" (a workplace)", "when": "role is not resident or work." }, { "message": "localities[{1}].wages must be a number (the wages earned there)", "when": "wages is not a number." }, { "message": "localities[{1}] must be a jurisdiction code such as \"NY-NYC\", or an object with one in `code`", "when": "An entry is neither a code string nor an object with one." }, { "message": "localities[{1}]: \"{2}\" is not a jurisdiction code the engine knows (GET /api/state-tax/localities?state={3} lists them)", "when": "The code is not in the registry." }, { "message": "localities[{1}]: {2} is in {3}, and this request is for {4}", "when": "A code of another state." }, { "message": "localities[{1}]: {2} taxes on a base the engine does not model (a grandfathered ordinance that reaches intangible income)", "when": "Wyoming or Indian Hill (Ohio)." }, { "message": "localities[{1}]: {2} taxes residents only (role \"work\" applies to the earned-income taxes of a workplace)", "when": "A workplace for a tax on residents only." }, { "message": "localities[{1}].wages applies to a workplace (role \"work\") only: a residence's tax reaches the household's whole income", "when": "wages on a residence." }, { "message": "localities[{1}]: {2} is a second residence of the same kind (one county, school district, municipality or city per return)", "when": "Two residences in one slot." }, { "message": "localities: the wages earned at workplaces exceed the household's wages", "when": "The workplaces' wages add up to more than the household's." }, { "message": "localTaxRate and a county in localities say the same thing: give one", "when": "Both given." }, { "message": "otherLocalTaxCredit is a resident's credit against a local return: it needs a residence in localities that files one", "when": "No residence with a separate local return." }, { "message": "localUnearnedIncome is the base of Philadelphia's School Income Tax: it needs localities [\"PA-PSD-510101\"]", "when": "No Philadelphia residence." }, { "message": "{1} needs localities (the jurisdictions it is about)", "when": "otherLocalTaxCredit or localUnearnedIncome without localities." }, { "message": "rentIncludesHeat describes rentPaid: give the rent too", "when": "rentIncludesHeat without a positive rentPaid." }, { "message": "residency must be an object: {\"status\": \"partYear\" or \"nonresident\", \"residentFrom\", \"residentTo\", \"stateIncome\": {...}}", "when": "residency is present and not an object." }, { "message": "residency.status is required: \"resident\", \"partYear\" or \"nonresident\"", "when": "residency.status is absent or another value." }, { "message": "a part-year or nonresident return is not modelled with {1}; leave them out or drop residency", "when": "An input the residency rules do not take. {1} = the inputs." }, { "message": "Washington's capital gains excise for a part-year resident or nonresident is not modelled", "when": "WA with residency and capital gains." }, { "message": "residency.stateIncome.{1} is more than the year's {2}: the state's part is a part of the whole", "when": "A stateIncome amount above the year's amount of the same key. {1}, {2} = the key." }, { "message": "a nonresident's retirement income is not taxable by the state: \"No State may impose an income tax on any retirement income of an individual who is not a resident or domiciliary of such State\" (4 U.S.C. 114(a)); stateIncome retirement amounts must be 0", "when": "A nonresident's stateIncome with IRA, pension or conversion amounts." }, { "message": "Social Security received while a nonresident is not income from the state's sources; stateIncome.socialSecurity and socialSecurityGross must be 0 on a nonresident return", "when": "A nonresident's stateIncome with Social Security." }, { "message": "{1}'s part-year / nonresident instructions do not say how to apportion when the whole-year income is zero or less and the {2} income is not; not computed", "when": "The whole-year income measure is zero or less, the state's is not, there is tax to apportion, and the state's instructions are silent. {1}, {2} = the state." }, { "message": "{1}{2} must be a date of {3} written YYYY-MM-DD", "when": "A date of residency or residency.spouse is not a date of the tax year. {1} = residency. or residency.spouse., {2} = the key, {3} = the tax year." }, { "message": "{1}stateIncome must be an object of amounts (the income the state taxes)", "when": "residency.stateIncome or residency.spouse.stateIncome is not an object. {1} = the prefix." }, { "message": "{1}stateIncome.{2} is not an amount the residency rules take — allowed: wages, ordinaryIncome, shortTermGains, capitalGains, capitalLoss, iraDistributions, pensionPrivate, pensionPublic, rothConversion, socialSecurity, socialSecurityGross", "when": "A stateIncome object has another key. {1} = the prefix, {2} = the key." }, { "message": "residency.{1} is not a residency field — allowed: status, residentFrom, residentTo, stateIncome, spouse, spouseShare, election", "when": "residency has another key. {1} = the key." }, { "message": "residency.spouse must be an object: the spouse's own {\"status\", \"residentFrom\", \"residentTo\", \"stateIncome\"}", "when": "Engine 1.13.0: residency.spouse is present and not an object." }, { "message": "residency.spouse.{1} is not a residency field — allowed: status, residentFrom, residentTo, stateIncome", "when": "residency.spouse has another key. {1} = the key." }, { "message": "residency.spouse.status is required: \"resident\", \"partYear\" or \"nonresident\"", "when": "residency.spouse.status is absent or another value." }, { "message": "residency.spouseShare must be an object of amounts (the spouse's part of the household amounts)", "when": "residency.spouseShare is present and not an object." }, { "message": "residency.spouseShare.{1} is not a household amount — allowed: ordinaryIncome, shortTermGains, capitalGains, capitalLoss, capitalLossCarryover, socialSecurity", "when": "residency.spouseShare has another key. {1} = the key." }, { "message": "residency.election must be \"joint\", \"separate\" or \"jointAsResidents\"", "when": "residency.election is another value or not a string." }, { "message": "localities[{1}] needs both residentFrom and residentTo (the period lived there)", "when": "Engine 1.13.0: a localities object has one of the two dates." }, { "message": "localities[{1}].residentIncome must be an object of amounts (the income received while living there)", "when": "localities[].residentIncome is not an object." }, { "message": "localities[{1}].residentIncome.{2} is not an amount the local rules take — allowed: the keys of residency.stateIncome", "when": "localities[].residentIncome has another key." }, { "message": "{1}residentFrom, residentTo and stateIncome apply to a part-year or nonresident return; a full-year resident gives only status", "when": "status resident with dates or stateIncome (residency or, engine 1.13.0, residency.spouse). {1} = the prefix." }, { "message": "a part-year return needs {1}residentFrom and {2}residentTo (the resident period, YYYY-MM-DD)", "when": "status partYear without both dates. {1}, {2} = the prefix." }, { "message": "{1}residentFrom / residentTo apply to a part-year return only", "when": "status nonresident with dates. {1} = the prefix." }, { "message": "{1}residentFrom is after residentTo", "when": "The resident period ends before it starts. {1} = the prefix." }, { "message": "residency.spouse is for a married couple filing jointly: it needs filingStatus \"mfj\" and the spouse object (each spouse's own amounts)", "when": "Engine 1.13.0: residency.spouse on a request that is not mfj, or without the spouse object." }, { "message": "residency.spouseShare.{1} is more than the household's {2}", "when": "A spouse's part exceeds the household amount. {1}, {2} = the key." }, { "message": "residency.spouseShare.{1} is needed: the spouses' residency differs, so the state taxes each spouse's own part of the household's {2} (give the spouse's part; 0 = all the primary's)", "when": "Engine 1.13.0: a household amount is not 0 and the couple's request does not split it." }, { "message": "spouse.socialSecurityGross is needed: the spouses' residency differs, so each spouse's own benefits count (give the spouse's part of socialSecurityGross)", "when": "Engine 1.13.0: socialSecurityGross is not 0 and the spouse object does not give the spouse's part." }, { "message": "{1}{2} is more than the {3} own {4}: the state's part is a part of the whole", "when": "Engine 1.13.0: a spouse's stateIncome amount exceeds that spouse's own amount. {1} = the prefix, {2}, {4} = the key, {3} = primary's or spouse's." }, { "message": "a nonresident's retirement income is not taxable by the state: \"No State may impose an income tax on any retirement income of an individual who is not a resident or domiciliary of such State\" (4 U.S.C. 114(a)); {1} retirement amounts must be 0", "when": "Engine 1.13.0: a nonresident spouse's stateIncome has retirement amounts. {1} = the prefix." }, { "message": "Social Security received while a nonresident is not income from the state's sources; {1}socialSecurity and socialSecurityGross must be 0 on a nonresident's part", "when": "Engine 1.13.0: a nonresident spouse's stateIncome has Social Security. {1} = the prefix." }, { "message": "{1}'s instructions do not say how a married couple files when {2}; not computed (drop residency.spouse to compute each return yourself)", "when": "Engine 1.13.0: the state's instructions do not address the couple's pair (the sourced list on the state's page). {1} = the state, {2} = the pair." }, { "message": "residency.election \"{1}\" is not open to this couple in {2}: {3}", "when": "Engine 1.13.0: the state does not allow the elected treatment for the pair. {1} = the election, {2} = the state, {3} = its rule." }, { "message": "localities[{1}]: residentFrom, residentTo and residentIncome describe a residence (role \"resident\"), not a workplace", "when": "Engine 1.13.0: a workplace with a period or residentIncome." }, { "message": "localities[{1}]: a part-year Yonkers resident's nonresident earnings tax prorates the exclusion by the months of residence (Form Y-203), a table the engine does not carry: not modelled", "when": "Engine 1.13.0: a Yonkers workplace beside a part-year Yonkers residence." }, { "message": "localities[{1}].residentFrom is after residentTo", "when": "Engine 1.13.0: a locality's period ends before it starts." }, { "message": "localities[{1}]: {2} follows the {3} of residence on {4}: give that one, without residentFrom / residentTo", "when": "Engine 1.13.0: a county or Iowa school district with a period. {2} = the locality, {3} = county or school district, {4} = the day." }, { "message": "localities[{1}]: {2}", "when": "Engine 1.13.0: a county or Iowa school district on a nonresident return (Maryland's special nonresident tax; Indiana's county of principal work, Schedule CT-40PNR Section 2; no Iowa school district). {2} = the reason." }, { "message": "localities[{1}]: {2}: {3}", "when": "Engine 1.13.0: on a part-year return, an Indiana county without January 1 residence, or an Iowa school district with the resident period ending before December 31. {2} = the locality, {3} = the reason." }, { "message": "localities[{1}]: a nonresident of the state does not live in {2} (a workplace is role \"work\"{3})", "when": "Engine 1.13.0: a resident locality on a nonresident return. {2} = the locality, {3} = NYC's note." }, { "message": "localities[{1}]: the period lived in {2} must lie inside the state resident period", "when": "Engine 1.13.0: a locality's period outside a part-year return's resident period." }, { "message": "localities[{1}].residentIncome applies to a part-year resident of {2} (a full-year resident's base is the whole year's income)", "when": "Engine 1.13.0: residentIncome for a locality lived in all year." }, { "message": "localities[{1}]: a part-year resident of {2} is not modelled: {3}", "when": "Engine 1.13.0: a part-year resident of a locality whose part-year rule is not settled (engine 1.14.0: Michigan cities, Louisville Metro, Wilmington; Philadelphia's and Kansas City / St. Louis's with net profits; Kansas City / St. Louis on a joint request with both spouses' wages). {3} = the reason." }, { "message": "localities[{1}].residentIncome is needed: a part-year resident of {2} is taxed on the income received while living there", "when": "Engine 1.13.0: a part-year resident of NYC, Yonkers or an Ohio school district without residentIncome." }, { "message": "localities[{1}].residentIncome.{2} is more than the year's {3}", "when": "Engine 1.13.0: a residentIncome amount exceeds the year's." }, { "message": "residency.spouseShare and residency.election are about a married couple whose residency differs: they need residency.spouse (the spouse's own residency)", "when": "Engine 1.13.0: spouseShare or election without residency.spouse." }, { "message": "rentalNetIncome must be a finite number between -$100 billion and $100 billion", "when": "rentalNetIncome not finite, or beyond the limit either way." }, { "message": "rentalNetIncome is not supported with residency (a part-year or nonresident return): the state-source part of a rental is not modelled; send it as stateIncome.ordinaryIncome (income only)", "when": "rentalNetIncome not 0 with residency." }, { "message": "inStateMunicipalInterest and outOfStateMunicipalInterest are parts of taxExemptInterest, so together they cannot exceed it (or leave taxExemptInterest out: it is then their sum)", "when": "taxExemptInterest given, and the parts given exceed it by more than half a cent." }, { "message": "usObligationInterest is a part of ordinaryIncome (it is federally taxable interest), so it cannot exceed ordinaryIncome", "when": "usObligationInterest above ordinaryIncome." }, { "message": "{1} is the retirement income received before reaching 59 1/2 in the year the person reaches it: it needs an age of 59 or 60", "when": "Given for a person whose age is under 59 or over 60. {1} = the field." }, { "message": "{1} cannot exceed the person's iraDistributions, employerPlanDistributions and pensionPrivate", "when": "Above the person's IRA, employer-plan and private pension income. {1} = the field." }, { "message": "computeFederal computes federalEarnedIncomeCredits (the federal return's earned income credit): leave it out, or leave computeFederal out", "when": "federalEarnedIncomeCredits with computeFederal." }, { "message": "localities[{1}]: rentalNetIncome is not supported for a part-year resident of {2} (the resident period's share of a rental is not modelled)", "when": "rentalNetIncome not 0 with a locality lived in for part of the year. {1} = the index, {2} = the locality's name." }, { "message": "localities[{1}].{2} is not a locality field — allowed: code, role, wages, residentFrom, residentTo, residentIncome, daysOutside, workDays", "when": "A localities object has another key. {1} = the index, {2} = the key." }, { "message": "{1}: {2}; not computed{3}", "when": "Engine 1.13.0: the treatment that applies to the couple is one the engine does not compute. {1} = the state's rule, {2} = why, {3} (engine 1.14.0) = the election that computes another option the couple may take, when one was computed." }, { "message": "localities[{1}].daysOutside and workDays apply to a part-year resident of Kansas City or St. Louis (their non-residency deduction formula), with residentFrom / residentTo", "when": "Engine 1.14.0: the formula days on another locality, a workplace, or a full-year residence." }, { "message": "localities[{1}].daysOutside is needed: a part-year resident of {2} deducts the wages x the days {3} / the work days", "when": "Engine 1.14.0: a part-year Kansas City or St. Louis resident without daysOutside. {3} = the city's own day rule." }, { "message": "localities[{1}].workDays does not apply to Kansas City: Form RD-109NR line 1 says \"Enter 260 for days worked everywhere.\"", "when": "Engine 1.14.0: workDays on a Kansas City residence." }, { "message": "localities[{1}].daysOutside ({2}) is more than the work days ({3})", "when": "Engine 1.14.0: the deducted days exceed the work days." }, { "message": "localities[{1}].residentIncome does not apply to {2}: {3}", "when": "Engine 1.13.0: residentIncome for a locality whose part-year rule takes the period instead (a PA EIT subdivision's months; engine 1.14.0: an Ohio traditional-base district's residency factor, Kansas City / St. Louis's day formula). {3} = the rule." }, { "message": "localities[{1}].daysOutside and workDays apply to a part-year resident of {2} (a full-year resident's wages are all taxed)", "when": "Engine 1.14.0: the formula days on a whole-year residence. {2} = the city." }, { "message": "{1}qualifiedTips and {2}qualifiedOvertime are parts of {3}wages (tips received as an employee and the overtime premium) and together cannot exceed them", "when": "A person's qualifiedTips plus qualifiedOvertime is more than their wages. {1}-{3} = \"\" or \"spouse.\"." }, { "message": "qualifiedTips, qualifiedOvertime, qualifiedCarLoanInterest and charityCash are taken on a full-year resident return only (the states divide them by their own part-year rules); leave them out with residency", "when": "Any of them other than 0 with residency." } ] }, "response": { "type": "object", "properties": { "state": { "type": "string", "description": "The jurisdiction's code." }, "stateName": { "type": "string", "description": "The jurisdiction's name." }, "tax": { "type": "number", "description": "State income tax for the year, unrounded; in Indiana and Maryland it includes the county tax (rules.localTax)." }, "filingStatusUsed": { "type": "string", "description": "State engine 1.16: on a joint request (resident) in Arkansas or Delaware, the status the return was figured on: mfj, or the form's filing status 4 when it gives the lower tax, as the instructions recommend: separateOnSameReturn (Arkansas, married filing separately on the same return) or combinedSeparate (Delaware, combined separate; the columns are in breakdown.combinedSeparateReturn). Absent elsewhere." }, "effectiveRate": { "type": "number", "description": "tax divided by the sum of every income amount supplied; 0 when that sum is 0." }, "totalTax": { "type": "number", "description": "tax plus the separate local returns (local.separateReturnsTax): every income tax the request's state and localities levy on the household for the year." }, "refundableCredits": { "type": "object", "description": "The state credits paid beyond the tax (tax is before them): earned income, property-tax, renter, grocery and senior credits.", "properties": { "total": { "type": "number", "description": "Their total." }, "items": { "type": "array", "description": "One entry per credit: id, name, form, amount, valueYear (the year of the amounts used: 2025 where the 2026 figures are not published).", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The credit's id." }, "amount": { "type": "number", "description": "The credit." } } } }, "projection": { "type": "string", "description": "Only with a projection beyond the rules year: the refundable credits are not projected (each uses the amounts of its valueYear)." } } }, "netTax": { "type": "number", "description": "totalTax less refundableCredits.total; negative when the refundable credits exceed every tax." }, "input": { "type": "object", "description": "The request as the engine read it.", "properties": { "filingStatus": { "type": "string", "description": "single, mfj, mfs, hoh or qss." }, "age": { "type": "number", "description": "The primary filer's age as used (0 when not supplied)." }, "ordinaryIncome": { "type": "number", "description": "As read (0 when absent or not a number)." }, "socialSecurity": { "type": "number", "description": "As read." }, "capitalGains": { "type": "number", "description": "As read." }, "wages": { "type": "number", "description": "Only when supplied." }, "iraDistributions": { "type": "number", "description": "Only when supplied." }, "pensionPrivate": { "type": "number", "description": "Only when supplied." }, "pensionPublic": { "type": "number", "description": "Only when supplied." }, "pensionMilitary": { "type": "number", "description": "Only when supplied." }, "rothConversion": { "type": "number", "description": "Only when supplied." }, "shortTermGains": { "type": "number", "description": "Only when supplied." }, "socialSecurityGross": { "type": "number", "description": "Only when supplied." }, "federalTax": { "type": "number", "description": "Only when supplied." }, "federalNiit": { "type": "number", "description": "Only when supplied." }, "pensionPublicSsCovered": { "type": "boolean", "description": "Only when supplied." }, "blind": { "type": "boolean", "description": "Only when supplied." }, "disabled": { "type": "boolean", "description": "Only when supplied." }, "spouse": { "type": "object", "description": "Only with a spouse object: the spouse's amounts as read.", "properties": { "age": { "type": "number", "description": "The spouse's age actually used (the primary filer's when spouse.age was absent)." }, "wages": { "type": "number", "description": "As read (0 when absent)." }, "iraDistributions": { "type": "number", "description": "As read." }, "pensionPrivate": { "type": "number", "description": "As read." }, "pensionPublic": { "type": "number", "description": "As read." }, "pensionMilitary": { "type": "number", "description": "As read." }, "rothConversion": { "type": "number", "description": "As read." }, "blind": { "type": "boolean", "description": "Only when supplied." }, "disabled": { "type": "boolean", "description": "Only when supplied." }, "railroadRetirementTier2": { "type": "number", "description": "As read, when given." }, "railroadRetirementTier1": { "type": "number", "description": "As read, when given." }, "employerPlanDistributions": { "type": "number", "description": "As read, when given." }, "planMinimumRetirementAge": { "type": "integer", "description": "Only when supplied (joint returns)." }, "deceasedSpouseAge": { "type": "integer", "description": "Only when supplied (joint returns)." }, "socialSecuritySurvivor": { "type": "boolean", "description": "As read, when given (joint returns)." }, "selfEmploymentIncome": { "type": "number", "description": "As read, when given." }, "qualifiedTips": { "type": "number", "description": "As read, when given." }, "qualifiedOvertime": { "type": "number", "description": "As read, when given." }, "domicileYears": { "type": "integer", "description": "As read, when given." } } }, "dependents": { "type": "array", "description": "The dependents as read (each with age, student and disabled), when given.", "items": { "type": "object", "properties": { "student": { "type": "boolean", "description": "As read (false when absent)." } } } }, "pensionFederalCivilService": { "type": "number", "description": "As read, when given." }, "disabilityIncome": { "type": "number", "description": "As read, when given." }, "earlyDistributions": { "type": "number", "description": "As read, when given." }, "earlyDistributionException": { "type": "string", "description": "As read, when given." }, "iraBasis": { "type": "number", "description": "As read, when given." }, "survivorBenefits": { "type": "boolean", "description": "As read, when given." }, "socialSecurityDisability": { "type": "boolean", "description": "As read, when given." }, "priorHohQualifyingPersonDied": { "type": "boolean", "description": "As read, when given." }, "railroadRetirementTier2": { "type": "number", "description": "As read, when given." }, "railroadRetirementTier1": { "type": "number", "description": "As read, when given." }, "employerPlanDistributions": { "type": "number", "description": "As read, when given." }, "qualifiedDividends": { "type": "number", "description": "As read, when given." }, "localTaxRate": { "type": "number", "description": "As read, when given." }, "localities": { "type": "array", "description": "Only when supplied: each locality as read, {code, role, wages (a workplace)}.", "items": { "type": "object", "properties": {} } }, "otherLocalTaxCredit": { "type": "number", "description": "Only when supplied." }, "localUnearnedIncome": { "type": "number", "description": "Only when supplied." }, "propertyTaxPaid": { "type": [ "number", "boolean" ], "description": "Only when supplied." }, "rentPaid": { "type": [ "number", "boolean" ], "description": "Only when supplied." }, "rentIncludesHeat": { "type": [ "number", "boolean" ], "description": "Only when supplied." }, "homeValue": { "type": [ "number", "boolean" ], "description": "Only when supplied." }, "taxExemptInterest": { "type": [ "number", "boolean" ], "description": "Only when supplied." }, "medicalExpenses": { "type": [ "number", "boolean" ], "description": "Only when supplied." }, "inStateMunicipalInterest": { "type": "number", "description": "inStateMunicipalInterest as given; present only when given (state engine 1.16)." }, "outOfStateMunicipalInterest": { "type": "number", "description": "outOfStateMunicipalInterest as given; present only when given (state engine 1.16)." }, "usObligationInterest": { "type": "number", "description": "usObligationInterest as given; present only when given (state engine 1.16)." }, "militaryServiceYears": { "type": [ "number", "boolean" ], "description": "militaryServiceYears as given; present only when given (state engine 1.16)." }, "militaryMedicalRetirement": { "type": [ "number", "boolean" ], "description": "militaryMedicalRetirement as given; present only when given (state engine 1.16)." }, "veteran": { "type": [ "number", "boolean" ], "description": "veteran as given; present only when given (state engine 1.16)." }, "retirementIncomeBefore59Half": { "type": [ "number", "boolean" ], "description": "retirementIncomeBefore59Half as given; present only when given (state engine 1.16)." }, "federalTaxBeforeCredits": { "type": "number", "description": "Only when supplied." }, "planMinimumRetirementAge": { "type": "integer", "description": "Only when supplied." }, "deceasedSpouseAge": { "type": "integer", "description": "Only when supplied." }, "socialSecuritySurvivor": { "type": "boolean", "description": "As read, when given." }, "federalRefundableCredits": { "type": "number", "description": "Only when supplied." }, "capitalLoss": { "type": "number", "description": "As read, when given." }, "capitalLossCarryover": { "type": "number", "description": "As read, when given." }, "selfEmploymentIncome": { "type": "number", "description": "As read, when given." }, "residency": { "type": "object", "description": "Only when supplied: the status, the resident period as days of the year (residentFromDay, residentToDay) and stateIncome as read.", "properties": { "status": { "type": "string", "description": "As read." }, "residentFromDay": { "type": "integer", "description": "residentFrom as a day of the tax year (1-365), when given." }, "residentToDay": { "type": "integer", "description": "residentTo as a day of the tax year, when given." }, "stateIncome": { "type": "object", "description": "The stateIncome amounts as read.", "properties": {} }, "spouse": { "type": "object", "description": "Only when supplied: the spouse's status, resident period (residentFromDay, residentToDay) and stateIncome as read.", "properties": {} }, "spouseShare": { "type": "object", "description": "Only when supplied: the spouse's parts of the household amounts as read.", "properties": {} }, "election": { "type": "string", "description": "Only when supplied: the election as read." } } }, "rentalNetIncome": { "type": "number", "description": "As read, when given." }, "qualifiedTips": { "type": "number", "description": "As read, when given." }, "qualifiedOvertime": { "type": "number", "description": "As read, when given." }, "qualifiedCarLoanInterest": { "type": "number", "description": "As read, when given." }, "charityCash": { "type": "number", "description": "As read, when given." }, "domicileYears": { "type": "integer", "description": "As read, when given." } } }, "rules": { "type": "object", "description": "The state's parameters as the engine applied them to this request: the bracket count, deductions, exemptions, senior subtraction and exclusion cap of its filing status (a qualifying surviving spouse: of the status the state taxes it as); partialCap and the income limits, which have only a joint and a single value, show the joint one for mfj and the single one otherwise. With the sources of each rule family that bears on the request.", "properties": { "taxesSocialSecurity": { "type": "boolean", "description": "Whether the state taxes any Social Security." }, "socialSecurityRule": { "type": "string", "description": "The Social Security rule (values below)." }, "bracketCount": { "type": "number", "description": "Brackets in the joint schedule (mfj) or the single schedule (other statuses)." }, "standardDeduction": { "type": "number", "description": "The joint (mfj) or single standard deduction, before 65+ additions and phase-outs." }, "personalExemption": { "type": "number", "description": "The joint (mfj) or single flat personal exemption (0 where the exemption is set by income tiers)." }, "seniorSubtraction": { "type": "number", "description": "The joint (mfj) or single age subtraction." }, "seniorSubtractionMinAge": { "type": "number", "description": "Its age (0 = none)." }, "capitalGainsTaxedAsOrdinary": { "type": "boolean", "description": "Whether long-term gains enter the base." }, "capitalGainsInclusionRatio": { "type": "number", "description": "The share of net long-term gain that enters the base (1 = all)." }, "retirementIncomeExclusion": { "type": "object", "description": "The capped retirement exclusion.", "properties": { "cap": { "type": "number", "description": "Joint (mfj) or single cap at the full age." }, "minAge": { "type": "number", "description": "Age for the full cap or the full exclusion." }, "partialCap": { "type": "number", "description": "Lower cap for the younger band." }, "partialMinAge": { "type": "number", "description": "Age for the lower cap (0 = none)." }, "incomeLimit": { "type": "number", "description": "Income limit (0 = none)." }, "reducedBySocialSecurity": { "type": "boolean", "description": "Whether the cap is reduced by Social Security received." } } }, "militaryRetirement": { "type": "object", "description": "The military retirement rule (treatments below). A field that does not apply is null.", "properties": { "treatment": { "type": "string", "description": "The treatment (values below)." }, "cap": { "type": [ "number", "null" ], "description": "Per-taxpayer cap; null = no dollar cap." }, "minAge": { "type": "number", "description": "Age splitting the two tiers (0 = one tier)." }, "capBelowMinAge": { "type": [ "number", "null" ], "description": "Cap below that age." }, "percentExempt": { "type": [ "number", "null" ], "description": "Share exempt (percentage rule)." }, "incomeLimit": { "type": [ "number", "null" ], "description": "Income limit (joint for mfj)." }, "incomeLimitPhaseoutRange": { "type": [ "number", "null" ], "description": "Phase-out width above the limit (null = a cliff)." }, "sharesGeneralExclusion": { "type": "boolean", "description": "Whether unexempted military pay counts as pension income for the general exclusion." }, "earnedIncomeBonus": { "type": [ "number", "null" ], "description": "Extra amount below the age split when own earned income exceeds the threshold." }, "earnedIncomeThreshold": { "type": [ "number", "null" ], "description": "That threshold." }, "reducedBySocialSecurity": { "type": "boolean", "description": "Whether the cap is reduced by the taxpayer's Social Security." }, "creditRate": { "type": [ "number", "null" ], "description": "Credit rate (credit treatment)." }, "perTaxpayer": { "type": "boolean", "description": "Always true: the rule is applied per taxpayer." } } }, "wages": { "type": "object", "description": "The earned-income rule.", "properties": { "treatment": { "type": "string", "description": "ordinary_income, earned_income_counts_toward_retirement_exclusion or no_income_tax." }, "earnedIncomeInRetirementExclusion": { "type": [ "number", "null" ], "description": "Earned income per taxpayer that counts toward the retirement exclusion." } } }, "localTax": { "type": "object", "description": "The county tax included in tax.", "properties": { "included": { "type": "boolean", "description": "Whether a county tax is included." }, "rate": { "type": [ "number", "null" ], "description": "The county rate applied (localTaxRate when given)." }, "basis": { "type": "string", "description": "How the rate was chosen (the population-weighted average, or the county rate given in localTaxRate), or none." } } }, "sources": { "type": "object", "description": "Omitted with includeSources: false. The official sources of each rule family that bears on this request, keyed by family (the anchor of that section on stateDocs, e.g. stateDocs#social_security): rates, deductions and, where the state has them, local_tax, federal_interaction, surtax and no_income_tax always; social_security with socialSecurity or socialSecurityGross; retirement_income with any pension, IRA, employer-plan, disability or Tier 2 amount; public_pension with pensionPublic or pensionFederalCivilService; military_retirement with pensionMilitary; wages with wages; roth_conversion with rothConversion; capital_gains with either gain or qualifiedDividends; senior with an age; blind_disability with blind, disabled, disabilityIncome, socialSecurityDisability true or a disabled dependent. Each value is an array of sources.", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The source document (an Internet Archive copy of the official URL where the state site refuses our checker; the title says so)." }, "title": { "type": "string", "description": "Its title." }, "kind": { "type": "string", "description": "statute, instructions, agency_page, legislation, federal, regulation (official), or form, worksheet, publication, guidance, advisory, secondary." }, "official": { "type": "boolean", "description": "The kind counts as an official source (the docs' definition: statute, instructions, agency_page, legislation, federal, regulation)." }, "quote": { "type": "string", "description": "A phrase or figure exactly as the source prints it, confirmed on the fetched document (the first of the source's verified claims; GET /api/state-tax/rules lists them all, each with the engine value it supports)." }, "checked": { "type": "string", "description": "The date (YYYY-MM-DD) the quote was last confirmed on the source." } } } } }, "unsourced": { "type": "object", "description": "Omitted with includeSources: false. Family → the reason it has no official source, for each family in rules.sources without one (the verification page lists every such family); {} when every family is sourced.", "properties": {} } } }, "priorYearFigures": { "type": "array", "description": "Every tax parameter this result used that is a prior-year figure (the state has not published the 2026 one), one entry per parameter; empty when none. A refundable credit's amounts are not listed here: each credit gives the year of its amounts in refundableCredits.items[].valueYear.", "items": { "type": "object", "properties": { "parameter": { "type": "string", "description": "The configuration parameter (as in GET /api/state-tax/rules)." }, "rule": { "type": "string", "description": "The indexing-registry rule that sources it." }, "valueYear": { "type": "number", "description": "The year the figure is from (2025)." }, "value": { "type": [ "number", "array" ], "description": "The figure used (a bracket table as rows)." }, "why": { "type": "string", "description": "Why a prior-year figure is used." } } } }, "local": { "type": "object", "description": "The local income taxes of this result.", "properties": { "onStateReturn": { "type": "array", "description": "Lines of the state return (included in tax): a county (Indiana, Maryland; without a county code the average-rate county tax), NYC, Yonkers, an Iowa school district.", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "The jurisdiction's code (null for the average-rate county tax)." }, "name": { "type": "string", "description": "The jurisdiction." }, "kind": { "type": "string", "description": "The local tax (a kind of research/data/state-tax-localities.json)." }, "role": { "type": "string", "description": "resident or work." }, "form": { "type": "string", "description": "Where it is filed." }, "base": { "type": "number", "description": "The base the rate applied to." }, "rate": { "type": "number", "description": "The rate (the first bracket's, for a bracketed tax; a share of the state tax for Yonkers and Iowa). In a projected result, the projected year's rate (engine 1.12.1)." }, "grossTax": { "type": "number", "description": "The tax before the local credits." }, "credits": { "type": "number", "description": "The local credits applied (at most grossTax)." }, "tax": { "type": "number", "description": "grossTax less credits." }, "valueYear": { "type": "number", "description": "The year the jurisdiction's rate is from (an earlier year where the 2026 one is not published)." }, "rateSource": { "type": "string", "description": "Only for a rate whose one source is another city's published table." }, "netProfitsBase": { "type": "number", "description": "Only for a net profits tax (Philadelphia, engine 1.12.1): the part of base that is self-employment income, taxed at netProfitsRate instead of rate." }, "netProfitsRate": { "type": "number", "description": "Only with netProfitsBase: the tax year's net profits tax rate." }, "partYear": { "type": "object", "description": "Engine 1.13.0, only for a part-year resident of the locality: residentFrom, residentTo, months (full months: more than half a month counts), proration (the factor the kind's part-year rule applied: NYC the household credit's months / 12, Yonkers the income percentage, PA EIT months / 12) and method (the form lines).", "properties": { "residentFrom": { "type": "string", "description": "The first day lived there." }, "residentTo": { "type": "string", "description": "The last day lived there." }, "months": { "type": "integer", "description": "Full months lived there (more than half a month counts)." }, "proration": { "type": "number", "description": "The factor the part-year rule applied." }, "method": { "type": "string", "description": "The form lines the part-year line follows." } } } } } }, "separateReturns": { "type": "array", "description": "Local returns filed apart from the state's (included in totalTax only).", "items": { "type": "object", "properties": { "partYear": { "type": "object", "description": "The same, for a separate local return (PA EIT, an Ohio school district).", "properties": {} } } } }, "separateReturnsTax": { "type": "number", "description": "Their total." }, "total": { "type": "number", "description": "Every local tax in this result." } } }, "taxYear": { "type": "string", "description": "The tax year the rules are for." }, "methodology": { "type": "string", "description": "This reference." }, "note": { "type": "string", "description": "What tax includes, in words." }, "perPerson": { "type": "array", "description": "Every response. With spouse on a joint return: the primary filer, then the spouse when the per-person model ran (spouse.age, or the primary's age, given). Otherwise one entry: role household on a joint return without spouse (the couple on one line), primary for every other return.", "items": { "type": "object", "properties": { "role": { "type": "string", "description": "primary, spouse or household." }, "age": { "type": "number", "description": "The age the rules used." }, "militaryPay": { "type": "number", "description": "Military pay attributed to the person." }, "militaryExcluded": { "type": "number", "description": "Military pay excluded by the military rule." }, "militaryRule": { "type": "string", "description": "The military treatment (values below)." }, "retirementExcluded": { "type": "number", "description": "Retirement income excluded (distributions, pooled conversions and gains, public and employer pensions, non-covered pension)." }, "retirementRule": { "type": "string", "description": "The retirement rule (values below)." }, "earnedIncomeExcluded": { "type": "number", "description": "Wages inside a retirement exclusion." }, "seniorSubtraction": { "type": "number", "description": "Age subtraction, age deduction and low-income age exemption." }, "seniorRule": { "type": "string", "description": "age_deduction_any_income, senior_subtraction or none." } } } }, "breakdown": { "type": "object", "description": "Household totals from the engine's detail record.", "properties": { "taxableIncome": { "type": "number", "description": "State taxable income (0 when negative)." }, "socialSecurityInBase": { "type": "number", "description": "Social Security entering the base." }, "retirementInBase": { "type": "number", "description": "Retirement income entering the base (including pooled conversions and gains in pool states)." }, "conversionInBase": { "type": "number", "description": "Conversion entering the base separately." }, "capitalGainsInBase": { "type": "number", "description": "Long-term gain entering the base separately." }, "capitalLossDeduction": { "type": "number", "description": "The net capital loss the state let reduce other income (inside federal taxable income where the state starts there). Present only when capitalLoss is given." }, "militaryExcluded": { "type": "number", "description": "Military pay excluded." }, "retirementExcluded": { "type": "number", "description": "Retirement income excluded." }, "earnedIncomeExcluded": { "type": "number", "description": "Wages inside a retirement exclusion." }, "seniorSubtraction": { "type": "number", "description": "Age subtractions and deductions." }, "militaryCredit": { "type": "number", "description": "Military retirement credit (before the credit floor)." }, "combinedSeparateReturn": { "type": "object", "description": "Present only when two separate columns on one form (Delaware filing status 4) cost less than the joint return; tax is then their sum and the other breakdown lines are the joint return's.", "properties": { "jointTax": { "type": "number", "description": "The joint return's tax." }, "filerTax": { "type": "number", "description": "The filer's column." }, "spouseTax": { "type": "number", "description": "The spouse's column." } } }, "railroadExcluded": { "type": "number", "description": "Railroad Retirement benefits kept out of the base: Tier 2 and the taxable share of Tier 1. Present only when railroadRetirementTier2 or railroadRetirementTier1 is given." }, "qualifiedDividendsExcluded": { "type": "number", "description": "Qualified dividends excluded by the state (0 where it has no exclusion). Present only when qualifiedDividends is given." }, "rentalLossDeduction": { "type": "number", "description": "The rental loss the state let reduce other income (0 in PA and NJ). Present only when rentalNetIncome is given." }, "interestAddition": { "type": "number", "description": "The federally tax-exempt interest the state added to its income: the out-of-state part (outOfStateMunicipalInterest) where the state taxes other states' obligations, and the in-state part where it taxes its own. Present only when the interest split is given." }, "usObligationSubtraction": { "type": "number", "description": "The interest on U.S. obligations (usObligationInterest) the state took out of its income. Present only when the interest split is given." } } }, "stateDocs": { "type": "string", "description": "This state's documentation page." }, "engineVersion": { "type": "string", "description": "The engine release." }, "error": { "type": "string", "description": "400 responses only: the message (listed below)." }, "federal": { "type": "object", "description": "The federal return computeFederal built (present only with computeFederal: true).", "properties": { "engineVersion": { "type": "string", "description": "The federal engine version." }, "taxYear": { "type": "integer", "description": "The federal tax year (the engine's parameters)." }, "inputs": { "type": "object", "description": "The federal return's inputs, mapped from the request (the federal API's field names).", "properties": { "filingStatus": { "type": "string", "description": "single, mfj, mfs, hoh or qss." }, "age": { "type": "integer", "description": "The primary filer's age." }, "spouseAge": { "type": "integer", "description": "The spouse's age (joint returns)." }, "blindCount": { "type": "integer", "description": "How many are blind (the filer, and the spouse on a joint return): present only when 1 or 2." }, "iraDistributions": { "type": "number", "description": "iraDistributions plus employerPlanDistributions, both spouses." }, "rothConversion": { "type": "number", "description": "rothConversion, both spouses." }, "pension": { "type": "number", "description": "Private, public, military and federal civil service pensions and Railroad Retirement Tier 2, both spouses." }, "shortTermGains": { "type": "number", "description": "shortTermGains." }, "longTermGains": { "type": "number", "description": "capitalGains; with capitalLoss, minus (capitalLoss less capitalLossCarryover): the year's own net loss, on Schedule D line 15." }, "capitalLossCarryoverLongTerm": { "type": "number", "description": "capitalLossCarryover, as the Schedule D line 14 carryover: present only when not 0." }, "socialSecurityGross": { "type": "number", "description": "socialSecurityGross." }, "taxableInterest": { "type": "number", "description": "ordinaryIncome (interest, non-qualified dividends), as Form 1040 line 2b: present only when not 0." }, "taxExemptInterest": { "type": "number", "description": "taxExemptInterest (or the sum of inStateMunicipalInterest and outOfStateMunicipalInterest), as Form 1040 line 2a: in the Social Security worksheet's provisional income; present only when not 0." }, "ordinaryDividends": { "type": "number", "description": "qualifiedDividends, as Form 1040 line 3b: present only when not 0." }, "qualifiedDividends": { "type": "number", "description": "qualifiedDividends, as Form 1040 line 3a (the capital-gains worksheet): present only when not 0." }, "wages": { "type": "number", "description": "wages (the filer's; the household's without spouse), as W-2 box 1 = box 3 (at most the wage base) = box 5: present only when not 0." }, "socialSecurityWithheld": { "type": "number", "description": "The employer's social security withholding on wages (W-2 box 4, on box 3): present with wages." }, "medicareTaxWithheld": { "type": "number", "description": "The employer's Medicare withholding on wages (W-2 box 6, with the additional Medicare withholding): present with wages." }, "selfEmploymentIncome": { "type": "number", "description": "selfEmploymentIncome, as the filer's Schedule C net profit: present only when not 0." }, "spouseWages": { "type": "number", "description": "spouse.wages on a joint return, as the spouse's W-2: present only when not 0." }, "spouseSocialSecurityWithheld": { "type": "number", "description": "The spouse's employer social security withholding: present with spouseWages." }, "spouseMedicareTaxWithheld": { "type": "number", "description": "The spouse's employer Medicare withholding: present with spouseWages." }, "spouseSelfEmploymentIncome": { "type": "number", "description": "spouse.selfEmploymentIncome on a joint return, as the spouse's Schedule C net profit: present only when not 0." }, "federalItemized": { "type": "object", "description": "With federalItemized: the Schedule A amounts the federal return used (2026-10-12).", "properties": { "saltIncomeOrSalesTax": { "type": "number", "description": "Schedule A line 5a: the state and local income tax paid in the year." }, "saltRealEstateTax": { "type": "number", "description": "Schedule A line 5b: real estate tax." }, "saltPersonalPropertyTax": { "type": "number", "description": "Schedule A line 5c: personal property tax." }, "mortgageInterest": { "type": "number", "description": "Schedule A lines 8a-8c: the deductible home mortgage interest." }, "charityCash": { "type": "number", "description": "Schedule A line 11: cash gifts to charity." }, "medicalExpenses": { "type": "number", "description": "Schedule A line 1: medical and dental expenses, before the AGI floor." } } }, "qualifiedTips": { "type": "number", "description": "qualifiedTips (both spouses' on a joint return), the federal Schedule 1-A employee tips: present only when not 0." }, "qualifiedOvertime": { "type": "number", "description": "qualifiedOvertime (both spouses'), Schedule 1-A Part III: present only when not 0." }, "charityCash": { "type": "number", "description": "charityCash, the federal cash gifts to public charities (170(p) for a non-itemizer): present only when not 0." } } }, "toState": { "type": "object", "description": "The values handed to the state engine.", "properties": { "socialSecurity": { "type": "number", "description": "The federally taxable Social Security (Form 1040 line 6b)." }, "federalTax": { "type": "number", "description": "The federal income tax without the NIIT (Form 1040 line 22: no credits are modelled)." }, "federalNiit": { "type": "number", "description": "The net investment income tax." }, "federalTaxBeforeCredits": { "type": "number", "description": "The same as federalTax (no credits are modelled)." }, "federalRefundableCredits": { "type": "number", "description": "Zero (no credits are modelled)." }, "federalEarnedIncomeCredits": { "type": "number", "description": "The federal return's earned income credit (Form 1040 line 27a), handed to the state as federalEarnedIncomeCredits (Missouri reads it): present only when not 0." }, "federalTaxableOrdinaryIncome": { "type": "number", "description": "The ordinary part of federal taxable income, read by the states whose base starts from federal taxable income." }, "federalTaxableLongTermGain": { "type": "number", "description": "The long-term gain part of federal taxable income." }, "earnedIncome": { "type": "number", "description": "With self-employment income: the filer's earned income the state engine received, wages plus the net profit less half the filer's self-employment tax. Present only when selfEmploymentIncome is given and not 0 (either spouse)." }, "spouseEarnedIncome": { "type": "number", "description": "The same for the spouse on a joint return." } } }, "result": { "type": "object", "description": "The federal result, in the shape POST /api/federal-tax returns it (see /docs/federal-tax/api/).", "properties": {} }, "schedules": { "type": "object", "description": "With wages or selfEmploymentIncome: the federal return's schedules as POST /api/federal-tax reports them (work: Schedule SE, the self-employment tax deduction, Form 8959; qbi: the qualified business income deduction; and the others). federal.result.totalTax then includes the self-employment tax and the Additional Medicare Tax (Schedule 2); federal.toState.federalTax stays the income tax. Also with federalItemized (2026-10-12), so the itemizing choice is in schedules.scheduleA.", "properties": {} }, "lines": { "type": "array", "description": "The federal return's Form 1040 lines, in the shape POST /api/federal-tax returns them.", "items": { "type": "object", "properties": {} } }, "docs": { "type": "string", "description": "The federal engine documentation." } } }, "rulesYear": { "type": "integer", "description": "With projection only (engine 1.10.0): the tax year whose rules were projected (2026)." }, "projectedYear": { "type": "integer", "description": "With projection only: the tax year estimated (projection.year)." }, "projected": { "type": "boolean", "description": "With projection only: true when projectedYear is after the rules year (the result is an estimate on the rules year's rules); false for projection.year 2026." }, "inputsNotSupplied": { "type": "array", "description": "Every response unless includeInputsNotSupplied is false (engine 1.10.0): the facts and splits the request did not give that could change this result, each probed (empty = no probe changed the tax).", "items": { "type": "object", "properties": { "input": { "type": "string", "description": "The request key, as a caller supplies it (spouse.age for the spouse's)." }, "family": { "type": "string", "description": "The rule family it belongs to (the keys of rules.sources)." }, "assumed": { "type": "string", "description": "What the engine used without it." }, "probed": { "type": "string", "description": "The probe values, in words." }, "taxMin": { "type": "number", "description": "The lowest tax over the probes and the result as given." }, "taxMax": { "type": "number", "description": "The highest tax over the probes and the result as given." }, "totalTaxMin": { "type": "number", "description": "The lowest totalTax among the probes and this result (engine 1.12.0: a probe can move only the separate local returns)." }, "totalTaxMax": { "type": "number", "description": "The highest." }, "netTaxMin": { "type": "number", "description": "The lowest netTax among the probes and this result (engine 1.12.0: a probe can also move only the refundable credits)." }, "netTaxMax": { "type": "number", "description": "The highest." } } } }, "notModelled": { "type": "array", "description": "Every response unless includeNotModelled is false (engine 1.12.0): the parts of the request's state's income tax law the engine does not model, from the state's form map and not-calculated list (empty for a state without an income tax). The other half of inputsNotSupplied: that lists facts the engine reads but was not given; this lists rules the engine does not have.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A stable identifier: the state, the list it comes from and a hash of its text." }, "category": { "type": "string", "description": "payments, tax-table, other-state-credit, part-year, amt, dependent-care (a child and dependent care credit figured on care expenses limited to earned income), dependents (needs a dependent), care-expenses (another care credit), itemized, business, locality or other." }, "description": { "type": "string", "description": "What is not modelled, in words." }, "lines": { "type": "array", "description": "The state form lines that carry it (form, line, description); empty for an item of the state's list with no single line.", "items": { "type": "object", "properties": { "form": { "type": "string", "description": "The form or schedule." }, "line": { "type": "string", "description": "The line." }, "description": { "type": "string", "description": "What the line is." } } } }, "couldApply": { "type": [ "boolean", "string" ], "description": "Whether it can bear on this request: true, false or \"unknown\" (it turns on facts the request does not carry). A part-year item is true only on a part-year or nonresident return; an item that needs a dependent is false when dependents is []; a child and dependent care item is false when the request has no wages or self-employment income (state engine 1.16; it can apply with no dependent, for care of a spouse who cannot care for themselves); an interest item is false when the request has no federally tax-exempt interest, a U.S.-obligation item when it has no ordinaryIncome (state engine 1.16); payments and penalties are false; a tax-table difference is true." }, "reason": { "type": "string", "description": "Why couldApply is what it is." }, "source": { "type": "object", "description": "Unless includeSources is false (and not in the library's no-sources build): the official document and a verbatim phrase from it.", "properties": { "url": { "type": "string", "description": "The official document." }, "quote": { "type": "string", "description": "A verbatim phrase from it." } } } } } }, "projection": { "type": "object", "description": "Projected responses only (engine 1.10.0): how the result was projected.", "properties": { "rulesYear": { "type": "integer", "description": "The rules year (2026)." }, "projectedYear": { "type": "integer", "description": "The tax year estimated." }, "cpiFactor": { "type": "number", "description": "The cumulative CPI factor used (from inflation, or as given)." }, "indexing": { "type": "string", "description": "The mode that ran: \"law\" or \"inflation\" (see the request field)." }, "inflation": { "type": "number", "description": "The annual rate, when the request gave inflation." }, "parameters": { "type": "array", "description": "Every amount of the state's rules that bears on this result (setting it to zero or far above its value would change the tax), in registry order. Engine 1.12.1: with localities, also each local amount that bears on the result, named local.. (rate, rateNonresident, schoolIncomeTaxRate, netProfitsRate, thresholdSingle, thresholdJoint, exemption, lowIncomeExemption, seniorCredit, zeroBelow), with its rule local..", "items": { "type": "object", "properties": { "parameter": { "type": "string", "description": "The engine configuration field (a brackets_* field is a rate schedule's thresholds)." }, "rule": { "type": "string", "description": "The registry rule that moves it (a key of projection.rules)." }, "method": { "type": "string", "description": "cpi, federal, fixed, scheduled, birth_year, age, derived or unknown; with indexing \"inflation\": inflation (multiplied by the factor), held, or birth_year." }, "lawMethod": { "type": "string", "description": "indexing \"inflation\" only: how the law would move this amount (the rule's method)." }, "rulesYearValue": { "type": [ "number", "array" ], "description": "The rules year's value: a number, an array, or a rate schedule [[from, to (null = no top), rate], ...]." }, "projectedValue": { "type": [ "number", "array" ], "description": "The value used for the projected year, in the same shape." }, "multiplier": { "type": "number", "description": "cpi and federal, and a scheduled amount indexed after its schedule: the factor applied to the increase." }, "valueYear": { "type": "integer", "description": "cpi and federal, when the engine carries an earlier year's figure: that year (the multiplier includes the years since)." }, "scheduleYear": { "type": [ "integer", "null" ], "description": "scheduled: the scheduled year whose value applies (null before the first). A local amount with published years (Metro's thresholds) carries it too." }, "afterSchedule": { "type": "boolean", "description": "scheduled: true when the projected year is past the last scheduled year." }, "ageShift": { "type": "integer", "description": "birth_year: the years added to the age test." } } } }, "codeTables": { "type": "array", "description": "The state's dollar tables held in code (every one, bearing or not), with their rule and method. Engine 1.12.1: with localities, also each locality's rate schedules and credit tables (local..tables), fixed.", "items": { "type": "object", "properties": { "table": { "type": "string", "description": "The table's registry id." }, "rule": { "type": "string", "description": "Its rule." }, "method": { "type": "string", "description": "Its method (fixed for every table the engine holds in code)." } } } }, "rules": { "type": "object", "description": "Rule id -> the rule of every parameter and code table listed.", "additionalProperties": { "type": "object", "properties": { "method": { "type": "string", "description": "The rule's method." }, "index": { "type": "string", "description": "cpi and federal: the index or federal amount the statute names." }, "rounding": { "type": "object", "description": "cpi and federal (and a schedule indexed after it): how the increase is rounded.", "properties": { "mode": { "type": "string", "description": "nearest, down, up or none." }, "step": { "type": "number", "description": "The multiple rounded to (0 with none)." } } }, "afterSchedule": { "type": "string", "description": "scheduled: fixed, cpi or federal after the last scheduled year." }, "scheduleValueYear": { "type": "integer", "description": "scheduled, when present: the scheduled values are that year's dollars and are indexed from it (the afterSchedule way) in every scheduled year too, not only after the last (Maine's standard deduction: from 2027 the federal one, scheduled at its 2026 amount)." }, "birthYear": { "type": "integer", "description": "birth_year: the cutoff birth year." }, "derivedFrom": { "type": "string", "description": "derived: the parameter this amount is defined from (the statute's ratio times that amount as projected, rounded the rule's way)." }, "ratio": { "type": "number", "description": "derived: the statute's ratio." }, "establishes": { "type": "string", "description": "What the law says about these amounts. Provenance: omitted with includeSources: false (and by a library built without sources)." }, "sources": { "type": "array", "description": "Omitted with includeSources: false: the official sources, each with url, title, kind, official, quote and checked (as rules.sources).", "items": { "type": "object", "properties": {} } }, "heldTopBoundaries": { "type": "integer", "description": "Bracket tables: the number of top boundaries between rows the statute fixes (held; the others are indexed), when not 0 (Oregon's top threshold)." }, "settledUntil": { "type": "integer", "description": "A local rule (local., engine 1.12.1): the last tax year the law settles its amounts; a later year is refused." } } } }, "notApplied": { "type": "array", "description": "What the projection does not do, in words (rates and rules stay the rules year's; the factor stands in for every index; below a factor of 1, no floor).", "items": { "type": "string" } }, "enactedChangesNotApplied": { "type": "array", "description": "Changes the state enacted for later years that the projection does not apply (in every build; only their sources are omitted with includeSources: false).", "items": { "type": "object", "properties": { "what": { "type": "string", "description": "The change, in words." }, "years": { "type": "string", "description": "The years it applies to." }, "conditional": { "type": "boolean", "description": "true when it depends on a revenue trigger or another future event." }, "rule": { "type": "string", "description": "indexing \"inflation\" only, on the entries it adds: the scheduled rule of the registry whose schedule this mode does not apply." }, "sources": { "type": "array", "description": "Omitted with includeSources: false: its sources, as above.", "items": { "type": "object", "properties": {} } } } } } } }, "residency": { "type": "object", "description": "Only with residency: how the return was figured.", "properties": { "status": { "type": "string", "description": "resident, partYear or nonresident: the residency of the return the breakdown describes (a couple: the applied option's main return, residency.couple.breakdownIs)." }, "method": { "type": "string", "description": "resident; R (the full-year tax × the ratio), D (the tax on the state's own income, items prorated), C (the full-year tax less a nonresident credit), S (the tax on the state's own income, nothing prorated) or none (no tax)." }, "methodText": { "type": "string", "description": "The method in words." }, "form": { "type": "string", "description": "The state's form for this return." }, "fullYearTax": { "type": "number", "description": "The tax a full-year resident would owe on all the year's income (the earned income credits left out)." }, "numerator": { "type": "number", "description": "The ratio's numerator: the state's own income measure (days or months for a days / months proration)." }, "denominator": { "type": "number", "description": "The ratio's denominator: the whole year's (365 days, 12 months)." }, "ratio": { "type": "number", "description": "The ratio as the form rounds and bounds it (C: 1 less the nonresident share)." }, "ratioDecimals": { "type": [ "integer", "null" ], "description": "Its places; null where the form states no rounding." }, "ratioLongTermGains": { "type": "number", "description": "Montana: the net long-term capital gains ratio." }, "proration": { "type": "number", "description": "The factor the prorated items were scaled by (D), or the factor of a special line (CA's deduction percentage, MD 505 line 15)." }, "prorationBasis": { "type": "string", "description": "income, days, months or none." }, "days": { "type": "integer", "description": "Days resident (a days proration)." }, "months": { "type": "integer", "description": "Months resident (NJ: 15 days or more is a month; MD's pension exclusion)." }, "incomePercentage": { "type": "number", "description": "Virginia 760PY: the standard deduction's income percentage." }, "nonresidentShare": { "type": "number", "description": "C: the share of the tax credited." }, "stateTaxableIncome": { "type": "number", "description": "CA, MD 505, VA 763: the state's taxable income on this return." }, "specialNonresidentTax": { "type": "number", "description": "Maryland 505NR line 17: the special nonresident tax on Maryland taxable income (in place of a county tax)." }, "retirementExclusionShare": { "type": "number", "description": "DE, ME: the share of the retirement exclusion in the state's own income." }, "notModelled": { "type": "array", "description": "What this return leaves out (the earned income credits; Indiana's county tax where it does not apply). The state's general list, with the part-year items marked couldApply true on this return, is the top-level notModelled.", "items": { "type": "string" } }, "couple": { "type": "object", "description": "Engine 1.13.0, only with residency.spouse: the state's rule for the couple and every treatment it allows, computed.", "properties": { "pair": { "type": "string", "description": "RP (one spouse a full-year resident, the other part-year), RN (full-year resident and nonresident), PN (part-year and nonresident), PP (both part-year, different periods), NN1 (both nonresidents, only one with income from the state) or same (the same residency: one joint return)." }, "rule": { "type": "string", "description": "The state's rule for the pair in words (quoted from its instructions in rules.sources, family residency)." }, "condition": { "type": "string", "description": "Engine 1.14.0: the condition of the couple's own facts that set the treatments (Massachusetts' filing-requirement and threshold exceptions, Vermont's TB-55 options, Virginia's Form 763 status); absent when none applies." }, "note": { "type": "string", "description": "Engine 1.14.0: what the state's documents leave open about this pair (for example, that they describe one treatment without saying whether another is allowed); absent when nothing." }, "options": { "type": "array", "description": "One entry per treatment the state allows: joint (one joint part-year / nonresident return), separate (each spouse's own return) or jointAsResidents (a joint resident return).", "items": { "type": "object", "properties": { "treatment": { "type": "string", "description": "joint, separate or jointAsResidents." }, "tax": { "type": "number", "description": "Only when computed: the option's state tax (both returns for separate)." }, "totalTax": { "type": "number", "description": "Only when computed: with the separate local returns." }, "netTax": { "type": "number", "description": "Only when computed: totalTax less the refundable credits." }, "notComputed": { "type": "string", "description": "Only when not computed: why (the state's instructions leave it unsettled, a computation the engine does not model, or the inputs it needs)." }, "returns": { "type": "array", "description": "Only when computed: the option's returns (one joint, or each spouse's).", "items": { "type": "object", "properties": { "return": { "type": "string", "description": "joint, primary or spouse." }, "filingStatus": { "type": "string", "description": "mfj (a joint return) or mfs (a spouse's separate return)." }, "residency": { "type": "string", "description": "resident, partYear or nonresident: the return's own." }, "method": { "type": "string", "description": "resident, or the state's part-year / nonresident method (R, D, C, S, none)." }, "form": { "type": "string", "description": "Only on a part-year / nonresident return: its form." }, "filed": { "type": "boolean", "description": "false: no return (no income the state taxes)." }, "tax": { "type": "number", "description": "The return's tax." }, "netTax": { "type": "number", "description": "The return's tax with its separate local returns, less its refundable credits." }, "taxableIncome": { "type": "number", "description": "The return's taxable income." }, "ratio": { "type": "number", "description": "Only with an apportionment ratio: the ratio as the form rounds it." } } } } } } }, "applied": { "type": "string", "description": "The treatment in tax: joint, separate or jointAsResidents." }, "appliedBecause": { "type": "string", "description": "Why: required (the only one allowed), the state's default absent an election, residency.election, or a free choice where the request's mfj names a joint return." }, "lowest": { "type": [ "string", "null" ], "description": "The computed option with the lowest netTax; null when fewer than two are computed or the lowest is shared." }, "breakdownIs": { "type": "string", "description": "Which return the breakdown, perPerson and residency method describe: the joint return, the primary's separate return or the joint resident return." } } } } } } }, "error": { "type": "object", "properties": { "error": { "type": "string", "description": "One of the messages under #/$defs/request/x-errors, with the parts taken from the request filled in." } }, "required": [ "error" ] } } }