What is \DocumentMetadata? What key-value pairs does it take and when should I use it?

Question

So, I stumbled across a document that began with,

\DocumentMetadata{pdfversion=1.2}
\nonstopmode\synctex=1
\documentclass{article}

I have seen line 2 and 3 in the wild but I have never seen line 1 anywhere before. I am curious what is it, what does it do and what values does it accept?

Answer 1

\DocumentMetadata is a rather new command, it has been announced one year ago in the LaTeX news . It is the trigger to tell LaTeX that the current document is a new/modern document that should use concepts not available in traditional LaTeX2e documents, for example, everything developed for the PDF tagging project which has the goal to enable LaTeX to easily and automatically produce tagged PDF's. (https://www.latex-project.org/publications/indexbytopic/pdf/)

This new command has to come first in a LaTeX document, before \documentclass. It is used, as the name suggests, to set metadata about the entire document, but while the PDF tagging project is being worked on, it is also used to enable new code from this project.

If you use it without any option if will load the new PDF management code (currently in the pdfmanagement-testphase package) which is used for various PDF related tasks like transparency, spotcolors, XMP-metadata, changing the pdfversion and support for PDF standards. A visible effect is that it will change the default link colors of hyperref.

\DocumentMetadata has a number of keys which are described in documentmetadata-support-doc.pdf (and also in ltdocinit.pdf of the pdfmanagement-testphase package):

• pdfversion: to set the pdfversion, e.g. pdfversion=2.0 (setting it to 1.2 as in your example is not something that I would recommend).
• pdfstandard: to set a standard, e.g. pdfstandard=A-2b
• lang: to set the /Lang key in the pdf catalog, e.g. lang=de
• xmp: a boolean to suppress the XMP-metadata
• colorprofiles: to add and configure color profiles (more info in l3pdfmeta.pdf)
• uncompress: to produce an uncompressed PDF (it is a short hand for debug={uncompress}, but I need it so often ...).
• backend: to set a backend/engine that can not be detected automatically, e.g. dvipdfmx.
• debug: to set debug options

There are a few packages and classes which are not compatible with the PDF management, but for most documents it should be unproblematic to use \DocumentMetadata with the keys mentioned above.

This is not the case for last key testphase. It enables automation for tagging and all of this automation is currently in a prototype state and restricted to the use of standard classes (article, report, and book) and supports only a limited number of add-on packages (feedback about problems with other packages are welcome).

The testphase key accepts a comma list of values. Currently the main values are phase-I (a bit tagging), phase-II (more tagging), phase-III (needs LaTeX 2023-06-01 or newer and perhaps a latex-dev). But there are some more, e.g. with \DocumentMetadata{testphase={phase-III,math}} you can additionally load a prototype for math tagging. It is recommended to follow the LaTeX news and to check the latex-lab bundle if you want to test that.

Answer 2

If everything else fails there's read-the-source-code in texdoc source2e.

As suggested, proceed to texdoc documentmetadata-support.

So in this case the command will "set the PDF version explicitly" to 1.2.

---

Internally, you can guess that LaTeX simply forward it to the corresponding engine primitive:

Technically, you can set whatever value you want and it seem to work anyway:

\DocumentMetadata{pdfversion=9.9}
\documentclass{article}
\begin{document}
hello world
\end{document}

gives a PDF file that starts with

%PDF-9.9
%¿÷¢þ

Realistically, according to Wikipedia the latest version is 2.0, and viewer compatibility varies.

See Why is 1.5 the default pdf version? - TeX - LaTeX Stack Exchange for the difference between PDF format versions and which version to pick.