Mustangproject, ZUV, ZUGFeRD 2 and the ZUGFeRD Extensions

veröffentlicht von usegroup am 19.03.2019 um 07:42

This is the preliminary list of homework to do for the next versions of ZUV and Mustangproject. Any help which speeds this up a bit is very welcome.

Andreas Starke had already published a way how ZUGFeRD "extensions"/additional data can accomodate special needs of industry branches (, e.g. if you need to specify the mileage in a logistics your invoice can say "one washing machne, one dry cleaner" and the additional data can say that the delivery truck transported the washing machine 500km but the dry cleaner only 25 because it was picked up elsewhere. There is a python library and a command line tool to embed/extract this files, the idea is that the mustangproject library and command line tool can do that too and ZUV can validate this additional data.

We had been in the process of implementing that but I would like to delay that until after our homework for ZUGFeRD 2 is done.

This means I am working on a mustangproject 2.0 for ZUGFeRD 2.0 and a ZUV 0.7.0 as validator, afterwards a mustangproject 2.1 and a ZUV 0.8 might cover the additional data might appear.

Homework for ZF2

check if extended should be re-introduced

Since the ZF2 extended profile has finally been published, one could check if it can be used again and is still valid
How you could help:
AFAIK the original code has just been commented out to be en16931 compatible for factur-x. Send me a PR with that code again active.

change name of embedded file

apparently there were changes after the public preview, e.g. the file name now seems to be zugferd-invoice again.

How you can help:

  • Check the specs if the filename is specified at all (since it's anyway in the metadata it's possible that it's arbitrary in which case we could leave it with factur-x)
  • Check if there were any other last minute changes
  • REMOVE the backward-compatibility layer (factur-x invoices currently also contain a ZF1 zugferd-invoice.xml, this is now no longer possible)
  • ZF2 should become standard in Mustangproject so we need a little method to enable factur-x instead (i.e. change the filename).

switch default version from 1 to 2

currently version 1 is the default and version2 has to be enabled by default (I think it's sth like setZUGFeRDVersion()). In future, v2 should be default and v1 needs to be enabled by default.
How you can help:
This is a trivial change since I think it's the change of the value of is a single member variable.
Send me a pull request. And by all means, change existing unit tests to factur-x and write unit tests for ZF2.

use the new schematron files in ZUV

Since ZF2 has now been officially released we can use it's schematron files.

How you could help:

  • download zugferd 2 infopaket
  • check if you can find the referenced files (the version from 2019-03-13 e.g. referred to zugferd2p0_en16931_codedb.xml in Schema/EN16931/zugferd2p0_en16931.sch and to zugferd2p0_extended_codedb.xml in Schema/EXTENDED/zugferd2p0_extended.sch): I did not find them
  • merge those files into one schematron each (because we deploy to one jar file and ph-shematron can not load dependencies from resources?). This can be done if you add the file in a namespace, e.g. codes:codedb, add the namespace declaration in schematron root element (xmlns:codes="") and references (e.g. ) and
  • update the reference everywhere the old document(filename) reference used to be and
  • send me a pull request

and check if that removes this error

How you can help:

  • check if the issue vanishes with the 1.1 release of cen schematron
    We deploy in a single jar and the schematron file uses include statements, last time it was sufficient to just copy all included files into one. if that does not help:
  • check if the issue vanishes with the new schematron files
  • add the file to the
  • extract the factur-x.xml and add a automatic test

Homework for ZUGFeRD Extensions

Mustang 2.1 with extensions

How you can help:
The library can already add/extract but we need tests for that and we options for the command line tool to be able to do that as well, probably both interactively prompting for the filename and scripted.

ZUV 0.8 with extensions

How you can help:

  • There is a generic schema(sic! not schematron) file for ZUGFeRD extensions and the extensions might get custom, extension specific schema files. We need a way to check schema files in the first place. For schematron we used but I don't know if that supports schema files, if not we need an according library, which can load from our resources (we deploy in a single jar file) preferrably via maven central or other maven repos.
  • Add that, add the schema file from Andreas' website to the resources, use the most recent, unreleased version of mustangproject
  • git pull mustangproject, "mvn clean package" have maven cache the local file as 1.6.1
    mvn install:install-file -Dfile=mustang-1.6.1-SNAPSHOT.jar -DgroupId=org.mustangproject.ZUGFeRD -DartifactId=mustang -Dversion=1.6.1 -Dpackaging=jar -DgeneratePom=true then in ZUV in

    switch version to
    "mvn clean install" and "mvn eclipse:eclipse") to check if there are extensions and get the value with sth like mustangprojects'getAdditionalDataXML()
  • invent some section for the report additional to the existing and and probably BELOW , document that syntax, have the schema check run in case additional data is there, bundle it all together and send me a PR.

Janitoral works:

a new sample invoice

For ZF2 we need a new official sample file, this time in english
How you can help:
Download the blanko 506 .odt file as documented, open in libreoffice, translate to english, adjust the dates and export to PDF.
copy the source code for the file generated in the tests (the factur-x file with 506 in it's name) to a new test, update the invoice date to today, translate the positions and by all means put more then half a litre of air into those balloons. Pull request, run the tests and attach the generated sample file to this ticket :-)

amend the timeline

This is a trivial one:

How you can help:
amend the einvoices-history.json file to include the dates of the ZF2 release
ZF2 release 11.03. and the ZF 2.0.1 release 13.03 (apparently there had been a correction or amendmend, see the infopaket's readme.txt). Send a according pull request.
Background: this json file feeds a timeline, e.g. embedded on

add ZF2 samples to corpus

The new official ZUGFeRD 2 samples need to be included in the corpus collection

How you can help
Download a infopaket from, upload it into ZUGFeRDv2/correct/intarsys (`cat zugferd_2p0_EXTENDED_Fremdwaehrung.pdf | grep -i intarsy` matches that's why I believe this could be the original engine) and submit

We also need to clean up corpus a little

How you can help: e.g. add a according table to with the file names, maybe an ID and commit comments

Translate Schematron file 

The ZF2 schematron displays error messages in german. The file should be translated to show them in english.
How you can help:
get the ZUGFeRD 2 infopaket, translate the german texts in the (assert tags only?) of the xml files SCHEMA/BASIC und MINIMUM/zugferd2p0_basicwl_minimum.sch, SCHEMA/EN16931/zugferd2p0_en16931.sch, and SCHEMA/EXTENDED/zugferd2p0_extended.sch and attach the files to this ticket

Make commandline similar to ZUV

ZUV e.g. starts with a "--action validate" parameter, we should also start mustangproject with something like "--action=embed-xml", "--action=embed-additional-data", "--action=extract-xml", "--action=extract-additional-data",

How you can help: have a look at ZUV, change toecount (the mustangproject command line) accordingly. Change help text. Propose changes for documentation e.g. on website. Currently we are only using jargs in both projects, maybe there is some library to have a uniform way to treat interactive (e.g. prompt for filename) and scripted parameters (i.e. filename is passed as argument).

Migrate Mustangproject homepage to Wordpress

How you can help:
someone is already working on that issue :-)
a preview of the german translations is a available if you add .de to the pages, e.g.

Möchtest Du Dich wirklich abmelden?

Abbrechen Jetzt abmelden