🧬 IMF SDMX 3.0 Dimensions Reference

May 10, 2026 · View on GitHub

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):

Empty filter maps are rejected. fetchData requires a non-empty filters object.
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:

INDICATOR code (word-bounded SDMX code from indicator-catalog.md §2).
REF_AREA either as an ISO-3 country, EU/EA, or a named EU member state in prose.
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">.
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

database-directory.md — full database list
indicator-catalog.md — SDMX indicator codes
eu-country-mapping.md — REF_AREA values
release-calendar.md — vintage timing
SDMX 3.0 specification (ISO 17369:2013)