> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Module 4 · The Classification Layer

> The classification seeds (asset-class taxonomy, GICS sector structure, FIGI identifier crosswalk) are already committed in the repo — nothing to load into your warehouse. Ana jo… (~20 min)

The classification seeds (asset-class taxonomy, GICS sector structure, FIGI identifier crosswalk) are **already committed in the repo** — nothing to load into your warehouse. Ana joins them in her Python sandbox at query time (see `ontology/notes/terminology-join-pattern.md`), so the grouper logic works with **zero warehouse writes** — the system of record stays pristine.

## 4.1 · Prove the groupers work

```text Prompt theme={null}
Using the ontology's classification layer, show me my firm-wide asset-class allocation, then roll the equity sleeve up to its GICS sectors. Explain how you joined the asset-class and GICS-structure seeds without writing to the warehouse.
```

<Check>
  **You'll see:** raw instruments resolved to meaningful asset-class and sector buckets, with the join-in-sandbox pattern explained — and weights that sum to 1.000 at one snapshot date.
</Check>

<Warning>
  **Two classification traps to name** — **The identifier tuple.** A security reference is *original (ticker) + normalized (FIGI) + system + version*, not a column (`notes/coding-tuple.md`). Join on the normalized, license-clean **FIGI** — never parse tickers, which are reused across venues and change on corporate actions. **Look-through & version.** A fund hides its underlying exposure, and GICS gets revised (the 2018 real-estate split). Decide whether allocation is top-level or looks through to underlying issuers, and name the GICS version when a number depends on it (`notes/asset-classification.md`).
</Warning>

## 4.2 · Refresh or extend the reference data — optional

**You don't need this on day one** — the current seeds are already committed. Come back when a taxonomy updates (GICS is revised periodically) or when you need to hydrate the FIGI crosswalk against your security master. And you don't run the scripts yourself — Ana does:

```text Prompt theme={null}
Run reference/terminology/load_terminology.py in your sandbox to regenerate the asset_class and gics_structure seed CSVs, then open a PR with the refreshed files and a summary of what changed between versions.
```

```text Prompt theme={null}
Using load_terminology.py --figi with our OPENFIGI_API_KEY, fetch the OpenFIGI crosswalk for the tickers/ISINs in my security master. Confirm we're committing only the public FIGI mapping, not the licensed CUSIP/GICS codes, per LICENSING.md.
```

<Check>
  **You'll see:** refreshed reference tables arriving as a reviewable PR — same governance motion as everything else. (The licensed per-security GICS mapping itself comes from your MSCI/S\&P feed onto `security.gics_sector`; we never bundle it.)
</Check>

### ✅ Checkpoint

* [ ] A grouper question worked against your data with no warehouse writes
* [ ] You can explain the join-in-sandbox pattern in one sentence
* [ ] You know what's public (asset-class, GICS structure, FIGI) vs. licensed (CUSIP, per-security GICS) and how the loader refreshes seeds