TUGboat, Volume 43 (2022), No. 3

263

Adding XMP metadata in LATEX
Ulrike Fischer, Frank Mittelbach
Abstract
One task of the “LATEX Tagged PDF Project” [6] isto evaluate existing solutions to add XMP metadata
to a PDF, and if needed, to design and implement
a new standard interface for this. In this article wewill describe the current state of this task.
Contents
1Introduction

263

2Creating the XMP metadata
2.1 The hyperxmp package . . . . . . . .
2.2 The pdfx package . . . . . . . . . . .
2.3 hyperxmp and pdfx clash . . . . . . .

263
264
264
265

3 XMP metadata with the LATEX PDF
management support
3.1 Design goals for the XMP metadata
support . . . . . . . . . . . . . . . .
3.2 Implementation of the design goal .
3.3 Status and outlook . . . . . . . . . .

1

265
266
266
267

Introduction

The PDF format offers two places to store metadata.
For one there is the Info dictionary. It is directly at
the root of the PDF structure and contains key–value
pairs representing document data, such as the PDF
creation date (e.g., /CreationDate (D:20221005153151+02’00’)) and title (e.g., /Title (Bearwear)).
(Recall that string constants in PDF and PostScript
are enclosed in parentheses.) Various standard keys
exist, such as /Title, /Author and /CreationDate,but the dictionary can also hold private keys. pdfTEX
for example adds its banner: /PTEX.Fullbanner(This is pdfTeX, ...). PDF viewers normallyshow a selection of the standard keys in the properties of a PDF. All TEX engines offer tools to addcontent to this dictionary and to change the values
added automatically by the engines. In LATEX thetitle and the author are normally added with thehelp of the hyperref package and its pdftitle andpdfauthor keys.
While the Info dictionary can hold arbitrary
data, it is nevertheless only an unordered list and not
well suited as a serious data container. So in PDF 1.4
a second option was added to the format: one canembed an XML file with the data and reference thisfile from the PDF catalog through the /Metadata

key.1 The format of the XML is defined as part of aframework called the Extensible Metadata Platform(XMP), first described in an Adobe document and
now an ISO standard [3], and so commonly these
metadata are referred to as XMP metadata.
In PDF 2.0, the XMP metadata replaces thedeprecated Info dictionary. In earlier PDF versions
the metadata has already been required by standards
like the various PDF/A and PDF/X versions, PDF/UA(the standard for accessible PDF), and standards forelectronic invoice data exchange like ZUGFeRD 2.2/
Factur-X 1.0 [1]. It is therefore quite important tohave tools and interfaces to add them to a PDF. In
the following we will describe various existing options
and give our outlook on future plans in this area.
We assume that all source files are UTF-8 encoded and won’t mention places where 8-bit encoded
files need perhaps additional care (XMP metadata
in the PDF are always UTF-8 encoded).
2Creating the XMP metadata

It is quite easy to add an XML file to a PDF andto reference it in the catalog. In all engines thiscan be done with a few lines of code; the small
package xmpincl [9] demonstrates it for pdfLATEX.
The challenge is to correctly build the content.
• At first, as always with XML there is quite alarge amount of formal syntax to understandand follow.
• PDF standards contain further demands on thecontent and the structure of the XML. As an example, properties that don’t count as predefined[8] must be declared in extension schemas, and if
data like a title is present in the Info dictionary
and in the XMP metadata they must match —something that is not easy to ensure as they use
different encodings and formatting and so thisrequires concrete tests with PDF viewers andvalidators.
• Then one must decide which XMP metadatashould be supported (various more or less standard name spaces exist here) and devise userinterfaces for the data that can’t be detected
automatically.
• User input must be sanitized, properly escapedfor use in an XML file and converted to UTF-8.
In the past, two LATEX packages took on thistask. They don’t produce exactly the same XMP
metadata, but the differences are small; on the whole,they settled more or less on the same set.
1 It is possible to add more XML files and to reference
them from other parts of the PDF but in this article we restrict
the discussion to the document-wide data container.

Adding XMP metadata in LATEX
doi.org/10.47397/tb/43-3/tb135fischer-xmp

264

TUGboat, Volume 43 (2022), No. 3

Listing 1: A selection of XMP metadata added
automatically by hyperxmp<pdf:PDFVersion>1.5</pdf:PDFVersion><dc:format>application/pdf</dc:format><xmp:CreateDate>2022-10-06T10:27:33+02:00</xmp:CreateDate><xmp:CreatorTool>LaTeX with hyperref</xmp:CreatorTool><xmpMM:DocumentID>
uuid:aef2b675-9b18-4d18-97f7-a3339b139000</xmpMM:DocumentID>

Listing 2: hyperxmp example with additional\hypersetup keys
\documentclass{article}\usepackage{hyperxmp}\usepackage{hyperref}\hypersetup{
pdftitle = {Über einen die Erzeugung undVerwandlung des Lichtes betreffenden
heuristischen Gesichtspunkt},pdfauthor={Albert Einstein},pdflang = {de},pdfmetalang={de},pdfdate={1905-03-17},
pdfcontactcity={Bern},
pdfcontactcountry={Switzerland},pdfissn={0003-3804},
pdfdoi={10.1002/andp.19053220607},}\begin{document}
Text\end{document}

2.1

The hyperxmp package

Simply loading the hyperxmp package from Scott
Pakin [7] will add XMP metadata. Listing 1 showssome selected lines.
hyperxmp supports all major compilation routes:
pdfLATEX, LuaLATEX, XELATEX, LATEX with dvips,2(u)(p)LATEX with DVIPDFMx.
For the user interface, the package hooks intothe \hypersetup command of hyperref. It retrieves
the values of native hyperref keys like pdftitle andpdfauthor and defines new keys for a variety ofadditional XMP metadata. Listing 2 shows a few
examples. The hyperxmp package supports quite alarge set of metadata tags but has no interface toextend this set.
2 But sadly Ghostscript has no option to add the XMP
metadata as an uncompressed stream.

Ulrike Fischer, Frank Mittelbach

hyperref is used by hyperxmp not only for theuser interface but also to sanitize the user input: Alluser input is first converted by \pdfstringdef to theformat used in bookmarks and then back to UTF-8;
it can contain arbitrary Unicode characters and allcommands supported by hyperref in the bookmarks.
If hyperref is missing it is loaded automatically byhyperxmp at the end of the preamble. If the document should contain XMP metadata but not links
or bookmarks, load hyperref with the package option
draft.
Individual items in the author and keyword lists
should be separated by commas; if a real comma iswanted \xmpcomma must be used.
Some keys allow adding language variants withthe command \XMPLangAlt:\hypersetup{pdflang=de,pdftitle=Mein Titel}\XMPLangAlt{en}{pdftitle={My title}}

This results in metadata using the xml:lang attribute:<dc:title><rdf:Alt><rdf:li xml:lang="x-default">Mein Titel</rdf:li><rdf:li xml:lang="de">Mein Titel</rdf:li><rdf:li xml:lang="en">My title</rdf:li></rdf:Alt></dc:title>

2.2

The pdfx package

The goal of the pdfx package [2], currently maintained by Ross Moore, is to support the generationof PDF/X-, PDF/A- and PDF/E-compliant documents.
As XMP metadata are required by the standards they
are created by the package, but it will (in part depending on the requested standard) also embed acolor profile, change ToUnicode values, redefine mathaccents and more.
pdfx can only be used with pdfLATEX, LuaLATEX
and XELATEX. (It makes use of the xmpincl package
written for pdfLATEX for the actual embedding of theXMP data and tweaks it a bit to make it compatible
with the two other engines). The compilation withXELATEX requires the use of --shell-escape as pdfxcalls LuaLATEX to retrieve the creation date of the file;
this can be avoided by defining \pdfcreationdate
manually before loading pdfx, e.g.3\def\pdfcreationdate{\string D:20221002224824+10’00’}
3 The \string is needed as pdfx expects a D with catcode
other.

TUGboat, Volume 43 (2022), No. 3

Listing 3: Example input with the pdfx package\begin{filecontents}[force]{\jobname.xmpdata}\Title{Baking through the ages}\Author{A. Baker\sep C. Kneader}\Language{en-GB}\Keywords{cookies\sep muffins\sep cakes}\Publisher{Baking International}\end{filecontents}\documentclass{article}\usepackage[a-1b]{pdfx}\begin{document}
some text\end{document}

When using pdfx the user must provide metadata in an external file with the extension .xmpdata.
It is recommended to create this file at the beginningof the document with a filecontents environment.
In this .xmpdata file the data are then given asarguments of various commands—Listing 3 shows
an example. The arguments can contain arbitrary
Unicode characters, and don’t need to be printablein the document. Commands for non-Latin characters like \CYRD (cyrillic), \hebzayin (hebrew) or\textarabicfa can also be used, if enabled throughpackage options like cyrxmp and hebxmp.
pdfx loads hyperref as it, like hyperxmp, uses
\pdfstringdef to sanitize some of the input. It alsouses hyperref to set the PDF version. As hyperref
normally should be loaded late but the PDF version
must be set early, getting the loading order right canget tricky.
The default setup for the XMP metadata isstored in external templates,4 pdfa.xmp, pdfx.xmp,pdfe.xmp, . . . . By copying these templates and adjusting them it is possible to add private data. As aside effect of the processing the resulting XMP data
are written to a file, pdfa.xmpi or pdfx.xmpi, whichallows to feed them to an RDF validator [11].
Lists are created if the items are separated by
the command \sep. Language support is offeredthrough optional arguments:\Title[en]{Baking through the ages}\Keywords[de]{Kekse%\sep[en]Cookies%\sep[fr]Biscuits}

This will result in:

4 Depending on the standard, pdfx will create slightly
different metadata.

265<dc:title><rdf:Alt><rdf:li xml:lang="en">Baking through the ages</rdf:li></rdf:Alt></dc:title><dc:subject><rdf:Bag><rdf:li xml:lang="de">Kekse</rdf:li><rdf:li xml:lang="en">Cookies</rdf:li><rdf:li xml:lang="fr">Biscuits</rdf:li></rdf:Bag></dc:subject>

2.3

hyperxmp and pdfx clash

The two packages can’t be used in the same document. As both use low-level primitive commands toreference their XMP stream, the PDF catalog would
contain two /Metadata entries if both packages areused, and this is invalid in a PDF:/Metadata 3 0 R /Metadata 6 0 R

3XMP metadata with the LATEX PDF

management support
Over the past years the LATEX Project Team has inconnection with the Tagged PDF project [6] written and released code targeting various PDF-relatedtasks. Some of this code is already included in the kernel through the l3pdf module of the L3 programminglayer [4], the rest is provided through the external
bundle pdfmanagement-testphase [5].
The goals of this code are, first, to provide abstracted, backend independent commands. So for example instead of setting the pdf version directly (depending on the engine: with \pdfminorversion, or\pdfvariable minorversion or with a \special),
you can use \pdf_gset_version:n{1.7} with all
supported backends. hyperref already makes use of
this: when the PDF management is active the samegeneric driver is loaded for all backends.
The second goal of the new code (and the reason why it is called PDF management) is to prevent
clashes like the one between hyperxmp and pdfx mentioned above, by providing interfaces for managed
access to central PDF resources. If for example twopackages try to add a /Metadata reference or someother resources to the catalag, then the code will
ensure that the conflict is correctly resolved — eitherby merging the resources or by rejecting one of therequests.
The PDF management doesn’t work with packages that bypass the interfaces by using primitive
Adding XMP metadata in LATEX

266

TUGboat, Volume 43 (2022), No. 3

commands. This means neither hyperxmp nor pdfx
are usable with it, and a replacement to add theimportant XMP metadata was needed. As an intermediate solution hyperxmp was patched but as partof task 2.3.4 of the feasibility study [6] this patch
has now been replaced by proper support in thel3pdfmeta package of the pdfmanagement-testphasebundle.
3.1

Design goals for the XMP metadata
supportAfter reviewing the existing packages the following
main design goals of the new XMP metadata support
have been identified:• The dependency to hyperref should be removed.
XMP metadata are not directly related to links
and other interactive features and should work
also in documents which don’t use them.
• The standard interface should be a key–value
system with \DocumentMetadata as the defaultinterface command. To ease the transition fromhyperxmp the \hypersetup keys should continue
to work where possible.
• The input should support the full range of Unicode and standard commands.
• The default set of supported XMP tags should
be similar to the set of the existing packages.
• There should be no need in the user input for special commands like \xmpcomma, \XMLlangalt or\sep. List items should be input as comma lists
where “real commas” are protected by braces
as usual. The language alternatives can be set
with optional arguments.
• As with pdfx it should be possible to export theXMP metadata in an external document, but
this should be a debug option.
• The XMP metadata should be extensible. As aproof of concept, an example document showing
how to add the metadata needed for a ZUGFeRD
document should be developed.
3.2

Listing 4: Minimal input for XMP metadata with thePDF management\DocumentMetadata{%xmp=false, % no XMP
xmp=true% optional as default}\documentclass{article}\begin{document}abc\end{document}

code relies on \text_purify:n and other functions
from the L3 layer to sanitize the input.
XMP metadata for the PDF standard,5 the PDF
version and the language are already retrieved fromkeys set in \DocumentMetadata:\DocumentMetadata{pdfstandard = a-2b,pdfversion = 1.7,
lang= de}At the moment other metadata still requires
the use of the hyperref and the \hypersetup interface with the hyperxmp keys known from listing 2 —we haven’t decided yet how to name and organize
suitable keys in the \DocumentMetadata command.
As outlined in the design goals, lists are input ascomma lists with real commas protected by braces asusual. Where sensible it is possible to add a language
tag with an optional argument before the item. The
next listing demonstrates both for the title:\hypersetup{ pdftitle={[en]Baking,[de]{Kekse, Kuchen und Torten backen}}}

This results in this metadata:

Implementation of the design goal

The new XMP metadata support has been implemented in the l3pdfmeta module and is loaded together with PDF management code. This is done byusing the \DocumentMetadata command with key–value pairs at the beginning of the document. XMP
metadata are then automatically added to the PDF
they can be suppressed by setting the key xmp tofalse (see listing 4). This works with all engines
supported by the L3 layer backend.
In accordance with the goals specified above
the minimal document doesn’t require hyperref: TheUlrike Fischer, Frank Mittelbach<dc:title><rdf:Alt><rdf:li xml:lang="en">Baking</rdf:li><rdf:li xml:lang="de">Kekse,Kuchen und Torten backen</rdf:li></rdf:Alt></dc:title>
5 As with pdfx, declaring a standard can have further effects; for example, embed a color profile or do some validations.
Be aware that LATEX can neither ensure nor check all requirements of any given standard, and an external validator likeveraPDF [10] should be used.

TUGboat, Volume 43 (2022), No. 3The XMP metadata can be exported to an external file — the default name is \jobname.xmpi —with a debug setting in \DocumentMetadata:\DocumentMetadata{debug = { xmp-export, more debug options . . . }}Finally, first steps have been undertaken to extend the XMP metadata. To support, for example,
the ZUGFeRD standard, additions to the XMP metadata are needed in three places:• A new XML namespace with a suitable prefixmust be declared.
• A new schema with declarations for the new tags
must be added to the pdfaExtension:schemas
section.
• And the data itself must be added.

267[3] International Organization for Standardization.
ISO 16684-1:2019: Graphic technology —Extensible metadata platform (XMP)
specification — Part 1: Data model,serialization and core properties. 2nd ed., 2019.
www.iso.org/obp/ui/#!iso:std:75163:en[4] LATEX Project Team. The l3kernel package.
ctan.org/pkg/l3kernel[5] LATEX Project Team. The pdfmanagementtestphase package. ctan.org/pkg/pdfmanagement-testphase[6] F. Mittelbach, U. Fischer, C. Rowley.
LATEX tagged PDF feasibility evaluation.
latex-project.org/publications/2020tagged-pdf-feasibility.pdf[7] S. Pakin. The hyperxmp package.
ctan.org/pkg/hyperxmp

For all these tasks internal functions have been defined, and a first prototype that implements theZUGFeRD 2.2 standard exists, but it isn’t yet clear
what the public interface should look like.

[8] PDF competence center. Technote 0008:
Predefined XMP properties in PDF/A-1.
Technical report, 2008. www.pdfa.org/
resource/technical-note-tn0008predefined-xmp-properties-in-pdfa-1/

3.3[9] M. Sneep. The xmpincl package.
ctan.org/pkg/xmpincl

Status and outlook

The new code supports XMP metadata at a comparable level to that provided by the existing packages.
Almost all of the above design goals are already
implemented. There remains some work to do toprovide suitable public interfaces for certain parts.
Also needed are more tests with PDF viewers andvalidators to check if their interpretation of the standards agrees with the code. Feedback and comments
are welcome!
References[1] Forum for Electronic Invoicing Germany.
What is ZUGFeRD? www.ferd-net.de/standards/what-is-zugferd[2] Hàn Thế Thành, P. Selinger, et al. The pdfx
package. ctan.org/pkg/pdfx[10] veraPDF consortium. veraPDF—industry
supported PDF/A validation. verapdf.org[11] W3C. W3C RDF validation service.
www.w3.org/RDF/Validator/⋄ Ulrike Fischer
LATEX Project TeamBonn
Germany
ulrike.fischer (at)latex-project.org⋄ Frank Mittelbach
LATEX Project Team
Mainz
Germany
frank.mittelbach (at)latex-project.org

Adding XMP metadata in LATEX