xbrlkit
Read SEC XBRL filings into typed Rust structs.
xbrlkit reads the tagged data of a 10-K, 10-Q or 8-K — inline XBRL in the
filing's HTML, or a traditional XML instance — and binds it to plain structs
with #[derive(FromXbrl)].
use ;
Install
[]
= "0.1"
Rust 1.85 or later.
Why
A filing's numbers are already structured: every figure on the face of the statements, and most of the ones in the notes, is tagged with a concept, a period, a unit and the dimension members it applies to. Reading them should not take an LLM or a table scraper. In practice it takes more than an XML parser, for two reasons this crate exists to handle.
Inline XBRL is HTML, and the tag holds what the reader sees, not the
value. A loss is printed as (1,234) in a column headed "in thousands", with
the parentheses outside the tag; the value is -1234000. A date is
September 30, 2025, a check box is ☒, a term is five years. Values run on
across page breaks through ix:continuation, sit inside <b> and <span>,
and nest inside the text block of the note that discusses them. The parser
applies the format transformation, scale and sign of each fact and gives
you -1234000, 2025-09-30, true and P5Y.
A filing reports each concept many times. us-gaap:Assets appears for
this year end and last; revenue for the quarter, the year to date and both of
last year's; shares outstanding once per class. A field needs one of them, and
"the last one in the document" is the prior year more often than not. Each
field takes the fact for the period the filing reports on, and a struct can
ask for one copy of itself per period instead.
Usage
Ready-made statements
The cover page and the three primary statements are already declared.
use Document;
use ;
let doc = parse?;
let dei: DeiInfo = doc.extract?;
println!;
let financials: Financials = doc.extract?;
println!;
// One statement per period the filing reports. In a 10-Q that is the quarter
// and the year to date, each beside last year's.
for statement in &financials.income_statements
Some("2026-04-01") to Some("2026-06-30"): revenue Some(28236000000.0), net income Some(1114000000.0)
Some("2026-01-01") to Some("2026-06-30"): revenue Some(50623000000.0), net income Some(1591000000.0)
Some("2025-04-01") to Some("2025-06-30"): revenue Some(22496000000.0), net income Some(1172000000.0)
Some("2025-01-01") to Some("2025-06-30"): revenue Some(41831000000.0), net income Some(1581000000.0)
us_gaap::Financials holds the line items most commercial filers report. It
is not the whole taxonomy and is not meant to be: when a field you need is
missing, declare a struct of your own.
Your own struct
use Serialize;
use ;
let report: Report = doc.extract?;
The type of a field decides how much of the filing it sees:
| A field of type | Holds |
|---|---|
Option<T> |
the value of the one best fact |
Option<Fact<T>> |
that fact with its period, unit, precision, dimensions |
Vec<Fact<T>> |
every period and dimension member the concept has |
a struct, #[xbrl(nested)] |
more fields, read the same way |
Vec of one, #[xbrl(each_period)] |
that struct once per period the filing reports |
where T is f64, i64, i32, u64, u32, bool or String.
Which fact a field gets
Read on its own, a struct takes each field from the fact that best matches the period the filing reports on — in a 10-Q, the year to date — falling back to a comparative or a dimensional breakdown when that is all there is. Its fields are chosen independently and can come from different periods.
Read through each_period, every field comes from one period's consolidated
figures, and what the filing does not report for that period is None. Use it
when the period matters.
Where a filing prints one figure twice, exactly on the statement and rounded in a note, the exact one is the value.
One concept, no struct
let assets: = doc.get;
let shares_by_class: = doc.get;
Everything the filing tags
for fact in doc.facts
println!;
A value that does not convert
Filers tag N/A under numeric concepts. extract fails on the first value
that does not fit its field; extract_lenient leaves that field empty and
hands back what it skipped, so one bad tag does not cost a filing its balance
sheet.
let = doc.;
for problem in &problems
With edgarkit
edgarkit fetches filings from EDGAR;
xbrlkit reads them.
use ;
let edgar = new?;
let html = edgar.get_latest_filing_content.await?;
let doc = from_ixbrl?;
let financials: Financials = doc.extract?;
examples/edgar is this as a runnable project.
Works with serde
The concept a field reads from lives in #[xbrl(..)], not in a serde rename,
so a struct's serde names are its Rust names. Derive Serialize beside
FromXbrl and what reaches JSON, Arrow or Parquet is assets, not
us-gaap:Assets:
Every field has a fixed type, so tools that derive a schema from the struct
(serde_arrow, schemars) need nothing from the data. The ready-made structs
all implement Serialize and Deserialize.
Tested on real filings
The crate was extracted from a production pipeline that follows US-listed SPACs, where it has been reading 10-K, 10-Q and 8-K filings since 2025. Most of what the parser steps over — unclosed tags, values wrapped in formatting, facts nested in text blocks, contexts declared in the default namespace — is there because a filing did it.
The test suite also holds the inline parser to the SEC's own reading. EDGAR
extracts an XML instance from every inline filing it accepts, with each
format, scale and sign already applied. Across the reports of eleven
large filers — Apple, Microsoft, JPMorgan, Exxon, Berkshire Hathaway, Tesla,
Nvidia, Walmart, Coca-Cola, Spotify's 20-F and an 8-K — xbrlkit read the
same number of facts as EDGAR from every inline document, and 22,835 of the
22,836 numeric and formatted values were equal. The one that differs is a
country name under ixt-sec:edgarprovcountryen, which this crate normalises
without mapping it to EDGAR's two-character code. Two of those filings are in
tests/fixtures and
tests/sec_conformance.rs repeats the comparison
on every run.
Performance
One pass over the text, no DOM. Measured with cargo bench on an Intel Core
i5-14400F, single-threaded, median of repeated runs:
| Document | Size | Facts | Parse | Throughput | Index | Cover page + statements |
|---|---|---|---|---|---|---|
| Apple 10-K, inline XBRL | 1.52 MB | 1,131 | 3.72 ms | 409 MB/s | 0.18 ms | 0.36 ms |
| Apple 10-K, XML instance | 1.42 MB | 1,131 | 1.98 ms | 715 MB/s | 0.19 ms | 0.34 ms |
| Tesla 10-Q, inline XBRL | 1.57 MB | 1,221 | 4.25 ms | 370 MB/s | 0.19 ms | 0.48 ms |
| Tesla 10-Q, XML instance | 1.47 MB | 1,221 | 2.61 ms | 565 MB/s | 0.18 ms | 0.47 ms |
| A SPAC's 10-Q, inline XBRL | 1.02 MB | 575 | 2.68 ms | 381 MB/s | 0.11 ms | 0.41 ms |
"Parse" is text to facts; "index" builds the lookups a struct is read
through; the last column reads DeiInfo and Financials, every period
included. End to end, Apple's 10-K goes from HTML to typed statements in under
five milliseconds. JPMorgan's 13 MB 10-K, with 8,442 facts, parses in 34 ms.
Run it on your own filings:
Other Rust XBRL crates
Compared in October 2026.
| xbrlkit 0.1 | crabrl 0.1.0 | xbrl-rs 0.3.0 | |
|---|---|---|---|
| Inline XBRL (filings since 2019) | yes | planned | no |
| XML instances | yes | yes | yes |
| Inline transformations | yes | — | — |
| Typed structs, derive | yes | no | no |
| Taxonomy schemas and linkbases | no | calculation, presentation, labels | yes, with DTS discovery |
| Validation | no | yes, with SEC rules | yes, against a taxonomy |
| License | MIT | AGPL-3.0 | Apache-2.0 |
They answer different questions. crabrl and xbrl-rs work with the
taxonomy as well as the instance and can tell you whether a document is valid.
xbrlkit does not load a taxonomy at all: it reads what the filing tags and
hands it to you as structs. If you need validation or the full specification,
those crates, or Arelle, are the tools; if you need the numbers out of SEC
filings, inline ones included, this one is.
On raw parsing of XML instances, the one thing all three do,
benches/compare reads the same files with each, through
its documented entry point and default configuration:
| XML instance | Facts in file | xbrlkit | crabrl | xbrl-rs |
|---|---|---|---|---|
| Apple 10-K (1.42 MB) | 1,131 | 2.11 ms, 1,131 | 2.34 ms, 1,032 | rejected |
| Tesla 10-Q (1.47 MB) | 1,221 | 2.58 ms, 1,221 | 2.51 ms, 1,049 | rejected |
| A SPAC's 10-Q (0.72 MB) | 479 | 1.13 ms, 479 | 1.46 ms, 361 | rejected |
Each cell is the median time and the number of facts returned. xbrlkit and
crabrl are both built on quick-xml and parse at about the same speed.
xbrl-rs checks more as it reads and declines these files, the instances
EDGAR extracts, over the unprefixed unit measure shares.
Scope
xbrlkit extracts; it does not validate.
- No taxonomy schemas or linkbases are read, so there are no labels, no calculation checks and no presentation trees
- Facts are found by concept name. A filer's own extension concept
(
aapl:…) is read like any other, by its name - Tuples and footnotes are not modelled
- Inline transformations cover the SEC's registry and the English and numeric rules of the Transformation Rules Registry; other languages are passed through as the text the filing shows
- Built for and tested on SEC filings. Inline XBRL from other regulators (ESEF, HMRC) follows the same specification and may well parse, but nothing here is tested against it
Features
| Feature | Default | Adds |
|---|---|---|
derive |
yes | #[derive(FromXbrl)] |
taxonomies |
yes | taxonomies::dei and taxonomies::us_gaap |
With default-features = false the crate is the parser, the transformations
and the FromXbrl trait.
Examples
With no path they read the Apple 10-K in tests/fixtures.
Contributing
Issues and pull requests are welcome; see CONTRIBUTING.md. A filing that reads wrongly is the most useful report there is: its accession number and the concept are enough.
License
MIT. See LICENSE.
This project is not affiliated with or endorsed by the U.S. Securities and
Exchange Commission. The filings in tests/fixtures are public documents
obtained from EDGAR.