{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/riskmodels-app/json-schema/riskmodels-app-lstar-response-schema.json",
  "title": "LstarResponse",
  "description": "Per-(ticker, date) recommended hedge level (L1/L2/L3) with the chosen level's dispatched hedge ratios and total explained-return. Arrays are parallel by date index. Each L\\* is a standalone hedge solution (not stacked layers) — `market_hr`/`sector_hr`/`subsector_hr` come from the chosen level's solver and are `null` where the chosen level doesn't use that ETF (sector_hr is null when L\\*=L1; subsector_hr is null when L\\*∈{L1,L2}). `axis` is always `industry` — the style axis was removed in v4 (style is a diagnostic block; see `POST /v4/decompose`).\n",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/riskmodels-app-openapi.json#/components/schemas/LstarResponse",
  "type": "object",
  "required": [
    "ticker",
    "axis",
    "dates",
    "lstar",
    "market_hr",
    "sector_hr",
    "subsector_hr",
    "total_er",
    "residual_return",
    "l2_sector_er",
    "l3_subsector_er",
    "threshold_used",
    "market_factor_etf",
    "universe",
    "data_source"
  ],
  "properties": {
    "ticker": {
      "type": "string"
    },
    "axis": {
      "type": "string",
      "enum": [
        "industry"
      ],
      "default": "industry",
      "description": "Cascade axis — always `industry`. `style` was removed in v4 (style is served as a diagnostic block by `POST /v4/decompose`).\n"
    },
    "dates": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "date"
      }
    },
    "lstar": {
      "type": "array",
      "description": "Recommended level per date. `null` where source ERs are unavailable.",
      "items": {
        "type": [
          "string",
          "null"
        ],
        "enum": [
          "L1",
          "L2",
          "L3"
        ]
      }
    },
    "market_hr": {
      "type": "array",
      "items": {
        "type": [
          "number",
          "null"
        ],
        "format": "float"
      }
    },
    "sector_hr": {
      "type": "array",
      "description": "Hedge ratio for the sector ETF. `null` when `lstar` = `L1`.",
      "items": {
        "type": [
          "number",
          "null"
        ],
        "format": "float"
      }
    },
    "subsector_hr": {
      "type": "array",
      "description": "Hedge ratio for the subsector ETF. `null` when `lstar` ∈ {`L1`, `L2`}.",
      "items": {
        "type": [
          "number",
          "null"
        ],
        "format": "float"
      }
    },
    "total_er": {
      "type": "array",
      "description": "Sum of explained-return components at the chosen level (market + sector + subsector, omitting residual).\n",
      "items": {
        "type": [
          "number",
          "null"
        ],
        "format": "float"
      }
    },
    "residual_return": {
      "type": "array",
      "description": "Daily simple residual return at the chosen Lstar level (`l1_rr`, `l2_rr`, or `l3_rr` from returns decomposition). Parallel to `dates`; `null` when Lstar or source return is unavailable. Not a hedge ratio and not explained-risk variance (`l*_res_er`).\n",
      "items": {
        "type": [
          "number",
          "null"
        ],
        "format": "float"
      }
    },
    "l2_sector_er": {
      "type": "array",
      "description": "Marginal L2 (sector) ER input. Exposed for audit / threshold override.\n",
      "items": {
        "type": [
          "number",
          "null"
        ],
        "format": "float"
      }
    },
    "l3_subsector_er": {
      "type": "array",
      "description": "Marginal L3 (subsector) ER input. Exposed for audit / threshold override.\n",
      "items": {
        "type": [
          "number",
          "null"
        ],
        "format": "float"
      }
    },
    "threshold_used": {
      "type": "number",
      "format": "float",
      "description": "The marginal-ER threshold used to assign each date's level."
    },
    "market_factor_etf": {
      "type": "string"
    },
    "universe": {
      "type": "string"
    },
    "data_source": {
      "type": "string"
    },
    "history_starts": {
      "type": "string",
      "format": "date",
      "description": "Present only when the returned arrays are empty because the requested window ends before this security's earliest non-null daily close or return observation.\n"
    }
  }
}