DecomposeResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/riskmodels-app/json-schema/riskmodels-app-decompose-response-schema.json",
  "title": "DecomposeResponse",
  "description": "Wire response for `POST /decompose`. Semantic four-layer shape; each tradable layer maps to one ETF. The top-level `hedge` map is the layer `hr` keyed by ETF: the ETF dollar position per $1 long stock (negative = short the ETF), summed when two layers share one ETF.\n",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/riskmodels-app-openapi.json#/components/schemas/DecomposeResponse",
  "type": "object",
  "required": [
    "ticker",
    "symbol",
    "data_as_of",
    "teo",
    "exposure",
    "hedge"
  ],
  "properties": {
    "ticker": {
      "type": "string"
    },
    "symbol": {
      "type": "string",
      "description": "Canonical symbol key in V3 registry."
    },
    "resolved_via": {
      "type": "string",
      "enum": [
        "most_recent_holder",
        "share_class_sibling"
      ],
      "description": "Present only when the modelled registry has no live row for the requested ticker. `share_class_sibling`: another share class of the same company answers it (e.g. `GOOGL` answered with `GOOG`'s series, named in `modelled_ticker`); risk and hedge ratios are the sibling's and price fields are withheld. `most_recent_holder`: the security that holds or most recently held the ticker answers. Same rule as `GET /ticker-returns`.\n"
    },
    "requested_ticker": {
      "type": "string",
      "description": "With `resolved_via: share_class_sibling`: the ticker requested (e.g. `GOOGL`)."
    },
    "modelled_ticker": {
      "type": [
        "string",
        "null"
      ],
      "description": "With `resolved_via`: the answering security's own ticker when it differs from the request (e.g. `GOOG`)."
    },
    "share_class": {
      "type": [
        "string",
        "null"
      ],
      "description": "With `share_class_sibling`: the requested class letter, when known (e.g. `A` for `BRK-A`)."
    },
    "modelled_share_class": {
      "type": [
        "string",
        "null"
      ],
      "description": "With `share_class_sibling`: the answering class letter, when known."
    },
    "price_withheld": {
      "type": "boolean",
      "description": "With `resolved_via: share_class_sibling`: `true`; price-bearing fields (`price_close`, `market_cap`) are null because the sibling's price is not the requested class's price.\n"
    },
    "data_as_of": {
      "type": "string",
      "format": "date",
      "description": "Latest trading day the metrics apply to."
    },
    "teo": {
      "type": "string",
      "format": "date",
      "description": "V3 observation date (time-end) for this row."
    },
    "exposure": {
      "type": "object",
      "required": [
        "market",
        "sector",
        "subsector",
        "residual"
      ],
      "properties": {
        "market": {
          "$ref": "#/$defs/DecomposeLayer"
        },
        "sector": {
          "$ref": "#/$defs/DecomposeLayer"
        },
        "subsector": {
          "$ref": "#/$defs/DecomposeLayer"
        },
        "residual": {
          "$ref": "#/$defs/DecomposeLayer"
        }
      }
    },
    "hedge": {
      "type": "object",
      "additionalProperties": {
        "type": "number"
      },
      "description": "Map of hedge-ETF → dollar ratio (= the layer `hr`: ETF dollars per $1 long stock, negative = short the ETF). If two layers share the same ETF (e.g. subsector falls back to the sector ETF), the values are summed so each ETF appears once.\n"
    },
    "hedge_levels": {
      "$ref": "#/$defs/HedgeLevelsBlock",
      "nullable": true,
      "description": "Canonical L1/L2/L3 compare alongside the L3-focused `exposure` map. Prefer this when the user asks how L1/L2/L3 hedge ratios differ — `exposure` alone is the four-bet semantic view for L3.\n"
    },
    "style": {
      "type": [
        "object",
        "null"
      ],
      "description": "FF2 (SMB + HML) diagnostic split of the `exposure.residual` variance — attribution only, never a tradable hedge (`hedgeable` is always `false`). `explained_variance` is a variance-ratio share on the `hedge_levels` basis named by `hedge_levels.statistical_lstar` (style + `stock_specific` ≈ that level's residual share). See `POST /v4/decompose` for the named-block form of this same split.\n",
      "properties": {
        "explained_variance": {
          "type": [
            "number",
            "null"
          ]
        },
        "hedgeable": {
          "type": "boolean"
        },
        "role": {
          "type": "string"
        }
      }
    },
    "stock_specific": {
      "type": [
        "object",
        "null"
      ],
      "description": "Doubly-cleaned skill residual — `exposure.residual` after the FF2 `style` strip. The stock-selection basis (skills-paper skill metric); not a tradable hedge.\n",
      "properties": {
        "explained_variance": {
          "type": [
            "number",
            "null"
          ]
        },
        "hedgeable": {
          "type": "boolean"
        }
      }
    },
    "_metadata": {
      "type": "object",
      "description": "Lineage, billing code, and freshness (same shape as `/metrics`)."
    },
    "_data_health": {
      "type": "object",
      "properties": {
        "er_populated": {
          "type": "boolean"
        },
        "er_sum": {
          "type": [
            "number",
            "null"
          ],
          "description": "Sum of L3 ER layers (should be ≈ 1 within tolerance)."
        }
      }
    }
  },
  "$defs": {
    "DecomposeLayer": {
      "type": "object",
      "description": "One layer of the four-bet decomposition. `er` is a variance fraction in [0, 1]. `hr` is a dollar-ratio hedge ratio (dollars of ETF per $1 of stock). `residual` has no tradable ETF, so `hr` and `hedge_etf` are null for that layer.\n",
      "required": [
        "er",
        "hr",
        "hedge_etf"
      ],
      "properties": {
        "er": {
          "type": [
            "number",
            "null"
          ],
          "description": "Explained-risk variance fraction for this layer."
        },
        "hr": {
          "type": [
            "number",
            "null"
          ],
          "description": "Hedge ratio (dollar ratio) for this layer. Null for residual."
        },
        "hedge_etf": {
          "type": [
            "string",
            "null"
          ],
          "description": "Tradable ETF for this layer. Null for residual."
        }
      }
    },
    "HedgeLevelsBlock": {
      "type": "object",
      "description": "Canonical L1/L2/L3 hedge snapshots (additive on metrics, decompose, batch success rows). Prefer this block over parsing flat `l*_mkt_hr` wire keys when comparing cascade levels.\n",
      "required": [
        "L1",
        "L2",
        "L3"
      ],
      "properties": {
        "L1": {
          "$ref": "#/$defs/LevelHedgeSnapshot"
        },
        "L2": {
          "$ref": "#/$defs/LevelHedgeSnapshot"
        },
        "L3": {
          "$ref": "#/$defs/LevelHedgeSnapshot"
        },
        "recommended_level": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "L1",
            "L2",
            "L3"
          ],
          "description": "Economic recommendation when emitted (user-segment hedge gate)."
        },
        "statistical_lstar": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "L1",
            "L2",
            "L3"
          ],
          "description": "Orthogonal cascade statistical layer pick."
        }
      }
    },
    "LevelHedgeSnapshot": {
      "type": "object",
      "description": "One hierarchical level (L1, L2, or L3) as a standalone hedge solution — HR and ER for each populated leg plus resolved ETF mnemonics. Null legs indicate that leg is not part of this level.\n",
      "required": [
        "market_hr",
        "sector_hr",
        "subsector_hr",
        "market_er",
        "sector_er",
        "subsector_er",
        "residual_er",
        "hedge_etfs"
      ],
      "properties": {
        "market_hr": {
          "type": [
            "number",
            "null"
          ],
          "description": "Dollar-ratio HR (ETF notional per $1 stock)."
        },
        "sector_hr": {
          "type": [
            "number",
            "null"
          ]
        },
        "subsector_hr": {
          "type": [
            "number",
            "null"
          ]
        },
        "market_er": {
          "type": [
            "number",
            "null"
          ],
          "description": "Explained-risk variance fraction where defined for this level."
        },
        "sector_er": {
          "type": [
            "number",
            "null"
          ]
        },
        "subsector_er": {
          "type": [
            "number",
            "null"
          ]
        },
        "residual_er": {
          "type": [
            "number",
            "null"
          ]
        },
        "hedge_etfs": {
          "type": "object",
          "required": [
            "market",
            "sector",
            "subsector"
          ],
          "properties": {
            "market": {
              "type": "string"
            },
            "sector": {
              "type": [
                "string",
                "null"
              ]
            },
            "subsector": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        }
      }
    }
  }
}