# `returns.json` — provenance, licence & attribution

The "time machine" tool (`/planning/history/`) reads a single bundled file,
`returns.json`, at runtime from our own origin. There is **no network request**
to any third party, and no live market data.

## What the data is

`returns.json` holds an **annual total-return series** for three generically
described building blocks, in **GBP, nominal (not inflation-adjusted), gross of
fees**, covering **1970–2023** (54 years):

| Key      | Shown in the UI as                                   |
|----------|------------------------------------------------------|
| `equity` | "A globally diversified equity index (illustrative)" |
| `bond`   | "A government-bond series (illustrative)"            |
| `cash`   | "Cash (illustrative)"                                |

Each value is a decimal fraction (`0.05` = +5% for that year). The three
selectable mixes are computed in the browser from these series:

- **100% equities** — the `equity` series.
- **60/40** — `0.6 × equity + 0.4 × bond` each year, **rebalanced annually**.
- **Cash** — the `cash` series.

## ⚠️ Licence status of the data — REPRESENTATIVE / ILLUSTRATIVE

**The figures in `returns.json` are a clearly-labelled REPRESENTATIVE series,
not a copy of any published dataset.** They were hand-constructed to echo the
broad character and rough magnitude of long-run developed-market history — the
major peak-to-trough drawdowns of the 1973–74 bear market, the 2000–2002
dot-com bust, the 2008 global financial crisis, and the 2022 bond sell-off are
deliberately present — so the tool can honestly show "the falls and the
recoveries alike" without smoothing.

Because they are our own construction and contain **no proprietary or branded
index values**, there is no third-party data licence to attribute here. This is
the safe path the issue calls for when precise historical sourcing is not
feasible in the build environment:

> "commit a clearly-labelled representative/illustrative series (marked as such
> in `NOTICE.md` and in the UI) rather than any scraped/branded data — never
> scrape live sources."

The UI therefore labels the series **"Illustrative — a generic index, not a
real product or portfolio; not advice."** and states the representative basis on
the page.

## Sourcing a production series (licence-free only)

If these figures are ever replaced with sourced historical returns before
go-live, use **only licence-free sources** and keep the generic descriptions
(never name a proprietary index such as FTSE, S&P or MSCI in the UI or the
data):

- **Robert Shiller's long-run US dataset** (equities, real total returns) —
  <http://www.econ.yale.edu/~shiller/data.htm> (freely provided for research).
- **Kenneth French Data Library** (equity factor / market returns) —
  <https://mba.tuck.dartmouth.edu/pages/faculty/ken.french/data_library.html>.
- **FRED** (Federal Reserve Bank of St. Louis) — rates and bond series.
- **ONS** (UK CPI / rates) and **HM Land Registry** under the **Open Government
  Licence v3.0** — commercial reuse and public display permitted, attribution
  the only obligation:
  <https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/>.

Record the exact source, date pulled, transformation and licence here, and
carry the required attribution line in the UI, before any sourced series ships.

## Charting library

The chart is drawn with **Highcharts**, vendored under
`public/assets/js/vendor/highcharts/` by the Planning foundation (#30). See that
directory's `NOTICE` for the Highcharts licence position — a paid commercial
licence must be purchased before go-live, and Highcharts' own credit stays
visible until it is.