87 lines
4.3 KiB
Markdown
87 lines
4.3 KiB
Markdown
# `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)
|