# SDMX provenance primitives

SDMX provides rich machine-traceable provenance but **prescribes no citation string**. The Content-Oriented Guidelines cover cross-domain concepts, code lists, subject-matter domains and the glossary — none prescribe citation. So the citation must be synthesised from the primitives below, aligned to DataCite and the RDA dynamic-data recommendations.

## The identity triplet

Every MaintainableArtefact — dataflow, DSD, codelist, concept scheme — is uniquely identified by:

```
{maintaining agencyID}:{artefact id}({version})
```

- Version defaults to `1.0` where unspecified.
- `latest`, or omitting the version, resolves to whatever version is currently in production. **Never cite unversioned.** A citation that silently re-points when the provider publishes a new version is not a citation.
- The triplet is enforced unique by the SDMX Global Registry.

## URN — the persistent identifier

```
urn:sdmx:org.sdmx.infomodel.{package}.{Class}={AGENCY}:{ID}({VERSION})
```

Example:

```
urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=ESTAT:ISOC_CI_ID_H(1.0)
```

Unlike a URL, which points to a resource's location, a URN provides only identity — it is permanent and will never change. Treat it as the SDMX analogue of a DOI for structural artefacts, and prefer it as the citation's persistent identifier **unless** the provider mints an actual DOI (OECD does), in which case prefer the DOI.

Common package/class segments: `datastructure.Dataflow`, `datastructure.DataStructure`, `codelist.Codelist`, `conceptscheme.ConceptScheme`, `categoryscheme.CategoryScheme`.

## Organisation roles

Three distinct roles in the Organisation Scheme, modelled separately even when the same body fills more than one:

| Role | Definition | Citation slot |
|---|---|---|
| **Agency / Maintenance Agency** | Maintains structural definitions — owns and versions the DSD, dataflow and codelists. The `agencyID` on every artefact. | Author / publisher |
| **Data Provider** | Reports or disseminates data sets or metadata sets. Linked to a dataflow via a **Provision Agreement**. | "Data source (if known)" — the element World Bank and OECD attribution wording asks for |
| **Data Consumer** | Collects or uses disseminated data sets. | Not cited |

Where agency and provider differ, both belong in the citation. This model is unchanged between SDMX 2.1 and 3.0.

## The query is the citable artifact

```
…/data/{agencyID},{dataflowID},{version}/{key}?startPeriod=…&endPeriod=…
```

Cite the **data query** — it returns the exact observations and is the reproducible artifact. The landing page is not: it renders a current view, not the view you cited. Keep the **structure query** (returning the DSD and codelists) separately where the reader needs to decode dimension codes; some tools, including ABS Data Explorer, generate both.

**Query identity and display naming are different concerns.** The URL reproduces the subset; it does not name it. The reader-facing label on that URL comes from the provider's formal title and selection metadata, never from the query string and never from a mechanism word. This is why "the query is the citable artifact" does not license link text reading `exact Data API query`.

"Exact" describes the selected observations only where the version, the period bounds and the vintage or fixity actually support the claim. A live query plus an extraction timestamp is reproducible on a best-effort basis, not an immutable snapshot — say `accessed`, not `snapshot`, unless the vintage is pinned.

Normalise the query before storing it: consistent parameter ordering, explicit version, explicit period bounds. An un-normalised query makes two identical citations look different and defeats deduplication.

**Normalised query identity** is the absolute URL with an explicit version, explicit period bounds where the provider supports them, stable parameter ordering and no fragment. The dedupe key for a source entry is:

```
agency_id + dataflow_id + version + normalized_query_url + extracted_at
```

`extracted_at` is in the key deliberately: two extractions of the same query at different vintages are two citable things, and collapsing them would claim a single vintage for numbers that have two.

## Vintage vs reference period

These are orthogonal and conflating them is the single most common provenance error.

- **Reference period** — the `TIME_PERIOD` dimension, the period the observation describes. Fiscal-year series carry `reportingYearStartDay`.
- **Vintage / extraction timestamp** — when you pulled the data. Captured by:
  - `asOf` — point-in-time retrieval, "time travel" to the data as it stood at a given instant. Standardised in the sdmx-rest specification. **This is the parameter that makes a citation reproducible.**
  - `updatedAfter` — returns deltas since a timestamp, with Append/Replace/Delete actions. Useful for revision tracking, not for citation.
  - SDMX also carries a "Data extraction date" cross-domain concept.
  - `includeHistory` is a **Fusion Registry implementation extra**, not core SDMX REST. Do not rely on it for portability.

Pin `asOf` where the provider supports it. Where it does not, record the wall-clock extraction timestamp in the citation and accept that reproduction is best-effort.

## Authoritative source

The **SDMX Global Registry** (registry.sdmx.org) is the central reference point and authoritative source for global DSDs, cross-domain concepts and code lists. It enforces triplet uniqueness and underpins the **URN Resolver** (urn.sdmx.io) and the **Global Discovery Service**. Together these three fill the role a DOI registration agency plays elsewhere.

*Unverified:* a "ROAP" convention appears in some secondary discussion but could not be confirmed in any SDMX source. Do not cite it. The authoritative-metadata role belongs to the Global Registry + URN Resolver + Global Discovery Service.

*Terminology drift:* SDMX is mid-rebrand ("SDMX" → "SDMx" on sdmx.org). Terminology and some URLs are in flux; the information model is not.

## Aligning with the RDA dynamic-data recommendations

The RDA Working Group on Data Citation recommendations apply directly to SDMX queries, because an SDMX subset is exactly the "dynamic data queried from a versioned database" case. Fourteen recommendations, grouped as versioning / timestamping / query identification. The ones that bind here:

| | Recommendation | SDMX implementation |
|---|---|---|
| R1 | Version the data | Cite the artefact version in the triplet; use `asOf` for the data vintage |
| R2 | Timestamp all operations | Record extraction timestamp |
| R3–R5 | Store, re-write and normalise the query | Persist the normalised REST query URL |
| R6 | Compute a result-set checksum | Hash the returned observation set for fixity |
| R7 | Timestamp the query | Distinct from R2: when the query ran |
| R8 | Assign a PID to the query | Resolves to a landing page and re-executes against the versioned store |

**Minimum viable implementation for a citation:** normalised query URL + extraction timestamp + artefact version. **Better:** add a result-set checksum, so a reader can verify they got the same data back. **Best:** mint a PID for the query itself.

## FORCE11 Joint Declaration of Data Citation Principles

Eight principles that justify the above: Importance; Credit and Attribution; Evidence; Unique Identification; Access; Persistence; Specificity and Verifiability; Interoperability and Flexibility.

The "Evidence" principle is the one that grounds the pre-emit check that every non-trivial number has a resolvable source. "Specificity and Verifiability" is what forces citation of the query rather than the dataset.

Cite as: Data Citation Synthesis Group, *Joint Declaration of Data Citation Principles*, Martone M. (ed.), FORCE11, 2014, https://doi.org/10.25490/a97f-egyk