Skip to content
LpdfDocsv0.36-r1119.4

Lpdf is pre-release. The XML schema and SDK APIs can change between releases.

Attachments

A PDF can carry files inside it: the XML of an invoice for the software that books it, the spreadsheet a report was made from, or the terms that go with an offer. A reader lists them in its attachments panel, and saves or opens them from there. Lpdf embeds the files a document lists in its attachments, as they are: it does not draw them.

<lpdf version="1">
<document>
<attachments>
<file name="invoice.xml" src="data/invoice-2026-0412.xml" mime="text/xml" relationship="data"
description="The invoice as data, for software to read"/>
<file name="terms.pdf" src="terms.pdf" mime="application/pdf" relationship="supplement"/>
</attachments>
<section>
<layout margin="48pt">
<text font-size="24pt">Invoice 2026-0412</text>
<text>The invoice data and the terms of sale are attached to this PDF.</text>
</layout>
</section>
</document>
</lpdf>

attachments sits in document, after meta and output and before the sections. It holds one file for each file the PDF carries.

Attribute Type Default Description
name string required The name a reader shows the file under and saves it as, such as invoice.xml. Each file of a document has a name of its own
src path — Where the SDK reads the file from, when it was not loaded on the engine
ref string the name The key the file was loaded on the engine under, when that is not its name
mime string application/octet-stream The type of the file, such as text/xml, application/pdf or text/csv: a type and a subtype. Without it a reader knows only that it is a file
relationship source data alternative supplement unspecified unspecified How the file relates to the document: the file it was made from, the data its pages show, the same content in another form, or more than the pages show. The XML of a Factur-X invoice gets the one its profile asks for
description string — A line about the file, which a reader shows beside its name

The files belong to the whole document. A file pinned to a spot on a page, or tied to one image or table, is not written.

The bytes of a file come as an image’s do. The SDK reads src, relative to the working directory of your app, or you load the bytes on the engine yourself, under the file’s name or its ref. A file loaded on the engine is used for every render of that engine, and its src, if it has one, is not read.

import { L } from '@lpdfio/lpdf'
import { readFileSync, writeFileSync } from 'node:fs'
const pdf = await L.engine()
.loadFile('invoice.xml', readFileSync('data/invoice-2026-0412.xml'))
.render(xml)
writeFileSync('invoice.pdf', pdf)

A document built in code lists its files in attachments, a list of FileAttr with the attributes of file: attachments: [{ name: 'invoice.xml', mime: 'text/xml', relationship: FileRelationship.Data }] in JavaScript, attachments(List.of(…)) on DocumentAttr in Java, Attachments in C#. FileRelationship holds the five relationships.

A file has no size limit of its own: its bytes count toward the render’s memory cap, 1024 MB unless the engine sets another. In the Python, Java, C# and PHP SDKs the bytes travel to the engine as base64 in a JSON request, so a large file costs several times its size in memory while it renders, and each copy counts toward the cap: the request, the bytes the engine decodes and the PDF that holds them. The SDK holds the request and the PDF sent back besides. JavaScript hands the bytes to the engine directly, before the render, so only the PDF that holds them counts.

In an encrypted document the files are encrypted with the rest, under the same passwords.

A PDF/A-2 file can carry only files that are PDF/A themselves, which the engine can’t check, so attachments with pdfa="2a", "2b" or "2u" is an error. PDF/A-3, pdfa="3a", "3b" or "3u", carries files of any kind. In a PDF/A-3 document, a file named factur-x.xml makes the PDF a Factur-X e-invoice.

A PDF/X file holds only what the press prints, so attachments with pdfx is an error. What combines with what has the other pairs.

Each of these stops the render with an error that says what to change:

  • a file with no bytes: no src, and nothing loaded under its name or ref. The error names the key to load it under
  • a src the SDK can’t read. The error names the file and the path
  • two files with the same name
  • a relationship that isn’t one of the five, or a mime that isn’t a type and a subtype
  • a file without a name
  • a file over 2 GB
  • attachments in a document whose output asks for pdfa="2a", pdfa="2b", pdfa="2u" or pdfx
  • a file named factur-x.xml or xrechnung.xml in a document that is not PDF/A-3: see Factur-X / ZUGFeRD