Skip to content

Publication Table

A Publication Table describes a table for disseminating data: the dataflows it reads from, the header rows, and the body rows whose cells are observation keys or calculations. It can also hold variables, observation formatting, missing value rules and footnotes. Publication Tables are a Fusion extension to SDMX, provided by the fusion-sdmx-publicationtable module. Documents start ref: "PublicationTable=AGENCY:ID(1.0)".

Simple form

The document starts with the common header, followed by the dataflows, the header rows and the body rows.

format: "fusion-yaml(1.0.0)"
ref: "PublicationTable=TEST:TEST(1.0.0)"
name: "Test PT"
dataflows:
- dataflow: "TEST:BANKING(1.0)"
header:
- row:
  - cell: "Employed"
  - cell: "UnEmployed"
body:
- row:
  - "2010"
  - "A:UK:EMP:2010"
  - "A:UK:UEMP:2010"
- row:
  - "2011"
  - "A:UK:EMP:2011"
  - "A:UK:UEMP:2011"
Source: publicationtable/testFixedObs.yaml

  • dataflows: an array with one object for each dataflow the table reads from. dataflow is the short URN of the Dataflow (AGENCY:ID(VERSION)); the field name gives the class.
  • header: an array of header rows. Each row is an object with a row array of cells, and each cell is an object with its label in cell.
  • body: an array of body rows. Each row is an object with a row holding strings: the first string is the label of the row's head cell, and the rest are the cells' observation keys (or calculations such as ":=[A:UK:EMP]+10"). row follows the value or array rule, so a row with only a head cell label is written as a string, e.g. - row: "UK Data".

Labels and keys can contain variables such as $(P) or $(REF_AREA); these are plain strings in the canonical format.

Complete example

The example below shows every optional field. It is assembled from the golden files testVariableDimensionsMultipleFlows, testFootnotesAndTimeFormat, testMissingValueRepMap, testObservationFormatting, testExternalVariables, testConditionalVariables and testVariableMappings, with long lists trimmed.

format: "fusion-yaml(1.0.0)"
ref: "PublicationTable=TEST:TEST(1.0.0)"
name: "Test PT"
dataflows:
- alias: "DF1"
  dataflow: "TEST:BANKING1(1.0)"
- alias: "DF2"
  dataflow: "TEST:BANKING2(1.0)"
timeFormat: "RepresentationMap=TEST:TIME_FORMAT(1.0)"
missingValues:
  component: "OBS_STATUS"
  default: "-"
  representationmap: "TEST:MV_MAP(1.0)"
obsFormat:
- keys:
  - "=A:UK+FR:EMP"
  - "=A:+UEMP"
  decimals: 2
  round: "HALF_UP"
  scientificNotation: true
- locale: "en"
  significantFigures: 1
  round: "DOWN"
  normalise: true
- scalingFactor: 2
variables:
  VAR_CL: "Codelist=TEST:CL_VAR(1.0)"
  VAR_VL: "ValueList=TEST:VL_VAR(1.0)"
conditionalVariables:
- id: "BANKNOTE"
  name: "Banknotes"
  dimension: "REF_AREA"
  values:
    NOTE1:
      UK: "£5"
      FR: "5Eur"
      US: "$5"
variableMappings:
- input: "REF_AREA"
  output: "INDICATOR"
  representationmap: "TEST:VAR_DIM_REPMAP(1.0)"
header:
- row:
  - cell: "$(REF_AREA)"
    colSpan: 2
- row:
  - cell: "$(P)"
  - cell: "$(P-1)"
body:
- row:
  - "$(INDICATOR)"
  - "DF1.A::"
  - "DF2.A:::P-1"
footnotes:
- text: "Data are incomplete"
- text: "Provisional figures"

Simple values become richer in these cases:

  • Dataflows. alias is written before dataflow only when the dataflow has a non-empty alias. Aliases are used when the table reads more than one dataflow, and prefix the observation keys (DF1.A::).
  • Header cells. A cell is {cell: "label"}. rowSpan and colSpan are added only when greater than 1.
  • Observation formatting. Each obsFormat entry applies to the observations matching its keys (a value or array). locale is a language code, or "dynamic" to use the viewer's locale. Precision is written as either decimals or significantFigures, and round (a Java RoundingMode name) is written only with a precision. normalise and scientificNotation are written only when true. scalingFactor is a number.
  • Variable mapping output. output is a value or array of dimension ids.
  • Footnotes. Each footnote is an object of localised text: text for English, text-<locale> for other languages.

The references in this artifact use two styles (see references):

  • Where the field name is the lower-case class of the target, the value is a short URN: dataflows[].dataflow (dataflow: "TEST:BANKING(1.0)") and the mapping in missingValues and variableMappings (representationmap: "TEST:MV_MAP(1.0)").
  • Where the field name does not determine the type, the value is a canonical value with the class: timeFormat (RepresentationMap=...) and the values of variables (Codelist=... / ValueList=...; a variable can reference either a Codelist or a Value List).

Field reference

Body fields, in written order:

Field Value Written when
dataflows Array of dataflow objects The table has dataflows
timeFormat Canonical value of a Representation Map A time format mapping is set
missingValues Object (below) Missing value rules are set
obsFormat Array of formatting objects There are observation formatting rules
variables Map of variable id to canonical value of a Codelist or Value List There are variables
conditionalVariables Array of conditional variable objects There are conditional variables
variableMappings Array of variable mapping objects There are variable mappings
header Array of {row: [cells]} There are header rows
body Array of {row: string or [strings]} There are body rows
footnotes Array of localised text objects There are footnotes

Nested objects, in written order:

Field Value Written when
dataflows[].alias String The alias is not empty
dataflows[].dataflow Short URN of the Dataflow Always
missingValues.component Component id Set
missingValues.default String Set
missingValues.representationmap Short URN A mapping is set
obsFormat[].keys Value or array of key patterns Set
obsFormat[].locale Language code, or "dynamic" Set
obsFormat[].decimals Number A precision is set, as decimal places
obsFormat[].significantFigures Number A precision is set, as significant figures
obsFormat[].round Rounding mode name, e.g. "HALF_UP" A precision and a rounding mode are set
obsFormat[].normalise true Normalise is on
obsFormat[].scientificNotation true Scientific notation is on
obsFormat[].scalingFactor Number Set
conditionalVariables[].id String Always
conditionalVariables[].name String (not localised) Set
conditionalVariables[].alias Dataflow alias The alias is not empty
conditionalVariables[].dimension Dimension id the condition is on Always
conditionalVariables[].values Map of mapped id to a map of dimension value to output There are values
variableMappings[].input Dimension id Always
variableMappings[].output Value or array of dimension ids Set
variableMappings[].representationmap Short URN A mapping is set
header[].row[].cell Label Set
header[].row[].rowSpan Number Greater than 1
header[].row[].colSpan Number Greater than 1
body[].row Value or array: head cell label, then observation keys Always
footnotes[].text, footnotes[].text-<locale> Localised text Always

Reading notes

  • Writing needs nothing; reading needs the module. A Publication Table writes itself like any other structure. Reading is different: CanonicalFormatReader finds the reader for the PublicationTable class through the ICanonicalReaderFactory instances registered in FusionBeanStore, and the Publication Table factory is registered by the module. Call PublicationTableModule.register() before reading, otherwise the read fails with "there is no reader for structure type".

    PublicationTableModule.register();
    PublicationTableBean table = CanonicalFormatReader.read(rdl, PublicationTableBean.class);
    
  • When alias is absent, the dataflow alias is set to an empty string.

  • Header cells without rowSpan or colSpan get a span of 1.
  • A body row is split back into its head cell (first string, with spans of 1) and its body cells (remaining strings).