{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://plantedmoney.ai/spec/scoring-contract.json", "title": "Planted Money \u2014 strategy_scores (Phase 3 Underwriting & Strategy Scoring Engine)", "description": "Authoritative shape of strategy_scores carried by every underwrite/scoring response (/api/underwrite, MCP underwrite, D1 listing ingest, /api/listings summary). The entire field is null when ARV is range-only, area context, stale, or suppressed; no midpoint may produce a strategy verdict. For point-supported valuations, FOUR independent strategy verdicts (flip, brrrr, hold, house_hack) follow raw composites -> hard gates (INV-4) -> inventory percentile per strategy per market (0-100). Every block echoes its component values, the weights used, gates triggered, the economics that produced the verdict, and a percentile phrase. Tract opportunity scores are CONTEXT only (tract_context), never the property score. Gates are never user-disableable; the gate ceiling (40) caps both the raw composite and the displayed percentile, so a gated listing can never reach the top decile.", "type": ["object", "null"], "required": [ "underwrite_version", "model_version", "market", "weights_used", "flip", "brrrr", "hold", "house_hack", "tract_context" ], "additionalProperties": true, "properties": { "underwrite_version": { "type": "string", "examples": [ "p3s-2026.07" ], "description": "Bumps whenever underwrite/scoring math changes; deterministic (same inputs -> same outputs)." }, "model_version": { "type": "string", "examples": [ "p3s-2026.07" ] }, "market": { "type": "string", "examples": [ "chicago" ], "description": "Percentile ranking is per strategy PER MARKET (county inventory)." }, "financing_type": { "type": [ "string", "null" ], "enum": [ "conventional_investor", "dscr_loan", "hard_money", "fha_oo", "conventional_oo" ], "description": "Selected financing product; every economics block echoes the terms used." }, "weights_used": { "type": "object", "description": "Component weights actually applied after clamping user weights to +-0.15 of defaults and normalizing to sum 1 per strategy. Gates are NOT here (never user-disableable).", "properties": { "flip": { "type": "object", "properties": { "margin": { "type": "number" }, "velocity": { "type": "number" }, "trend": { "type": "number" } } }, "brrrr": { "type": "object", "properties": { "ratio": { "type": "number" }, "dscr": { "type": "number" } } }, "hold": { "type": "object", "properties": { "coc": { "type": "number" }, "risk": { "type": "number" } } } } }, "flip": { "type": "object", "required": [ "score", "raw", "components", "gates_triggered", "economics" ], "properties": { "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Inventory percentile (0-100) of the gated raw composite among active flip candidates in the market; null when ARV suppressed. Capped at the gate ceiling (40) when gated." }, "raw": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Gated raw composite BEFORE percentile ranking (0-100)." }, "raw_ungated": { "type": [ "number", "null" ], "description": "Composite before the gate was applied (diagnostic)." }, "percentile_note": { "type": [ "string", "null" ], "description": "e.g. 'beats 92% of active flip candidates in Cook County'." }, "weights_used": { "type": "object", "properties": { "margin": { "type": "number" }, "velocity": { "type": "number" }, "trend": { "type": "number" } } }, "components": { "type": "object", "required": [ "margin", "velocity", "trend" ], "properties": { "margin": { "type": [ "number", "null" ], "description": "Margin score: flip_net/ARV 0%->0, 20%->100 (linear clamp)." }, "velocity": { "type": [ "number", "null" ], "description": "Tract DOM/s2l velocity percentile." }, "trend": { "type": [ "number", "null" ], "description": "Tract 12-month yoy price-trend percentile." } } }, "gates_triggered": { "type": "array", "items": { "type": "string", "enum": [ "flip_net_negative_at_ask" ] } }, "economics": { "type": "object", "required": [ "flip_net", "margin_pct", "holding", "selling", "buying" ], "properties": { "flip_net": { "type": [ "number", "null" ], "description": "ARV - Purchase - Rehab - Holding - Selling - Buying (at ask)." }, "margin_pct": { "type": [ "number", "null" ] }, "holding": { "type": [ "number", "null" ], "description": "HM interest (0.9*P + 0.5*Rehab) + points + taxes/insurance/utilities carry, over DOM+scope months." }, "holding_months": { "type": [ "number", "null" ] }, "selling": { "type": [ "number", "null" ], "description": "6% agent + 2% closing of ARV." }, "buying": { "type": [ "number", "null" ], "description": "1.5% closing of purchase." }, "arv": { "type": [ "number", "null" ] }, "purchase": { "type": [ "number", "null" ] }, "rehab": { "type": [ "number", "null" ] }, "financing": { "type": "object", "description": "Hard-money terms used (rate, points, term, ltv_arv)." } } } } }, "brrrr": { "type": "object", "required": [ "score", "raw", "components", "gates_triggered", "economics" ], "properties": { "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "raw": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "raw_ungated": { "type": [ "number", "null" ] }, "percentile_note": { "type": [ "string", "null" ] }, "weights_used": { "type": "object", "properties": { "ratio": { "type": "number" }, "dscr": { "type": "number" } } }, "components": { "type": "object", "required": [ "ratio", "dscr" ], "properties": { "ratio": { "type": [ "number", "null" ], "description": "Capital-efficiency score: (P+Rehab)/ARV <=0.70 -> 100, exp decay above." }, "dscr": { "type": [ "number", "null" ], "description": "Post-refi DSCR score (1.0->40, 1.25->80, 1.5->100)." } } }, "gates_triggered": { "type": "array", "items": { "type": "string", "enum": [ "dscr_market_below_1" ] } }, "economics": { "type": "object", "required": [ "ratio", "dscr_post", "cash_left_in", "capital_recycled_pct" ], "properties": { "ratio": { "type": [ "number", "null" ], "description": "(Purchase+Rehab)/ARV." }, "dscr_post": { "type": [ "number", "null" ], "description": "NOI_full / (P&I on 0.75*ARV at DSCR-loan rate)." }, "cash_left_in": { "type": [ "number", "null" ], "description": "(P+Rehab+acquisition+bridge costs) - net_refi_proceeds; negative = capital fully recycled." }, "coc_post_refi": { "type": [ "number", "null" ], "description": "(NOI_full - refi debt service) / cash_left_in; null when fully recycled." }, "capital_recycled_pct": { "type": [ "number", "null" ], "description": "net_refi_proceeds/(Purchase+Rehab), after the registered refinance closing-cost scenario." }, "refi_loan": { "type": [ "number", "null" ] }, "refi_closing": { "type": [ "number", "null" ], "description": "Registered refinance-cost scenario deducted from gross refinance proceeds." }, "net_refi_proceeds": { "type": [ "number", "null" ], "description": "refi_loan minus refi_closing; basis for cash-left-in and capital-recycled metrics." }, "noi_full": { "type": [ "number", "null" ] }, "appraisal_ceiling": { "type": [ "object", "null" ], "description": "Propagated from valuation.arv.appraisal_ceiling (a renovated resale may not appraise at target ARV)." } } } } }, "hold": { "type": "object", "required": [ "score", "raw", "components", "gates_triggered", "economics" ], "properties": { "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "raw": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "raw_ungated": { "type": [ "number", "null" ] }, "percentile_note": { "type": [ "string", "null" ] }, "weights_used": { "type": "object", "properties": { "coc": { "type": "number" }, "risk": { "type": "number" } } }, "components": { "type": "object", "required": [ "coc", "risk" ], "properties": { "coc": { "type": [ "number", "null" ], "description": "Cash-on-cash score (0%->0, 8%->70, 12%->100)." }, "risk": { "type": [ "number", "null" ], "description": "Risk overlay = 100 - risk_score (from the separate riskFlags engine)." } } }, "gates_triggered": { "type": "array", "items": { "type": "string", "enum": [ "dscr_market_below_1" ] } }, "economics": { "type": "object", "required": [ "coc", "noi", "opex_itemized" ], "properties": { "coc": { "type": [ "number", "null" ], "description": "True cash-on-cash %: (NOI_full - debt service on 0.75*Purchase) / (down + closing + rehab)." }, "noi": { "type": [ "number", "null" ], "description": "NOI after the full itemized OpEx waterfall (renovated rent)." }, "risk_score": { "type": [ "number", "null" ] }, "all_in_cash": { "type": [ "number", "null" ] }, "debt_service": { "type": [ "number", "null" ] }, "opex_itemized": { "$ref": "#/$defs/opex_waterfall" } } } } }, "house_hack": { "type": "object", "description": "Owner-occupied 2-4 unit house-hack (FHA). Requires an EXACT VERIFIED unit count (units_source record or caller; INV-3) \u2014 a consumer assumed-SFH, or a listing_type_inferred multifamily (units inferred from listing type, exact 3-4u count unverified), gets house_hack.applicable=false with note unit_count_unverified. FHA self-sufficiency is an ELIGIBILITY gate for 3-4 units (an ineligibility flag, never a score haircut).", "required": [ "applicable", "eligible" ], "properties": { "applicable": { "type": "boolean", "description": "False when units<2, units not verified (record/caller only), or units_source is listing_type_inferred (exact count unverified; INV-3)." }, "eligible": { "type": [ "boolean", "null" ], "description": "False when the FHA 3-4 unit self-sufficiency gate fails; null when not applicable." }, "gate": { "type": [ "string", "null" ], "enum": [ "fha_self_sufficiency", null ] }, "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Percentile among active house-hack candidates; null when ineligible/not applicable." }, "raw": { "type": [ "number", "null" ] }, "percentile_note": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ], "enum": [ "unit_count_unverified", null ], "description": "unit_count_unverified when units were inferred from listing type (units_source listing_type_inferred) so the exact 3-4u count the FHA self-sufficiency gate needs is unavailable; absent otherwise." }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Why not applicable/eligible." }, "net_housing_cost": { "type": [ "number", "null" ], "description": "Monthly PITI_FHA (P&I + MIP + taxes/12 + insurance/12) + owner OpEx share - rent from OTHER units (owner occupies the cheapest-rent unit)." }, "comparable_rent": { "type": [ "number", "null" ], "description": "Tract 2BR SAFMR \u2014 the market rent the owner would otherwise pay." }, "piti": { "type": [ "number", "null" ] }, "base_loan": { "type": [ "number", "null" ], "description": "Purchase price less the FHA down payment, before up-front mortgage insurance." }, "upfront_mip": { "type": [ "number", "null" ], "description": "Registered FHA up-front mortgage-insurance premium financed into the note." }, "financed_loan": { "type": [ "number", "null" ], "description": "base_loan plus upfront_mip; principal used for the P&I calculation." }, "other_unit_rent": { "type": [ "number", "null" ] }, "self_sufficiency": { "type": [ "object", "null" ], "properties": { "required_coverage": { "type": [ "number", "null" ], "description": "0.75 * gross market rent (ALL units)." }, "piti_full": { "type": [ "number", "null" ] }, "passes": { "type": [ "boolean", "null" ] } } } } }, "tract_context": { "type": "object", "description": "Tract opportunity screens (location context) \u2014 clearly labeled, NEVER the property score.", "properties": { "flip": { "type": [ "number", "null" ], "description": "Tract flip opportunity percentile." }, "brrrr": { "type": [ "number", "null" ], "description": "Tract BRRRR opportunity percentile." }, "note": { "type": "string" } } } }, "$defs": { "opex_waterfall": { "type": "object", "description": "Itemized OpEx waterfall (replaces the flat 30%). total INCLUDES predictive taxes; NOI = gross rent - total.", "required": [ "taxes", "insurance", "vacancy", "maintenance_capex", "management", "utilities", "hoa", "total", "opex_ratio" ], "properties": { "taxes": { "type": [ "number", "null" ], "description": "Predictive annual tax (Phase 2 predictiveTax)." }, "insurance": { "type": [ "number", "null" ], "description": "$0.55/sf/yr, floor $1,200/bldg, x1.25 pre-1940." }, "vacancy": { "type": [ "number", "null" ], "description": "5% strong / 8% weak submarket (by tract velocity percentile)." }, "maintenance_capex": { "type": [ "number", "null" ], "description": "Vintage-scaled 7% (post-2000) -> 12% (pre-1940); x0.6 for 3y after gut/structural (post-rehab reserve relief)." }, "management": { "type": [ "number", "null" ], "description": "8% of gross; 0 when self-managed." }, "utilities": { "type": [ "number", "null" ], "description": "$55/unit/mo owner-paid common (MF only)." }, "hoa": { "type": [ "number", "null" ], "description": "Condo only (param)." }, "total": { "type": [ "number", "null" ] }, "opex_ratio": { "type": [ "number", "null" ], "description": "total / gross annual rent." }, "assumptions": { "type": "object", "description": "Echo of every rate/source used (vacancy source, maint vintage, mgmt, insurance basis)." } } } } }