Views: 2
Structured CSV: Expressing XML Hierarchies in a Single Sheet
2025-04-13
Structured CSV is a standards-based format derived from the xBRL-CSV specification, enabling complex hierarchical data to be recorded in a flat, tabular form. It is not a simple dump of relational tables. Instead, it uses structured conventions and a metadata-driven approach to express multi-level business documents — such as invoices or journal entries — in a single CSV sheet.
1. Based on xBRL-CSV
Structured CSV follows the xBRL-CSV syntax model, where:
-
A
CSVfile holds the fact data — one row per fact. -
A
JSONmetadata file defines the table structure, the dimensions and members for each column, and the mapping to the XBRL taxonomy. -
Each column is explicitly defined as a
dimension,concept, or aunit. -
Hierarchical records (e.g. header and detail) are flattened but grouped using dimension-based sequence numbers.
This format is ideal for encoding any data that would traditionally be captured in XML, such as an XBRL GL instance, but with the compactness and simplicity of CSV.
2. Metadata: Structure and Semantics
The metadata JSON file:
-
Declares the
taxonomyschema URL (usually an.xsdfile). -
Maps each CSV column to a corresponding concept in the taxonomy (e.g.
gl-cor:entryNumber,gl-cor:amount). -
Specifies whether a column is a
dimension,member, or a core concept. -
Enables multilingual interpretation — column names and definitions can be retrieved in local language using the
labellinkbases of the taxonomy.
3. Hierarchy in Flat Rows
Structured CSV can represent header-detail relationships — or even deeper nested structures — by using integer-based dimension values:
entryHeader,entryDetail,entryNumber,lineNumber,amount
1,,INV-001,,
1,1,,1,100.00
1,2,,2,-100.00
2,,INV-002,,
2,3,,1,300.00| entryHeader | entryDetail | entryNumber | lineNumber | amount |
|---|---|---|---|---|
|
1 |
INV-001 |
|||
|
1 |
1 |
1 |
100.00 |
|
|
1 |
2 |
2 |
250.00 |
|
|
2 |
INV-002 |
|||
|
2 |
1 |
1 |
300.00 |
-
entryHeaderandentryDetailare sequence numbers (integers). -
Rows with only
entryHeaderpopulated are header-level facts. -
Rows with
entryDetailpopulated are detail-level facts grouped under the most recent header.
4. Graphical Illustration
This diagram illustrates how entryDetail rows are logically grouped under entryHeader using the sequence numbers, even though all data resides in a single flat CSV file.
5. Example for a Customer Invoice
The following is an example of a structured CSV representing a customer invoice. It includes both header and detail facts flattened into a single sheet, using sequence numbers to distinguish between entryHeader and entryDetail.
| accountingEntries | entryHeader | entryDetail | entriesType | uniqueID | postedDate | entryNumber | entryComment | lineNumber | amount | maturityDate | terms | measurableDescription | measurableQuantity | measurableUnitOfMeasure | measurableCostPerUnit |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
1 |
other |
001 |
|||||||||||||
|
1 |
1 |
2005-10-14 |
50 |
Invoice: #2 Customer: Joe’s Materials |
|||||||||||
|
1 |
1 |
1 |
1 |
220 |
2005-10-21 |
7 Days Date |
MK II Widgets with improved spatulas |
10 |
EACH |
22 |
|||||
|
1 |
1 |
2 |
2 |
25 |
2005-10-21 |
7 Days Date |
Service Kits for MK II widgets |
5 |
EACH |
5 |
|||||
|
1 |
2 |
2005-10-14 |
51 |
Invoice: #3 Customer: Joe’s Materials |
|||||||||||
|
1 |
2 |
1 |
1 |
60 |
2005-10-14 |
COD |
Service Kits for MK I Widgets |
20 |
EACH |
3 |
|||||
|
1 |
2 |
2 |
2 |
80 |
2005-10-14 |
COD |
Bottled Water |
100 |
EACH |
0.8 |
|||||
|
1 |
3 |
2005-10-14 |
52 |
Invoice: #5 Customer: Jacquiline Hau Shearer’s Snacks |
|||||||||||
|
1 |
3 |
1 |
1 |
325 |
2005-10-21 |
7 Days Date |
Bottled Water Shrink Wrap Dozens |
50 |
EACH |
6.5 |
6. Localised Semantics
Thanks to the connected XBRL taxonomy:
-
Concept names can be resolved to user-friendly labels in the local language (e.g. Japanese, English, etc.).
-
Documentation strings and business definitions can be extracted from the taxonomy’s label linkbases.
-
The
presentationlinkbase can express the hierarchical structure defined in the dimensional hypercube. This allows structured CSV facts to be rendered in a simplified, human-friendly hierarchy, mirroring the conceptual model of the business document.
7. Merging Single-Line Headers
When a header contains exactly one detail, a dimensional definition linkbase using xbrldt:targetRole can specify that the two dimensions may be merged. This simplifies display while preserving semantic integrity — especially useful for one-line records in SME transactions.
8. Conclusion
Structured CSV, backed by xBRL-CSV and its powerful JSON metadata, provides a future-ready solution for representing semantically rich business documents in a compact, interoperable format. Combined with a well-defined taxonomy, this format ensures accurate interpretation, multilingual usability, and efficient exchange across systems and jurisdictions.
It is a foundational building block for modern, structured data exchange in audit, e-Tax, and regulatory reporting ecosystems.
Leave a Reply