gaebboss

GAEB DA XML is how German construction tenders travel: the Leistungsverzeichnis (bill of quantities) goes out as X83, bidders send their prices back as X84, the order is placed as X86. gaebboss reads every version from 3.0 to 3.3, writes X83, X84 and X86 that the official schemas accept, and turns a tender into a priced bid without a single floating-point operation.

It is built from the standard, not from other parsers: the typed model, the readers, the writers and the per-phase rules are generated from the official XSDs that GAEB publishes. Where the Fachdokumentation prescribes a rule, such as how totals round or which items count towards the sum, that rule is implemented and tested against the official sample files.

What you get

• gaebboss-core, a Rust crate with no C dependencies: tokenizer, typed model, navigation over categories and items, text projections, writers, validation and bid construction.
• gaebboss, the command line: info, items, text, json, validate, roundtrip, bid.
• gaebboss, the Python package: the same engine behind a small API that hands out decimal.Decimal, never floats.

How it treats bad input

Real files are not clean. Vendor elements, HTML where the schema has none, decimal commas, duplicated elements, truncated files and Latin-1 bytes under a UTF-8 declaration all occur in the wild. gaebboss reads all of them, reports each defect as a warning with its byte offset, keeps unknown elements for writing back, and raises an error only when the input is not GAEB DA XML at all.

Quickstart

cargo install gaebboss-cli
pip install gaebboss

Look at a tender:

gaebboss info tender.X83
gaebboss items tender.X83
gaebboss text tender.X83 --oz 01.02.0010 --markdown

Price it:

gaebboss items tender.X83 --tsv | cut -f1 > prices.csv   # then add ",<unit price>" per line
cat > bidder.toml <<'EOT'
name1 = "Bau GmbH"
street = "Weg 1"
pcode = "12345"
city = "Berlin"
vat_percent = "19"
EOT
gaebboss bid tender.X83 --prices prices.csv --bidder bidder.toml -o bid.X84
gaebboss validate bid.X84 --tender tender.X83

The same in Python:

from decimal import Decimal
import gaebboss

tender = gaebboss.Document("tender.X83")
for item in tender.items():
    print(item.oz, item.quantity, item.unit, item.short_text)

bid = gaebboss.Bid.from_tender(tender, {"name1": "Bau GmbH", "street": "Weg 1", "pcode": "12345", "city": "Berlin"})
for item in tender.items():
    bid.price(item.id, Decimal("12.50"))
bid.vat_percent(Decimal("19"))
open("bid.X84", "wb").write(bid.finish().write())

And in Rust:

#![allow(unused)]
fn main() {
use gaebboss_core::Document;

let doc = Document::open(std::path::Path::new("tender.X83"))?;
for item in doc.items() {
    println!("{} {:?} {}", item.oz, item.quantity(), item.short_text());
}
}

Reading a bill

Document::open or Document::parse reads a file of any GAEB DA XML version from 3.0 to 3.3. The version and phase come from the namespace first, then from GAEBInfo/Version and Award/DP, then from the file extension; every guess is a warning you can read in doc.warnings.

The typed tree is doc.gaeb: one struct per schema type, strings as spans resolved with doc.str(span), decimals as Decimal. Most callers never touch it and use the navigation layer instead:

• doc.items() yields every item in document order with its Oz (the Ordnungszahl formed from the BoQBkdn levels), its kind, quantity, unit, prices and texts, plus the categories above it in path.
• doc.categories() yields the LV-Bereiche with label, depth and declared totals.
• doc.markup_items() yields Zuschlagspositionen.
• doc.computed_totals() sums items per Fachdokumentation 4.6.17 and puts the result next to what the file declares.

Kinds of items

ItemRef::kind() tells a Standard item from a LumpSum, a Bedarfsposition with or without Gesamtbetrag (ProvisionalWithTotal, ProvisionalWithoutTotal), a Grundposition (Base) and its alternatives (Alternative { group, serial }), hourly and key items, a free quantity the bidder fills in, and a not-applicable item. counts_towards_total() applies the standard’s rule: alternatives, Bedarfspositionen ohne GB, not-applicable and not-offered items stay out of the sums, whatever else they are.

Ordnungszahl

item.oz.dotted() prints 001.002.0010A: levels zero-padded to their declared width (or space-padded per alignment for non-numeric levels), joined by dots, the index appended directly; a skipped level shows as _. compact() gives the fixed-width form, trade() the first level, lot() the lot when the breakdown starts with one.

Texts and bidder fields

Long texts are formatted text: paragraphs, spans with styles, lists, tables and images, with TextComplement fields inside. gaebboss renders them from the tape in document order, so vendor deviations such as a list placed directly under DetailTxt or a <b> inside a span still read.

• item.short_text() is the OutlineText as one line.
• item.long_text() is plain text: paragraphs on their own lines, list items bulleted, table cells tab-separated, fields inline. An empty bidder field reads '....'.
• item.long_text_markdown() turns bold and italic spans into Markdown emphasis and tables into GFM tables.
• item.complements() lists the fields with mark, kind (Owner or Bidder), caption, body, tail, the number behind ComplBodyDec/ComplBodyInt, and value() which strips the quote marks a body is written with.

The same functions work on any text-carrying node: text::plain(&doc, node) takes a category label, a remark or an AddText as well.

From tender to bid

Bid::from_tender(&tender, bidder) re-reads the tender, relabels it X84 and carries the bidder as CTR. Then:

• price(id, up) sets the unit price (three decimals) and the total from the quantity.
• price_components(id, &[...]) sets up to six components that must add up to the unit price.
• free_quantity(id, qty) fills a quantity the tender left open (QtyTBD).
• not_offered(id) marks an item as not offered: no price is transmitted.
• fill_complement(id, mark, text) answers a bidder field in the long text.
• markup(id, base, percent) prices a Zuschlagsposition.
• discount_percent, vat_percent set the bill-level figures.

finish() refuses when an item is neither priced nor marked, computes the total of every category and of the bill with the standard’s rounding, writes no total on items that do not count (an X84 no longer says why they would not), and returns the X84 document. doc.write(&doc.x84_options()) writes it strictly: a missing required element is an error, not a report.

Tenders in 3.0 or 3.1 are answered in 3.2, the oldest version gaebboss writes; 3.2 and 3.3 tenders are answered in their own version.

Validation

validate(&doc) checks a document on its own:

• phase rules from the official schema profile: elements the phase does not carry, required elements that are missing (3.2 and 3.3 only);
• identifiers: duplicated ID, dangling IDRef;
• Ordnungszahlen: the RNoPart pattern, 14 characters at most, unique and ascending in the standard’s sort order;
• decimals: Qty and UP with at most three places, IT and VAT with two;
• arithmetic: IT = round2(Qty × UP), category totals against their items, the bill total against its categories;
• X84: no unit price on a not-offered item.

validate_against_tender(&bid, &tender) checks a bid against the tender it answers: the same categories, the same items, quantities unchanged unless the tender left them open. Items are matched by ID and, failing that, by Ordnungszahl; a changed ID is a warning.

Findings carry a severity, a code, the Ordnungszahl where there is one and a message. The CLI exits 1 when any finding is an error.

Writing files

doc.write(&WriteOptions { version, phase, indent, prog_system, strict }) writes the typed tree as XML in the target version’s element order, applying the target phase’s profile: elements the phase does not carry are dropped and reported in WriteReport.dropped; required elements that are missing are reported in missing, or refused when strict is set.

Writing the version and phase a file came in reproduces its content: every official fixture and every file of the real-world corpus round-trips to byte-identical output on the second pass, with unknown vendor elements copied verbatim.

Children that may interleave in the schema (texts and bidder fields, items and remarks, paragraphs and lists) keep the order they were read in; everything else follows the schema. Pretty printing never touches text-level elements, so whitespace inside a paragraph is never changed.

make conformance writes X81 to X84 files from the official fixtures and validates them against the official XSDs with lxml.

Python

pip install gaebboss

gaebboss.Document(path) or gaebboss.Document(data=bytes, name="x.X83") parses with the GIL released; data takes bytes, bytearray, memoryview or any other buffer and copies it once. Everything it returns is a plain object: items(), categories(), markup_items(), boq, project, warnings, validate(), validate_against(tender), to_json(), write(...) and write_report(...). Every GAEB number is a decimal.Decimal built from its exact text; passing a float to a bid raises GaebError.

from decimal import Decimal
import gaebboss

tender = gaebboss.Document("tender.X83")
bid = gaebboss.Bid.from_tender(tender, {"name1": "Bau GmbH", "street": "Weg 1", "pcode": "12345", "city": "Berlin"})
for item in tender.items():
    if item.kind == "FreeQuantity":
        bid.free_quantity(item.id, Decimal("10.000"))
    bid.price(item.id, Decimal("12.50"))
bid.vat_percent(Decimal("19"))
doc = bid.finish()
assert [f for f in doc.validate() if f.severity == "Error"] == []
open("bid.X84", "wb").write(doc.write())

Documents are immutable and can be shared between threads; parsing sixteen copies in a thread pool scales with cores. Reading a file, items(), validate(), validate_against(), write(), write_report(), to_json(), Bid.from_tender() and Bid.finish() all run with the GIL released, so other Python threads keep running meanwhile. Item decimals become decimal.Decimal when the attribute is read.

Command line

gaebboss info FILE                      # version, phase, project, counts, total, warnings
gaebboss items FILE [--counting] [--tsv]
gaebboss text FILE --oz OZ [--markdown]
gaebboss json FILE [--compact]
gaebboss validate FILE [--tender X83]   # exit 1 on errors
gaebboss roundtrip FILE -o OUT [--phase X84] [--version 3.3] [--pretty] [--strict]
gaebboss bid X83 --prices prices.csv --bidder bidder.toml -o OUT.X84 [--pretty]

prices.csv has a header oz,up or id,up, one row per item, - for a not-offered item and an optional third column with the quantity of a free quantity item. bidder.toml holds name1, street, pcode, city and optionally name2, contact, email, bidder_no, vat_percent, discount_percent.

Rust API

The crate is gaebboss-core; cargo doc --open -p gaebboss-core has the full reference. The entry points:

Lower layers are public too: bytes::normalize, lexer::lex and tape::Tape give the flat tape; version::detect the route; read::Reader and the generated generated::read the typed readers.

Python API

The authoritative signatures are the stubs shipped with the package, gaebboss/_gaebboss.pyi. In short:

• Document(path=None, *, data=None, name=None); properties version, phase, warnings, project, boq; methods items(kind="all"), categories(), markup_items(), to_json(), validate(), validate_against(tender), write(*, phase, version, pretty, strict), write_report(*, phase, version, strict).
• Item: id, oz, kind, alternative_group, alternative_serial, short_text, long_text, long_text_markdown, quantity, unit, unit_price, total, vat, counts_towards_total, not_offered, category_ozs, complements.
• Bid.from_tender(document, bidder); price, price_components, not_offered, free_quantity, fill_complement, markup, discount_percent, vat_percent, finish().
• GaebError for every failure.

CLI reference

gaebboss --help and gaebboss <command> --help print the options. Exit codes: 0 on success, 1 when validate finds errors, 2 on an unreadable input or a bad argument.

Schema coverage

Generated by cargo xtask coverage from standard/3.3/GAEB_DA_XML_Lib_3.3_2021-05.xsd. Every element the 3.3 library declares is read into the typed model and written back; this table says which ones the semantic layer (items, texts, bids, validation, JSON) also interprets.

Performance

Measured on 2026-11-01 on an aarch64 workstation (Cortex-X925, 20 cores, single-threaded throughout), Rust 1.99, release profile. Reproduce with cargo bench -p gaebboss-core and cargo xtask corpus --dir <files>.

Stages, criterion

The synthetic file is dense: small items with long texts and many elements per byte. Real files carry more text per element, which is why the 75 MB X81 reads four times faster per byte.

Whole corpus, cargo xtask corpus

164 real-world files, 189.6 MB, DA XML 3.0 to 3.3:

Warnings over the corpus: 800 unknown elements (vendor extensions such as Codetext and OZ, and HTML placed where the schema has none) and 9 duplicated Totals, all kept.

Why it is fast

• One pass over the bytes with memchr builds a flat tape of spans; nothing is copied unless an entity has to be decoded.
• Element names resolve through a generated length-switched match, no hashing.
• The typed model stores spans and fixed-point decimals, so building it allocates one Vec per repeated field and nothing per string.
• Readers and writers are generated per type as straight loops: no reflection, no per-value dispatch, no intermediate DOM.
• Texts are rendered from the tape on demand, so a caller that never asks for a long text never pays for it.

perf is not available in the environment this was built in; the remaining profiling work is listed under limitations.

Limitations

• GAEB 90 (.d8x), GAEB 2000 (.p8x) and DA XML before 3.0 are detected and named, not parsed.
• Writing targets 3.2 and 3.3. A 3.0 or 3.1 document is written as 3.2.
• Phases outside X80 to X89 (trade X93 to X97, cost X50 to X52, quantity X31, Zeitvertrag) are read into the typed model and written back, but have no navigation layer, no validation rules and no tests beyond “reads without error”.
• Converting a document to a phase that requires elements the source lacks yields an invalid file by construction; the write report names the missing elements, and strict turns them into an error.
• Validation checks decimal places for Qty, UP, IT and VAT; other facets (string lengths, patterns beyond RNoPart) are left to the XSD check in make conformance.
• Text projections and complements read the parsed source; edits made through Bid show up after the document is written and read again.
• perf was unavailable where this was built, so the profiling pass is still open; see performance.