SPB Git

spb/air Public MIT

AIR — The Language of Accounting.

languageaccountingcompiler
Python 100%
17.9 KB
View source Raw Blame History

# Research Report — Existing Accounting & Business Data Standards

Date of research / consultation of all sources: 2026-08-05 Purpose: Survey prior art before designing the AIR format (CLAUDE.md §1.1, Phase 0). AIR models economic events, not journal entries; this report assesses which existing standards to align with, borrow from, or avoid.

# 1. XBRL and XBRL-GL (Global Ledger)

# 1.1 XBRL (financial reporting)

XBRL (eXtensible Business Reporting Language) is the dominant global standard for aggregated financial reporting — regulator-facing filings (SEC, ESEF, EDINET). It is taxonomy-driven: facts are tagged against concepts defined in jurisdiction-specific taxonomies (US GAAP, IFRS). The SEC continues to publish annual taxonomy updates (2025 update confirmed). XBRL operates at the report level, downstream of everything AIR does.

# 1.2 XBRL-GL (Global Ledger)

XBRL-GL is a separate, generic, system-independent XML representation of detailed ledger/transactional data — journal entries, sub-ledger detail, master data — meant to bridge transactional systems and reporting standards. Its data model is a hierarchy of accountingEntries → entryHeader → entryDetail, organized in composable taxonomy modules (core gl-cor, business gl-bus, multicurrency gl-muc, US/UK extensions gl-usk, tax audit gl-taf).

Status (as of 2026-08-05): The 2015 XBRL GL Taxonomy reached Recommendation status (stable) and remains listed among the specifications maintained by XBRL International, with a later Public Working Draft of an updated framework. However, real-world adoption is narrow: the most notable deployment is the Turkish government's mandated electronic bookkeeping (e-Defter) for tax purposes. Wikipedia and practitioner commentary note persistent barriers (producer incentives, lack of practical instruction sets). It is best described as maintained but dormant/niche, not a living ecosystem.

Sources (consulted 2026-08-05):

Relevance to AIR:

  • Borrow: the idea of a system-independent transactional interchange layer sitting between ERPs and reporting; the modular taxonomy design (core + optional extension modules) is a good pattern for AIR schema layering.
  • Align (export only): an XBRL-GL export backend is a credible long-term target (drill-down from XBRL reports to AIR provenance is exactly XBRL-GL's pitch).
  • Avoid: adopting it as AIR's core format. It models journal entries (post-compilation artifacts in AIR terms), it is XML/taxonomy-heavy, tooling is scarce, and adoption never materialized. AIR's core must stay upstream of the journal entry.

# 2. UBL (OASIS Universal Business Language) and Peppol / EN 16931

# 2.1 UBL

UBL is an open, royalty-free, XML-based OASIS standard for business documents. UBL 2.4 is the current OASIS Standard (published 2024-06-20), defining 94 document schemas — Invoice, Credit Note, Debit Note, Self Billed Invoice/Credit Note, Order, Despatch Advice, Receipt Advice, Catalogue, Tender, transport documents, etc. Minor revisions are guaranteed backward compatible: documents conforming to UBL 2.1 remain valid under 2.4. The document model is built from reusable common aggregate components (Party, Item, TaxTotal/TaxSubtotal, MonetaryTotal, PaymentMeans, Delivery, AllowanceCharge), all with explicit currency-qualified amounts.

# 2.2 Peppol BIS Billing 3.0 and EN 16931

Peppol (the pan-European — now global — e-procurement network) mandates Peppol BIS Billing 3.0, which uses UBL 2.1 Invoice and CreditNote document types. BIS Billing 3.0 is a CIUS (Core Invoice Usage Specification) of EN 16931, the European semantic model for electronic invoices: compliance with BIS Billing implies EN 16931 compliance. Validation involves ~200 business rules (VAT consistency, mandatory fields, totals arithmetic). EN 16931 is significant because it is a semantic model with two syntax bindings (UBL and UN/CEFACT CII) — a semantics-first design AIR should emulate.

Sources (consulted 2026-08-05):

Relevance to AIR:

  • Borrow: UBL/EN 16931's field-level vocabulary for invoices — party identification, tax category/subtotal breakdown, allowance/charge modeling, payment means codes, currency-qualified amount types. AIR's Sale/Purchase event items, tax blocks, and payment blocks should map cleanly onto these components so LLM extraction from Peppol invoices is near-lossless.
  • Align (import + export): UBL invoices are a first-class ingestion source (structured, no OCR needed) and a natural export target. An AIR↔UBL mapping table belongs in the spec.
  • Avoid: using UBL as the core IR. It is document-centric (an invoice is a claim document, not the economic event) and says nothing about ledger posting, provenance, or compilation.

# 3. ISO 20022 (camt.053) and OFX — bank statement models

# 3.1 ISO 20022 camt.053

camt.053 (BankToCustomerStatement) is the ISO 20022 end-of-day bank statement message: a Group Header plus one or more Statements containing balances (opening/closing/available, coded Bal/Tp) and entries (Ntry), each with amount, credit/debit indicator, status, booking/value dates, bank transaction codes (domain/family/subfamily), and nested EntryDetails/TransactionDetails carrying end-to-end references, debtor/creditor parties and accounts, structured remittance information, purpose codes, and charge breakdowns. It is deeply hierarchical XML (~1,300 tags in v.001.02; later versions add more); this replaces the flat positional MT940 (SWIFT's ISO 20022 migration has made camt the strategic format). Related messages: camt.052 (intraday report), camt.054 (debit/credit notification — the reconciliation workhorse).

# 3.2 OFX

OFX (Open Financial Exchange, 1997) is the legacy North American consumer format for bank/card statement download (SGML then XML; STMTTRN records with TRNTYPE, DTPOSTED, TRNAMT, FITID, NAME/MEMO). Current release is OFX 2.3 (split into OFX Banking 2.3 and OFX Tax). Since 2019 stewardship sits with the Financial Data Exchange (FDX) consortium; OFX is in maintenance mode while FDX's REST/JSON API is the modern successor for open-banking-style data sharing. In practice, aggregators (Plaid, Flinks) expose their own JSON models on top.

Sources (consulted 2026-08-05):

Relevance to AIR:

  • Borrow: camt.053's separation of entry vs transaction details, its bank transaction code taxonomy (domain/family/subfamily) for classifying settlement events, and its end-to-end reference chain — directly useful for AIR's Settlement events and the Phase 6 reconciliation pass.
  • Align (import): camt.053/camt.054 (and MT940 legacy, plus Plaid/Flinks JSON) are ingestion sources producing AIR Settlement/BankEntry events. OFX matters only as a legacy import for NA consumer data.
  • Avoid: modeling AIR amounts or events on OFX's loose semantics (no double-entry, weak typing); avoid inheriting camt's XML verbosity — map its semantics, not its syntax.

# 4. Plain-Text Accounting: ledger-cli, hledger, beancount

All three share the core model: a text file of dated transactions, each a list of postings (account, amount+commodity) that must balance to zero — i.e., double-entry with multi-commodity support and first-class cost/price annotations (@, @@, {cost} lots).

  • ledger-cli (C++): the original; fastest; accounts created implicitly on use; very flexible expression language; loosest validation.
  • hledger (Haskell): compatible middle ground; more structure, strict mode available, official web UI, strong CSV import rules.
  • beancount (Python, v3 current): the strictest — mandatory YYYY-MM-DD open Account directives (typo-proof accounts), a small closed set of directives (open, close, balance assertions, pad, price, commodity, event, document, note, custom), full re-derivation of state from the file, and a Python plugin pipeline for arbitrary validation/transformation during load. Balance assertions and inventory/lot tracking are notable features. Active comparisons through 2025–2026 confirm all three are alive; beancount's philosophy is "assume data-entry errors, build guardrails."

Sources (consulted 2026-08-05):

Relevance to AIR:

  • Borrow (heavily): beancount's strictness philosophy — explicit account opening, balance assertions, deterministic re-derivation of all state from source data, plugin/pass pipeline (a direct analogue of AIC passes); the zero-sum posting invariant as the executable form of Assets = Liabilities + Equity; decimal-only amounts with explicit commodities; cost-basis/lot tracking ideas for FX and inventory.
  • Align (export): a beancount/hledger text export backend is cheap and gives instant query/reporting tooling for golden tests and debugging — strongly recommended as a dev-facing backend alongside generic CSV.
  • Avoid: their transaction-as-source-of-truth model. PTA files ARE the journal; AIR's source of truth is the economic event, with journals compiled. Also single-user, file-based — no concurrency, approval, or provenance model.

# 5. REA Ontology (ISO 15944-4) and ValueFlows

# 5.1 REA

REA (Resources–Events–Agents), proposed by William E. McCarthy in 1982 ("The REA Accounting Model," The Accounting Review), models economic activity as:

  • Resources: goods, services, rights, claims under agents' control;
  • Events: phenomena that change resources (production, exchange, consumption, distribution), paired by duality (e.g., a Sale event dual to a CashReceipt event — give/take);
  • Agents: identifiable parties who obtain, use, or dispose of resources.

Key insight: debits, credits, and accounts are derived views, not primitives — the base data is the event graph. REA was standardized as ISO/IEC 15944-4:2007 (Business Operational View — business transaction scenarios, accounting and economic ontology) and influenced IBM's financial reporting architecture. Later formalizations (REA2, Laurier/Kiehn/Polovina 2018) unify the exchange and conversion views. Extended REA adds commitments (promised future events, e.g., an order) and contracts (bundles of commitments) — exactly what AIR needs for pending delivery / revenue recognition (IFRS 15 performance obligations map naturally to commitments).

# 5.2 ValueFlows

ValueFlows is a modern RDF-based vocabulary built explicitly on REA/ISO 15944-4 for networked economies (used by hREA on Holochain, Bonfire, etc.). Three layers: Knowledge (resource types, recipes/rules), Plan (intents, commitments, offers/requests), Observation (actual economic events as they occur). Its accounting page states the AIR thesis almost verbatim: "A standard General Ledger, Balance Sheet, and Income Statement can be generated automatically from Valueflows data. No need to... post double-entries; those can all be created by a computer program on request." It also formalizes perspective-dependence: one agent's purchase is the counterparty's sale — one neutral event, multiple ledger views.

Sources (consulted 2026-08-05):

Relevance to AIR:

  • Align (core): REA is the theoretical foundation AIR should explicitly claim. AIR's EconomicEvent already IS an REA event with resources (items, money) and agents (seller, buyer). Adopting REA vocabulary (duality, commitment, fulfillment, agent, resource) gives AIR 40 years of academic grounding plus an ISO citation.
  • Borrow: duality pairing (Sale ↔ Payment) as the structural basis for AIR's provenance/SSA chain; commitments for pending deliveries and revenue recognition; ValueFlows' plan/observation split (quote/order = plan; invoice/payment = observation) and its perspective-neutral event with per-agent views (one AIR event compiles to different journals for each party).
  • Avoid: ValueFlows' RDF/linked-data serialization and P2P-network scope creep — AIR needs a closed, versioned JSON Schema, deterministic compilation, and enterprise concerns (tax, approval, audit) that REA/VF leave out.

# 6. Decisions / Recommendations for AIR

  1. Adopt REA as AIR's conceptual foundation (YES). AIR models economic events, not journal entries — this is precisely McCarthy's REA claim that debits/credits are derived views. State the REA/ISO 15944-4 lineage in the spec (docs/spec/), and adopt its vocabulary: EconomicEvent, Agent, Resource, duality, Commitment/fulfills. Add commitments to the schema early (orders, pending deliveries → IFRS 15/ASC 606 performance obligations).

  2. Do NOT adopt XBRL-GL, UBL, camt, or PTA formats as the core IR. Each models a different downstream/upstream artifact (journal entries, claim documents, bank entries, journal files). AIR stays event-centric; all of these become mappings:

    • Import (frontends): UBL 2.1/2.4 + Peppol BIS Billing invoices; camt.053/054 (+ MT940, OFX legacy, Plaid/Flinks JSON) bank data.
    • Export (backends): generic CSV (Phase 1), beancount/hledger text (recommended addition — near-free, enables golden-test diffing and instant reporting), XBRL-GL (later, for audit/tax interchange; note its niche adoption before investing).

  3. Emulate EN 16931's semantics-first design: define the AIR semantic model independently of syntax (JSON Schema as normative binding, others derivable), and reuse EN 16931/UBL field vocabulary for invoice-like events (tax subtotals per category, allowance/charge, payment means codes) so Peppol ingestion is lossless.

  4. Steal beancount's discipline for AIC: explicit account/entity declarations (no on-the-fly creation), balance assertions as a pass, deterministic full re-derivation from events, decimal-only amounts with explicit currency, and a plugin-style pass pipeline. The zero-sum posting rule is the executable Assets = Liabilities + Equity invariant to enforce after every pass.

  5. Model settlements on camt semantics: AIR bank/settlement events should carry ISO 20022-style bank transaction codes and end-to-end references to power the Phase 6 reconciliation pass; map camt's meaning, not its XML shape.

  6. Perspective-neutral events (from ValueFlows): one AIR event, per-agent compiled views (seller's journal vs buyer's journal). This should be a stated design principle even if v0.1 compiles for a single reporting entity.

  7. Follow-up research needed: ISO/IEC 15944-4 full text (paywalled — obtain for spec citations); XBRL-GL 2015 module reference if/when an export backend is scoped; FDX API model for future bank-feed frontends; UN/CEFACT CII as the second EN 16931 syntax.

End of report — consulted 2026-08-05 — Simon-Pierre Boucher — contact@spboucher.ai