Reading the metadata file

---

1. What is it?

metadata.json is an optional side‑car file that can be generated together with a StoryTeller report. It only appears when enabled for the tenant. Tenants that do not have this enabled will not see the file.

Why do we generate it?

metadata.json serves two distinct purposes:

1. Preview assets: Some tenants embed StoryTeller reports inside their own portals. A lightweight preview (cover image and title) lets them show a card before a user opens the full report. The metadata.json exposes the cover image (2 sizes) and the cover title directly for this purpose.
2. Example company exposure transparency: StoryTeller highlights real companies the portfolio is exposed to, to make the story more interesting. The file breaks down the portfolio’s exposure to each highlighted instrument so advisors can answer follow‑up questions like "How am I exposed to Apple?".

2. Where is it stored?

The file is written to the same folder as the generated report.

3. File structure

{
  "pdf": {
    "teaser_image": {
      "original": "…",
      "small": "…"
    },
    "title": "A return to glory after a dip in fortunes."
  },
  "web_responsive": {
    "teaser_image": {
      "original": "…",
      "small": "…"
    },
    "title": "A return to glory after a dip in fortunes."
  },
  "company_examples": {
    "INSTRUMENT_ID": {
      "avg_weight_fraction": 0.01,
      "weight_per_source_instrument_id": {
        "FUND_INSTRUMENT_ID": 0.01
      },
      "name": "Example Corp"
    }
  }
}

The object has three top‑level sections:

Key	Type	Purpose
pdf	object	Presentation metadata used by the PDF version of the report.
web_responsive	object	Equivalent metadata for the web‑responsive version.
company_examples	object	Mapping of company example instruments to their exposure paths.

Each section can be enabled and disabled per tenant.

3.1 pdf & web_responsive

Both sections share an identical schema:

Field	Type	Description
teaser_image.original	string	URL to a high‑resolution image of the cover image of the report.
teaser_image.small	string	URL to a thumbnail image optimised for mobile and previews.
title	string	The report cover title.

3.2 company_examples

A dictionary keyed by the instrument ID (ISIN, Ticker or internal ID). Each entry contains:

Field	Type	Description
avg_weight_fraction	number	Portfolio‑level average exposure to the instrument, over the reporting period, expressed as a fraction (0.20 = 20%).
weight_per_source_instrument_id	object	Breakdown of exposure by source instrument. Keys are the IDs of the direct holdings (e.g. underlying funds); values are their individual weight contributions. If the portfolio is directly invested in an example company, the key is portfolio.
name	string	Name of the instrument.

Example interpretation

"weight_per_source_instrument_id": {
  "IE00B4L5Y983": 0.001,
  "portfolio": 0.004
}

The portfolio was on average 5% exposed to Example Corp over the reporting period, of which 4% via a direct investment in Example Corp, and 1% indirectly via the fund IE00B4L5Y983.