Add enum docs

documentation/properties/asset_class.md

@@ -43,87 +43,91 @@ Primary asset classes are Foreign Exchange, Interest Rates, Credit, Equities, Co
 ```
 
 ### fx
-*Needs definition*
+Derivatives whose underlying risk is the exchange rate between currencies, such as currency forwards, swaps and options. See the [BIS OTC derivatives asset classes][bis-otc].
 
 ### ir
-*Needs definition*
+Derivatives linked to interest rates or interest-bearing instruments, such as interest rate swaps, forward rate agreements and interest rate options. See the [BIS OTC derivatives asset classes][bis-otc].
 
 ### inflation
-*Needs definition*
+Derivatives with payments linked to changes in a price index or inflation rate. FIRE groups these under **ir**. The [ECB explanation of inflation-linked swaps][ecb-inflation] describes exchanging fixed payments for inflation-linked payments.
 
 ### cr
-*Needs definition*
+Derivatives transferring credit risk relating to a reference entity or group of entities, such as credit default swaps. See the [BIS OTC derivatives asset classes][bis-otc].
 
 ### cr_index
-*Needs definition*
+Credit derivatives referencing an index of multiple reference entities, rather than one entity. See the [BIS definitions of credit derivatives][bis-otc].
 
 ### cr_single
-*Needs definition*
+Credit derivatives referencing a single entity, such as a single-name credit default swap. See the [BIS definitions of credit derivatives][bis-otc].
 
 ### eq
-*Needs definition*
+Derivatives linked to equity prices or returns, including individual shares and equity indices. See the [BIS OTC derivatives asset classes][bis-otc].
 
 ### eq_index
-*Needs definition*
+Equity derivatives referencing a share-price index. See the [BIS definitions of equity derivatives][bis-otc].
 
 ### eq_single
-*Needs definition*
+Equity derivatives referencing the shares of a single issuer. See the [BIS definitions of equity derivatives][bis-otc].
 
 ### co
-*Needs definition*
+Derivatives linked to commodity prices or indices. FIRE subdivides this category into metals, energy, agricultural and other commodities. The commodity names below are described in [Regulation (EU) 2017/585, Annex, Table 2][commodity-taxonomy].
 
 ### metals
-*Needs definition*
+Commodity derivatives referencing [metals, including base and precious metals][commodity-taxonomy].
 
 ### precious_metals
-*Needs definition*
+Commodity derivatives referencing [precious metals][commodity-taxonomy].
 
 ### gold
-*Needs definition*
+Commodity derivatives referencing [gold][commodity-taxonomy].
 
 ### silver
-*Needs definition*
+Commodity derivatives referencing [silver][commodity-taxonomy].
 
 ### platinum
-*Needs definition*
+Commodity derivatives referencing [platinum][commodity-taxonomy].
 
 ### palladium
-*Needs definition*
+Commodity derivatives referencing [palladium][commodity-taxonomy].
 
 ### energy
-*Needs definition*
+Commodity derivatives referencing [energy commodities][commodity-taxonomy].
 
 ### oil
-*Needs definition*
+Commodity derivatives referencing [oil][commodity-taxonomy].
 
 ### gas
-*Needs definition*
+Commodity derivatives referencing [natural gas][commodity-taxonomy].
 
 ### coal
-*Needs definition*
+Commodity derivatives referencing [coal][commodity-taxonomy].
 
 ### electricity
-*Needs definition*
+Commodity derivatives referencing [electricity][commodity-taxonomy].
 
 ### agri
-*Needs definition*
+Commodity derivatives referencing [agricultural commodities][commodity-taxonomy].
 
 ### sugar
-*Needs definition*
+Commodity derivatives referencing [sugar][commodity-taxonomy].
 
 ### coffee
-*Needs definition*
+Commodity derivatives referencing [coffee][commodity-taxonomy].
 
 ### corn
-*Needs definition*
+Commodity derivatives referencing [corn (maize)][commodity-taxonomy].
 
 ### co_other
-*Needs definition*
+Commodity derivatives whose underlying commodity does not fall within the metals, energy or agricultural categories in this hierarchy.
 
 ### other
-*Needs definition*
+Derivatives whose underlying asset class does not fall within the foreign exchange, interest rate, credit, equity or commodity categories above.
 
 
 ---
 
 [wiki]: https://en.wikipedia.org/wiki/Asset_classes
+
+[bis-otc]: https://data.bis.org/topics/OTC_DER
+[ecb-inflation]: https://www.ecb.europa.eu/pub/pdf/other/mb200309_focus04.en.pdf
+[commodity-taxonomy]: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32017R0585#:~:text=Table%202

documentation/properties/capital_tier.md

@@ -9,7 +9,7 @@ schemas:    [account, security]
 ```bash
 ├── tier_1
 ├── ce_tier_1
-├── ce_tier_1_ineligible  
+├── ce_tier_1_ineligible
 ├── add_tier_1
 │   └── add_tier_1_indirect
 ├── cet1_grandfathered
@@ -23,8 +23,17 @@ schemas:    [account, security]
 └── bas_tier_3
 ```
 
-Capital tier of an instrument in accordance with CRR2 regulation
-(REGULATION (EU) No 575/2013 AS AMENDED BY REGULATION (EU) 2019/876 (CRR2) ).
+Capital tier of an instrument under the applicable regulatory framework. For banks,
+[Basel Framework CAP10.1–10.3][basel-capital] distinguishes Common Equity Tier 1
+(CET1), Additional Tier 1 (AT1) and Tier 2 capital. In the EU, the corresponding
+rules are in [Regulation (EU) No 575/2013 (CRR), Part Two][crr-own-funds], as amended.
+
+The property also supports insurance own-fund classifications and historical
+banking classifications. **Basic** and **ancillary** own funds are distinctions
+under [Solvency II, Articles 88–94][solvency-own-funds]; CRR does not subdivide bank
+Tier 2 capital into these categories. Banking Tier 3 is a historical category,
+as explained below. Classify the instrument under the relevant framework rather
+than treating similarly named banking and insurance tiers as interchangeable.
 
 Note that this includes 'grandfathered capital' which is capital which would
 have been classified in capital tiers under Basel 2 regulations, rules but are
@@ -38,43 +47,45 @@ The fields here are listed in a flat structure as they are mutually exclusive.
 ### tier_1
 Securities classed as tier 1 capital instruments, these include securities
 classed as common equity tier 1 and securities classed as additional tier 1
-capital instruments.
+capital instruments. See [CRR Article 25][crr-tier-1] and
+[Basel Framework CAP10.1–10.3][basel-capital].
 
 ### ce_tier_1
 Securities classed as common equity tier 1 (CET1) capital instruments.
-As set out in CRR Article 26, these are  capital instruments,
-provided that the conditions laid down in CRR Article 28 or, where applicable,
-Article 29 are met.
+As set out in [CRR Article 26][crr-cet1-items], these are  capital instruments,
+provided that the conditions laid down in [CRR Article 28][crr-cet1-instruments] or, where applicable,
+[Article 29][crr-mutual-cet1] are met.
 
 ### ce_tier_1_ineligible
-Capital instruments which do not meet the condition in points (b), (l) and (m) of Article 28(1) CRR Conditions in those points reflect different situations of the capital which are reversible, and thus the amount reported here can be eligible in subsequent periods.
+Capital instruments which do not meet the condition in points (b), (l) and (m) of [CRR Article 28(1)][crr-cet1-instruments]. Conditions in those points reflect different situations of the capital which are reversible, and thus the amount reported here can be eligible in subsequent periods.
 
 ### add_tier_1
 Securities classed as additional tier 1 capital instruments.
-As set out in CRR Article 51, these are capital instruments, where the
-conditions laid down in Article 52(1) are met.
+As set out in [CRR Article 51][crr-at1-items], these are capital instruments, where the
+conditions laid down in [Article 52(1)][crr-at1-instruments] are met.
 
 ### add_tier_1_indirect
-Indirect holdings of securities classed as additional tier 1 capital instruments where the condition set out in point (b)(ii) of Article 52(1) is met.
+Indirect holdings of securities classed as additional tier 1 capital instruments where the condition set out in point (b)(ii) of [CRR Article 52(1)][crr-at1-instruments] is met.
 
 ### tier_2
 Securities classed as Tier 2 capital instruments.
-As set out in CRR Article 62 these are capital instruments where the
-conditions laid down in Article 63 are met.
+For banks, [CRR Article 62][crr-tier2-items] identifies Tier 2 items, including
+capital instruments and subordinated loans meeting [Article 63][crr-tier2-instruments].
+See also [Basel Framework CAP10, “Tier 2 capital”][basel-tier2].
 
 ### anc_tier_2
-*Needs definition*
+Ancillary own funds classified as Tier 2 under Solvency II. These are callable loss-absorbing items, such as eligible uncalled capital or guarantees, meeting the Tier 2 criteria. See [Directive 2009/138/EC, Articles 89 and 94(2)][solvency-own-funds] and [EIOPA’s Article 94 text][solvency-classification].
 
 ### bas_tier_2
-*Needs definition*
+Basic own funds classified as Tier 2 under Solvency II, meeting the applicable subordination and other classification criteria. Basic own funds comprise the excess of assets over liabilities, subject to adjustments, and subordinated liabilities. See [Directive 2009/138/EC, Articles 88 and 94(2)][solvency-own-funds].
 
 ### cet1_grandfathered
 Instruments which are considered as grandfathered
 as CET1 Capital, in that they no longer meet the tighter restrictions
 introduced  in the CRR\CRR2 regulation for CET1 capital, but are still included
 in transitional arrangements.
 
-According to CRR2 Regulation Article 484(3) this is capital within the meaning
+Under the historical transitional provisions of [CRR Article 484(3)][crr-grandfathering] this is capital within the meaning
 of Article 22 of Directive 86/635/EEC, that qualified as original own funds
 under the national transposition measures for point (a) of Article 57 of
 Directive 2006/48/EC notwithstanding that the conditions laid down in
@@ -86,7 +97,7 @@ as additional tier 1 capital, in that they no longer meet the tighter
 restrictions introduced  in the CRR\CRR2 regulation for additional tier 1
 capital, but are still included in transitional arrangements.
 
-According to CRR2 Regulation Article 484(4) this is instruments that qualified
+Under the historical transitional provisions of [CRR Article 484(4)][crr-grandfathering] this is instruments that qualified
 as original own funds under national transposition measures for point (ca)
 of Article 57 and Article 154(8) and (9) of Directive 2006/48/EC
 notwithstanding that the conditions laid down in Article 52 of this Regulation
@@ -98,19 +109,44 @@ as tier 2 capital, in that they no longer meet the tighter
 restrictions introduced  in the CRR\CRR2 regulation for tier 2
 capital, but are still included in transitional arrangements.
 
-According to CRR2 Regulation Article 484(5) this is instruments that qualified
+Under the historical transitional provisions of [CRR Article 484(5)][crr-grandfathering] this is instruments that qualified
 under national transposition measures for points (e), (f), (g) or (h) of
 Article 57 of Directive 2006/48/EC shall qualify as Tier 2 items,
 notwithstanding that those items are not included in Article 62 of this
 Regulation or that the conditions laid down in Article 63 of this
 Regulation are not met.
 
 ### tier_3
-*Needs definition*
+Capital classified as Tier 3 under the applicable framework:
+
+- **Historical banking framework:** short-term subordinated debt permitted, at national supervisory discretion and subject to limits, to meet part of the capital requirement for market risk. See [Basel II, paragraphs 49(xiii)–49(xiv)][basel2-tier3]. Banking Tier 3 was abolished by [Basel III, introductory paragraph 9][basel3-tier3]; it is not a current Basel III/CRR own-funds category.
+- **Solvency II:** basic or ancillary own-fund items that do not qualify for Tier 1 or Tier 2. See [Directive 2009/138/EC, Article 94(3)][solvency-own-funds].
 
 
 ### anc_tier_3
-*Needs definition*
+Ancillary own funds classified as Tier 3 under Solvency II because they do not meet the Tier 2 criteria. See [Directive 2009/138/EC, Articles 89 and 94(3)][solvency-own-funds].
 
 ### bas_tier_3
-*Needs definition*
+Basic own funds classified as Tier 3 under Solvency II because they do not meet the Tier 1 or Tier 2 criteria. See [Directive 2009/138/EC, Articles 88 and 94(3)][solvency-own-funds].
+
+
+---
+
+
+[solvency-own-funds]: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32009L0138#:~:text=Classification%20into%20tiers
+[solvency-classification]: https://www.eiopa.europa.eu/rulebook/solvency-ii-single-rulebook/article-2182_en
+
+[basel-capital]: https://www.bis.org/committees/bcbs/basel-framework/standard/cap?allChapters=true#:~:text=10.1
+[basel-tier2]: https://www.bis.org/committees/bcbs/basel-framework/standard/cap?allChapters=true#:~:text=Tier%202%20capital
+[basel2-tier3]: https://www.bis.org/publications/200606-standards-basel-ii-international-convergence-capital-measurement-and-capital-standards-revised-framework.pdf
+[basel3-tier3]: https://www.bis.org/publ/bcbs189.pdf
+[crr-own-funds]: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32013R0575#:~:text=Own%20funds
+[crr-tier-1]: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32013R0575#:~:text=Article%2025
+[crr-cet1-items]: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32013R0575#:~:text=Article%2026
+[crr-cet1-instruments]: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32013R0575#:~:text=Article%2028
+[crr-mutual-cet1]: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32013R0575#:~:text=Article%2029
+[crr-at1-items]: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32013R0575#:~:text=Article%2051
+[crr-at1-instruments]: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32013R0575#:~:text=Article%2052
+[crr-tier2-items]: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32013R0575#:~:text=Article%2062
+[crr-tier2-instruments]: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32013R0575#:~:text=Article%2063
+[crr-grandfathering]: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32013R0575#:~:text=Article%20484

documentation/properties/movement.md

@@ -59,6 +59,6 @@ From Central Bank Open Market Operations
 A a securities issuance of stocks or bonds (determined by the security - *type*)
 
 ### other
-*Needs definition*
+A security movement that is not a cash or asset leg of a securities financing transaction, a central bank open market operation, or an issuance, as described by the categories above.
 
 [eu]: http://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:52015PC0472