Module and API reference — datev-exporter

Deep-dive references

Four pages cover the parts of the DATEV contract that generate the most questions. Each is generated from the library, so the tables match what the exporters actually write.

Field reference

All 125 Buchungsstapel columns in output order, with official headings, checker types, lengths and version-12 availability.

Validation errors

The six stable error codes, what raises each one, the paired fields and the three validation depths.

EXTF header

The 31-field management record: fixed identifiers, date and timestamp formats, quoting rules and the coded fields.

Encoding and umlauts

Windows-1252, CRLF, semicolons and quoting — which characters survive and how exports get corrupted afterwards.

Artifacts

Module map

Published Maven artifacts in release 0.2.0
Artifact	Runtime dependencies	Responsibility
`datev-exporter`	None (platform POM)	BOM that aligns every module on one version. It contains no runtime API.
`datev-exporter-core`	None	Canonical schemas, field definitions, metadata, headers, CSV codec and validation model.
`datev-exporter-plain`	`core`	Fixed v13/v12 retained file and forward-only writer. Recommended output module.
`datev-exporter-field-validator`	`core`	Optional semantic validator callback for the plain exporter.
`datev-exporter-advanced`	`core`	Retained files with custom/renamed/reordered headings and built-in validation modes.
`datev-exporter-advanced-univocity`	`advanced` + Univocity	Adapter for applications already committed to a Univocity `CsvWriter` pipeline.

datev-exporter-verification and datev-exporter-benchmarks are internal build modules; they are not in the BOM or Maven Central publication.

Decision table

Plain, advanced or Univocity?

Exporter trade-offs
Need	Plain	Advanced	Univocity adapter
Complete fixed v13/v12 EXTF	recommended	yes with exact official header, strict mode and compatible metadata	no management record
Forward-only rows	yes `DatevStreamWriter`	no rows retained	Writes advanced retained rows through a third-party writer
Rename/reorder headings	no	yes	yes via advanced file
Custom charset	no byte path is Windows-1252	Only for metadata-free custom downstream contracts	Uses advanced file charset; strict encoder wrapper provided
Third-party runtime dependency	None beyond core	None beyond core	Univocity
Official heading byte shape	Canonical unquoted heading	Canonical on built-in writer with official header	Text headings are quoted differently

Default recommendation

Use plain unless you can state a concrete custom-heading requirement. Use retained DatevFile for inspection/replay and DatevStreamWriter for one-pass production.

Layered checks

Validation catches technical defects, not business truth

Always on in built-in output

Structural and encoding safety

Column width/order, known headings, CSV syntax/control characters, row limit and strict Windows-1252 encodability on byte output.

Optional plain dependency

`DatevValidator`

A format-version/immutable-row callback. Build it with account length, fiscal-year start and period to validate context-dependent account and date rules.

Advanced configuration

`DatevValidationMode`

STRICT adds mandatory fields and dependencies; FIELD_LEVEL validates supplied known fields; NONE keeps structural CSV/header checks.

Always application-owned

Accounting and master data

Account selection, tax treatment, validity in the target ledger and client-specific requirements must be validated outside this library.

Adding datev-exporter-field-validator alone changes nothing. Pass the validator to the plain builder/factory. Official advanced schemas default to STRICT; custom headers default to NONE because their domain semantics are unknown.

Interop, not replacement

The Univocity adapter solves one narrow problem

Choose datev-exporter-advanced-univocity only when the surrounding application already centralizes CSV emission in Univocity and heading-plus-booking-row output is the intended boundary.

CsvWriter writer = DatevUnivocityWriters.newCsvWriter(file, outputStream);
DatevUnivocityWriters.writeTo(file, writer);

A CsvWriter emits uniformly shaped records and therefore cannot emit the differently shaped 31-field EXTF management record.
writeTo rejects a metadata-backed file. Use the advanced built-in DatevFile.writeTo(OutputStream) for a complete file.
writeDataTo explicitly writes only heading and rows, even if metadata exists.
With unmodified official v12/v13 settings, booking rows match built-in output, but text headings are quoted differently. Whole-file byte parity is not claimed.
The supplied newCsvWriter reports unmappable characters and leaves the caller stream open. Avoid raw Univocity constructors that may replace unsupported characters with ?.

Ownership rules

Output stays caller-owned

Built-in writers flush but do not close a caller-supplied OutputStream or Writer.
Use the OutputStream overload for canonical Windows-1252 bytes. A character Writer is only a character contract; its final encoder is yours.
Wrap otherwise unbuffered file/network output once. The library intentionally does not choose a persistent buffer size.
Plain and advanced DatevFile retain accepted rows. DatevStreamWriter hands each accepted row forward and discards its assembly storage.
All mutable exporter instances are single-threaded by design.

See the buffered streaming example and benchmark report before choosing based on volume.

Symbol-level reference

Use versioned Javadoc for exact signatures

This guide explains contracts and decisions. The generated API site is the source for public classes, methods and their lifecycle details:

Pre-1.0 compatibility

The project follows Semantic Versioning, but public APIs may change between minor versions until 1.0.0. Pin the BOM version and read release notes when upgrading.