gPdf
Blog

PDF-Metadatenfelder erklärt: title, language, author, subject, creator, producer

Feldweise Tour durch die sechs Standard-PDF-Metadatenfelder, die gPdf anbietet — title, language, author, subject, creator, producer. Wofür sie da sind, wer sie liest, häufige Fehler und wie Sie das Ergebnis verifizieren.

gPdf Engineering
#pdf-metadata#pdf-spec#technical-reference

Das Pendant zu In den PDF-Eigenschaften sollte Ihre Marke stehen, nicht das Tool eines anderen — jener Beitrag machte den Fall, warum PDF-Metadaten zählen. Dieser hier ist das Betriebshandbuch: Wofür jedes Feld in der PDF-Spezifikation steht, wer es liest, häufige Fehler und wie Sie verifizieren, dass Ihr Output tatsächlich enthält, was Sie senden wollten.

gPdf stellt die sechs Standardfelder bereit, die die PDF-Spezifikation für Metadaten auf Dokumentebene definiert. Sie liegen unter settings.metadata im DocumentRequest-JSON. Jedes Feld ist optional — wenn Sie es nicht setzen, fällt gPdf entweder auf das default_metadata des Tokens (Enterprise-Policy-Feature) oder auf einen System-Default zurück.

{
  "settings": {
    "metadata": {
      "title":    "...",
      "language": "...",
      "author":   "...",
      "subject":  "...",
      "creator":  "...",
      "producer": "..."
    }
  }
}

Der Rest des Beitrags besteht aus je einem Abschnitt pro Feld. Jeder Abschnitt folgt derselben Form: was das Feld ist, wo es auftaucht, häufige Fehler, Faustregel. Die Reihenfolge entspricht dem, was Sie zuerst befüllen sollten → zweites → … → zuletzt.

title — was das Dokument ist

Die PDF-Spezifikation beschreibt dies als „Dokumenttitel“.

Wo es auftaucht:

  • Die Titelleiste in PDF-Viewern (Adobe Reader, Preview, Foxit, Chromium-PDF-Viewer zeigen ihn alle an).
  • Der Browser-Tab, wenn das PDF inline geöffnet wird (Content-Disposition: inline).
  • Suchindizes — Spotlight, Outlook, SharePoint, Google Drives Volltextindex lesen title und gewichten ihn stark.

Häufige Fehler:

  • ❌ title auf den Dateinamen setzen. invoice-20260318.pdf ist der Dateiname. Der Titel sollte etwas sein, das ein Mensch liest, etwa Invoice INV-2026-3401. Dateiname und Titel sind unterschiedliche Belange: Der Dateiname ist für Dateisysteme, der Titel für Viewer und Suche.
  • ❌ title leer lassen. Viewer fallen auf den Dateinamen zurück. Das Ergebnis liest sich als automatisch generiert und maschinell ausgegeben.
  • ❌ Die Marke in title hineinstopfen. Acme Logistics — Invoice INV-2026-3401 macht die Titelleiste unübersichtlich. Die Marke gehört in author, nicht in title.

Faustregel: Der Titel sollte dem H1 der gerenderten Seite entsprechen. Wenn die Kopfzeile Ihres Rechnungstemplates „Invoice INV-2026-3401“ lautet, ist genau das der Titel.

language — für Barrierefreiheit, Suche und Compliance

language ist ein BCP-47-Sprachtag: en, de, zh-Hans, pt-BR, ar-SA. Setzen Sie es für jedes Dokument. Von den sechs Feldern hat es die konkretesten nachgelagerten Konsequenzen und die geringsten Implementierungskosten — deshalb steht es auf Position 2 und nicht weiter unten.

Wo es auftaucht:

  • Bildschirmleser — JAWS, NVDA, VoiceOver verwenden es, um den richtigen Phonemsatz zu wählen. Ein englischer Bildschirmleser, der ein PDF mit language: "de" liest, spricht deutsche Wörter korrekt aus; ohne das Tag stimmt die Prosodie nicht.
  • Suchmaschinen und Indexer — bestimmt, welche Stemmingregeln und Stopword-Listen einer Locale angewendet werden. Eine Rechnung mit language: "zh-Hans" wird mit chinesischer Segmentierung indexiert; ein fehlendes Tag fällt häufig auf Englisch zurück und der Index wird unbrauchbar.
  • PDF/A-Konformität — PDF/A-2a und PDF/A-3a (Barrierefreiheits-Profile) verlangen den Sprachtag. Ohne ihn schlägt die veraPDF-Validierung schlicht fehl.

Häufige Fehler:

  • ❌ Es ungesetzt lassen. Default sollte „die Sprache des Empfängers“ sein, nicht „der Default der Plattform“. Die meisten undichten Stacks schreiben das Feld einfach nicht; Folge sind Bildschirmleser, die falsch aussprechen, und Suchindizes, die falsch stemmen.
  • ❌ Einen Nicht-BCP-47-String wie "english" oder "EN-US" verwenden. Die PDF-Spezifikation erwartet RFC-5646-Tags: en, en-US, de, pt-BR.
  • ❌ Den Plattform-Default hart kodieren (z. B. immer "en"), unabhängig von der tatsächlichen Inhaltssprache. Eine portugiesische Rechnung mit "en" zu taggen, ist schlimmer als ein ungetaggtes Dokument — es führt den Indexer aktiv in die Irre.

Faustregel: Der Tag sollte der tatsächlichen Inhaltssprache entsprechen. Für eine Kundin in Brasilien, die eine portugiesische Rechnung erhält, setzen Sie "language": "pt-BR", nicht "en". Für mehrsprachige Dokumente nehmen Sie die dominante Sprache und verwenden für den Rest das Lang-Attribut an einzelnen Inhaltselementen — das ist ein Barrierefreiheits-Feature von tagged PDFs jenseits des Feldes language auf Dokumentebene.

author — wem das Dokument gehört

In der PDF-Spezifikation ist author „der Name der Person oder Organisation, die das Dokument erstellt hat“. Für Geschäfts-PDFs, die an Empfänger gehen, ist die Antwort fast immer die Organisation — die richtige Form variiert aber tatsächlich nach Kontext.

Wo es auftaucht:

  • Der Eigenschaftendialog in jedem PDF-Viewer, prominent mit „Author“ beschriftet.
  • DMS-/Archiv-Indexer, häufig als Filter genutzt.
  • Der XMP-Metadatenstrom in PDF/A, der ins Langzeitarchiv übernommen wird.

Häufige Fehler:

  • ❌ "author": "[email protected]" — leakt versehentlich die E-Mail-Adresse der Bedienperson in jedes PDF, landet in jedem Suchindex, wird zu einem dauerhaften PII-Problem.
  • ❌ "author": "PDF Generator Service" — interner Tool-Name; bedeutet dem Empfänger nichts.
  • ❌ Leer — Preview und die meisten Viewer zeigen wortwörtlich „(no author)“ im Eigenschaftendialog, was sich liest wie „niemand verantwortet dieses Dokument“.

Funktionierende Formen:

  • ✅ "author": "Acme Logistics, Inc." — schlichte Organisation.
  • ✅ "author": "Acme Logistics — Billing" — Organisation + Abteilung, für Dokumente, die zu einem bestimmten Posten routen.
  • ✅ "author": "Bridge Capital Partners — Fund III" — nützlich im Finanz-/Rechtsumfeld, wo die Zuordnung zu einer spezifischen Entität gehört.
  • ✅ "author": "Maria López, RICS Surveyor" — für einzeln autorenschaftliches Publizieren (Gutachten, Wertermittlungen, juristische Stellungnahmen), wo die Person die redaktionelle Zuordnung IST.

Faustregel: Author ist die Entität, mit der der Empfänger das Dokument assoziieren soll. In einem Multi-Tenant-SaaS, in dem die Plattform PDFs im Namen von Kunden erzeugt, sollte author der Organisationsname des Kunden sein, nicht der Name der Plattform. (Der Name der Plattform gehört in creator — siehe unten.) In Beratungs-/Publishing-/Rechtskontexten, in denen Einzelpersonen die Marke sind, sind Einzelpersonen okay.

subject — welche Art von Dokument das ist

subject ist die Kurzbeschreibung des Dokuments. Viewer machen es nicht prominent — die meisten Nutzer sehen es nie, außer sie öffnen den Eigenschaftendialog. Dokumenten-Management-Systeme, Archivsysteme und regelbasiertes E-Mail-/Datei-Routing nutzen es aber.

Wo es auftaucht:

  • Eigenschaftendialog, sekundäre Position.
  • DMS-Routing-Regeln, Archiv-Bucketing-Logik.
  • XMP-Metadatenstrom (PDF/A).

Häufige Fehler:

  • ❌ "subject": "Invoice for Acme on 2026-03-18 for $4,532.10" — das ist eine Beschreibung einer Dokumenten-Instanz, kein Typ. Gehört in title.
  • ❌ Leer — verschenkt einen kostenfreien Routing-Hook für nachgelagerte Systeme.
  • ❌ Klassen inkonsistent mischen ("Invoice" vs "Invoice/2026-03" vs "Monthly invoice") — DMS-Filter können nicht auf bewegliche Ziele bucketen.

Funktionierende Formen:

  • ✅ "subject": "Invoice"
  • ✅ "subject": "Monthly account statement"
  • ✅ "subject": "Shipping label — 4×6 thermal"
  • ✅ "subject": "Q3 2026 board pack"

Faustregel: Die richtige Granularität ist die Dokumentenklasse, nicht die Dokumenteninstanz. Ein DMS mit Tausenden eingehender PDFs kann auf subject routen, wenn Sie ihm ein konsistentes Vokabular geben. Wählen Sie eine endliche Menge an Klassen für Ihre Plattform und weichen Sie nie davon ab — jede Rechnung, die Ihre Plattform erzeugt, sollte exakt "subject": "Invoice" haben.

creator vs. producer — das am häufigsten verwechselte Paar

Hier hören die meisten Teams auf, die PDF-Spezifikation zu lesen, und beginnen zu raten. Die Spezifikation ist präzise; die beiden Felder bedeuten Unterschiedliches.

  • creator — die Anwendung, die den Quellinhalt erzeugt hat (das vorgelagerte System, das entschieden hat, was das Dokument sagen soll).
  • producer — die Anwendung, die die PDF-Bytes erzeugt hat (die Rendering-Engine, die diesen Inhalt in eine PDF-Datei verwandelt hat).

Für eine SaaS-Billing-Plattform, die Rechnungen über eine JSON-to-PDF-API wie gPdf erzeugt:

  • creator = die SaaS-Billing-Plattform mit ihrer Version. Diese Anwendung hat entschieden, dass das eine Rechnung für Acme über 4.532,10 USD sein soll.
  • producer = der Renderer. Standardmäßig ist das „gPdf“. Da die Rendering-Schicht jedoch Infrastruktur ist, die der SaaS gewählt hat, kann der SaaS producer legitim auf den eigenen Plattformnamen setzen — die Plattform hat in einem echten Sinne die PDF-Bytes erzeugt, indem sie an gPdf als Infrastruktur delegiert hat.
{
  "creator":  "Acme Billing Platform v7.2",
  "producer": "Acme Billing Platform"
}

Wo sie auftauchen:

  • Eigenschaftendialog, beide beschriftet.
  • pdfinfo-Output, nebeneinander.
  • PDF/A-XMP-Strom (in PDF/A müssen beide Felder nicht-leer sein).

Häufige Fehler:

  • ❌ creator auf einen Chromium-/Mozilla-User-Agent-String gesetzt. Passiert, wenn ein Headless-Browser-PDF-Stack den User-Agent automatisch in creator durchreicht. Das ist die Browser-Version, nicht das maßgebliche Quellsystem. Überschreiben.
  • ❌ producer als Default-Renderer-Name belassen. Die meisten Teams überschreiben das nie, also sagt jedes PDF „Skia/PDF m120“ oder „wkhtmltopdf“ — warum das für B2B zählt, siehe den White-Label-Beitrag.
  • ❌ Denselben Wert in beide Felder schreiben. Zulässig, aber verschwenderisch — die beiden Felder existieren genau, damit ein Viewer „Quell-App“ von „Render-Engine“ unterscheiden kann. Nutzen Sie sie.

Faustregel: creator ist Ihr Anwendungsname mit Version (z. B. "Acme Billing Platform v7.2"); producer ist die Marke oder der Plattformname Ihrer Anwendung ohne Version (z. B. "Acme Billing Platform"). Beides sollten Werte sein, die der Empfänger wiedererkennt.

Leere Felder, Token-Defaults, nachgelagerte Überraschungen

Drei Implementierungsdetails, die vor dem Live-Gehen lohnen:

  1. Leere oder reine Whitespace-Strings werden als nicht angegeben behandelt. "title": "" zu senden ist dasselbe wie title wegzulassen — es schreibt keine leere Zeichenkette ins PDF, sondern durchläuft die Fallback-Kette (Token-Default → System-Default). Das ist die häufigste Ursache des Bugs „Ich habe es gesetzt, es wurde nicht übernommen“.
  2. Token-Policies können Metadatenfelder entfernen oder mit Defaults belegen. Ein Multi-Tenant-SaaS, der gPdf nutzt, kann pro API-Token ein default_metadata setzen, sodass jedes PDF, das mit diesem Token erzeugt wird, die author- und producer-Werte des Kunden trägt, ohne darauf zu vertrauen, dass jeder Entwickler sie pro Request setzt. Der Token-Default ist die richtige Durchsetzungs-Schicht für „Jedes Acme-PDF muss Acme sagen“.
  3. Nachgelagerte Pipelines können Ihre Metadaten überschreiben. Tools, die PDFs nach der Rückgabe von gPdf nachbearbeiten — Ghostscript ohne explizite Metadaten-Erhaltungs-Flags, manche Enterprise-DRM-Tools, manche „PDF-Optimierer“ — können Producer mit ihrem eigenen Namen überschreiben und das gerade gesetzte Branding zunichte machen. Verifizieren Sie gegen Ihre tatsächliche Produktions-Pipeline, nicht nur gegen die rohe gPdf-Antwort.

Verifizieren Sie Ihre Metadaten

Nach Umsetzung der Änderungen oben gibt es drei schnelle Wege zu prüfen, ob das PDF auch wirklich enthält, was Sie senden wollten:

Kommandozeile (macOS / Linux, benötigt poppler-utils):

$ pdfinfo your-output.pdf | head -10
Title:           Invoice INV-2026-3401
Subject:         Monthly invoice — 2026-03
Author:          Acme Logistics, Inc.
Creator:         Acme Billing Platform v7.2
Producer:        Acme Billing Platform
Language:        en

Acrobat / Adobe Reader: Datei → Eigenschaften → Tab Beschreibung. Alle sechs Felder erscheinen, Title zusätzlich oben in der Titelleiste des Viewers.

macOS Preview: ⌘+I (Informationen einblenden). Der „PDF“-Inspektor zeigt dieselben Felder.

Erscheint ein Feld leer, blank oder mit einem Tool-Namen, den Sie nicht gesetzt haben, gehen Sie den Request-Body durch — die häufigste Ursache ist das Senden von "" (leerer String), den die API als „nicht angegeben“ behandelt und die Fallback-Kette zu einem Default-Wert durchläuft. Zweithäufigste Ursache ist eine nachgelagerte Pipeline (Ghostscript, DRM, Optimierer), die das Feld nach der Rückgabe von gPdf überschreibt; testen Sie gegen Produktion, nicht nur gegen die rohe Render-Antwort.

Metadaten in der PDF/A-Archivierung

Wenn Sie für die Langzeitarchivierung mit settings.profile: "pdfa-2b" (oder -2a, -3a, -3b) rendern, hört Metadaten auf, optional zu sein, und wird tragend:

  • Das Feld producer darf in einer PDF/A-konformen Datei nicht leer sein — mindestens der System-Default wird geschrieben.
  • language ist für die Barrierefreiheits-Profile (PDF/A-2a, PDF/A-3a) erforderlich. Ohne es fällt die veraPDF-Validierung schlicht durch.
  • Der XMP-Metadatenstrom, den PDF/A verlangt, wird aus den sechs Feldern oben automatisch erzeugt; Sie müssen ihn nicht selbst konstruieren.
  • title, author, subject, creator, producer und language wandern allesamt in den XMP-Strom, sodass der Metadaten-Indexer eines nachgelagerten Archivs (Preservica, Archivematica) seinen Katalog daraus aufbauen kann, ohne den Dokumentkörper neu zu parsen.

Für ein Archivdokument sind gebrandete Metadaten nicht nur Markenkosmetik — sie sind Teil der Dauerhaftigkeit des Artefakts. Das deutsche Zollamt, die brasilianische Steuerbehörde oder jedes Langzeitarchiv, das Ihr PDF in zehn Jahren öffnet, sieht das, was am Tag des Renderings in diesen Feldern stand. Sie bewusst zur Render-Zeit zu setzen, ist die einzige Gelegenheit, die Sie haben.

Was gPdf (noch) nicht bietet

Um über die heutige Oberfläche ehrlich zu bleiben: Die PDF-Spezifikation definiert auch Keywords (frei-form Suchbegriffe) sowie einen XMP-Metadatenstrom, der beliebige benutzerdefinierte Key-Value-Paare unterstützt. Beides exponiert gPdf in der aktuellen API nicht.

Wenn Sie heute beliebige Geschäftsdaten ins PDF einbetten müssen (Bestell-UUID, Lagercode, Template-Version), sind die Workarounds:

  • subject auf einen strukturierten Kurzstring setzen, den nachgelagerte Systeme parsen.
  • Die Geschäftsdaten in der eigenen Datenbank halten, indexiert per Dateiname oder Inhalts-Hash.
  • Abwarten — XMP-Custom-Felder stehen auf der Roadmap, und wenn sie ausgeliefert sind, sind sie die richtige Antwort für verborgenen, maschinenlesbaren Workflow-Kontext.

„Gebrandete Metadaten“ (die sechs Standardfelder, heute) und „benutzerdefinierte Business-Metadaten“ (XMP-Custom-Felder, zukünftig) zu vermengen, ist der einfachste Weg, das heute Mögliche zu überversprechen. Lohnt, beides in der eigenen Planung getrennt zu halten.

Ein vollständiges Beispiel

Eine SaaS-Billing-Plattform (Acme Billing Platform) erzeugt eine Rechnung für einen deutschen Kunden (Müller Versand GmbH), bereit zur Archivierung als PDF/A:

{
  "settings": {
    "profile": "pdfa-3b",
    "metadata": {
      "title":    "Rechnung RE-2026-0412",
      "language": "de",
      "author":   "Müller Versand GmbH",
      "subject":  "Monatsrechnung — März 2026",
      "creator":  "Acme Billing Platform v7.2",
      "producer": "Acme Billing Platform"
    }
  }
}

pdfinfo gegen das resultierende PDF:

$ pdfinfo invoice-2026-0412.pdf | head -10
Title:           Rechnung RE-2026-0412
Subject:         Monatsrechnung — März 2026
Author:          Müller Versand GmbH
Creator:         Acme Billing Platform v7.2
Producer:        Acme Billing Platform
Language:        de

Titel auf Deutsch, author als Müller Versand (die GmbH des Kunden, Empfänger des Dokuments), creator als Acme Billing Platform (das redaktionelle System, das entschieden hat, was auf der Seite steht), producer als Marke der Acme Billing Platform, language korrekt für den deutschen Bildschirmleser und für den deutschen Volltextindexer getaggt, der das später im DMS von Müller aufgreift. Das Profil PDF/A-3b bedeutet, dass dieser Metadatensatz für die Langzeitarchivierung zusätzlich in den XMP-Strom serialisiert wird.

Nichts in den Dateieigenschaften nennt gPdf, Chromium oder irgendein Tool, das der Kunde nicht gewählt hat. Was genau der Punkt ist.

Das kleinstmögliche Upgrade

Wenn Sie bereits an /api/v1/pdf/render POSTen und Ihr aktueller Call kein settings.metadata enthält, ist die kleinste Verbesserung drei zusätzliche Zeilen im JSON, das Sie ohnehin senden:

 {
   "pages": [...],
   "settings": {
+    "metadata": {
+      "author":   "Your customer's organisation",
+      "producer": "Your platform"
+    }
   }
 }

Zwei Felder, ein neuer Key. In Sekunden mit pdfinfo verifizierbar. Sobald das steht, befüllen Sie title, language, subject und creator, wenn Sie Zeit haben.

Wo das landet