XBRL facts: match contexts before choosing a number
An XBRL concept name is not enough to identify the number your research needs. Match the entity, period, unit, dimensions and filing version before selecting or aggregating facts. A technically valid financial tag can appear with several legitimate contexts, each answering a different economic question.
Begin with the intended observation
Write the target in ordinary language: consolidated revenue for one issuer during a particular quarter, measured in a specified currency and taken from a stated reporting version. Then map that definition to the machine-readable facts. Starting with the first numeric value returned by an API reverses the process and can make the research question follow an accidental record order.
XBRL International’s essentials guide explains facts, concepts, contextual information and dimensions. The SEC API documentation also describes the scope of its extracted XBRL services. Their standardized entity-wide aggregations are not a promise that every custom or segment fact in the original filing is represented.
A hypothetical context collision
Suppose an invented issuer has several revenue facts in source filings. You want the latest reported first-quarter consolidated figure. The table uses simplified descriptions rather than claiming these are real filing identifiers or an exact API response.
| Fact | Period and scope | Value | Role in the question |
|---|---|---|---|
| A | January–March, consolidated, original report | 40 | Earlier version of the target |
| B | January–June, consolidated | 85 | Six-month figure, not Q1 |
| C | January–March, one segment | 25 | Narrower scope, not consolidated |
| D | January–March, consolidated, amended report | 42 | Candidate if the amendment supersedes A |
Adding these values would mix periods, scopes and versions. Selecting D still requires checking what the amendment actually changed. A later filing date alone does not prove that every earlier fact was replaced. If the question concerns information known before the amendment, A may be the appropriate historical observation instead.
Construct a fact identity
Record the concept’s namespace and local name, entity identifier, start and end dates or instant, unit, dimension-member combinations and source accession. A context identifier is a local reference within a document; identical context labels in different documents do not establish identical economic meaning. Compare the underlying fields rather than the convenience label.
Distinguish duration measures such as revenue from instant measures such as a closing balance. A calendar-year label cannot substitute for actual dates when fiscal periods differ. Keep the source’s dimensions even when your current analysis uses only consolidated facts, so excluded segments remain traceable rather than disappearing without explanation.
Treat extensions and omissions explicitly
An issuer may use an extension concept for a business-specific disclosure. A similar label does not guarantee equivalence to a standard concept, while a missing standardized API value does not prove the underlying business measure was zero. Inspect the taxonomy definition and original filing when the required detail is absent or ambiguous.
Do not invent a mapping because it makes a peer table complete. Record unmapped concepts and the reason for any proposed relationship. A mapping suitable for one company-period comparison may fail after a business restructuring or presentation change. Preserve the mapping version with the resulting dataset.
Reconcile before trusting the extraction
Trace a sample of selected machine facts back to the visible financial statement and its notes. Check sign, units, period and accounting scope. Reconcile a total only with components that belong to the same relationship; do not sum every fact sharing the word revenue. An extraction can be syntactically correct while the selection rule is economically wrong.
Keep original and derived values separately, including any unit conversion. A structured source removes some transcription work but does not replace judgment about which observation answers the question. The final research record should show why the selected fact was chosen and which alternatives were excluded.
FAQ
Is the latest returned value always the right one?
No. Check the requested period, version and information cutoff. Return order is not a research definition.
Does a missing companyfacts item mean zero?
No. Coverage and taxonomy scope matter. Inspect the original disclosure or retain the value as unavailable rather than filling zero automatically.