Skip to content

Limitations: Hierarchy Fusion XL Writer

This document records known limitations of the current HierarchyXLSXWriterEngine implementation. In each case the information model supports the feature, but the XLSX format does not yet represent it. Affected data is silently dropped on output unless otherwise noted.

1. Level Coding Format Not Serialized

Background

The SDMX information model allows each LevelBean in a hierarchy to carry an optional coding format (LevelBean.getCodingFormat() → TextFormatBean). This is a CodingTextFormat constraint that restricts the identifiers of codes valid at that level. Attributes include:

Attribute Description
textType SDMX text type (e.g. Alpha, AlphaNumeric, Numeric, String)
minLength / maxLength Character-length bounds on the code identifier
pattern Regular expression the identifier must match
startValue / endValue Numeric range for numeric code identifiers
interval Numeric step between valid sequential identifiers
isSequence Whether identifiers form an ordered numerical sequence
minValue / maxValue Numeric value bounds
decimals Maximum number of fractional digits

Current Behaviour

The Levels table in the Excel spreadsheet writes only three columns: Id, Name Locale, and Name. Any coding format present on the level is not written to the spreadsheet and is lost when the file is the sole representation of the hierarchy.

2. Annotations on Hierarchical Codes Not Serialized

Background

HierarchicalCodeBean is an AnnotableBean. Like every SDMX identifiable object it may carry zero or more AnnotationBean instances. Annotations are the primary mechanism for attaching supplementary metadata to a hierarchical code — for example, locale-specific display labels (stored as annotations with a language tag), provenance notes, or custom flags.

By contrast, annotations are fully serialized at the maintainable (HierarchyBean) level, consistent with the standard FusionXL treatment of all maintainable structures.

Current Behaviour

Region 4 (Hierarchical Codes) includes no column for annotations. All annotations present on individual HierarchicalCodeBean instances are silently dropped during output. As a practical consequence:

  • Custom per-code localized labels stored as annotations cannot be round-tripped through the XLSX format.
  • Any other annotation-based metadata on hierarchical codes is lost.

3. Annotations on Levels Not Serialized

Background

LevelBean extends NameableBean → AnnotableBean and can therefore carry annotations just as any other named SDMX object.

Current Behaviour

The Levels region (Region 2) writes only Id, Name Locale, and Name. Annotations present on level objects are not written and are lost on output.

4. Level Names: Only One Locale Serialized

Background

LevelBean is a NameableBean and supports localized names in multiple languages (e.g. en, fr, de), exactly as codelists and data structures do.

Current Behaviour

The Levels region writes one row per level, capturing a single Name Locale + Name pair. When a level carries names in multiple locales only the default locale is written; all other translations are dropped.

5. HierarchicalCodeBean Version Field Not Serialized

Background

CodeRefMutableBean (the mutable counterpart of HierarchicalCodeBean) exposes a version field (getVersion() / setVersion()). This allows a hierarchical code to carry a version marker that is distinct from the version of the hierarchy itself — for example to tag codes that were introduced or modified at particular hierarchy revisions.

Current Behaviour

Region 4 includes no Version column. The version field is silently ignored on output.

6. Write-Only Format (No Reader Implementation)

Background

A complete round-trip format requires both a writer and a reader. Several other FusionXL structure types (e.g. Codelist, DataStructureDefinition) have corresponding reader engines that parse the spreadsheet back into the information model.

Current Behaviour

No HierarchyXLSXReaderEngine exists. The produced spreadsheet cannot be parsed back into a HierarchyBean through FusionXL. The format is currently write-only, useful for human inspection and export but not for import or round-trip validation workflows.

7. HierarchyBean Only — No HierarchicalCodelistBean Export

Background

The codebase supports two related object types for representing hierarchical classifications:

  • HierarchyBean — an individual hierarchy that references codes via HierarchicalCodeBean entries pointing to items in separate Codelist objects. This is the object the writer operates on.
  • HierarchicalCodelistBean — the SDMX 2.1 container structure that groups one or more HierarchyBean instances. A HierarchicalCodelistBean contains its hierarchies via getHierarchies(), which returns List<HierarchyBean>.

Current Behaviour

The HierarchyXLSXWriterEngine operates exclusively on individual HierarchyBean instances. There is no corresponding writer for HierarchicalCodelistBean as a whole. Each HierarchyBean within a HierarchicalCodelistBean can be exported individually, but the container itself (including any container-level metadata) is not represented in the XLSX output.