SEC bulk XBRL data¶

Source¶

The SEC publishes the Financial Statement and Notes Data Sets as periodic bulk downloads. Each release contains tab-separated, normalized tables extracted from the XBRL submitted with SEC filings. A mounted example is available at /data/2025q1_notes/.

The source is relational rather than a single firm-year panel. Facts, filing identity, concepts, dimensions, and presentation/calculation relationships are stored separately and are linked primarily through the accession number (adsh) and concept identifier (tag, version).

Raw tables¶

SEC table	Grain	Main content
`sub.tsv`	Filing (`adsh`)	Submission, issuer, form, reporting-period, filing-date, and acceptance metadata.
`num.tsv`	Numeric XBRL fact	Numeric value and its original XBRL context, including concept, date, duration, unit, dimensions, and footnote fields.
`txt.tsv`	Text XBRL fact	Text fact and its original XBRL context.
`tag.tsv`	Concept (`tag`, `version`)	Standard/custom status, data type, labels, documentation, and accounting attributes.
`pre.tsv`	Filing presentation relationship	How a fact is presented in a filing: report, line, statement, label, and role.
`cal.tsv`	Filing calculation arc	Parent-child calculation relationships and weights/sign information.
`dim.tsv`	Dimension hash	Human-readable segment and dimensional members associated with `dimh`.
`ren.tsv`	Filing report	Report, statement, and role names that enrich presentation records.

Keys and reporting contexts¶

adsh identifies a specific SEC submission, rather than a company or reporting period. cik identifies the SEC registrant. A single filing can contain many facts, and the same firm/reporting-date combination can appear in a later amendment or another filing.

The XBRL fact context is essential:

tag and version identify the concept;
ddate is the end date reported by the fact;
qtrs is the duration in quarters for duration facts;
uom is the unit, such as USD or shares;
dimh, dimn, and coreg describe the dimensional context;
iprx, durp, datp, and dcml preserve additional instant/duration, data-type, and decimal attributes.

filed and accepted come from the submission table and measure when the SEC received the filing. They are not substitutes for ddate.

Standard and custom concepts¶

US-GAAP concepts generally use a us-gaap/... taxonomy version. A filer can also define custom concepts, whose tags, labels, documentation, and relationships are supplied in the filing data. Custom tags therefore require filing-specific interpretation; the same spelling need not represent an identical economic construct across issuers or years.

Tags versus labels¶

A tag is the machine-readable XBRL concept identifier, such as AdvertisingExpense. Together, tag and version identify the taxonomy concept applied to a fact. Tags are the stable fields used to join numeric facts, text facts, concept definitions, presentation relationships, and calculation relationships.

A label is human-readable text associated with a concept. Labels need not match a tag's camel-case name, and they are not necessarily unique. Several kinds of labels are relevant in the SEC data:

Field	Source	Meaning
`tlabel`	`tag.tsv` / `concepts.parquet`	The taxonomy's standard label for a concept.
`doc`	`tag.tsv` / `concepts.parquet`	The taxonomy or filer documentation/definition.
`plabel`	`pre.tsv` / `presentation.parquet`	The display label used at a particular filing presentation location.
`longname`, `shortname`	`ren.tsv` / `presentation.parquet`	Names for the report or presentation role in which a concept appears.

Thus, a fact tagged AdvertisingExpense may appear to readers under a filing-specific label such as “Marketing and advertising,” and two different tags can be displayed with similar labels. A label is useful evidence about presentation and economic meaning, but it does not replace the tag as the fact identifier. The final project data retain both concept metadata and the available filing presentation labels for this reason.

Axes, members, and segments¶

An XBRL fact can be reported for the consolidated company or for a more specific dimensional context. A dimension consists of an axis and one or more members. For example, an issuer may report revenue by a product axis with product members, or assets by a geographical axis with country members.

Business segments are one common dimensional use, but they are not synonymous with all XBRL dimensions. Dimensions can also identify products, geographies, major customers, legal entities, classes of stock, or other filer-specific breakdowns. A fact with a segment-like label should therefore be interpreted from its full axis/member context rather than from the word “segment” alone.

Marketing and advertising examples¶

The following are common XBRL patterns an analyst could encounter. They illustrate the structure of a fact; they do not imply that every issuer uses the same axis or that the reported amounts are comparable without reviewing the filing.

Fact tag	Axis	Member	Illustrative meaning
`AdvertisingExpense`	`StatementBusinessSegmentsAxis`	`ConsumerProductsSegmentMember`	Advertising expense reported for the consumer-products business segment rather than for the consolidated company.
`MarketingAndAdvertisingExpense`	`GeographicAreasAxis`	`UnitedStatesMember`	Marketing and advertising expense attributed to the United States geographic area. A second fact for another country is not necessarily a complete global breakdown.
`SellingAndMarketingExpense`	`ProductOrServiceAxis`	`CloudServicesMember`	A selling-and-marketing subtotal assigned to a particular product or service line. This is broader than advertising alone.
`AdvertisingExpense`	custom `AdvertisingChannelAxis`	custom `DigitalAdvertisingMember`	A filer-defined breakdown of advertising by channel, such as digital, television, or print. Both the axis and members may be custom concepts.
`MarketingExpense`	custom `CustomerTypeAxis`	`DirectToConsumerMember`	A filer-defined distinction between direct-to-consumer and business-to-business marketing.

StatementBusinessSegmentsAxis, GeographicAreasAxis, and ProductOrServiceAxis illustrate common standard taxonomy patterns; a preparer may instead use a different standard axis or a custom axis. The last two rows are deliberately custom examples: advertising-channel and customer-type detail is often issuer-specific rather than a standard US-GAAP breakdown.

For example, an issuer can report a consolidated AdvertisingExpense fact of $100 and also two segment facts of $60 and $40. Those three rows are overlapping views of the same disclosure, not three expenses totaling $200. Conversely, the issuer could report only one segment fact, or could use a broad SellingAndMarketingExpense tag for its segment facts and a narrower advertising tag only at the consolidated level. The researcher must use the tag, axis/member context, unit, duration, and filing presentation together.

The SEC data preserve this context as follows:

Field	Meaning
`dimh`	Hash identifying the fact's dimensional context.
`dim.tsv`	Lookup from the dimension hash to readable dimensional/segment information in the bulk download.
`dimn`, `coreg`	Additional dimensional and co-registrant context carried with the fact.
`segments`, `segt`	Readable segment/dimension information added by the pre-project Parquet normalization.

Dimensioned facts should not be mechanically added to consolidated facts or to each other. The same filing may contain a consolidated amount, a set of disaggregated amounts, and other overlapping contexts for the same tag and date. The project retains all original contexts and leaves any aggregation or selection rule to the researcher.

Why relationships matter¶

The raw numeric table does not by itself say whether a custom tag is an advertising expense, a marketing subtotal, or an unrelated measure. pre.tsv provides presentation evidence, while cal.tsv can connect a custom concept to standard accounting concepts. The project additionally uses canonical US-GAAP taxonomy relationships because filers do not necessarily restate standard arcs in their own calculation tables.