Skip to content

sdmx-dimensions-reference.md

Latest commit

 

History

History
206 lines (159 loc) · 9.86 KB

sdmx-dimensions-reference.md

File metadata and controls

206 lines (159 loc) · 9.86 KB

🧬 IMF SDMX 3.0 Dimensions Reference — EU Parliament Monitor

Purpose: Canonical reference for the SDMX 3.0 dimensions that appear across IMF dataflows, with codelist conventions, example values, and notes on how each dimension is handled by the native TypeScript client (src/mcp/imf-mcp-client.ts).

📅 Last Updated: 2026-04-24 | 🏷️ Classification: Public | 🌀 Wave: 4

SDMX (Statistical Data and Metadata eXchange) is an ISO standard for exchanging statistical data. The IMF REST surface is SDMX 3.0 (v2.1 message schema); queries are expressed as a key (slash-separated dimension values) against a dataflow. This document explains each dimension from the EP editorial perspective — for the authoritative spec see sdmx.org.

1. Dimensions Glossary

SDMX 3.0 dimension naming: post-Sept-2025 the IMF Data Portal uses UPPERCASE dimension names on api.imf.org — COUNTRY, INDICATOR, FREQUENCY (not the legacy lowercase / FREQ / REF_AREA shapes that appeared in SDMX 2.1 IFS payloads). The IMFMCPClient matches filter keys case-insensitively so legacy country/indicator/frequency aliases keep working.

Dimension Appears on Required? Example values EP handling
FREQUENCY All ✅ A / Q / M Last series-level dimension in every editorial DSD; client supplies dataflow-default when omitted
COUNTRY All ✅ DEU, FRA, EU, EA ISO-3 country or IMF aggregate — see eu-country-mapping.md
INDICATOR WEO, FM, IFS, FSI, PCPS, SRF, … ✅ NGDP_RPCH, GGXWDG_NGDP Canonical SDMX code; see indicator-catalog.md §2
COUNTERPART_AREA BOP, DOT, CDIS, CPIS ✅ W00 (World), USA, CHN Bilateral partner for flow data
INSTRUMENT CPIS ✅ F1, F2, F3 Financial-instrument classification
SECTOR FSI, GFS, GFSR, CDIS ✅/optional S1 (total economy), S11 (non-financial corps), S13 (general govt) ESA 2010 sector codes
UNIT / UNIT_MEASURE GFS, ER, all (obs-level) varies XDC (domestic currency), USD, EUR, PT (percent), IX (index) Required positional dim on GFS; observation-level metadata elsewhere
TYPE_OF_TRANSFORMATION CPI, ER optional IX (index), PCH (% change), LCY WEO ships the change form via INDICATOR suffix; CPI/ER ship transformation as a dimension
INDEX_TYPE CPI ✅ CPI, CCPI Headline vs. core
COICOP_1999 CPI ✅ _T (all items) COICOP product breakdown
BOP_ACCOUNTING_ENTRY BOP ✅ C, D, N (credit/debit/net) BPM6 entry side
OBS_STATUS All (observation-level) — A, F, E, B, P See indicator-catalog.md §4
SCALE All (observation-level) — 0, 3, 6, 9 Power-of-10 multiplier for the observation value
METHODOLOGY GFS, BOP optional GFSM2014, BPM6 Methodological-vintage tag
TIME_PERIOD All ✅ (in query range) 2026, 2026-Q1, 2026-03 Emitted as startPeriod / endPeriod query params

2. Dimension ordering in the SDMX key

The SDMX key is a dot-separated concatenation of dimension values in the order defined by the dataflow's datastructure. The TypeScript client's imf-fetch-data builds this automatically from the filters map; agents should supply filters by name, not by position.

For "all codes in this dimension" use the SDMX 3.0 wildcard *. The bare empty form (DEU..A) is rejected by api.imf.org and returns 0 series — always emit * when you want a wildcard.

Example for WEO (agency IMF.RES, order COUNTRY.INDICATOR.FREQUENCY):

GET /data/dataflow/IMF.RES/WEO/+/DEU.NGDP_RPCH.A?startPeriod=2020&endPeriod=2030&format=jsondata
                                  │   │          │
                                  │   │          └── FREQUENCY
                                  │   └────────────── INDICATOR
                                  └────────────────── COUNTRY

Example for BOP_AGG (agency IMF.STA, order COUNTRY.INDICATOR.FREQUENCY):

GET /data/dataflow/IMF.STA/BOP_AGG/+/DEU.BFD_BP6_USD.Q?startPeriod=2024
                                     │   │            │
                                     │   │            └── FREQUENCY
                                     │   └──────────────── INDICATOR
                                     └──────────────────── COUNTRY

Wildcard segments are legal: *.NGDP_RPCH.A means "all countries, WEO GDP growth, annual". Two scope rules apply on data-fetch calls (structure-discovery calls — imf-search-databases / imf-get-parameter-codes — may use wildcards freely):

  1. Empty filter maps are rejected. fetchData requires a non-empty filters object.
  2. At least one non-FREQUENCY dimension must be concrete. Because FREQUENCY auto-injects via the dataflow's default (e.g. A for WEO) and every other unspecified slot resolves to *, a typo'd or unrecognised filter key (e.g. region: ['EU'] against a dataflow that declares COUNTRY instead) would otherwise yield an effectively unbounded key like *.*.A and download the full cross-product. The client refuses such requests and returns the empty IMF_FALLBACK payload with a console warning identifying the rejected filter keys. Single-wildcard intent like DEU.*.A still passes because DEU pins COUNTRY.

3. Codelist discovery

Each dimension's valid values come from an SDMX codelist referenced by the data-structure definition. The client exposes codelists via imf-get-parameter-codes(db, dimension, search?):

// Fetch the list of valid INDICATOR codes for WEO
await client.getParameterCodes('WEO', 'INDICATOR');

// Search within the codelist
await client.getParameterCodes('WEO', 'INDICATOR', 'inflation');

The search is a simple substring match against code_description; the client does not perform fuzzy matching.

4. REF_AREA conventions

  • Countries: ISO-3 (DEU, FRA, ITA) for every EU-27 member.
  • EU aggregates: EU (27 members, current), EA (Euro Area, current membership), EFTA (4 members), SM (single market — EU + EFTA).
  • Global aggregates: WLD (World), G7, G20, ADV (advanced economies), EMDE (emerging/developing).

EA membership drift: Croatia joined the Euro Area on 2023-01-01. WEO EA timeseries use the current membership throughout history — there is no automatic back-splicing. Articles covering pre-2023 timeseries MUST cite "EA current membership" in the chart caption.

For EP-level framing (where WB aggregate codes EUU/EMU are rejected), always use IMF EU or EA.

5. TIME_PERIOD formats

Frequency (FREQ) TIME_PERIOD format Example
A YYYY 2026
S YYYY-S1 / YYYY-S2 2026-S1
Q YYYY-Q1..4 2026-Q2
M YYYY-MM 2026-03
D (rare) YYYY-MM-DD 2026-04-24

The client accepts numeric startYear / endYear integers and converts them per the frequency. For sub-annual series the query is expanded to the full year range.

6. Observation attributes (beyond OBS_STATUS)

Attribute Meaning EP handling
OBS_CONF Confidentiality (C = confidential, F = free) Only F observations are ingested; C is filtered by the parser
TIME_FORMAT ISO-8601 time precision of the observation Informational; not surfaced to articles
COMMENT Free-text annotation from the source Captured in the manifest when present
OBS_PRE_BREAK Value before a structural break Cited in prose when a B status is encountered
UNIT_MULT Power-of-10 multiplier Applied by the parser during normalisation

7. Editorial dimensions (Stage-C review)

editorial review requires that every IMF citation in a policy-required article carries:

  1. INDICATOR code (word-bounded SDMX code from indicator-catalog.md §2).
  2. REF_AREA either as an ISO-3 country, EU/EA, or a named EU member state in prose.
  3. Vintage string when OBS_STATUS is F (forecast) — e.g. IMF WEO April 2026 in prose and data-vintage="WEO-April-2026" on the enclosing <section class="economic-context imf-economic-context">.
  4. FREQ is inferred from the cadence and is not gated.

Missing REF_AREA context (e.g. "inflation is 3.2%" with no country or aggregate) fails Stage-C review per .github/prompts/04-article-generation.md §5.

8. Client API surface (for reference)

Method Dimensions involved Returns
listDatabases — MCPToolResult<DataflowSummary[]>
searchDatabases(keyword) dataflow names & descriptions MCPToolResult<DataflowSummary[]>
getParameterDefs(databaseId) all dimensions for a dataflow MCPToolResult<DataStructureDefinition>
getParameterCodes(db, dim, search?) codelist for one dimension MCPToolResult<Codelist>
fetchData({ databaseId, startYear, endYear, filters }) all dimensions + TIME_PERIOD MCPToolResult<TimeSeries[]>

9. See also