Expand description
Read SEC XBRL filings into typed Rust structs.
xbrlkit reads the two forms an SEC filing carries its tagged data in —
inline XBRL, embedded in the HTML of a 10-K, 10-Q or 8-K, and the
traditional XML instance — and binds the facts to plain structs with
#[derive(FromXbrl)].
use xbrlkit::{Document, FromXbrl};
#[derive(Debug, Default, FromXbrl)]
struct Summary {
#[xbrl(concept = "dei:EntityRegistrantName")]
name: Option<String>,
#[xbrl(concept = "us-gaap:Assets")]
assets: Option<f64>,
// The first concept the filing reports wins.
#[xbrl(
concept = "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax",
alias = "us-gaap:Revenues"
)]
revenue: Option<f64>,
}
// `html` is a filing's primary document, as EDGAR serves it.
let doc = Document::parse(html)?;
let summary: Summary = doc.extract()?;
assert_eq!(summary.name.as_deref(), Some("Apple Inc."));
assert_eq!(summary.assets, Some(359_241_000_000.0));
assert_eq!(summary.revenue, Some(416_161_000_000.0));§Two layers
The parser (parser) keeps everything the filing tags: every
context, unit and fact, in an Instance. For inline XBRL a fact’s value
is the text of everything inside its tag — whatever HTML wraps it,
continued through any ix:continuation — with its format
transformation, scale and sign applied, so a loss
printed as (1,234) in thousands is -1234000. It is built for filings as
they are, malformed HTML included.
The binding (bind) reads a struct from that table of facts. A
filing reports each concept many times over — this year and last, the
quarter and the year to date, the whole company and each segment — and a
field needs one of them. Document::extract picks, per field, the fact
for the period the filing reports on; #[xbrl(each_period)] gives a
statement per period instead.
§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
next to FromXbrl and what reaches JSON, Arrow or Parquet is assets,
not us-gaap:Assets.
§Features
| Feature | Default | Adds |
|---|---|---|
derive | yes | #[derive(FromXbrl)] |
taxonomies | yes | taxonomies::dei and taxonomies::us_gaap, ready-made structs |
Without either, the crate is the parser, the transformations and the
FromXbrl trait to implement by hand.
§What it is not
xbrlkit extracts; it does not validate. It reads no taxonomy schemas or
linkbases, so it does not check calculations, resolve labels or know a
concept’s type beyond what the fact itself says.
Re-exports§
pub use bind::Dimension;pub use bind::Document;pub use bind::Fact;pub use bind::FromXbrl;pub use bind::Span;pub use error::Result;pub use error::XbrlError;pub use instance::Instance;pub use instance::RawFact;pub use instance::XbrlValue;
Modules§
- bind
- Binding facts to structs
- error
- Error types.
- instance
- The parsed document
- parser
- The parser
- taxonomies
taxonomies - Ready-made structs
- transformations
- Inline XBRL transformations