XBRL Caveats

Understanding XBRL Limitations

SEC EDGAR XBRL data is rich but imperfect. Understanding its quirks is essential for building reliable financial applications.

1. Inconsistent Naming

Different companies label the same concept differently in XBRL. One company may report “RevenueFromContractWithCustomerExcludingAssessedTax” while another reports “Revenues”. The mapping phase (07) uses a 5-phase SQL engine — global curated mappings (dim_gaap_mappings) run first, then heuristic layers fill gaps via calculation linkbase walk-up and name matching (prefix/reverse/container/synonym).

Consequence: Not all metrics are available for all companies. The unmapped_concepts table logs QNames that couldn’t be mapped.

2. Cumulative Reporting

As described in Understanding TTM, most XBRL filings report cumulative (YTD) values. Quarterly increments are computed by the pipeline, which means they carry the is_unverified_flow flag.

Consequence: If a company restates prior quarters, the derived quarterly values may not sum to the annual total.

3. Filing Supersedence

Companies may file multiple XBRL documents for the same fiscal period (e.g., an initial filing, then a corrected 10-K/A). The pipeline takes the latest filing for each period, but this is not always correct — the earlier filing may have been correct in different ways.

By design: The pipeline assumes newer is better. If you need the raw data, query xbrl_facts directly.

4. Zero and Missing Values

Some facts are reported as 0 when they should be null, and vice versa. The pipeline preserves the source value without imputation.

5. Taxonomy Changes

US GAAP taxonomy evolves yearly (2011–2025 taxonomies are supported). A concept may appear only in certain taxonomy years, or may change its QName between years.

6. Derived Metrics vs. Reported Metrics

The fact_xbrl_derived_facts table contains values computed from accounting-equation rules (e.g., deriving total liabilities from assets minus equity) and quarterly increment derivation. Reported facts always take precedence over derived ones.

Best Practices

1. Always check quality flags (is_unverified_flow, is_instant_fact) before using quarterly data
2. Cross-reference with unmapped_concepts to understand coverage gaps
3. Use FY (full-year) values for annual analysis when available — they are reported directly, not derived
4. Validate against known values — the pipeline catches structural errors but cannot detect semantic errors in XBRL source data