sdmxlib

Note: This library has been written extensively with AI assistance (Claude Code). Users who are not comfortable with AI-generated code should take that into account before adopting it.

SDMX structural metadata library for Python. Fetch and navigate Data Structure Definitions, Codelists, Dataflows, and related artefacts from any SDMX REST endpoint — with plain attribute access, no XML or URN chasing required.

Quick start

import sdmxlib as sl

with sl.RestRegistry(sl.Provider.BIS) as reg:
    urn = sl.DataStructure.urn_for(agency="BIS", id="WS_CBPOL")
    dsd = reg.get(urn, resolve=True)

    for dim in dsd.dimensions:
        if dim.is_enumerated:
            cl = dim.representation()
            print(f"{dim.id}: {cl.id} ({len(cl.codes)} codes)")

FREQ: CL_FREQ (7 codes)
REF_AREA: CL_BIS_IF_REF_AREA (44 codes)
INSTR_ASSET: CL_INSTR_ASSET (12 codes)
BORROWER_CTY: CL_BIS_IF_REF_AREA (44 codes)

Installation

uv add sdmxlib
# or: pip install sdmxlib

What it does

Connects to any SDMX 2.1 or 3.0 REST endpoint; built-in shortcuts for ECB, BIS, ESTAT, IMF, OECD, and the SDMX Global Registry via sl.Provider
One read, with resolution depth as a parameter: get(urn) for a skeleton, get(urn, resolve=True) for the full reference graph, resolve=[sl.Codelist] for named types only, and partial=False for untrimmed schemes
Returns fully resolved domain objects with plain attribute access — no XML, no URN chasing
Filter collections with lambdas or the item() expression API
Build SDMX artefacts locally and serialise to SDMX-ML or SDMX-JSON
LocalRegistry — a DuckDB-backed persistent store for offline access, and a position in a RestRegistry's source chain via store=
A path query language over both planes: reg.query(sl.q.dataflow) for structures, reg.observations(flow) for rows with lazy codelist + hierarchy loading, automatic Ref resolution, and direct SQL code maps; supports shared connections and any-language queries
Uniform SKOS-aligned tree API (roots/leaves/narrower/broader/ *_transitive/depth_of plus bulk projections depths/broader_map/ ancestors_map/inherit_along_broader) on Codelist, Hierarchy, CategoryScheme, MetadataStructure — and their lazy SQL variants LazyCodelist/LazyHierarchy
Reference metadata via MetadataStructure (MSD), Metadataflow, and MetadataSet — attach typed footnotes, methodology notes, or quality reports to any identifiable artefact. Definitions ride in StructureMessage; populated payloads ride in MetadataMessage (<mes:GenericMetadata> in SDMX-ML 3.0; metadata-schema envelope in SDMX-JSON 2.0). Both message kinds round-trip through Registry, JSON, and XML.
Integrates with Polars for schema generation and data validation
Fully typed — IDE completion and static analysis work throughout

For AI assistants

Two condensed reference files at the repo root are written for LLM tools (Claude Code, Cursor, Copilot, etc.):

llms.txt — full library overview: install, registries, data fetching, reference metadata, and the domain-type cheat sheet
llms-dsl.txt — focused query-DSL reference: sl.item / sl.q / sl.dim predicates, the Query / Frame / DataQuery chains, and the uniform SKOS tree API

Point your assistant at these to keep generated code aligned with the library's actual surface.

Upgrading

sdmxlib is pre-stability and breaks cleanly rather than carrying two spellings of the same idea. If you are coming from 0.48, read Upgrading — sl.Registry is now sl.LocalRegistry, get() takes a URN and a resolution depth, and the four query DSLs are one path language.

Documentation

See the docs for the full cookbook, including:

Connecting to registries and choosing a resolution depth
Persisting artefacts in a local DuckDB store with LocalRegistry
Querying structures and observations with the sl.q path language
Fetching observation data and pivoting to wide format
Inspecting DSDs and building code maps for ETL pipelines
Generating Polars schemas from SDMX Data Structure Definitions
Browsing data catalogs and filtering dataflows
Working with constraints, hierarchies, and serialisation

Development

just check           # lint + typecheck
just test            # unit tests
just test-integration  # live endpoint tests (requires network)
just ci              # full pre-commit gate

Metadata

Release files for sdmxlib 0.61.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sdmxlib 0.61.0
File	Size	Uploaded
sdmxlib-0.61.0.tar.gz	603.7 kB	Aug 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for sdmxlib 0.61.0
File	Interpreter	ABI	Platform	Reset
sdmxlib-0.61.0-py3-none-any.whl 677.8 kB Aug 25, 2026	Python 3	none	any	Details

Total release size: 1.3 MB

Release files / sdmxlib-0.61.0.tar.gz

Download URL	sdmxlib-0.61.0.tar.gz
Size	603.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`8811033741cac307a853fa08d7b6520d97fa25a2e90e2f2412203547e83bae60`
BLAKE2b-256 checksum How to use checksums	`3e5e74f62866301f0f4f305a1a0dd00ba236d55263745c57b5ef65fdcaec959d`
Upload date	Aug 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / sdmxlib-0.61.0-py3-none-any.whl

Download URL	sdmxlib-0.61.0-py3-none-any.whl
Size	677.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`48495eaa77ddb47c0a38c3329dcda46fc909849fb44bac39590399edad4d1a59`
BLAKE2b-256 checksum How to use checksums	`90315a27dc0458eec4d4a5fc40a6a32eec81d86cd2f0e55a2edd9ca150ddd7b4`
Upload date	Aug 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`