# `metadata.srf` reference

`metadata.srf` classifies each symbol by asset class, sector, and
geography so [`zfin analysis`](../cli/analysis.md) can produce
allocation breakdowns and [`zfin review`](../cli/review.md) can group
holdings by sector. zfin loads it from the same directory as the
resolved portfolio file.

It is optional, but without it the Asset Category / Sector / Geographic
breakdowns have nothing to group by. The fastest way to create one is
[`zfin enrich`](../cli/enrich.md); see
[Classify your holdings](../../guides/classify-holdings.md).

## File format

One record per `(symbol, allocation)` pair. A single-asset-class
security needs one line; a blended fund needs several lines that sum to
~100%.

```srf
#!srfv1
symbol::VTI,sector::Diversified,geo::US,asset_class::US Large Cap
symbol::AGG,sector::Bonds,geo::US,asset_class::Bonds
```

## Fields

| Field         | Type   | Required | Default   | Description                                                                                                               |
|---------------|--------|----------|-----------|---------------------------------------------------------------------------------------------------------------------------|
| `symbol`      | string | Yes      | --        | Ticker or CUSIP. Must match `symbol::` (or `ticker::`) on a portfolio lot.                                                |
| `name`        | string | No       | --        | Human-readable security name (e.g. "SPDR S&P 500 ETF Trust"). Shown where available; falls back to the symbol.            |
| `asset_class` | string | No       | --        | e.g. `US Large Cap`, `Bonds`, `International Developed`, `Emerging Markets`.                                              |
| `sector`      | string | No       | --        | e.g. `Technology`, `Healthcare`, `Financials`, `Diversified`, `Bonds`.                                                    |
| `geo`         | string | No       | --        | e.g. `US`, `International Developed`, `Emerging Markets`.                                                                 |
| `bucket`      | string | No       | (derived) | User-curated grouping label that overrides the auto-derived sector bucket for concentration/dominance checks (see below). |
| `pct`         | number | No       | `100`     | Weight of this allocation line for the symbol. Use multiple lines for blended funds.                                      |

Cash and CD lots are classified as "Cash & CDs" automatically -- they
need no metadata entry.

## The `bucket` field

For concentration and sector-dominance analysis, zfin needs a
meaningful grouping label. It derives one automatically, but the
upstream `sector` can be uninformative -- ETF holdings data often tags
everything as the generic "Equity / Corporate." When several distinct
holdings collapse into one meaningless bucket, set `bucket::` yourself
to a label that actually distinguishes them. When `bucket` is unset,
zfin falls back through: `sector` (if it isn't a fund-decomposition
category) -> a composite `"<geo> <asset_class>"` -> `Unclassified`.
See [Classify your holdings](../../guides/classify-holdings.md#fixing-uninformative-sectors)
for a worked `bucket` example.

## Blended funds

For a target-date or balanced fund, add one line per asset class with
`pct:num:` weights summing to ~100:

```srf
#!srfv1
symbol::02315N600,asset_class::US Large Cap,pct:num:55
symbol::02315N600,asset_class::International Developed,pct:num:20
symbol::02315N600,asset_class::Bonds,pct:num:15
symbol::02315N600,asset_class::Emerging Markets,pct:num:10
```

## Example (from `examples/pre-retirement-both`)

```srf
#!srfv1
symbol::VTI,sector::Diversified,geo::US,asset_class::US Large Cap
symbol::SPY,sector::Diversified,geo::US,asset_class::US Large Cap
symbol::QQQ,sector::Technology,geo::US,asset_class::US Large Cap
symbol::SCHD,sector::Diversified,geo::US,asset_class::US Large Cap
symbol::AGG,sector::Bonds,geo::US,asset_class::Bonds
```

## See also

- [Classify your holdings](../../guides/classify-holdings.md) -- the walkthrough, including `enrich`.
- [`zfin enrich`](../cli/enrich.md) -- bootstrap this file from Wikidata + SEC EDGAR.
- [`zfin analysis`](../cli/analysis.md) -- the breakdowns this file feeds.
- [`zfin review`](../cli/review.md) -- the per-holding Sector column and grouping this file feeds.

---

[Documentation home](../../README.md#reference)