Versions of the auditfile¶

The Auditfile Financieel (auditfile for financial records) is a Dutch standard for exporting a general ledger: master data, opening balance and all journal entries of one fiscal year. Tax inspectors and auditors request it from the company's accounting software. Over 25 years it went through seven iterations; pyxaf reads all of them into the same model.

History¶

Identification and namespaces¶

Namespaces alone are therefore unreliable: the two official 4.0 documents disagree, 3.2.1 has a namespace of its own, some exporters invent one, and CLAIR2 and some 3.x exporters write none. pyxaf compares namespaces case-insensitively and ignores a trailing slash.

How detection works¶

pyxaf.detect() inspects only the first 64 KiB (after decompression) and scores several signals:

1. the ADF signature;
2. the root element (auditfile, any case) and its namespace, looked up with a trust status;
3. the element vocabulary of the first 64 KiB compared with each version's catalogue (trLine/amnt vs line/debitAmount, 4.0-only RGScode/Commercenr/settDate, 3.2-only companyIdent/opBalDate, 3.1-only taxonomies, …);
4. header/auditfileVersion (CLAIR2) and the continuation comment.

>>> info = pyxaf.detect("2024.xaf")
>>> info.version, info.namespace_status, info.confidence
(<Version.XAF40: '4.0'>, <NamespaceStatus.OFFICIAL: 'official'>, 1.0)
>>> info.reasons
('official namespace of XAF 4.0',)
>>> pyxaf.detect("export.xaf").reasons
("namespace 'http://www.auditfiles.nl/XAF/4.0' is known-bogus for 4.0",)

The result is a FormatInfo:

How the confidence comes about:

Detection never fails because of contradictory signals; it chooses a version and says why. When reading or validating, the decision becomes findings: XAF3001 (INFO) or XAF3007 (WARNING, confidence below 0.7) with the reasons, XAF3002 for the documented variant (XSD validation will fail), XAF3003 for a namespace that does not exist, XAF3004 for an unknown one. Only input that is not an auditfile at all raises NotAnAuditfileError.

Normalized field mapping¶

The normalized model uses English names that are the same for every iteration. The table shows where the core fields come from. "ADF n" is field number n of the ADF mutation line; "hdr" the ADF header line. Paths are relative to auditfile/company for XAF and to auditfile for CLAIR2.

Every other element is still available through .raw and, for lines and transactions, .extra.

Notes per version¶

ADF¶

• Fields are left-justified and space-padded at fixed positions; pyxaf reads CR LF and LF line ends. Field problems are reported as XAF3050.
• Numbers: the decimal symbol may be a comma, a point or absent, but the two decimal digits are always present, and grouping symbols are allowed: 10.239,87, 10239,87, 10239.87 and 1023987 all mean 10,239.87. A leading minus is allowed.
• Dates are dd-mm-jjjj or ddmmjjjj.
• The opening balance is period 0 (2003 erratum). All amounts are in one currency; field 24 holds an exchange rate, which pyxaf exposes as ForeignAmount.exchange_rate.
• The encoding is ASCII per the specification; pyxaf decodes windows-1252 by default (DOS-era files), overridable with encoding=.
• ADF has no transaction records: pyxaf groups consecutive mutation lines with the same journal (field 1), period (3), Volgnummer (4) and Identificatie journaalpost (6) into one transaction.
• Accounts, relations and journals are collected from the mutation lines; the header's counts and totals become af.transaction_totals.

CLAIR2¶

• No namespace; recognised by header/auditfileVersion = CLAIR2.00.00.
• Company data sits in header; accounts have free-text types (Balans, W, Assets, …), interpreted heuristically.
• Each line has debitAmount and creditAmount; signed_amount is debit minus credit.
• transactions/numberEntries should count lines; some exporters count transactions.
• Unique IDs and references are rules of the manual (keyrefs), not numbered rules.

XAF 3.0 and 3.1¶

No XSD of either version is publicly available. pyxaf's catalogues for them are derived: the element paths come from a cross-version XPath mapping that matches the 3.2 XSD exactly, and the value rules are borrowed from 3.2. Because of that uncertainty, the validator reports unknown elements and missing required elements in 3.0/3.1 files as WARNING instead of ERROR, and skips the element-order check. 3.0 → 3.1 only adds customerSupplier/custSupTp. In 3.1, RGS links live in generalLedger/taxonomies/taxonomy/taxoElement (glAccID → txCd). The 3.0 namespace is unverified (XAF3004, INFO).

XAF 3.2 and 3.2.1¶

• 298 elements, 250 leaf fields. 3.2.1 has the same structure under a new namespace, an updated ISO 4217 currency list (3.2 still lists obsolete codes such as EEK and LTL), linesCount ≥ 1, qntity ≥ 1 and periodNumber ≥ 0.
• The opening balance must be given exactly once: either as openingBalance or as transactions with period number 0.
• Allowed encodings: UTF-8 and ISO-8859-1.
• Journal types jrnTp: B bank, C cash, G goods, M memo, O opening balance, P purchases, S sales, T production, Y payroll, Z other. Account types accTp: B balance, M mixed, P profit and loss.

XAF 4.0¶

• 111 elements, 90 leaf fields; amounts decimal with 20 digits and 2 decimals and no minimum (negative amounts are allowed); vatPerc decimal(8,3); fiscalYear is YYYY or YYYY-YYYY for broken fiscal years.
• The opening balance may only be given in openingBalance (XAF7005 otherwise); per the 4.0 explanation a file always contains one.
• effDate now means the invoice date (3.2: date of the event); settDate is new (delivery or prepayment date).
• Removed: companyIdent, postal addresses, history and change information, lead*, taxonomy, opBalDate/opBalDesc of the opening balance, subledgers, qntity, matchKeyID, among others. Renamed in effect: sourceID → Source, userID → User, costID/prodID/projID → cost/product/project.
• Casing quirks are real element names: Commercenr (company) vs commerceNr (relation), Source, User, RGScode, RGSVersion. opBalDesc/clBalDesc of a customer/supplier hold amounts.
• RGSVersion has no specified format (3.7, RGS 3.8 and RGS-1 occur); pyxaf parses it leniently.
• The functional description defines consistency rules [0001]–[0010], which pyxaf implements as XAF6001–XAF6003 and XAF5004–XAF5010 (see Validation).
• Account types are B and P only; the 4.0 functional description no longer lists journal type O, but the XSD still allows it.

Sources¶

• XML Auditfile Financieel (XAF) 4.0.3 and background information on XAF 4.0, published by the ODB (Ontwikkelaars Documentatie Belastingdienst).
• Phase-out of the older auditfiles from 1 January 2027.
• The bundled schemas and where they come from: src/pyxaf/schemas/NOTICE.md.
• The XAF 3.0/3.1 element lists: the "XAF Mapping en Namen" table of AnalyticsLibrary (Apache-2.0).