Document Purpose: Comprehensive guide to XBRL data format specifications
Last Updated: January 2026
This document covers all XBRL data representation formats: xBRL-XML, Inline XBRL, xBRL-JSON, and xBRL-CSV.
XBRL data can be represented in multiple formats, each optimized for different use cases:
| Format | Released | Best For | File Types |
|---|---|---|---|
| xBRL-XML | 2003 | Traditional systems, B2B | .xml, .xbrl |
| Inline XBRL | 2010 | Human+machine reports | .xhtml, .html |
| xBRL-JSON | 2021 | Web apps, APIs, publication | .json |
| xBRL-CSV | 2021 | Bulk data, granular reporting | .json + .csv |
All formats map to the Open Information Model (OIM), enabling lossless transformation between them.
The traditional XML-based format defined by XBRL 2.1. This is the format most XBRL processors support.
When to Use:
See 04-XBRL-Core-Specifications.md for detailed XML structure.
✅ Mature, well-supported
✅ Comprehensive tooling
✅ Full feature support
✅ Industry standard since 2003
❌ Verbose (large file sizes)
❌ Complex for humans to read/write
❌ Requires XML expertise
❌ Context management complexity
Status: Recommendation (REC)
Released: April 2010
Embeds XBRL data within HTML/XHTML documents, enabling a single file to serve both human and machine readers.
Ideal for:
Examples:
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:ix="http://www.xbrl.org/2013/inlineXBRL"
xmlns:xbrli="http://www.xbrl.org/2003/instance"
xmlns:iso4217="http://www.xbrl.org/2003/iso4217"
xmlns:ex="http://example.com/taxonomy/2024">
<head>
<title>Acme Corp Financial Statements</title>
<style>
/* Styling for human readers */
table { border-collapse: collapse; }
td { padding: 5px; border: 1px solid black; }
</style>
</head>
<body>
<!-- Hidden XBRL metadata -->
<ix:hidden>
<ix:references>
<link:schemaRef xlink:href="http://example.com/taxonomy/2024/example.xsd"/>
</ix:references>
<xbrli:context id="current">
<xbrli:entity>
<xbrli:identifier scheme="http://example.com">ABC Corp</xbrli:identifier>
</xbrli:entity>
<xbrli:period>
<xbrli:startDate>2024-01-01</xbrli:startDate>
<xbrli:endDate>2024-12-31</xbrli:endDate>
</xbrli:period>
</xbrli:context>
<xbrli:unit id="usd">
<xbrli:measure>iso4217:USD</xbrli:measure>
</xbrli:unit>
</ix:hidden>
<!-- Human-readable report with embedded XBRL -->
<h1>Acme Corporation - Income Statement</h1>
<p>For the year ended December 31, 2024</p>
<table>
<tr>
<td>Revenue</td>
<td style="text-align: right;">
$<ix:nonFraction name="ex:Revenue"
contextRef="current"
unitRef="usd"
decimals="-3"
format="ixt:numdotdecimal">1,000,000</ix:nonFraction>
</td>
</tr>
<tr>
<td>Cost of Sales</td>
<td style="text-align: right;">
$<ix:nonFraction name="ex:CostOfSales"
contextRef="current"
unitRef="usd"
decimals="-3"
format="ixt:numdotdecimal">600,000</ix:nonFraction>
</td>
</tr>
<tr>
<td><strong>Gross Profit</strong></td>
<td style="text-align: right;">
<strong>$<ix:nonFraction name="ex:GrossProfit"
contextRef="current"
unitRef="usd"
decimals="-3"
format="ixt:numdotdecimal">400,000</ix:nonFraction></strong>
</td>
</tr>
</table>
<p>The company name is
<ix:nonNumeric name="ex:EntityName" contextRef="current">
Acme Corporation
</ix:nonNumeric>.
</p>
</body>
</html>
<ix:nonFraction
name="ex:Revenue" <!-- Concept -->
contextRef="current" <!-- Context reference -->
unitRef="usd" <!-- Unit reference -->
decimals="-3" <!-- Precision -->
format="ixt:numdotdecimal" <!-- Display format -->
scale="0"> <!-- Scale factor -->
1,000,000
</ix:nonFraction>
Attributes:
name: Qualified concept namecontextRef: Context IDunitRef: Unit IDdecimals or precision: Accuracyformat: Transformation function (from registry)scale: Multiplier (e.g., thousands)sign: Reversal (- for negation)<ix:nonNumeric
name="ex:CompanyName"
contextRef="current">
Acme Corporation
</ix:nonNumeric>
<ix:fraction
name="ex:Ownership"
contextRef="current"
unitRef="pure">
<ix:numerator>1</ix:numerator>
<ix:denominator>3</ix:denominator>
</ix:fraction>
Displays as: 1/3
<ix:hidden>
<ix:nonFraction name="ex:DetailedCalculation"
contextRef="current"
unitRef="usd"
decimals="2">12345.67</ix:nonFraction>
</ix:hidden>
<p id="para1">This is the beginning of a long text fact
<ix:continuation id="continue1" />
</p>
<p>Some other content in between.</p>
<p>
<ix:continuation continuedAt="continue1" id="continue2" />
This is more of the text fact.
<ix:continuation continuedAt="continue2" />
And this is the end.
</p>
<ix:nonNumeric name="ex:LongText" contextRef="current" continueAt="para1">
<!-- Full text is assembled from continued sections -->
</ix:nonNumeric>
<ix:tuple name="ex:LoanDetails">
<ix:nonNumeric name="ex:LoanID" contextRef="current">L001</ix:nonNumeric>
<ix:nonFraction name="ex:LoanAmount" contextRef="current" unitRef="usd" decimals="0">
100000
</ix:nonFraction>
</ix:tuple>
Inline XBRL uses a transformation registry to convert displayed formats to XBRL formats.
Common Transformations:
| Transform | Display | XBRL Format |
|---|---|---|
ixt:datedaymonthyear |
31-12-2024 | 2024-12-31 |
ixt:datemonthyear |
December 2024 | 2024-12 |
ixt:numdotdecimal |
1,000,000.00 | 1000000.00 |
ixt:numcommadecimal |
1.000.000,00 | 1000000.00 |
ixt:zerodash |
- | 0 |
ixt:booleanfalse |
No | false |
ixt:booleantrue |
Yes | true |
Full registry: https://www.xbrl.org/registries/transformation-rules/
<ix:hidden> and <ix:references>✅ Single file for humans and machines
✅ Flexible presentation
✅ Widely adopted by regulators
✅ No separate rendering needed
✅ Preserves exact report layout
❌ More complex to generate
❌ Larger file size than pure XML
❌ Requires HTML expertise
❌ Transformation functions add complexity
Status: Recommendation (REC)
Released: October 13, 2021
JSON representation of XBRL reports, designed for web applications, APIs, and data publication.
Ideal for:
Examples:
{
"documentInfo": {
"documentType": "https://xbrl.org/2021/xbrl-json",
"namespaces": {
"ex": "http://example.com/taxonomy/2024",
"iso4217": "http://www.xbrl.org/2003/iso4217",
"xbrl": "https://xbrl.org/2021"
},
"taxonomy": [
"http://example.com/taxonomy/2024/example.xsd"
],
"reportDimensions": {
"xbrl:entity": "http://example.com/entity/ABC",
"xbrl:periodStart": "2024-01-01",
"xbrl:periodEnd": "2024-12-31"
},
"features": {
"xbrl:canonicalValues": true
}
},
"facts": {
"f1": {
"value": "1000000",
"dimensions": {
"concept": "ex:Revenue",
"xbrl:unit": "iso4217:USD"
},
"decimals": -3
},
"f2": {
"value": "600000",
"dimensions": {
"concept": "ex:CostOfSales",
"xbrl:unit": "iso4217:USD"
},
"decimals": -3
},
"f3": {
"value": "Acme Corporation",
"dimensions": {
"concept": "ex:EntityName",
"xbrl:period": "2024-12-31"
}
},
"f4": {
"value": "1000000",
"dimensions": {
"concept": "ex:Revenue",
"xbrl:entity": "http://example.com/entity/ABC",
"xbrl:period": "2024-01-01/2024-12-31",
"xbrl:unit": "iso4217:USD",
"ex:Region": "ex:NorthAmerica"
},
"decimals": -3
}
},
"links": {
"footnote": {
"l1": {
"from": ["f1"],
"to": "fn1"
}
}
},
"footnotes": {
"fn1": {
"value": "Revenue includes extraordinary item.",
"dimensions": {
"xbrl:language": "en"
}
}
}
}
Metadata about the report:
documentType: Format versionnamespaces: Namespace prefix mappingstaxonomy: Taxonomy referencesreportDimensions: Common dimensions shared by many factsfeatures: Optional feature flagsMap of fact ID to fact object:
value: The fact value (always string)dimensions: Map of dimension QNames to valuesdecimals (optional): Precision for numeric factsid (optional): Explicit fact IDCommon Dimensions:
concept: Concept QName (required)xbrl:entity: Entity identifierxbrl:period: Period (instant or start/end)xbrl:unit: Unit of measurexbrl:language: Language for text factsRelationships between facts:
footnote: Footnote linksMap of footnote ID to footnote text
Instant:
"xbrl:period": "2024-12-31"
Duration:
"xbrl:period": "2024-01-01/2024-12-31"
Or separately:
"xbrl:periodStart": "2024-01-01",
"xbrl:periodEnd": "2024-12-31"
Simple unit:
"xbrl:unit": "iso4217:USD"
Divide unit:
"xbrl:unit": {
"numerator": ["iso4217:USD"],
"denominator": ["xbrl:shares"]
}
Multiply unit:
"xbrl:unit": ["units:kW", "units:hr"]
"xbrl:entity": "http://example.com/entity/ABC"
Or with segment:
"xbrl:entity": {
"scheme": "http://www.sec.gov/CIK",
"id": "0001234567"
}
Explicit dimension:
"ex:Region": "ex:NorthAmerica"
Typed dimension:
"ex:CustomerID": "CUST-001"
Dimensions in reportDimensions apply to all facts unless overridden:
{
"documentInfo": {
"reportDimensions": {
"xbrl:entity": "http://example.com/entity/ABC",
"xbrl:period": "2024-01-01/2024-12-31",
"xbrl:unit": "iso4217:USD"
}
},
"facts": {
"f1": {
"value": "1000000",
"dimensions": {
"concept": "ex:Revenue"
// entity, period, unit inherited
},
"decimals": -3
}
}
}
✅ Simple, intuitive structure
✅ Easy to parse in any language
✅ Compact size
✅ Native JSON - no conversion needed
✅ Perfect for web APIs
✅ Human-readable
❌ Relatively new (2021)
❌ Less tooling than XML
❌ Not ideal for very large datasets
❌ Limited OIM feature support vs XML
Parsing (Input):
Generation (Output):
Status: Recommendation (REC)
Released: October 13, 2021
CSV-based format optimized for bulk data and granular reporting.
Ideal for:
Not ideal for:
xBRL-CSV combines:
loans-metadata.json:
{
"documentInfo": {
"documentType": "https://xbrl.org/2021/xbrl-csv",
"namespaces": {
"ex": "http://example.com/taxonomy/2024",
"iso4217": "http://www.xbrl.org/2003/iso4217",
"xbrl": "https://xbrl.org/2021"
},
"taxonomy": [
"http://example.com/taxonomy/2024/loans.xsd"
],
"reportDimensions": {
"xbrl:entity": "http://example.com/bank/XYZ",
"xbrl:period": "2024-12-31",
"xbrl:unit": "iso4217:USD"
}
},
"tableTemplates": {
"loans": {
"url": "loans-data.csv",
"dimensions": {
"concept": "ex:LoanAmount"
},
"columns": {
"loan_id": {
"dimensions": {
"ex:LoanID": "$"
}
},
"amount": {
"decimals": 0
},
"interest_rate": {
"dimensions": {
"concept": "ex:InterestRate"
},
"decimals": 2
}
}
},
"provisions": {
"url": "loans-data.csv",
"dimensions": {
"concept": "ex:LoanLossProvision"
},
"columns": {
"loan_id": {
"dimensions": {
"ex:LoanID": "$"
}
},
"provision": {
"decimals": 0
}
}
}
}
}
loans-data.csv:
loan_id,amount,interest_rate,provision
L001,100000,5.25,1000
L002,250000,4.75,2500
L003,75000,5.50,750
L004,150000,5.00,1500
Map of table name to table definition:
Table properties:
url: CSV file path/URLdimensions: Dimensions common to all facts in tabledecimals: Default decimals for numeric columnscolumns: Column definitionsSimple fact column:
"amount": {
"decimals": 0
}
Dimension parameter ($ = column value):
"loan_id": {
"dimensions": {
"ex:LoanID": "$"
}
}
Different concept:
"interest_rate": {
"dimensions": {
"concept": "ex:InterestRate"
},
"decimals": 2
}
Remove inherited dimension (#none):
"total": {
"dimensions": {
"ex:LoanID": "#none"
}
}
$ parameter reference)Lower levels override higher levels.
Reusable dimension sets:
{
"propertyGroups": {
"loan_props": {
"dimensions": {
"xbrl:unit": "iso4217:USD"
},
"decimals": 0
}
},
"tableTemplates": {
"loans": {
"url": "loans-data.csv",
"propertiesFrom": ["loan_props"],
"columns": {
"amount": {}
}
}
}
}
One metadata file can reference multiple CSV files:
{
"tableTemplates": {
"individual_loans": {
"url": "loans-granular.csv",
...
},
"loan_summary_by_country": {
"url": "loans-summary.csv",
...
}
}
}
#nil - Nil/null value:
loan_id,amount
L001,100000
L002,#nil
#empty - Empty string:
loan_id,note
L001,#empty
L002,Some note
#none - Remove inherited dimension:
loan_id,total
L001,#none
L002,500000
xBRL-CSV auto-generates fact IDs:
{table-name}-{row-number}-{column-name}loans-1-amount, loans-2-interest_rateCan be customized with id column.
✅ Extremely compact for bulk data (20x compression)
✅ Familiar CSV format
✅ Excel/pandas/SQL friendly
✅ Efficient for repeating patterns
✅ Great for granular reporting
❌ Requires JSON metadata understanding
❌ Not intuitive for complex structures
❌ Metadata design requires thought
❌ Less human-readable than JSON
❌ Not ideal for varied/hierarchical reports
Parsing (Input):
$ parameters with cell valuesGeneration (Output):
Challenge: Finding optimal table structure (may need user input/heuristics).
For 1000 facts with similar dimensions:
| Format | Approximate Size | Compression |
|---|---|---|
| xBRL-XML | 500 KB | 1x (baseline) |
| Inline XBRL | 600 KB | 1.2x (+ HTML) |
| xBRL-JSON | 200 KB | 0.4x |
| xBRL-CSV | 25 KB | 0.05x (20x smaller) |
Actual results vary by data structure
| Format | Generate | Parse | Human Read | Machine Read |
|---|---|---|---|---|
| xBRL-XML | High | High | Hard | Easy |
| Inline XBRL | Very High | High | Easy | Medium |
| xBRL-JSON | Medium | Low | Medium | Very Easy |
| xBRL-CSV | High | Medium | Medium | Easy |
| Feature | xBRL-XML | Inline XBRL | xBRL-JSON | xBRL-CSV |
|---|---|---|---|---|
| Tuples | Full | Full | Limited | Limited |
| Footnotes | Full | Full | Limited | Limited |
| Fractions | Full | Full | No | No |
| Typed Dims | Full | Full | Simplified | Simplified |
| Large Data | Yes | No | No | Excellent |
| Presentation | Via linkbase | Embedded | No | No |
Do you need human-readable report with exact layout?
├─ YES → Inline XBRL
└─ NO ↓
Is it bulk/granular data with millions of facts?
├─ YES → xBRL-CSV
└─ NO ↓
Publishing data for web consumption or API?
├─ YES → xBRL-JSON
└─ NO ↓
Traditional system integration?
└─ YES → xBRL-XML
Public Company Financial Statements:
Regulatory Bulk Data:
Data APIs:
Legacy Systems:
Internal Reporting:
All formats map to OIM, enabling transformation:
┌─────────────┐
│ xBRL-XML │──┐
└─────────────┘ │
┌─────────────┐ │ ┌─────────┐ ┌─────────────┐
│ Inline XBRL │──┼───→│ OIM │────→│ xBRL-JSON │
└─────────────┘ │ └─────────┘ └─────────────┘
┌─────────────┐ │ ┌─────────────┐
│ xBRL-CSV │──┘ │ xBRL-CSV │
└─────────────┘ └─────────────┘
Transformation Rules:
XML Parsing:
JSON:
CSV:
Arelle (Python):
XBRL International Test Suites:
| Requirement | Best Format |
|---|---|
| Human readability | Inline XBRL |
| File size | xBRL-CSV |
| Simplicity | xBRL-JSON |
| Full features | xBRL-XML |
| Web APIs | xBRL-JSON |
| Bulk data | xBRL-CSV |
| Legacy support | xBRL-XML |
| Publication | xBRL-JSON |