---
name: citing-official-statistics
description: Cites and provenance-tags figures from official statistics — SDMX dataflows, ABS, OECD, Eurostat, ILOSTAT, Statistics Canada, World Bank, UN. Fires at emission, whenever a number reaches the reader — prose, report, table, chart, slide, dashboard, media release, one-line answer — including plain lookups, derived and cross-provider values, and series named in a refusal or escalation, even when citation is never mentioned. Covers the citation skeleton, extraction date and vintage, DOI/URN/query-URL precedence, quality flags, table source lines, footnote markers and mandatory licence attribution wording. Excludes computation admissibility (guarding-derived-indicators) and series combinability (reasoning-linkage-confidence).
license: CC-BY-4.0
metadata:
  author: Aard
  homepage: https://aard.ai
---

# Citing official statistics

Numbers from statistical agencies carry obligations that ordinary prose citation does not handle: the value has a vintage separate from its reference period, it may carry a quality flag that changes its meaning, its units may be scaled by a multiplier held in metadata, and the licence usually mandates specific attribution wording. This skill encodes one citation grammar plus the per-source lookups that vary.

The governing principle: **a reader must be able to re-fetch the exact number.** Not the dataset — the number. That means identifier, query, and extraction timestamp, not just a homepage link.

## Workflow

1. **Choose a document profile** (below). It determines whether a reference list exists, which footnote markers to use, and how much methodological caveat travels with each number.
2. **Check for an overriding house style.** If the host document declares APA/Chicago/Harvard or an agency style, defer to it for mechanics and keep only the provenance elements from this skill (extraction date, identifier, flags).
3. **Resolve the formal name from source metadata, before assembling anything.** Take the agency's published table or resource title where it supplies one; otherwise take the SDMX dataflow/structure name carried in the source's own metadata. Never promote a user's phrasing, a chart headline or your own paraphrase into the citation's title — an invented formal name is a false citation, and it is false in the one field a reader uses to find the data again.
4. **Build each citation** from the invariant skeleton, populated from source-native primitives.
5. **Run the pre-emit checks** before any number leaves the pipeline.
6. **Confirm the per-dataset licence and render it once** in the canonical source block below. Where the licence mandates source-acknowledgement wording, satisfy it *inside* `Source:` rather than by appending a second source sentence.

## The invariant citation skeleton

Every citation resolves to this shape, which maps onto DataCite's mandatory properties (Identifier, Creator, Title, Publisher, PublicationYear, ResourceType):

```text
Agency (Reference period) Title [medium/identifier].
Selection: selected official labels, reproducible data link, response format,
accessed date.
Licence: confirmed licence and terms URL.
```

The three name-like elements are distinct and are not interchangeable:

- **Title** — the provider-authored name of the whole resource: a published table title, or the SDMX dataflow/structure name. Verbatim, including its spelling and capitalisation.
- **Selection** — which observations inside that resource were taken, labelled in the provider's own words. Present only where the citation covers a subset. Where the provider itself publishes a formal title for a series inside a larger resource, that title *is* the selection, as a single label.
- **Response format** — CSV, SDMX-CSV, JSON, XLSX: how the bytes were served. It is a transport fact, never part of a name, and it sits outside the linked text.

Two further elements do the heavy lifting and are the ones most often dropped:

- **Reference period ≠ publication year.** Use the period the data describes (`2021-Q3`, `2015–2024`), not the year the page was published. If both matter, reference period in the parentheses, publication year in the title block.
- **Access/extraction date is mandatory, not decorative.** Agency databases are continuously revised; ABS states this explicitly as the reason. A citation without it is not reproducible.

Omit the publisher when the agency is also the publisher (ABS, OECD). Include it when they differ (ILO is the agency, ILOSTAT the database/publisher).

Worked examples for each major agency are in `references/agency-formats.md` — read it when citing a source whose exact house wording you are unsure of. Several agencies publish mandatory "how to cite" wording; where they do, that wording wins over the generic skeleton.

## SDMX sources

SDMX has no canonical bibliographic citation format, so synthesise one from its provenance primitives. Map them onto the skeleton like this:

| Skeleton slot | SDMX primitive |
|---|---|
| Agency | maintaining `agencyID`, resolved to the organisation's full name |
| Reference period | span of `TIME_PERIOD` actually used, not the dataflow's full coverage |
| Title | the provider-authored dataflow/resource name, followed by the `AGENCY:ID(VERSION)` triplet |
| Selection | the provider-authored member labels for the selected dimensions, kept in DSD order |
| Response format | CSV, SDMX-CSV, JSON or other transport representation — outside the formal name |
| Medium | `[SDMX dataflow]`, `[Data Explorer]`, `[SDMX API]` — bibliographic renderings only, see below |
| Persistent identifier | DOI if the provider mints one, else the URN |
| Reproducible artifact | the REST **data query** URL |
| Accessed | extraction timestamp, pinned via `asOf` where supported |

Four things to get right:

- **Version the triplet.** `AGENCY:ID(VERSION)`. An unversioned reference resolves to whatever is in production today, which defeats the purpose. Version defaults to `1.0` when unspecified.
- **Prefer the URN as the identifier**: `urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=ESTAT:ISOC_CI_ID_H(1.0)`. A URL points at a location; a URN is permanent and identity-bearing — the SDMX analogue of a DOI.
- **The query URL is the citable artifact, not the landing page.** Cite the data query (returns the observations), and keep the structure query separately if the reader needs the DSD.
- **Distinguish maintenance agency from data provider.** The Agency owns and versions the structural definitions and is the author/publisher. The Data Provider reports or disseminates the data and is the "data source" element that OECD and World Bank attribution wording asks for. They are often the same body but are modelled separately, and where they differ, both belong in the citation.

**Medium and the triplet compete for one bracket, and the triplet wins.** In the canonical block the bracket carries the versioned identifier — `[ABS:IIP(1.0.0)]` — because that is what resolves to the artefact; adding the medium as well gives `[SDMX dataflow, ABS:IIP(1.0.0)]`, which is longer and identifies nothing further. Supply `medium` where there is no triplet, or for the bibliographic footnote and reference-list renderings where access route is conventionally stated. Both examples in `references/agency-formats.md` and `references/profiles.md` show the triplet alone for this reason.

`references/sdmx-provenance.md` covers vintage handling (`asOf` vs `updatedAfter`), the Global Registry's role, and how to align a query citation with the RDA dynamic-data recommendations. Read it when citing an API query rather than a published table.

Run `scripts/sdmx_cite.py` to assemble the citation, construct the URN and check for missing provenance fields rather than composing these by hand — the URN grammar, the reference-period/extraction-date split and the projection below are all easy to get subtly wrong.

## From the query key to the reader's line

A full SDMX key names every dimension. A readable selection label does not, and cutting it down by taste is how invented series names get created. Cut it down by rule instead — this is a **display projection over retained provenance, not a discard**:

1. Retain every selected dimension, code and label in the provenance unit. Nothing here removes anything from the unit or from the query.
2. Assign each selected member exactly one `citation_role`, and record the evidence for it: `identity`, `interpretation` or `neutral_scope`.
3. **Default to `identity`.** Assign `interpretation` only from a bound concept identity — frequency, unit or currency, multiplier, adjustment, price basis or another named interpretation concept. Assign `neutral_scope` only where the provider's codelist or code semantics identify the selected member as the aggregate or default; never from an English-label substring such as the word "Total" alone. Record the evidence in the prefixed form `concept:<ID>`, `codelist:<ID>` or `provider_aggregate:<ID>` — prose describing the evidence is not the evidence, and the renderer rejects it. Full grammar in `references/units-and-tiers.md`.
4. Join the `identity` member labels, in DSD order, to form `Selection:`.
5. Render the `interpretation` members plus unit and attribute metadata as ordered `Note:` clauses. Omit verified `neutral_scope` members from the human text while keeping them in the bounded query and in structured provenance.

Where the evidence for a role is unavailable, keep the member as `identity` rather than guessing. Over-stating a selection is a readability cost; under-stating it misdescribes which numbers were used.

The fields this reads and writes — `resource_title`, `resource_kind`, `resource_title_status`, `selected_members` with its per-member `citation_role` and `role_evidence`, `selection_basis`, `selection_labels`, `selection_status`, `response_format`, `licence_label`, `licence_url`, `notes`, `query_url` and `extracted_at` — are defined once in `references/units-and-tiers.md` and arrive already populated. This skill owns the role assignment and the projection; it does not own the labels.

**Worked projection — `ABS:IIP(1.0.0)`, key `6.903A.3000999.TOT.T.700.10.Q`.** The labelled response supplies structure name *International Investment Position* plus eight member labels. They project like this:

| Dimension | Member label | Role | Where it lands |
|---|---|---|---|
| Measure | Position at end of period | identity | `Selection:` |
| Data item | Foreign Liabilities, Total foreign debt | identity | `Selection:` |
| Sector | General Government Total | identity | `Selection:` |
| Maturity | Total | neutral_scope | query key only |
| Industry | Total | neutral_scope | query key only |
| Currency | Australian dollar | interpretation | `Note:` |
| Adjustment type | Original | interpretation | `Note:` |
| Frequency | Quarterly | interpretation | `Note:` |

`Maturity=TOT` and `Industry=T` stay in the bounded query as provider-verified `neutral_scope` — they are still part of what was fetched, and the reader can still re-run the exact query.

**Note formatting is deterministic.** Generic SDMX renders `Dimension label: Member label` clauses in source order, plus explicit unit and multiplier clauses. The ABS Profile 4 formatter alone composes the verified adjustment, frequency, currency and multiplier values into `Original quarterly observations` and `Australian dollars, millions`. That composition is scoped to the canonical block; it does not change the legacy per-agency bibliography renderings.

**`query_url` stays the technical field name.** It is the reproducible artifact and the schema field; do not rename it to a presentation label because its link text now reads differently.

**Link text names the data, never the mechanism.** Link the official series title or the formal selection. Do not expose `exact query`, `Data API query`, `API call`, `query URL`, `data URL` or `click here` to a reader. Use `snapshot` only where the vintage or result set is genuinely pinned.

## Table and figure sourcing

Items below a table go in this order, grouped at the end of the table, each indented and italicised with a colon:

1. `Source:`
2. `Licence:`
3. `Note:` — general explanation, abbreviation keys, rounding statement
4. Footnotes, keyed by marker

**Render each field label exactly once, in the singular.** Three sources go inside one `Source:` field, not into `Sources:` and not into three `Source:` lines. The same holds for `Licence:` and `Note:`. Field cardinality is what makes the block machine-readable and what stops a citation growing a second, abbreviated credit line beside the full one.

Deduplicate within a field, and deduplicate on the right key — the keys differ per field because the fields identify different things:

- **Sources** deduplicate on agency/dataflow/version, normalised query identity and extraction vintage. Two distinct selections that happen to share a dataflow title are two sources; collapsing them hides which numbers came from where.
- **Licences** deduplicate on normalised licence URL plus display label.
- **Note clauses** deduplicate after whitespace normalisation.
- **Selection labels never deduplicate.** Two different dimensions can legitimately carry the same displayed label, and dropping the second one silently changes which slice was cited.

**Markers inside tables and figures: use lower-case letters** (`a`, `b`, `c`…), read across rows then down; switch to arabic numerals if the series runs past `z`. This is not arbitrary fussiness — numbered markers inside a table collide visually with the data and with quality flags. **Markers in body text: use numbers.** Where symbol-marked and number-marked notes appear on the same page, symbol notes sit above.

A marker on a column head or stub entry governs the whole column or row and is not repeated in each cell.

Some agencies go further and forbid superscripts entirely in datasets, signposting with `[note 1]` and putting codes in a separate column. Follow that pattern for Profile 4 (data portals and dashboards) and any machine-readable output, where superscripts corrupt the value.

**Units belong in a headnote** in parentheses below the title — `(Thousands of United States dollars)`, `(Percentage)` — spelled out, not `(000 US$)` or `(%)`. Where units differ by column, put them in the column head. Always state: current vs constant prices, base/reference period, chain-linking, PPP vs market exchange rates, and original vs seasonally adjusted vs trend.

Standard rounding note: *"Where figures have been rounded, discrepancies may occur between the sums of the component items and totals."*

Conventional "no data" symbols in tables: en dash (–) for nil or negligible, two dots (..) for not available, `n/a` for not applicable. Note that these are *presentation* conventions and differ from the source's own flags — see below.

## Data-quality flags

There is no shared standard here. Eurostat uses lower-case letters, ABS uses dots and asterisks, Statistics Canada uses letter grades keyed to coefficient of variation, SDMX uses single-character codes in a DSD-declared code list. The same letter means different things in different systems, and often in different *providers'* SDMX lists too. Two different jobs follow. **Publication symbols** — Eurostat's `:c`, ABS's `n.p.`, StatCan's grades — resolve from `references/flags.md`, which owns them. **SDMX `OBS_STATUS`/`CONF_STATUS`** resolve at runtime against the code list this dataflow's DSD names: read it from `inspect`, then `sdmx_cite.py flag --code <CODE> --codelist <file>`. Nothing is hardcoded for those, because a shipped table answers for dataflows it has never seen — a cross-domain copy once glossed `R` as "revised" when it means "excludes one or more subcategories". If you cannot resolve a code, report it raw and publish no meaning. Never carry a flag across systems unmapped.

Three rules that do generalise:

- **Render flags as codes in a separate column or legend**, never as inline superscripts against the value, where they can be mistaken for footnote markers or digits.
- **Never silently drop flagged observations.** Not-available and confidential markers must be shown as such. A gap the reader cannot see is worse than a gap they can.
- **A flag changes what the number means**, so it must survive into any derived figure. If you aggregate over a series containing a break or a provisional value, say so in the note on the aggregate.

## Pre-emit verification

These are the checks that apply to a **single observation on its way to the reader**. They are about stating a number correctly, not about whether the number should have been computed — cross-operand compatibility belongs to `guarding-derived-indicators`, and whether two series may be combined at all belongs to `reasoning-linkage-confidence`. If those skills are in play, they run first and this list runs on their output.

- **Every non-trivial number has a resolvable source.** Commonly known or easily verifiable facts do not need one; a statistic does. This is the "Evidence" principle in the FORCE11 declaration.
- **Title and selection text came from provider metadata.** Trace each to the labelled response, the DSD/codelist or the published table title. If you cannot, you do not have a formal name — see the refusal rule below.
- **Response format is outside the formal name.** `… Foreign Debt Series CSV` is not a title the ABS publishes; `(CSV)` after the link is the same fact stated correctly.
- **A confirmed licence name is present,** with its terms URL where the provider publishes one. Confirmed per dataset, not assumed from the portal default or from the agency name.
- **The agency appears once in the source block,** unless a licence mandates verbatim wording that repeats it.
- **No query-mechanism label reaches the reader.** Link text names the data.
- **Units and multipliers read correctly.** Check `UNIT_MEASURE`, `UNIT_MULT` (a power-of-ten multiplier applied to the value) and `DECIMALS`. A value of `1.2` with `UNIT_MULT=6` is 1.2 million; reporting it as 1.2 is a six-order-of-magnitude error that needs no arithmetic to occur. State the multiplier in the headnote or column head.
- **Seasonal adjustment labelled.** Original, seasonally adjusted and trend are different series; an unlabelled figure is ambiguous even when quoted alone.
- **Flags rendered, not dropped.** Every not-available, confidential, provisional, estimated or break marker on the observation appears in the output. A gap the reader cannot see is worse than one they can.
- **Reliability thresholds stated where reliability markers are used** — what RSE band the asterisk denotes, what CV range the letter grade covers. A marker without its threshold is uninterpretable.
- **Extraction timestamp pinned.** One timestamp per table, or the mismatch noted explicitly. Without it the citation is not reproducible.
- **Breaks and revisions annotated.** Where the observation carries a break flag, note the methodological or definitional change and preserve `PRE_BREAK_VALUE` where the source supplies one. Explain significant revisions briefly rather than exhaustively.
- **Converted figures state the rate, its date, and whether market or PPP.** This is a disclosure obligation on the reported value; whether the conversion was legitimate is a separate question answered upstream.
- **Derived figures labelled as derived.** A ratio, growth rate, share or rebased index you computed is not something the agency published. Tag it *"calculated by [author] from [source]"* — naming the underlying source, since attributing to "Author" alone hides the provenance while attributing to the agency alone falsely implies they published it. Licences that permit reuse generally require you to indicate that changes were made and to avoid implying endorsement. Note this is the *attribution* consequence of a derivation; whether the derivation was admissible is decided upstream.

**When the official name cannot be obtained, say so — do not supply one.** If the title or the member labels will not resolve from provider metadata, keep the versioned identifier and the dimension codes, set the availability state to `unavailable` on the field that failed, refuse to render a publication-ready Profile 4 block, and report which metadata is unresolved. A codes-only citation is honest and re-fetchable. A citation carrying an invented formal name passes every check and is wrong in the field a reader trusts most.

## Boundaries

This skill fires at **emission** — when a number reaches the reader. The Aard linkage skills fire at **construction** — when a question is decomposed, when units are combined, when arithmetic runs. They are orthogonal, not sequential:

| Situation | Construction skills | This skill |
|---|---|---|
| Single published figure quoted in prose | — | fires |
| Growth rate computed from one dataflow | decompose, guard | fires |
| Cross-provider ratio | all three | fires |
| Intermediate value never surfaced | all three | does not fire |
| Refusal to combine two series | decompose, linkage | fires — cite what you declined to combine |

Do not treat this skill as the last stage of a pipeline. Treating it that way makes it under-trigger on plain lookups, which are the most common case and the one where a missing extraction date does the most damage.

Where the concerns look identical, they divide by arity:

| Fact | Here (one observation) | `guarding-derived-indicators` (across operands) |
|---|---|---|
| `UNIT_MULT` | read it for the value quoted | check the multipliers agree |
| `ADJUSTMENT` | label the series | block mixing adjusted with raw |
| Currency | state rate and date on the reported figure | block converting growth rates and same-currency ratios |
| Break flag | note it, keep the pre-break value | switch basis or refuse the span |
| Derived figure | attribute the calculation | decide whether the calculation is legitimate |

Two kinds of citation coexist and never substitute for one another. **Data citations** — this skill — identify which observations, from whom, pulled when. **Authority citations** — the linkage skills' source registry — identify the methodological rule that grounds a decision, e.g. why chain-linked volumes do not sum. A decision record needs both; merging them loses the distinction between what you used and why you were allowed to use it.

## Licensing and attribution

Licence terms constrain citation wording, and several are mandatory rather than advisory. World Bank requires a specific three-part attribution string plus no-endorsement and no-association clauses; OECD requires a credit line with DOI and access date and explicitly forbids `Source: OECD` or `Source: Authors` as the sole attribution for data; ABS requires acknowledgement as source in all reproduction. Exact strings are in `references/licensing.md` — read it before publishing anything externally, and check the per-dataset licence, since some datasets within an otherwise open portal carry more restrictive terms.

The confirmed licence goes in the canonical block's own `Licence:` field, between `Source:` and `Note:`. Agency-specific mandatory wording **replaces the generic content of `Source:`**; it is never appended after it. A licence that requires the agency to be acknowledged as the source is already satisfied by a complete source line naming that agency — a trailing `Source: ABS` after a full ABS citation is a duplicate, not compliance.

## Document profiles

Pick one at the start; it governs mechanics throughout.

| Profile | Reference list | Source placement | Markers | Caveat load |
|---|---|---|---|---|
| **1. Short release / media** | No | Inline `Source:` line; caveats in prose | Minimal; flags only | High-salience only: seasonal adjustment, provisional status, key revisions |
| **2. Flagship / annual report** | Yes, plus statistical annex | `Source:` under each table, then `Licence:`, then `Note:`; lettered footnotes | Lettered in tables, numbered in body | Full — annex carries per-series source, units, base, flags |
| **3. Technical / methodological** | Yes, full bibliography | Source line plus numbered footnotes; methods in text | Numbered | Maximal — full methodology, reliability measures, definitions |
| **4. Data portal / dashboard / slides** | No | Canonical block — `Source:`, `Licence:`, `Note:` — with the formal selection carrying the data link | Flags as codes in a separate field | Metadata-driven: flags, extraction date, query link |

Standards and methodological instruments (ICLS resolutions, SNA, SDMX guidelines) are a sub-mode of Profile 3: cite by instrument name and adopting body rather than as a publication.

Fuller guidance per profile, including what to do when a table's source note can substitute for a reference-list entry, is in `references/profiles.md`.

## Footnote mechanics

- First citation gives the full reference in the footnote; subsequent citations use a shortened form, with `ibid.` for an immediately repeated identical source. Repeat a full reference only for clarity or to change a specific element.
- In body text, the numbered indicator goes after the phrase or sentence being substantiated, after punctuation in English. The footnote carries the full citation including access date.
- In a table cell, use a lettered marker; the source goes in the table's `Source:` line and specifics in the lettered footnote. Do not put numbered footnotes inside tables.
- Prefer page-bottom or end-of-section footnotes over endnotes for agent-generated documents.
- A source given in full under a table may be omitted from the reference list. A numbered body-text data citation should resolve to a reference-list or endnote entry in longer documents.

## Reference files

- `references/agency-formats.md` — exact citation wording per agency (ABS, OECD, ILOSTAT, Eurostat, Statistics Canada, World Bank, UN) and the DataCite mapping.
- `references/flags.md` — per-agency publication-symbol tables and reliability thresholds. SDMX `OBS_STATUS`/`CONF_STATUS` are **not** tabulated there; they are resolved at runtime from the DSD's own code list.
- `references/sdmx-provenance.md` — URN grammar, triplet versioning, `asOf`/`updatedAfter`, organisation roles, RDA dynamic-data alignment.
- `references/licensing.md` — mandatory attribution strings and licence constraints.
- `references/profiles.md` — the four document profiles in detail.
- `references/units-and-tiers.md` — the data-unit schema this skill consumes, the attribution principle, and the decision-record `citations[]` block this skill populates.
- `references/source-registry.md` — authority citations, owned by the construction skills. Distinct from data citations; see Boundaries above.
- `scripts/sdmx_cite.py` — build a citation and URN from SDMX artefact fields; look up a flag; validate provenance completeness. Run `python3 scripts/sdmx_cite.py --help`.