Skip to main content

Crate xbrlkit

Crate xbrlkit 

Source
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

FeatureDefaultAdds
deriveyes#[derive(FromXbrl)]
taxonomiesyestaxonomies::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
taxonomiestaxonomies
Ready-made structs
transformations
Inline XBRL transformations

Derive Macros§

FromXbrlderive
Binds a struct’s fields to XBRL concepts. See the bind module. Derives xbrlkit::FromXbrl for a struct with named fields. See the crate docs.