A hybrid invoice is not "a PDF with an attachment", it is a contract between four pieces: a PDF/A-3 container, an embedded XML under a prescribed file name, an AFRelationship that declares what the XML is, and an XMP metadata block that mirrors the invoice profile. Validators check the pieces against each other, so most embedding bugs are mismatches: the XMP names a file that is not there, the conformance level contradicts BT-24, the attachment exists but is not associated. Here is what each piece must say.
The container: PDF/A-3, nothing less
Only PDF/A-3 permits embedding arbitrary files, so the base document must genuinely conform: fonts embedded, an output intent (sRGB in practice), no encryption, no forbidden features. Two consequences developers meet early:
- You cannot upgrade a random PDF by stamping metadata on it. A non-conformant base stays non-conformant with an invoice inside.
- Anything that re-saves the file can demote it. Print-to-PDF, "optimize", stamping tools and some mail gateways silently produce a plain PDF and drop the attachment, which is how valid invoices die in transit.
The attachment: one XML, the right name
| Format and profile | Required attachment name |
|---|---|
| Factur-X 1.x and ZUGFeRD 2.x, all normal profiles | factur-x.xml |
| ZUGFeRD, the XRECHNUNG reference profile | xrechnung.xml |
| Legacy ZUGFeRD 1.0 | zugferd-invoice.xml |
The embedded file entry itself carries a MIME subtype of text/xml and, for a clean file, modification date, size and checksum parameters. The name is not decoration: receiving systems locate the invoice by it, and a beautifully embedded invoice.xml is simply not found.
Two structural requirements round it off: the file must be reachable through the document's embedded-files name tree and referenced from the document-level /AF (associated files) array. Libraries that only do one of the two produce files that some validators accept and others refuse.
AFRelationship: what the XML claims to be
The file specification carries an AFRelationship key that declares the role of the XML:
/Alternativefor full-invoice profiles: the XML is an alternative representation of the same invoice. This is the German practice for BASIC, EN 16931, EXTENDED and XRECHNUNG./Datafor MINIMUM and BASIC WL: those profiles are booking aids, not complete invoices, so they must not claim to be an alternative representation. French Factur-X practice has historically used/Datamore broadly; both values are within the specification.
Omitting the key entirely is the actual bug to avoid: an embedded file without a declared relationship fails PDF/A-3 association checks.
The XMP block: the profile, said twice
The Factur-X extension schema (shared by ZUGFeRD, the fx namespace) must be declared in the XMP packet and filled with four properties:
| Property | Correct value |
|---|---|
fx:DocumentType |
INVOICE |
fx:DocumentFileName |
Exactly the attachment name, e.g. factur-x.xml |
fx:Version |
The schema version, 1.0; the XRECHNUNG profile carries its CIUS version |
fx:ConformanceLevel |
One of the closed set: MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED, XRECHNUNG |
Two classic failures live here. First, the extension schema must be declared in the XMP (PDF/A validators reject undeclared custom properties), not just used. Second, fx:ConformanceLevel must mirror the profile URN in the XML's BT-24: a file whose XMP says EN 16931 while the XML says BASIC contradicts itself, and contradiction is what validators are for.
The mistakes validators actually flag
- Name mismatches: XMP says
factur-x.xml, the attachment isinvoice.xml, or the XRECHNUNG profile ships asfactur-x.xml. - Missing association: attachment present,
/AFarray absent, or no AFRelationship. - Profile contradiction between
fx:ConformanceLeveland BT-24. - Undeclared XMP extension schema, failing PDF/A metadata checks.
- A base PDF that never was PDF/A: missing fonts, no output intent, or an encrypted file.
- Duplicate attachment file names once supporting documents ride along; every embedded file needs a unique name.
- Post-processing after embedding: any tool that touches the file last must preserve conformance, or the pipeline's order must change.
Doing and checking it
The fastest route is the tool to embed XML in PDF: it packages a CII XML into a conformant PDF/A-3 with naming, association and XMP handled for you. If you build the container in your own code, check it in the ZUGFeRD validator: the report covers the container and the embedding alongside the XML rules, so a seam mismatch shows up before a customer sees it. For the rule layers on the XML itself, start with validating ZUGFeRD output from your own code.
What to do now
- Write the four-piece contract into one constant table in your code: profile, attachment name, AFRelationship, conformance level. Derive everything from it, including BT-24.
- Embed as the last step of your pipeline, after every other PDF manipulation.
- Validate the hybrid, not just the XML, in CI and after any library upgrade.
- Check a golden file after each release of whatever produces your base PDF; conformance regressions arrive silently.
- Or skip the container work entirely: the ZUGFeRD API creates the conformant PDF/A-3 from JSON in one call, embedding handled; the create/zugferd endpoint reference shows the request.
Legal position as at September 2026, last reviewed on 25 September 2026. Based on the ZUGFeRD and Factur-X specifications with the shared fx XMP extension schema, the PDF/A-3 standard (ISO 19005-3) and the European standard EN 16931.
Frequently asked questions
Why must it be PDF/A-3 and not PDF/A-1 or a normal PDF?
Because only PDF/A-3 allows embedding arbitrary files. PDF/A-1 forbids attachments entirely, and a plain PDF gives no conformance guarantees, so receiving systems will not treat the result as a hybrid invoice. How the whole hybrid file fits together is covered in the ZUGFeRD format guide.
Which attachment name is correct?
factur-x.xml for Factur-X and ZUGFeRD in the normal profiles, xrechnung.xml for the ZUGFeRD XRECHNUNG reference profile, and zugferd-invoice.xml only in legacy ZUGFeRD 1.0 files. The XMP's DocumentFileName must repeat the name exactly.
Alternative or Data for AFRelationship?
/Alternative when the XML is a full invoice (BASIC and above): it is an alternative representation of the same document. /Data for the MINIMUM and BASIC WL booking-aid profiles, which must not claim that status.
Can I embed additional documents next to the invoice XML?
Yes, PDF/A-3 allows further attachments, for example timesheets. Give every file a unique name and its own association; duplicate names are an error on the German rule side.
My XML validates on its own. Why does the hybrid fail?
Because the container is checked too: PDF/A conformance, the association of the attachment and the XMP block that mirrors the profile. Validate the finished hybrid file, not only the XML you put into it.