spb/air Public MIT

1<!--2Project : AIR — Accounting Intermediate Representation3Author : Simon-Pierre Boucher4Contact : contact@spboucher.ai5File : accounting-data-standards.md6-->78# Research Report — Existing Accounting & Business Data Standards910**Date of research / consultation of all sources: 2026-08-05**11**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.1213---1415## 1. XBRL and XBRL-GL (Global Ledger)1617### 1.1 XBRL (financial reporting)1819XBRL (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.2021### 1.2 XBRL-GL (Global Ledger)2223XBRL-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`).2425**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.2627**Sources (consulted 2026-08-05):**28- XBRL International — Global Ledger overview: https://www.xbrl.org/the-standard/what/global-ledger/29- XBRL Specifications — Transactional Reporting (GL spec group): https://specifications.xbrl.org/transactional.html30- XBRL GL tag archive (status news): https://www.xbrl.org/tag/xbrl-gl/31- XBRL Japan — What is XBRL GL: https://www.xbrl.or.jp/modules/pico7/index.php?content_id=8&ml_lang=en32- Wikipedia — XBRL GL (adoption, Turkey e-bookkeeping): https://en.wikipedia.org/wiki/XBRL_GL33- SEC 2025 taxonomy update: https://www.sec.gov/newsroom/whats-new/2503-2025-xbrl-taxonomies-update3435**Relevance to AIR:**36- **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.37- **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).38- **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.3940---4142## 2. UBL (OASIS Universal Business Language) and Peppol / EN 169314344### 2.1 UBL4546UBL 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.4748### 2.2 Peppol BIS Billing 3.0 and EN 169314950Peppol (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.5152**Sources (consulted 2026-08-05):**53- OASIS UBL 2.4 Standard: https://docs.oasis-open.org/ubl/UBL-2.4.html54- Peppol BIS Billing 3.0 specification: https://docs.peppol.eu/poacc/billing/3.0/bis/55- Peppol document formats introduction (ionite, 2025): https://ionite.net/news-articles/2025-03-07_peppol_document_formats/56- UBL invoice format guide / field reference: https://e-invoice.be/blog/ubl-format-guide57- Singapore BIS Billing (Peppol beyond EU): https://www.peppolguide.sg/billing/bis/5859**Relevance to AIR:**60- **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.61- **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.62- **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.6364---6566## 3. ISO 20022 (camt.053) and OFX — bank statement models6768### 3.1 ISO 20022 camt.0536970`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).7172### 3.2 OFX7374OFX (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.7576**Sources (consulted 2026-08-05):**77- Betaalvereniging NL — camt.053 implementation guidelines (v1.1, 2026): https://www.betaalvereniging.nl/wp-content/uploads/2026/03/IG-Bank-to-Customer-Statement-CAMT-053-v1-1.pdf78- Bank of America — camt.053 reference guide: https://images.em.bankofamerica.com/GTS/ISO_20022/ReferenceGuideBanktoCustomerStatement(CAMT.053).pdf79- Finanssiala — ISO 20022 Account Statement Guide: https://www.finanssiala.fi/wp-content/uploads/2021/03/ISO-20022-Account-Statement-Guide-2020.pdf80- MT940 vs camt.053 comparison: https://invoicedataextraction.com/blog/mt940-camt053-bank-statement-format-guide81- FDX — OFX Work Group: https://financialdataexchange.org/about-fdx/ofx-work-group/82- Wikipedia — Open Financial Exchange: https://en.wikipedia.org/wiki/Open_Financial_Exchange83- OFX→FDX evolution: https://ninth-wave.com/blog/the-evolution-of-data-sharing-part-1-from-ofx-foundation-to-today-fdx/8485**Relevance to AIR:**86- **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.87- **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.88- **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.8990---9192## 4. Plain-Text Accounting: ledger-cli, hledger, beancount9394All 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).9596- **ledger-cli** (C++): the original; fastest; accounts created implicitly on use; very flexible expression language; loosest validation.97- **hledger** (Haskell): compatible middle ground; more structure, strict mode available, official web UI, strong CSV import rules.98- **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."99100**Sources (consulted 2026-08-05):**101- plaintextaccounting.org (ecosystem hub): https://plaintextaccounting.org/102- hledger FAQ (differences from ledger): https://hledger.org/faq.html103- Beancount vs hledger developer deep-dive: https://beancount.io/forum/t/beancount-vs-hledger-a-developers-deep-dive-after-using-both/34104- Plain Text Accounting Showdown 2025 (Beancount v3 vs hledger vs Ledger): https://beancount.io/forum/t/the-ultimate-plain-text-accounting-showdown-2025-beancount-v3-vs-hledger-vs-ledger/81105- Beancount technical comparison (performance, data integrity): https://beancount.io/blog/2025/07/22/beancounts-technical-edge-a-deep-dive-on-performance-python-api-and-data-integrity-vs-ledger-hledger-and-gnucash106107**Relevance to AIR:**108- **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.109- **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.110- **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.111112---113114## 5. REA Ontology (ISO 15944-4) and ValueFlows115116### 5.1 REA117118REA (Resources–Events–Agents), proposed by William E. McCarthy in 1982 ("The REA Accounting Model," *The Accounting Review*), models economic activity as:119- **Resources**: goods, services, rights, claims under agents' control;120- **Events**: phenomena that change resources (production, exchange, consumption, distribution), paired by **duality** (e.g., a Sale event dual to a CashReceipt event — give/take);121- **Agents**: identifiable parties who obtain, use, or dispose of resources.122123Key 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).124125### 5.2 ValueFlows126127ValueFlows 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.128129**Sources (consulted 2026-08-05):**130- Wikipedia — Resources, Events, Agents (McCarthy 1982, ISO 15944-4): https://en.wikipedia.org/wiki/Resources,_Events,_Agents131- ValueFlows — Accounting concepts: https://www.valueflo.ws/concepts/accounting/132- REA2: A unified formalisation of the REA ontology (Applied Ontology, 2018): https://journals.sagepub.com/doi/10.3233/AO-180198133- REA, Triple-Entry Accounting and Blockchain (arXiv 2005.07802): https://arxiv.org/pdf/2005.07802134- P2P Foundation — REA model overview: https://wiki.p2pfoundation.net/Resource-Event-Agent_Model135- From REA to hREA (decentralized implementations): https://happeningscommunity.substack.com/p/from-rea-to-hrea-a-journey-into-decentralized136137**Relevance to AIR:**138- **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.139- **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).140- **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.141142---143144## 6. Decisions / Recommendations for AIR1451461. **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).1471482. **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**:149   - **Import (frontends):** UBL 2.1/2.4 + Peppol BIS Billing invoices; camt.053/054 (+ MT940, OFX legacy, Plaid/Flinks JSON) bank data.150   - **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).1511523. **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.1531544. **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.1551565. **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.1571586. **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.1591607. **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.161162---163164*End of report — consulted 2026-08-05 — Simon-Pierre Boucher — contact@spboucher.ai*165