IMF Data Dictionary

May 11, 2026 · View on GitHub

Purpose: Complete reference for every IMF dataflow, dimension, frequency, code list, release cadence, projection horizon, and known quirk that Riksdagsmonitor consumes. Read this before adding a new IMF indicator, debugging a 404, or interpreting divergent values between IMF and SCB/WB.

Companion to indicators-inventory.json (machine-readable) and indicator-policy-mapping.md (committee mapping).

Authority: IMF SDMX 3.0 documentation at https://data.imf.org/api/documentation and IMF Data Portal at https://data.imf.org.

1 · Transport layers

IMF public data is exposed on two transports, both unauthenticated and both on the Riksdagsmonitor firewall allowlist.

1.1 Datamapper JSON (simple, WEO-optimised)

Base URL: https://www.imf.org/external/datamapper/api/v1
URL pattern: /{indicatorCode}/{iso3} (single indicator, single country) or /{indicatorCode} (indicator across all countries).
Country codes: ISO-3 alpha-3 (SWE, DNK, NOR, FIN, DEU, EU, EURO).
Response: JSON object with values[indicatorCode][countryCode][year] = number | string | null.
Used by: scripts/imf-client.ts → getWeoIndicator(), compareCountriesWeo(), getLatestWeoIndicator().
CLI: tsx scripts/imf-fetch.ts weo --country SWE --indicator NGDP_RPCH --years 15 --persist.
Scope: Datamapper surfaces WEO + Fiscal Monitor headline indicators. For anything else, use SDMX 3.0.

1.2 SDMX 3.0 (full catalogue)

Base URL: https://api.imf.org/external/sdmx/3.0
Authentication (required): every /data/... request to this surface MUST include the Ocp-Apim-Subscription-Key: <IMF_SDMX_SUBSCRIPTION_KEY> Azure APIM header. Without it the gateway returns an auth-mask HTTP 404 (not 401/403), which is silent and easy to misdiagnose. See agentic-integration.md §"Pre-warm gate" for the env-var forwarding chain.
URL pattern (canonical, on the wire): /data/dataflow/{agencyId}/{dataflowId}/{version}/{key}?startPeriod=…&endPeriod=… — the SDMX 3.0 REST shape.
URL pattern (human-readable, kept in docs/CLI): /data/{agencyId},{dataflowId},{version}/{key}?startPeriod=…&endPeriod=… — the legacy comma form. The ImfClient.sdmxFetch() client transparently rewrites comma → slash via normalizeSdmxPathForBase() before sending (scripts/imf-client.ts), because api.imf.org/sdmx/3.0 404s the comma form. Docs, CLI examples, and weoSdmxPath() keep the readable comma form for clarity.
Agency: IMF.STA (Statistics Department) for most datasets; IMF.RES (Research) for WEO; IMF.FAD (Fiscal Affairs) for FM.
Country codes: ISO 3166-1 alpha-3 (SWE, DNK, NOR, FIN, DEU) for every dataflow we cite. The legacy 3-digit numeric IMF AREA codes (e.g. 144=SWE) were retired in the 2026-05 SDMX 3.0 refactor; passing them now yields an empty dataSets[].series (HTTP 200, zero observations).
Response: SDMX-JSON 2.0.0 (application/vnd.sdmx.data+json;version=2.0.0).
Used by: scripts/imf-client.ts → sdmxFetch() (which applies the comma → slash rewrite + injects the subscription-key header).
CLI: tsx scripts/imf-fetch.ts sdmx --path "/data/IMF.STA,CPI,5.0.0/SWE.CPI._T.IX.M?startPeriod=2024-01" (CLI keeps comma form; client rewrites it).

1.3 Transport choice matrix

Dataset	Preferred transport	Notes
WEO	Datamapper (faster, JSON)	SDMX also works via `/data/IMF.RES,WEO,9.0.0/…`
FM	Datamapper	SDMX fallback via `/data/IMF.FAD,FM,4.0.0/…`
CPI	SDMX only	Dissolved out of legacy IFS in the 2026-05 refactor; v5.0.0
BOP / BOP_AGG	SDMX only	v21.0.0
GFS_COFOG	SDMX only	v11.0.0; ISO3 country, indicators `GF{02,07,09,10}_T`
MFS_IR (policy rates)	SDMX only	v8.0.1; `FPOLM_PA` retired for SWE — use `MMRT_RT_PT_A_PT` proxy
IMTS	SDMX only	v1.0.0; replaces retired DOTS dataflow; bilateral flows require partner-country dimension
PCPS	SDMX only	v9.0.0, agency `IMF.RES` (moved from `IMF.STA`)
ER (exchange rates)	SDMX only	v4.0.1; `ENDA_/ENDE_XDC_USD_RATE` retired — use `USD_XDC.PA_RT` / `EOP_RT`

2 · Dataflows

2.1 WEO — World Economic Outlook

Dataflow ID: WEO (SDMX), / root (Datamapper)
Agency: IMF.RES
Frequency: Annual (A)
Release cadence: April flagship (~3rd week) and October flagship (~2nd week). Update window publishes an "Update" (July / January) — subset of indicators; no new projections.
Projection horizon: T+5 (April 2026 release → 2026–2031 projections).
Vintage tag: WEO-YYYY-MM (e.g. WEO-2026-04). Stamp every projection with this.
Dimensions (SDMX key): FREQ.REF_AREA.INDICATOR
- FREQ = A
- REF_AREA = ISO-3 or aggregate (EU, EURO, G7, AE, WORLD)
- INDICATOR = e.g. NGDP_RPCH
Key indicators (complete list in indicators-inventory.json):
- NGDP_RPCH — real GDP growth, %
- NGDPD — nominal GDP, USD billions
- NGDPDPC — GDP per capita, current USD
- PPPPC — GDP per capita, PPP international $
- PCPIPCH — CPI inflation, average, %
- PCPIEPCH — CPI inflation, end of period, %
- LUR — unemployment rate, %
- LE — employment, millions
- LP — population, millions
- GGR_NGDP — government revenue, % of GDP
- GGX_NGDP — government expenditure, % of GDP
- GGXCNL_NGDP — net lending/borrowing, % of GDP
- GGXWDG_NGDP — gross debt, % of GDP
- BCA_NGDPD — current account, % of GDP
- TX_RPCH / TM_RPCH — exports / imports volume growth, %
Quirks:
- WEO LUR may differ from SCB AKU by 0.1–0.3 pp due to ILO definition; cite explicitly when adjacent to SCB numbers.
- GGXWDG_NGDP WEO vintage may diverge from the FM-vintage value of the same code by up to 1 pp in the same year — WEO is more aggregated, FM has later cutoff.
- Datamapper sometimes returns "n/a" as a string for missing observations; the client filters these via explicit null/NaN guards.

2.2 FM — Fiscal Monitor

Dataflow ID: FM
Agency: IMF.FAD
Frequency: Annual (A)
Release cadence: Aligned with WEO — April and October.
Projection horizon: T+5.
Vintage tag: FM-YYYY-MM (e.g. FM-2026-04).
Why use FM over WEO for fiscal: FM publishes cyclically-adjusted balances, primary balances, and debt-sustainability vintages that WEO does not.
Key indicators:
- GGXONLB_NGDP — primary balance, % of GDP
- GGSB_NPGDP — cyclically-adjusted primary balance, % of potential GDP
- GGXWDG_NGDP — gross debt (FM vintage)
- GGXCNLB_NGDP — primary net lending/borrowing

2.3 CPI — Consumer Price Index (replaces the legacy IFS monthly CPI block)

Dataflow ID: CPI (the legacy IFS dataflow no longer exists as a single SDMX 3.0 dataflow — its CPI block lives here, its policy-rate block in MFS_IR, and its exchange-rate block in ER).
Agency: IMF.STA
Version: 5.0.0 (post-2026-05 SDMX 3.0 refactor — 4.0.0 and the standalone PCPI_IX series were retired).
Frequency: Monthly (M), Quarterly (Q), or Annual (A).
Release cadence: Monthly, ~30–45 days after reference period.
No projections — historical only (use WEO:PCPIPCH for forward-looking inflation).
Dimensions (5): COUNTRY.INDEX_TYPE.COICOP_1999.TYPE_OF_TRANSFORMATION.FREQUENCY.
- COUNTRY — ISO3 (e.g. SWE). The legacy 3-digit IMF AREA code (144) is no longer accepted.
- INDEX_TYPE — CPI for consumer-price index; other values include PPI, WPI.
- COICOP_1999 — classification code; _T is "all items".
- TYPE_OF_TRANSFORMATION — IX (level / index), PC_PA (year-on-year %), PC_PP_PT (period-on-period %).
- FREQUENCY — M, Q, A.

Example SDMX path (Sweden all-items CPI level, monthly):

/data/IMF.STA,CPI,5.0.0/SWE.CPI._T.IX.M?startPeriod=2024-01

Quirks: All SDMX 3.0 dataflows now accept ISO3 directly as COUNTRY. The 2-letter ISO-2 (SE) and 3-digit numeric IMF AREA (144) are not accepted by IMF.STA/CPI v5.0.0 — verified live 2026-05-11.

2.4 BOP / BOP_AGG — Balance of Payments

Dataflow ID: BOP, BOP_AGG
Agency: IMF.STA
Version: 21.0.0 (post-2026-05 refactor).
Frequency: Quarterly (Q) or Annual (A).
Methodology: BPM6.
Dimensions (5): COUNTRY.BOP_ACCOUNTING_ENTRY.INDICATOR.UNIT.FREQUENCY.
Key measures: current account (CAB), capital account, financial account, reserve assets, errors and omissions.

Example SDMX path (Sweden current-account balance, USD, annual):

/data/IMF.STA,BOP,21.0.0/SWE.NETCD_T.CAB.USD.A?startPeriod=2020

Use case: Deeper external-sector detail than WEO's BCA_NGDPD.

2.5 GFS_COFOG — Government Finance Statistics by Function

Dataflow ID: GFS_COFOG
Agency: IMF.STA
Version: 11.0.0 (post-2026-05 refactor — indicator codes were renamed from G02/G07/G09/G10 to GF02_T/GF07_T/GF09_T/GF10_T).
Frequency: Annual (A).
Release cadence: T+1 (data for year Y released in late Y+1).
Methodology: GFSM 2014.
Dimensions (6): COUNTRY.SECTOR.GFS_GRP.INDICATOR.TYPE_OF_TRANSFORMATION.FREQUENCY.
- SECTOR — S13 (general government).
- GFS_GRP — G2MF (expense by function — main).
- INDICATOR — GF02_T (defence), GF07_T (health), GF09_T (education), GF10_T (social protection), etc.
- TYPE_OF_TRANSFORMATION — POGDP_PT (% of GDP), POTO_PT (% of total expenditure), XDC (national currency).
COFOG functions (critical for committee mapping):
- 01 General public services
- 02 Defence (GF02_T) → FöU
- 03 Public order and safety → JuU
- 04 Economic affairs
- 05 Environmental protection → MJU (partial — WB still primary)
- 06 Housing and community amenities
- 07 Health (GF07_T) → SoU
- 08 Recreation, culture, religion → KrU
- 09 Education (GF09_T) → UbU
- 10 Social protection (GF10_T) → SfU

Example SDMX path (Sweden defence spending, % of GDP, annual):

/data/IMF.STA,GFS_COFOG,11.0.0/SWE.S13.G2MF.GF02_T.POGDP_PT.A?startPeriod=2015

Use case: Committee-aligned spending decomposition when a report or motion concerns function-specific policy.

2.6 MFS_IR — Monetary & Financial Statistics, Interest Rates

Dataflow ID: MFS_IR
Agency: IMF.STA
Version: 8.0.1 (post-2026-05 refactor).
Frequency: Monthly (M).
Dimensions (3): COUNTRY.INDICATOR.FREQUENCY.
Key indicators (Sweden codelist, verified 2026-05-11): MMRT_RT_PT_A_PT (money-market rate, IMF proxy for the Riksbank policy rate), S13BOND_RT_PT_A_PT (sovereign-bond yield), MFS135_RT_PT_A_PT, MFS162_RT_PT_A_PT, MFS166_RT_PT_A_PT, MFS171_RT_PT_A_PT, GSTBILY_RT_PT_A_PT.

Example SDMX path (Sweden money-market rate, monthly):

/data/IMF.STA,MFS_IR,8.0.1/SWE.MMRT_RT_PT_A_PT.M?startPeriod=2024-01

Swedish relevance: The legacy FPOLM_PA central-bank policy-rate code is no longer in the SWE codelist. Use MMRT_RT_PT_A_PT as the IMF proxy and prefer Riksbank statistics directly for the official styrränta.

2.7 IMTS — International Merchandise Trade Statistics (replaces the legacy DOTS dataflow)

Dataflow ID: IMTS (the DOTS / DOT dataflow no longer exists in SDMX 3.0).
Agency: IMF.STA
Version: 1.0.0 (post-2026-05 refactor).
Frequency: Monthly (M), Quarterly (Q), or Annual (A).
Dimensions (4): COUNTRY.INDICATOR.COUNTERPART_COUNTRY.FREQUENCY.
Key indicators: XG_FOB_USD (exports FOB, USD — formerly TXG_FOB_USD), MG_FOB_USD / MG_CIF_USD (imports FOB / CIF, USD — formerly TMG_CIF_USD), TBG_USD (trade balance, USD).

Example SDMX path (Sweden exports to USA, annual):

/data/IMF.STA,IMTS,1.0.0/SWE.XG_FOB_USD.USA.A?startPeriod=2023

Use case: Bilateral trade flows — e.g. Swedish exports to Russia, EU, China. Critical for foreign-policy / sanctions coverage.

2.8 PCPS — Primary Commodity Prices

Dataflow ID: PCPS
Agency: IMF.RES (moved from IMF.STA to IMF.RES in the 2026-05 refactor).
Version: 9.0.0.
Frequency: Monthly (M).
Dimensions (4): COUNTRY.INDICATOR.DATA_TRANSFORMATION.FREQUENCY — COUNTRY=G001 (global aggregate), DATA_TRANSFORMATION=USD for nominal USD prices.
Key indicators: PALLFNF (all commodities, non-fuel), POILAPSP (oil, average of Brent/Dubai/WTI), POILBRE (Brent), POILWTI (WTI), POILDUB (Dubai).

Example SDMX path (Brent crude, monthly):

/data/IMF.RES,PCPS,9.0.0/G001.POILBRE.USD.M?startPeriod=2024-01

Use case: Inflation drivers commentary — tie Swedish CPI movements to commodity shocks.

2.9 ER — Exchange Rates

Dataflow ID: ER
Agency: IMF.STA
Version: 4.0.1 (post-2026-05 refactor).
Frequency: Monthly (M), Quarterly (Q), or Annual (A) — period-average and end-of-period variants.
Dimensions (4): COUNTRY.INDICATOR.TYPE_OF_TRANSFORMATION.FREQUENCY.
- TYPE_OF_TRANSFORMATION — PA_RT (period average), EOP_RT (end of period).
Key indicators: USD_XDC (USD per national currency), EUR_XDC (EUR per national currency), XDC_USD (national currency per USD), XDC_EUR, XDR_XDC, EREER_IX (real effective exchange rate index).

Example SDMX path (Sweden SEK/USD period-average, monthly):

/data/IMF.STA,ER,4.0.1/SWE.USD_XDC.PA_RT.M?startPeriod=2024-01

Use case: Monetary-policy coverage, export-competitiveness commentary.

3 · Aggregate country codes

IMF WEO publishes aggregates that make peer-comparison cleaner than adding up ISO-3 countries manually.

Aggregate	WEO code	SDMX equivalent	Description
European Union	`EU`	`EU`	27 member states
Euro Area	`EURO`	`EA`	20 member states
Advanced Economies	`AE`	`AE`	IMF classification
G7	`G7`	`G7`
G20	`G20`	`G20`
World	`WORLD`	`W0`

Use: For comparative-international.md, use EU and EURO as baseline aggregates alongside the Nordic peer set (SWE,DNK,NOR,FIN,DEU) — one batched compare call per indicator delivers all comparators.

4 · Release calendar (2026)

Date	Release
Late April 2026	WEO Apr-2026 (flagship) + Fiscal Monitor Apr-2026
Mid July 2026	WEO Update (subset, no new projections)
Mid October 2026	WEO Oct-2026 (flagship) + Fiscal Monitor Oct-2026
Mid January 2027	WEO Update

Action: On each flagship release (April / October), update DEFAULT_WEO_VINTAGE in scripts/imf-client.ts, the vintageDiscipline.current field in indicators-inventory.json, and the banner in analysis/imf/README.md in the same PR.

5 · Known quirks & caveats

5.1 Null / n/a observations

Datamapper returns null, "n/a", or omits the key for missing observations. The client filters via:

if (rawValue === null || rawValue === undefined) continue;
if (!Number.isFinite(numeric)) continue;

Never coerce via Number(x) without a Number.isFinite guard — Number(null) === 0 would silently inject bogus zeros.

5.2 Country code mismatches

Datamapper = ISO-3 (SWE)
SDMX WEO = ISO-3 (SWE)
SDMX IFS = ISO-2 (SE) in some dataflows
SDMX GFS / BOP = IMF AREA 3-digit numeric (144)

Use scripts/imf-codes.ts → toImfAreaCode(iso3) for SDMX-numeric mapping; the function throws on unknown codes (fail-loud — prevents silent data loss).

5.3 Vintage divergence

The same code (e.g. GGXWDG_NGDP) in WEO and in FM may differ by up to 1 pp in the same year because the two flagships have slightly different cutoff dates and revision policies. Rule of thumb: use WEO for headline macro, FM for debt-sustainability. When both are cited in the same article, disambiguate with the vintage tag.

5.4 Rate limiting

IMF advertises ~10 requests / 5 s. The client defaults to maxRetries=2 with 1s→2s back-off. Agentic workflows should:

Prefer compare (one call per indicator across the peer set) over parallel weo calls.
Sleep 1 s between separate imf-fetch.ts invocations.
Pre-warm 1 request at workflow start to avoid cold-start latency spikes.
Cache with --persist.

5.5 WEO `LUR` vs SCB AKU

WEO LUR uses ILO harmonised definition.
SCB AKU uses Swedish survey methodology.
Divergence: 0.1–0.3 pp typical.
Rule: SCB for Swedish-specific ground truth; IMF for cross-country comparison. When both cited, annotate the methodology difference.

5.6 Projection year detection

The client classifies any year > currentYear as a projection. This is correct for WEO/FM (which extend to T+5) but for IFS/BOP/GFS_COFOG — which have no projections — every observation is historical. Client tags projection: false for all non-WEO/FM datasets.

6 · Migration map — WB → IMF

WB code	IMF replacement	Rationale
`NY.GDP.MKTP.KD.ZG` (GDP growth)	`WEO:NGDP_RPCH`	Freshness + projections
`NY.GDP.MKTP.CD` (GDP USD)	`WEO:NGDPD`	Same
`NY.GDP.PCAP.CD` (GDP per capita)	`WEO:NGDPDPC`	Same
`FP.CPI.TOTL.ZG` (CPI inflation)	`WEO:PCPIPCH`	Same
`SL.UEM.TOTL.ZS` (unemployment)	`WEO:LUR`	Same; SCB still preferred for Swedish-specific
`GC.DOD.TOTL.GD.ZS` (central-gov debt)	`WEO:GGXWDG_NGDP`	GFSM 2014 general-government basis
`GC.XPN.TOTL.GD.ZS` (expenditure)	`WEO:GGX_NGDP`	Same
`GC.REV.XGRT.GD.ZS` (revenue)	`WEO:GGR_NGDP`	Same
`BN.CAB.XOKA.GD.ZS` (current account)	`WEO:BCA_NGDPD`	Same
`NE.EXP.GNFS.ZS` (exports)	`WEO:TX_RPCH`	Growth basis cleaner than % of GDP for trend articles

These WB codes remain read-only reference. New articles MUST cite the IMF counterpart; existing committed articles do not require retroactive update.

7 · Cross-references

analysis/imf/README.md — high-level overview & adoption strategy
analysis/imf/indicators-inventory.json — machine-readable catalogue
analysis/imf/indicator-policy-mapping.md — committee mapping
analysis/imf/agentic-integration.md — integration playbook for agentic workflows
analysis/imf/use-cases.md — canonical article examples
analysis/methodologies/imf-indicator-mapping.md — authoritative methodology
.github/aw/ECONOMIC_DATA_CONTRACT.md — validator contract (v2.1+)
scripts/imf-client.ts / scripts/imf-fetch.ts / scripts/imf-codes.ts / scripts/imf-context.ts — code surface