{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/riskmodels-app/json-schema/riskmodels-app-fund-holdings-response-schema.json",
  "title": "FundHoldingsResponse",
  "description": "A fund's selected filed book, shorts included, ranked by |adj_mv|. `aum_reported` is the fund's reported net assets; `aum_erm3` is the net value of its in-model positions (for a long/short fund this is small, so weights use `aum_reported`).\n",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/riskmodels-app-openapi.json#/components/schemas/FundHoldingsResponse",
  "type": "object",
  "required": [
    "bw_fund_id",
    "teo",
    "n_holdings_returned",
    "n_total_holdings",
    "holdings"
  ],
  "properties": {
    "bw_fund_id": {
      "type": "string"
    },
    "ticker": {
      "type": [
        "string",
        "null"
      ]
    },
    "fund_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "equity_style_9box": {
      "type": [
        "string",
        "null"
      ]
    },
    "source": {
      "type": "string",
      "enum": [
        "full_book",
        "top_25_longs"
      ],
      "description": "`full_book`: every position from the fund's holdings panel. `top_25_longs`: fallback for a fund with no panel, holding only its 25 largest long positions.\n"
    },
    "teo": {
      "type": "string",
      "format": "date",
      "description": "Report date of the filing the book comes from."
    },
    "report_date": {
      "type": "string",
      "format": "date",
      "description": "Report date of the selected filing; equal to `teo`. Present when `as_of` is set."
    },
    "time_basis": {
      "type": "string",
      "enum": [
        "report_date",
        "available_date"
      ],
      "description": "Axis used to select the book. Present when `as_of` is set."
    },
    "filing_date": {
      "type": [
        "string",
        "null"
      ],
      "format": "date",
      "description": "SEC filing date of the selected report. Under time_basis=report_date it can be after as_of: the book is the period's, filed later."
    },
    "filing_date_source": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "exact",
        "approx"
      ],
      "description": "Provenance label carried by the selected filing date. Present when `as_of` is set."
    },
    "has_new_data": {
      "type": "boolean",
      "description": "True when at least one position was newly reported at the selected report date. Present when `as_of` is set."
    },
    "book_rows": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Number of source filing rows when published by the holdings store. Present when `as_of` is set."
    },
    "universe_dropped_mv": {
      "type": [
        "number",
        "null"
      ],
      "description": "Market value excluded by the model-universe gate. Present when `as_of` is set."
    },
    "ticker_as_of": {
      "type": "string",
      "enum": [
        "current_registry"
      ],
      "description": "Tickers are current registry labels, not historical report-date labels. Present when `as_of` is set."
    },
    "aum_reported": {
      "type": [
        "number",
        "null"
      ],
      "format": "float"
    },
    "aum_erm3": {
      "type": [
        "number",
        "null"
      ],
      "format": "float"
    },
    "net_assets": {
      "type": [
        "number",
        "null"
      ],
      "description": "Net assets from the filing's own N-PORT header. Null when the filing has none (then `aum_reported` is only the sum of positions).\n"
    },
    "weight_basis": {
      "type": "string",
      "enum": [
        "net_assets",
        "gross"
      ],
      "description": "Denominator of each holding's `weight`: `net_assets` when the filing reports them, else the book's gross value. Never the net in-model value, which for a long/short fund would inflate weights.\n"
    },
    "book": {
      "type": "object",
      "description": "Totals over every position, whatever `limit` is. Present when `source` is `full_book`.",
      "properties": {
        "n_long": {
          "type": "integer"
        },
        "n_short": {
          "type": "integer"
        },
        "long_mv": {
          "type": "number"
        },
        "short_mv": {
          "type": "number"
        },
        "net_mv": {
          "type": "number"
        },
        "gross_mv": {
          "type": "number"
        },
        "long_pct_nav": {
          "type": [
            "number",
            "null"
          ],
          "description": "long_mv / net_assets"
        },
        "short_pct_nav": {
          "type": [
            "number",
            "null"
          ],
          "description": "short_mv / net_assets"
        },
        "net_pct_nav": {
          "type": [
            "number",
            "null"
          ],
          "description": "net_mv / net_assets"
        },
        "gross_pct_nav": {
          "type": [
            "number",
            "null"
          ],
          "description": "gross_mv / net_assets"
        }
      }
    },
    "coverage": {
      "type": "object",
      "description": "How much of the filed book the response covers, over every position. Small caps outside the symbol registry come back with `ticker: null`; filed positions that could not be matched to any security are not in `holdings` at all. Present when `source` is `full_book`.\n",
      "properties": {
        "n_positions": {
          "type": "integer"
        },
        "n_with_ticker": {
          "type": "integer"
        },
        "gross_with_ticker": {
          "type": "number",
          "description": "Share of `book.gross_mv` in positions that have a ticker (0–1)."
        },
        "unmatched_mv": {
          "type": [
            "number",
            "null"
          ],
          "description": "Net (signed) adj_mv of filed positions not matched to any security."
        }
      }
    },
    "n_holdings_returned": {
      "type": "integer"
    },
    "n_total_holdings": {
      "type": "integer"
    },
    "holdings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/FundHolding"
      }
    }
  },
  "$defs": {
    "FundHolding": {
      "type": "object",
      "description": "One holding (security) within a fund's holdings list.",
      "required": [
        "bw_sym_id",
        "adj_mv"
      ],
      "properties": {
        "ticker": {
          "type": [
            "string",
            "null"
          ],
          "description": "Ticker from the symbol registry. Null for the few holdings whose symbol is not in the registry; `bw_sym_id` still identifies them.\n"
        },
        "bw_sym_id": {
          "type": "string",
          "description": "Internal symbol id. Resolve to ticker via POST /api/data/symbols/batch with {\"symbols\": [...]}."
        },
        "adj_mv": {
          "type": "number",
          "format": "float",
          "description": "Adjusted market value (USD) of this position at the report date. Negative for a short."
        },
        "weight": {
          "type": [
            "number",
            "null"
          ],
          "format": "float",
          "description": "Signed fraction of the denominator named by the response's `weight_basis` (reported net assets on `/funds/{bw_fund_id}/holdings`; `aum_erm3` in fund snapshots). Null when that denominator is null/0.\n"
        }
      }
    }
  }
}