ixbrl

name: ixbrl description: Use for preparing, reviewing, validating, or debugging Inline XBRL (iXBRL) and XBRL filings. Trigger on iXBRL, XBRL, ESEF, EDGAR/EFM, UK FRC/HMRC, Dutch SBR/KvK/AFM, EBA/EIOPA DPM, IFRS, US-GAAP, EDINET, MCA, Arelle, taxonomy packages, report packages, extension taxonomies, anchoring, block or narrative tagging, fact mapping, contexts, units, decimals, transformation formats, calculation/linkbase/dimension errors, and validator codes such as FR-NL-, EFM.6., ESEF., xbrldie:, xbrldte:*, and xbrl.5.2.5.2. Use it to route to primary-source references, templates, and validation scripts. license: MIT

iXBRL skill

Inline XBRL embeds XBRL facts inside an XHTML host document via ix:* elements: one file, two audiences (human reader + machine consumer).

This skill provides reference material, scripts, and decision-rules for iXBRL work across the major regulatory regimes. It does not replace the regulator's filer manual; it routes you to the right page of the right manual and encodes patterns experts recognise on sight.

When you load this skill, do this first

1. Identify the regulator and reporting basis. The same iXBRL file passes or fails depending on which validator runs. Ask the user which jurisdiction and which taxonomy. Common combinations:
   • EU listed issuer, IFRS consolidated AFR → ESEF, see references/esef.md
   • US SEC registrant → EDGAR / EFM, see references/sec-edgar.md
   • Dutch entity (KvK deposit or AFM listed) → NL Taxonomie / SBR, see references/nl-sbr.md (and the NL section of references/taxonomies.md for entry-point catalogue)
   • UK statutory accounts or HMRC tax → UK FRC Suite, see references/taxonomies.md
   • Bank or insurer supervisory return → EBA / EIOPA DPM, see references/taxonomies.md
   • IFRS digital financial statements (no jurisdictional overlay) → IFRS Accounting Taxonomy, see references/taxonomies.md
2. Pin the operative rules to the reporting period — bi-temporal. Taxonomies and filing rules are versioned per year, and the rules in force when a report was prepared are not necessarily the rules in force today. Before reviewing or validating, state explicitly:
   • Which financial year the report covers (use the period in <xbrli:period>, not today's date).
   • Which taxonomy generation and version applied for that year (ESEF 2024 ≠ ESEF 2025; NT19 ≠ NT20; FASB 2024 GRT ≠ 2025 GRT; FRC 2025 Suite ≠ 2026 Suite; EBA Reporting Framework 4.2 ≠ 4.4).
   • Which Filing Rules / Filer Manual edition applied (ESEF Reporting Manual editions, SEC EDGAR Filer Manual volume/version, SBR Filing Rules NT-generation supplement). Confirm against references/taxonomies.md (entry-point catalogue), references/nl-sbr.md §2 (Dutch bi-temporal cheatsheet), and the regulator's published cut-in dates. Do not apply current-year rules retroactively to a prior-year filing — e.g. KvK Dutch GAAP notes block-tagging is a FY2026 obligation, not a FY2024 one, and declaring its absence on a FY2024 deposit a defect would itself be the defect.
3. Choose your validation profile. Use scripts/validate_with_arelle.sh <file> <profile> (esef, efm, ukfrc, hmrc, core). Run core first to isolate XBRL 2.1 violations from jurisdictional ones.
4. Prepare an Arelle iXBRL Viewer for review. When reviewing a local iXBRL file or document set, generate a viewer with the Arelle iXBRL Viewer plugin before doing the content-level review. The full preparation command (single file, document set, stub viewer mode), version-pinning guidance, and the per-step review checklist live in references/viewer.md.
5. Use the live filing corpus for real examples. For ESEF, UKSEF, and Ukraine filings, use https://filings.xbrl.org/ before and after authoring:
   • Filter the index by Country (for example NL for the Netherlands, or another listed country) to inspect filings from the relevant market.
   • Open the Inline XBRL viewer to compare how facts, continuations, hidden facts, labels, dimensions, and note block tags appear in a real report.
   • Download or inspect the xBRL-JSON and XBRL Report Package when you need concrete examples of fact values, contexts, units, taxonomy package layout, and validation messages.
   • Treat the corpus as evidence, not as authority: the repository is not complete, and many included filings have validation errors or warnings. Use it to learn market practice, then validate against the operative regulator rules.

How to use the references

Each reference is a focused dive. Load on demand — do not read all of them up front.

GitHub source repositories to use

Prefer the live source repositories when debugging tooling behaviour, checking option names, or tracing validator codes:

• Arelle core: https://github.com/Arelle/Arelle. Use for CLI, plugin loading, report-package handling, Inline XBRL processing, ESEF validation implementation, and source-level issue searches.
• Arelle iXBRL Viewer: https://github.com/Arelle/ixbrl-viewer. This is the open-source project behind the ReadTheDocs viewer docs; it contains the iXBRLViewerPlugin, the browser ixbrlviewer.js application, release assets, samples, tests, and viewer README.
• Arelle EDGAR plugin: https://github.com/Arelle/EDGAR. Use for SEC/EFM-specific plugin behaviour rather than assuming it lives in Arelle core.

For normative reporting obligations, GitHub source is implementation evidence, not the legal source. Cross-check against the regulator manual or specification before treating a behaviour as required.

First principles every preparer must internalise

Truths that, when violated, produce silent failures no validator catches early.

1. The decimals ↔ rendering ↔ value relationship

ix:nonFraction carries three numbers in tension: rendered text (what the reader sees), canonical XBRL value (what the consumer parses), and declared accuracy (decimals).

• format (an ixt:* transformation, see references/spec.md §TRR) converts rendered text to a canonical numeric value.
• scale multiplies the parsed text by 10^scale. scale="3" on rendered "1,234" yields canonical 1,234,000.
• decimals declares accuracy. decimals="-3" ≡ "rounded to thousands"; decimals="0" ≡ "whole units". Never use decimals="INF" for a rounded value — SEC EFM 6.05.16 rejects it; ESEF discourages it; both reject when rendered text is shorter than INF claims.
• precision is mutually exclusive with decimals on the same fact. SEC and SBR forbid precision — use decimals only.

Audit rule: canonical value = transform(rendered_text) × 10^scale × (sign == "-" ? -1 : 1). If that doesn't match the natural-language number the reader sees, it's a tagging defect.

2. Sign convention, balance type, and preferredLabel are three different things

The single most common substantive error in ESEF filings.

• The canonical XBRL value is signed per the as-reported mathematical fact; sign="-" appears on the inline tag only when parentheses-formatting is used in the host XHTML.
• The concept's balance attribute (debit/credit on monetary types) drives downstream arithmetic. Reporting a credit-balance concept with the same sign as a debit-balance concept inverts the result for any balance-respecting consumer.
• The preferredLabel role on a presentation arc (terseLabel, negatedLabel, negatedTerseLabel, periodStartLabel, totalLabel, etc.) is a display instruction. negatedLabel flips the visible sign; the underlying fact is unchanged.

Rule of thumb: never flip a fact's sign to fix visible parentheses. Tag the as-reported absolute value with sign="-" iff the value is negative; let preferred-label roles handle display.

3. Period type is concept-driven, not document-driven

Balance-sheet concepts (assets, liabilities, equity) are instant — <xbrli:instant>YYYY-MM-DD</xbrli:instant>. Income statement, OCI, cash-flow, and changes-in-equity flows are duration — <xbrli:startDate> + <xbrli:endDate>.

Mismatching period type to concept class causes xbrldie:PrimaryItemDimensionallyInvalidError or schema validation failures. Respect the concept's declared periodType.

4. Identifier scheme constancy

Every <xbrli:identifier scheme="..."> in an instance must use the same scheme URI: ESEF → LEI scheme (http://standard.iso.org/iso/17442); SEC → CIK scheme (http://www.sec.gov/CIK); SBR → KvK scheme. Mixing schemes silently produces "duplicate fact" errors because consumers treat differently-scheme'd entities as different.

5. Dimensions and axes — XDT is the substrate of every regime

XBRL Dimensions 1.0 ("XDT") makes a fact say more than "this amount, this period". Hypercubes attached to primary items declare which dimensions (taxonomy practice calls them axes) apply; the fact's dimensional context lives in xbrli:segment or xbrli:scenario carrying xbrldi:explicitMember (taxonomy-defined members) or xbrldi:typedMember (open-ended typed values).

Minimum rules:

• Default members are implicit. Never emit a dimension's default member explicitly. Triggers xbrldie:DefaultValueUsedInInstanceError.
• xbrldt:contextElement lives on the all/notAll has-hypercube arc, not on hypercube-dimension. It picks segment or scenario.
• ESEF is scenario-only. Reporting Manual §2.1.3 forbids xbrli:segment; xbrli:scenario may contain only xbrldi:explicitMember / xbrldi:typedMember.
• "Axis" ≠ XDT vocabulary. XDT uses dimensions. "Axis" is FASB/IFRS taxonomy convention (SEC EDGAR XBRL Filing Guide §3.5) — a label suffix marking explicit dimensions.
• Closed hypercubes are exclusive. @xbrldt:closed="true" means the container must contain only and exactly the declared dimensions.
• Error namespaces split: xbrldie:* is instance-level (e.g., PrimaryItemDimensionallyInvalidError); xbrldte:* is taxonomy/DTS-level (e.g., HasHypercubeMissingContextElementAttributeError, TooManyDefaultMembersError).

See references/dimensions.md for the full arcrole table, error codes, explicit-vs-typed contrast, and per-regime axis examples (IFRS, US-GAAP / SRT / DEI, SBR, EBA DPM).

6. Anchoring is mandatory only in some regimes — but always good practice

• ESEF: anchor every primary-statement extension to the closest wider IFRS/ESEF base concept (Reporting Manual 1.4.1), plus to each narrower base concept when the extension combines two or more (RTS Annex IV §9(b)). Pure subtotals are exempt from wider anchoring (§10) but must still participate in the calculation linkbase. Never anchor to an abstract concept (ESEF.3.3.1.ExtensionConceptAnchoredToAbstractConcept).
• SEC EDGAR: strongly recommended; EFM and SEC Sample Letter require using base concepts before extensions; IFRS foreign private issuers must anchor under the SEC's IFRS entry-point rules.
• Dutch SBR / KvK: fixed entry points by entity-size class; extensions are generally not authored for KvK deposits.

When in doubt, anchor wider.

7. Block tagging is structured narrative, not a screenshot

Where note-block tagging is required (ESEF Article 6, mandatory from FY2022; analogous regimes elsewhere), an ix:nonNumeric escape="true" element wraps the entire note's XHTML. The escaped XHTML is the fact value — preserve tables, lists, headings, and ensure machine-readability after extraction (Reporting Manual 2.2.6). Empty or whitespace-only block tags are valid syntactically but useless and often trip downstream formula assertions.

8. The hidden section is for facts that exist, not for facts you're embarrassed by

ix:hidden carries facts required in XBRL but with no natural visible rendering (notably SEC dei: cover-page facts). ESEF and EFM both require any hidden fact whose value also appears as visible text to be linked via the -esef-ix-hidden (ESEF) or -sec-ix-hidden (SEC) CSS style. Do not put numeric/transformable facts in ix:hidden to suppress them — ESEF forbids it (ESEF.2.4.1.transformableElementIncludedInHiddenSection).

The mistake runs both ways. ix:hidden is under-used as often as it is abused: taxonomy-mandated entity metadata (registered name, registration number, legal form, document/report type, period-end date) and non-numeric classification facts that steer interpretation but are not a line in any statement (an entity-size class member, a reporting-framework choice, a consolidated-vs-company-only indicator) are real required facts with no row to sit on — they belong in ix:hidden, not omitted. See references/conversion.md §8 for the positive case.

Converting a source document to iXBRL

Most iXBRL is converted from a finished PDF, Word, or accounts-production document, not authored from scratch. Conversion is where filings quietly go wrong: a converted file can pass every validator and still misrepresent the underlying financial statements, because validators check syntax and DTS wiring rather than fidelity to the source.

If the task involves a conversion (or building a pipeline that does one), read references/conversion.md. It covers the recurring silent-failure patterns — flattened presentation hierarchy, lost column/period contexts, half-tagged primary statements (especially the changes-in-equity matrix), incomplete or sign-wrong calc trees, re-authored labels on base concepts, and toy test filings that exercise none of the hard parts. After validators are clean, do the content-level review pass at references/conversion.md §10 — read the rendered statements as a financial professional. That pass catches what no validator does.

Reviewing with the Arelle iXBRL Viewer

The Arelle iXBRL Viewer is the visual review workbench that complements validation — it makes content-level defects visible that no validator catches (sign errors, scope mis-tagging, orphan presentation arcs, dimensional context drift). Validate first; review second.

Generate a viewer for any iXBRL file or document set before doing the content pass, then walk the review checklist. See references/viewer.md for the full preparation command (single file, document set, stub viewer mode), the per-step review checklist (fact inspector, document summary, search filters, duplicate-fact cycle, Excel export, Calc 1.1 toolbar, review mode for drafts), and what the viewer does not catch (per-scope value mapping, fidelity to source document, entity-metadata correctness).

Reviewing an existing iXBRL report package

When a user hands you a .zip (or .xbri) report package and asks "please review this", the work is not "run Arelle and report what it says". Validators check syntax and DTS wiring; they do not check whether the iXBRL faithfully represents the underlying financial statements, whether it is tagged in the right scope, or whether the right rules were applied for the report's vintage. A package can pass every validator and still be defective in ways the regulator's downstream tooling — or the next reviewer — will catch.

A disciplined review proceeds in this order. Each step depends on the prior being clean.

1. Pin the regime, period, taxonomy version, and entry point. Read the period from <xbrli:period>; do not assume "this year". Open META-INF/taxonomyPackage.xml and link:schemaRef to confirm the taxonomy generation and entry point. Apply bi-temporal reasoning (the "When you load this skill, do this first" §2 above) — the rules in force when this report was prepared may differ from current rules. State the regime / period / version / entry point explicitly before opening the file in earnest.
2. Pin the filer's classification. For Dutch SBR, the entity-size class (Micro / Klein / Middelgroot / Groot) changes which absences count as defects — see references/nl-sbr.md §3. For SEC filings, the filer category (LAF / AF / NAF / SRC) drives DEI requirements. For ESEF, IFRS vs national-GAAP issuer drives which extension patterns are normal.
3. Run validation in the operative profile, with calculations on the right basis. Standard validation pipeline below. For SBR Dutch GAAP 2025, prefer --calc c11r as the substantive review verdict (Calc 1.1 handles iXBRL's duplicate facts and surfaces the dual-statement cross-scope inconsistencies that Calc 1.0 hides), then run --calc c10 separately as the formal deposit-acceptance check — NT20 Filing Rules still list XBRL 2.1 as normative. See nl-sbr.md §4.2 for why both passes earn their keep. For ESEF run --calc c11r if the issuer's taxonomy has Calc 1.1 arcroles, else c10; for SEC EFM use the EDGAR plugin defaults. Capture all messages, including warnings; some Filing Rules surface as warnings in Arelle.
4. Classify each finding by code prefix. Route via the common-error decision tree. Distinguish real defects from known artefacts (dual-scope calc cross-binding, prefix-by-design noise, diagnostic-only cross-scope warnings). When in doubt, quote the validator's log line verbatim and route on its leading code.
5. Verify concept binding. Every fact's QName must resolve to a concept declared in (or imported into) the operative DTS. A fact tagged with a plausible-but-nonexistent QName carries no concept semantics; downstream checks become meaningless. See references/validation.md §6 item 26 (ix11.12.1.2:missingReferences).
6. Open the Arelle iXBRL Viewer and walk the report. The viewer makes content defects visible that no validator catches — see the "Reviewing with the Arelle iXBRL Viewer" section above. At minimum: highlight tagged facts, click each primary-statement subtotal to read its calculation network, search for hidden facts, and sample a dozen facts across statements to confirm period, unit, decimals, scale, and dimensional context.
7. Content-level review of the rendered statements. Read the report as a financial professional would — does the balance sheet balance, do the cash-flow categories reconcile, are sign conventions consistent, do extension concepts make accounting sense in context, do period-end metadata facts match the statements they accompany. See references/conversion.md §10.
8. Package shape. No .DS_Store / __MACOSX/ at package root; no .html files (must be .xhtml); META-INF/taxonomyPackage.xml present and well-formed; for Report Packages 1.0, reports.json present and consistent; for jurisdictions that require it, the auditor's report packaged as a separate tagged iXBRL document (Dutch SBR, see references/nl-sbr.md §7).

For regime-specific review checklists, load:

• SBR Dutch GAAP / KvK / AFM → references/nl-sbr.md (end-to-end review pass at §13).
• ESEF (listed-issuer AFR) → references/esef.md.
• SEC EFM → references/sec-edgar.md.

The output of a review is not "validates / does not validate". It is a categorised list: deposit-blockers, deposit-allowed-but-substantive defects, style/cosmetic defects, and known artefacts. Each finding quotes the evidence (validator code or rendered-document observation) and cites the rule it violates with version. That is the form a filer's preparer, an auditor, and the regulator can all act on.

Standard validation pipeline

Run these in order. Each step depends on the prior being clean.

# 1. Base XBRL spec — catches xbrl.* and xbrldie:* violations
scripts/validate_with_arelle.sh report.zip core

# 2. Jurisdictional rules — catches ESEF.*, EFM.6.*, UKFRC.*, FR-NL-*
scripts/validate_with_arelle.sh report.zip esef        # or efm, ukfrc, hmrc

# 3. Pre-flight pure-XML sanity (cheap, no Arelle dependency)
python scripts/check_facts.py path/to/document.xhtml

# 4. (If applicable) cryptographic seal/sign of the validated package

Step 1 first because a base XBRL error makes step 2 noisy. Step 3 catches issues validators don't always surface clearly: dangling continuation chains, undefined contexts/units, inconsistent duplicate facts, decimals="INF" abuse, non-ISO currency unit measures.

Common-error decision tree

When the user shows you a validator error, route by code prefix:

• ESEF.2.x.* → iXBRL/instance-construction issue. See the table in references/esef.md §8 and the duplicated/expanded table in references/validation.md §5.1.
• ESEF.3.x.* → extension-taxonomy issue (anchoring, labels, link roles). Same references.
• EFM.6.05.* → SEC iXBRL syntax/DEI/decimals issue. See references/sec-edgar.md §7 and references/validation.md §5.2.
• EFM.6.08.* → SEC industry-overlay (ECD, RXP, OEF, CEF) linkbase issue.
• FR-NL-* / FG-NL-* → SBR Filing Rules / Filing Guidelines (taxonomy-agnostic). The most common are encoding (1.01–1.05), missing xml:lang (2.03), link:schemaRef placement (2.04), xbrli:forever use (3.04), precision usage (5.06), xsi:nil on facts (5.07), footnotes (6.01). See references/nl-sbr.md §6 and references/validation.md §5.3.
• NL-KVK.* → KvK-specific Filing Rules supplement (layered on top of FR-NL-). Recurring deposit blockers: 4.4.2.5 mixed-scope ELR missing for a dual-scope concept; 4.4.6.1 usable concepts not applied by tagged facts; 3.4.1.3 transformable element in ix:hidden. See references/nl-sbr.md §5 and §4 for the dual-scope pattern, and the duplicated/expanded table in references/validation.md §5.3.
• xbrl.5.2.5.2 → calculation inconsistency. Either fix the data or move to Calc 1.1 if the regulator accepts it. See references/validation.md §4.
• xbrldie:* (instance-level) → dimensional context error. See references/dimensions.md §"Dimensional validity errors".
• xbrldte:* (taxonomy/DTS-level) → hypercube/dimension/domain wiring error in the linkbases. See references/dimensions.md §"Dimensional validity errors".

Anti-patterns that pass syntax but fail review

No validator error in step 1 or 2, but flagged by auditors or NCA post-filing reviews. Full list in references/validation.md §6 — highlights:

• Negated-label sign confusion. Tagging (1,234) as -1234 when the calc tree expects +1234 (let the negated-label role handle display).
• Decimals drift across calc tree levels. Parent at thousands, child at units; rounding tolerance computed from the looser side; cumulative drift fires xbrl.5.2.5.2.
• Same fact, two values. Same concept tagged in summary and footnote with different rounding.
• Wrong namespace for shared concepts. Concepts exist in exactly one namespace per taxonomy. Picking a jurisdiction-extension prefix when the core concept exists makes the calc tree silently fail.
• Tagged but not in any presentation linkbase. ESEF requires every tagged fact's concept to appear in at least one presentation link.
• Default-member explicit emission. Drop default members — they are implicit.
• External CSS / <script> / xml:base. All forbidden in ESEF and EFM. Inline everything; sanitise the HTML at generation time.

Authoring an extension taxonomy (high level)

When base taxonomy lacks a needed concept, build a small extension. Typical ESEF / EFM-style layout:

{prefix}-{date}/
├── {prefix}-{date}.xsd          # schema with new concepts
├── {prefix}-{date}_pre.xml      # presentation linkbase
├── {prefix}-{date}_cal.xml      # calculation linkbase
├── {prefix}-{date}_def.xml      # definition linkbase (anchoring lives here)
├── {prefix}-{date}_lab-en.xml   # English labels
├── {prefix}-{date}_lab-{lang}.xml  # report-language labels
└── META-INF/
    ├── taxonomyPackage.xml      # manifest with <tp:identifier>, <tp:entryPoint>
    └── catalog.xml              # URI rewrite for offline resolution

Rules:

• Concept names: PascalCase, no spaces, derived from xbrli:item or xbrli:tuple substitution group.
• Each concept has a Standard Label in the report language. Add English labels.
• For monetary concepts, set balance="debit" or balance="credit" correctly — this drives sign convention everywhere downstream.
• For ESEF: anchor each non-subtotal extension to the closest wider IFRS concept (and to each narrower component concept if the extension is an aggregation). Never anchor to abstract concepts.
• Add an abstract concept for every section header and grouping so the presentation linkbase tree mirrors the statement's visible hierarchy (see references/conversion.md §2).
• Wire concepts into a presentation link with appropriate preferredLabel roles on subtotal arcs.
• Wire calculation links with weight="1" when parent and child share the same balance, weight="-1" when they are opposite (XBRL 2.1 §5.1.1.2). Give every subtotal a summation network covering all of its children.

See references/esef.md §5 for ESEF specifics and references/sec-edgar.md §4 for EFM specifics.

Generating a Report Package

Both ESEF and report-package-aware regulators expect a .zip (or .xbri) with:

report-package.zip
├── META-INF/
│   ├── taxonomyPackage.xml      # manifest (mandatory)
│   ├── catalog.xml              # standard remap (optional but expected)
│   └── reports.json             # for newer Report Packages 1.0
├── reports/
│   └── {LEI}-{YYYY-MM-DD}.xhtml # single-file iXBRL
│   └── {set}/                    # OR a folder with multiple .xhtml files
│       ├── statements.xhtml
│       └── notes.xhtml
└── {prefix}-{date}/             # extension taxonomy (if any)
    ├── *.xsd
    └── *.xml

Common rejection grounds: macOS .DS_Store / __MACOSX artifacts at package root; PDFs at root; .html instead of .xhtml; filename pattern violations (Arelle enforces via regex); missing taxonomyPackage.xml. See references/esef.md §6.

When this skill can't answer with confidence

Be honest. iXBRL has many regimes and they evolve. If a question concerns:

• a regulator not covered in references/taxonomies.md,
• a rule version newer than what the references cite,
• an Arelle error code not listed in references/validation.md,

— say so and point to the primary source on the regulator's website. Do not invent error codes, rule numbers, or taxonomy versions. The cost of a wrong citation in a regulated filing is high.

Bundled scripts

• scripts/validate_with_arelle.sh <file> [profile] — wraps arelleCmdLine with the right plugins per profile (esef, efm, ukfrc, hmrc, core). Auto-detects single file, iXBRL document set, or .zip / .xbri report package.
• scripts/check_facts.py <ixbrl.xhtml> — pure-Python pre-flight sanity check. Catches: required attributes (contextRef, unitRef, decimals/precision), unresolved context/unit references, non-ISO-4217 currency measures, decimals="INF" abuse, broken continuation chains, inconsistent duplicate facts. Run before Arelle to surface cheap-to-detect errors fast.

Both scripts are dependency-light (arelle-release, lxml) and CI-safe.

Editing this skill

This file is loaded into agent runtimes with real size limits — Codex CLI caps project documentation files at 32 KiB by default and silently truncates beyond that, and Anthropic limits the YAML frontmatter description to 1024 characters. Before adding substantive content, prefer extending a file in references/ (loaded only when this body points the agent at it) over expanding SKILL.md. See CONTRIBUTING.md §"Size discipline" for the full rules and the wc -c check to run before merging.