De begeleidende post bij PDF-eigenschappen horen uw merk te tonen, niet de tool van iemand anders — die post bouwde het pleidooi voor het serieus nemen van PDF-metadata. Deze is de handleiding: waar elk veld voor dient in de PDF-specificatie, wie het leest, de veelvoorkomende fouten en hoe u verifieert dat uw output werkelijk bevat wat u bedoelde.

gPdf legt de zes standaardvelden bloot die de PDF-spec definieert voor metadata op documentniveau. Ze leven onder settings.metadata in de DocumentRequest-JSON. Elk veld is optioneel — als u er één niet instelt, valt gPdf terug op ofwel het default_metadata van het token (Enterprise-policy-functie) ofwel op een systeemdefault.

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

De rest van deze post bestaat uit één sectie per veld. Elke sectie volgt dezelfde vorm: wat het veld is, waar het verschijnt, veelvoorkomende fouten, vuistregel. De volgorde is wat eerst invullen → daarna → … → als laatste.

`title` — wat het document is

De PDF-spec beschrijft dit als de “documenttitel”.

Waar het verschijnt:

De titelbalk in PDF-viewers (Adobe Reader, Preview, Foxit, de PDF-viewer van Chromium tonen het allemaal).
Het browser-tabblad wanneer de PDF inline opent (Content-Disposition: inline).
Zoekindexen — Spotlight, Outlook, SharePoint en de full-text indexer van Google Drive lezen allemaal title en wegen het zwaar.

Veelvoorkomende fouten:

❌ Title gelijkstellen aan de bestandsnaam. invoice-20260318.pdf is de bestandsnaam. De title zou iets moeten zijn dat een mens leest, zoals Invoice INV-2026-3401. Bestandsnaam en title zijn verschillende zaken; de bestandsnaam is voor filesystems, de title is voor viewers en zoekfuncties.
❌ Title leeg laten. Viewers vallen terug op de bestandsnaam. Het resultaat leest als automatisch gegenereerd en door een machine uitgespuugd.
❌ Het merk in de title stoppen. Acme Logistics — Invoice INV-2026-3401 slibt de titelbalk dicht. Het merk hoort thuis in author, niet in title.

Vuistregel: de title zou moeten overeenkomen met de H1 van de gerenderde pagina. Als de bovenste regel van uw factuurtemplate “Invoice INV-2026-3401” is, dan is dat de title.

`language` — voor toegankelijkheid, zoekfuncties en naleving

language is een BCP-47-taaltag: en, de, zh-Hans, pt-BR, ar-SA. Stel het in voor elk document. Van de zes velden heeft dit de meest concrete gevolgen verderop in de keten bij de kleinste implementatiekosten — daarom staat het op positie 2 en niet ergens lager begraven.

Waar het verschijnt:

Schermlezers — JAWS, NVDA, VoiceOver gebruiken het om de juiste verzameling fonemen te kiezen. Een Engelse schermlezer die een PDF met language: "de" voorleest, spreekt Duitse woorden correct uit; zonder de tag wordt de prosodie verkeerd.
Zoekmachines en indexers — bepaalt welke regels voor stemming en welke stopwoordenlijst van de locale van toepassing zijn. Een factuur met language: "zh-Hans" wordt geïndexeerd met Chinese segmentatie; een ontbrekende tag valt vaak terug op Engels en de index wordt onbruikbaar.
PDF/A-conformiteit — PDF/A-2a en PDF/A-3a (toegankelijkheidsprofielen) vereisen de taaltag. Zonder deze tag faalt veraPDF-validatie direct.

Veelvoorkomende fouten:

❌ Niet instellen. Gebruik als standaard “de locale van de ontvanger”, niet “de default van het platform”. De meeste lekkende stacks schrijven het veld eenvoudigweg niet; het resultaat zijn schermlezers die verkeerd uitspreken en zoekindexen die de verkeerde stemmingregels toepassen.
❌ Een niet-BCP-47 string gebruiken zoals "english" of "EN-US". De PDF-specificatie verwacht RFC 5646-tags: en, en-US, de, pt-BR.
❌ De default van het platform hard-coderen (bijvoorbeeld altijd "en") zonder rekening te houden met de werkelijke inhoudstaal van het document. Een Portugese factuur getagd "en" is erger dan een ongetagd document — het misleidt de indexer actief.

Vuistregel: de tag moet overeenkomen met de werkelijke inhoudstaal. Voor een klant in Brazilië die een factuur in het Portugees ontvangt, zet u "language": "pt-BR", niet "en". Voor meertalige documenten kiest u de dominante taal en gebruikt u het Lang-attribuut op individuele content-elementen voor de rest — dat is een tagged-PDF toegankelijkheidsfunctie, voorbij het language-veld op documentniveau.

`author` — wie het document toebehoort

In de PDF-spec is author “de naam van de persoon of organisatie die het document heeft gemaakt”. Voor business-PDF’s die naar ontvangers gaan, is het antwoord vrijwel altijd de organisatie — maar de juiste vorm verschilt werkelijk per context.

Waar het verschijnt:

Eigenschappendialoog in elke PDF-viewer, prominent gelabeld als “Author”.
DMS / archief-indexers, vaak gebruikt als filter.
PDF/A XMP-metadatastroom, waar het wordt meegedragen in langetermijnarchieven.

Veelvoorkomende fouten:

❌ "author": "[email protected]" — laat per ongeluk de e-mail van de operator in elke PDF lekken, belandt in elke zoekindex, wordt een langetermijn-PII-probleem.
❌ "author": "PDF Generator Service" — interne toolnaam; betekent niets voor de ontvanger.
❌ Leeg — Preview en de meeste viewers tonen letterlijk “(no author)” in de eigenschappendialoog, wat leest als “niemand is eigenaar van dit”.

Vormen die werken:

✅ "author": "Acme Logistics, Inc." — rechttoe rechtaan organisatie.
✅ "author": "Acme Logistics — Billing" — organisatie + afdeling, voor documenten die naar een specifiek bureau worden gerouteerd.
✅ "author": "Bridge Capital Partners — Fund III" — handig in finance/legal waar de toeschrijving aan een specifieke entiteit is.
✅ "author": "Maria López, RICS Surveyor" — voor mono-auteur publicaties (rapporten, taxaties, juridische opinies) waar de persoon DE redactionele toeschrijving is.

Vuistregel: author is de entiteit waaraan de ontvanger het document zou moeten koppelen. In een multi-tenant SaaS waar het platform PDF’s namens klanten genereert, zou author de organisatienaam van de klant moeten zijn, niet de naam van het platform. (De naam van het platform hoort in creator — zie hieronder.) Voor advies / publicaties / juridische contexten waarin individuen het merk zijn, zijn individuen prima.

`subject` — wat voor type document dit is

subject is de korte-beschrijving-van-het-document. Viewers tonen het niet prominent — de meeste gebruikers zullen het nooit zien tenzij ze de eigenschappendialoog openen. Maar documentbeheersystemen, archiefsystemen en regelgebaseerde e-mail/bestand-routering gebruiken het wel.

Waar het verschijnt:

Eigenschappendialoog, secundaire positie.
DMS-routeringsregels, archief-bucketinglogica.
XMP-metadatastroom (PDF/A).

Veelvoorkomende fouten:

❌ "subject": "Invoice for Acme on 2026-03-18 for $4,532.10" — dat is een instantiebeschrijving van een document, geen type. Het hoort in title.
❌ Leeg — kost u een gratis routeerhaak voor systemen verderop in de keten.
❌ Klassen inconsistent mengen ("Invoice" vs "Invoice/2026-03" vs "Monthly invoice") — DMS-filters kunnen niet bucketen op een bewegend doel.

Vormen die werken:

✅ "subject": "Invoice"
✅ "subject": "Monthly account statement"
✅ "subject": "Verzendetiket — 4×6 thermisch"
✅ "subject": "Q3 2026 board pack"

Vuistregel: de juiste granulariteit is de documentklasse, niet de documentinstantie. Een DMS met duizenden binnenkomende PDF’s kan op subject routeren als u het een consistent vocabulaire geeft. Kies een eindige set klassen voor uw platform en wijk er nooit van af — elke factuur die uw platform genereert moet precies "subject": "Invoice" hebben.

`creator` vs `producer` — het meest verwarde paar

Dit is waar de meeste teams stoppen met het lezen van de PDF-spec en gaan gokken. De spec is precies; de twee velden betekenen verschillende dingen.

creator — de applicatie die de broninhoud heeft geproduceerd (het upstream-systeem dat besliste wat het document zou moeten zeggen).
producer — de applicatie die de PDF-bytes heeft geproduceerd (de renderengine die die inhoud in een PDF-bestand heeft omgezet).

Voor een SaaS facturatie-platform dat facturen genereert via een JSON-to-PDF API zoals gPdf:

creator = het SaaS facturatie-platform met versie. Dat is de applicatie die besloot dat dit een factuur voor Acme van $4.532,10 zou moeten zijn.
producer = de renderengine. Standaard is dat “gPdf”. Maar omdat de renderlaag infrastructuur is die de SaaS koos, kan de SaaS legitiem producer zetten op de eigen platformnaam — zijn platform produceerde, in een werkelijke zin, de PDF-bytes door te delegeren aan gPdf als infrastructuur.

{
  "creator":  "Acme Billing Platform v7.2",
  "producer": "Acme Billing Platform"
}

Waar ze verschijnen:

Eigenschappendialoog, beide gelabeld.
pdfinfo-output, naast elkaar.
PDF/A XMP-stroom (beide velden moeten niet-leeg zijn in PDF/A).

Veelvoorkomende fouten:

❌ creator ingesteld op een Chromium / Mozilla user-agent string. Gebeurt wanneer een PDF-stack gebaseerd op een headless browser de User-Agent automatisch in creator doorgeeft. Het is de browserversie, geen gezaghebbend bronsysteem. Overschrijf het.
❌ producer gelaten als de standaard renderenginenaam. De meeste teams overschrijven dit nooit, dus elke PDF zegt “Skia/PDF m120” of “wkhtmltopdf” — zie de white-labelpost voor waarom dit ertoe doet in B2B.
❌ Dezelfde waarde in beide zetten. Acceptabel maar verspilling — de twee velden bestaan juist zodat een viewer onderscheid kan maken tussen “bronapp” en “renderengine”. Gebruik ze.

Vuistregel: creator is de naam van uw applicatie met versie (bijvoorbeeld "Acme Billing Platform v7.2"); producer is het merk of de platformnaam van uw applicatie zonder versie (bijvoorbeeld "Acme Billing Platform"). Beide zouden waarden moeten zijn die de ontvanger zou herkennen.

Lege velden, per-token defaults, downstream verrassingen

Drie implementatiedetails die het waard zijn om te kennen voordat u in productie gaat:

Lege of alleen-whitespace strings worden behandeld als niet meegegeven. "title": "" versturen is hetzelfde als title weglaten — het schrijft geen lege string in de PDF, maar loopt de fallback-keten af (token-default → systeem-default). Dit is de oorzaak van het meest voorkomende “ik heb het ingesteld, het pakte niet” bugrapport.
Token-policies kunnen metadatavelden strippen of een default geven. Een multi-tenant SaaS die gPdf gebruikt, kan een default_metadata op elk API-token instellen, zodat elke PDF die dat token genereert de author en producer van de klant meedraagt zonder te hoeven vertrouwen dat elke ontwikkelaar ze bij elke request instelt. De default op tokenniveau is de juiste afdwingingslaag voor “elke Acme PDF moet Acme zeggen”.
Naverwerkingsketens kunnen uw metadata herschrijven. Tools die PDF’s naverwerken nadat gPdf ze heeft teruggegeven — Ghostscript zonder expliciete metadata-behoudvlaggen, sommige enterprise DRM-tools, sommige “PDF-optimalisatoren” — kunnen Producer overschrijven met hun eigen naam en de branding die u zojuist instelde tenietdoen. Verifieer tegen uw werkelijke productieketen, niet alleen tegen de ruwe gPdf-respons.

Verifieer uw metadata

Na het implementeren van de bovenstaande wijzigingen, drie snelle manieren om te controleren of de PDF werkelijk verzonden heeft wat u bedoelde:

Commandoregel (macOS / Linux, vereist 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: Bestand → Eigenschappen → tabblad Beschrijving. Alle zes velden verschijnen, met Title getoond in de titelbalk van de viewer bovenaan.

macOS Preview: ⌘+I (Toon info). Het “PDF” inspector-paneel toont dezelfde velden.

Als een veld leeg, blank of met een toolnaam verschijnt die u niet heeft ingesteld, loop dan de request body opnieuw na — de meest voorkomende oorzaak is het versturen van "" (lege string), die de API behandelt als “niet meegegeven” en die de fallback-keten laat doorlopen tot een defaultwaarde. De op één na meest voorkomende oorzaak is een naverwerkingsketen (Ghostscript, DRM, optimalisator) die het veld overschrijft nadat gPdf het heeft teruggegeven; test tegen productie, niet alleen tegen de ruwe renderrespons.

Metadata in PDF/A-archivering

Als u rendert voor langetermijnarchivering met settings.profile: "pdfa-2b" (of -2a, -3a, -3b), houden metadata op optioneel te zijn en worden ze dragend:

Het producer-veld mag niet leeg zijn in een PDF/A-conform bestand — minimaal de systeem-default wordt meegegeven.
language is vereist voor de toegankelijkheidsprofielen (PDF/A-2a, PDF/A-3a). Zonder die tag faalt veraPDF-validatie ronduit.
De XMP-metadatastroom die PDF/A vereist, wordt automatisch gegenereerd uit de zes velden hierboven; u hoeft die zelf niet te construeren.
title, author, subject, creator, producer en language reizen allemaal mee in de XMP-stroom, zodat de metadata-indexer van een archiefsysteem verderop in de keten (Preservica, Archivematica) zijn catalogus eruit kan opbouwen zonder de documentbody opnieuw te parseren.

Voor een archiefdocument zijn gebrande metadata niet alleen merkpolitoer — ze maken deel uit van de duurzaamheid van het artefact. Het Duitse douanekantoor, de Braziliaanse belastingautoriteit of welk langetermijnarchief dan ook dat uw PDF over tien jaar opent, zal zien wat in die velden stond op de dag dat u het renderde. Ze bewust instellen op het moment van renderen is de enige kans die u krijgt.

Wat gPdf (nog) niet blootlegt

Om eerlijk te blijven over het oppervlak van vandaag: de PDF-specificatie definieert ook Keywords (vrije-tekst zoektermen) en een XMP-metadatastroom die willekeurige custom key-value pairs ondersteunt. gPdf legt geen van beide bloot in de huidige API.

Als u willekeurige businessdata in de PDF moet verstoppen (order-UUID, magazijncode, templateversie), zijn de huidige workarounds:

subject op een gestructureerde korte string zetten die systemen verderop in de keten parsen.
De businessdata in uw eigen database houden, gekoppeld aan bestandsnaam of contenthash.
Wachten — XMP custom fields staan op de roadmap, en wanneer ze landen zullen ze het juiste antwoord zijn voor verborgen machineleesbare procescontext.

“Gebrande metadata” (de zes standaardvelden, nu beschikbaar) verwarren met “custom business-metadata” (XMP custom fields, toekomst) is de gemakkelijkste manier om te veel te beloven over wat vandaag mogelijk is. Het is de moeite waard om die in uw eigen planning gescheiden te houden.

Een compleet voorbeeld

Een SaaS facturatie-platform (Acme Billing Platform) dat een factuur genereert voor een Duitse klant (Müller Versand GmbH), klaar om als PDF/A te worden gearchiveerd:

{
  "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 op de resulterende 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

Title in het Duits, author als Müller Versand (de GmbH-entiteit van de klant, ontvanger van het document), creator als Acme Billing Platform (het redactionele systeem dat besliste wat op de pagina kwam), producer als het merk van Acme Billing Platform, taal correct getagd voor de Duitse schermlezer en voor de Duitse full-text indexer die dit later in het DMS van Müller zal oppikken. Het PDF/A-3b profiel betekent dat deze set metadata ook in de XMP-stroom wordt geserialiseerd voor langetermijnarchivering.

Niets in de bestandseigenschappen noemt gPdf, Chromium of een tool die de klant niet koos. Wat precies het punt is.

De kleinst mogelijke upgrade

Als u al een POST doet naar /api/v1/pdf/render en uw huidige aanroep heeft geen settings.metadata, is de kleinste verbetering drie regels toegevoegd aan de JSON die u al verstuurt:

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

Twee velden, één nieuwe sleutel. Verifieerbaar met pdfinfo binnen seconden. Zodra deze landen, vult u title, language, subject en creator in wanneer u tijd heeft.

Waar dit landt

§4.14.2 Metadata — de API-referentie voor deze velden.
PDF-white-labelling (begeleidende post) — het waarom en het B2B SaaS-argument.
PDF/A en Factur-X uitgelegd voor engineers — relevant als uw metadataverhaal langetermijnarchivering omvat.

title — wat het document is

language — voor toegankelijkheid, zoekfuncties en naleving

author — wie het document toebehoort

subject — wat voor type document dit is

creator vs producer — het meest verwarde paar

Lege velden, per-token defaults, downstream verrassingen

Verifieer uw metadata

Metadata in PDF/A-archivering

Wat gPdf (nog) niet blootlegt

Een compleet voorbeeld

De kleinst mogelijke upgrade

Waar dit landt

`title` — wat het document is

`language` — voor toegankelijkheid, zoekfuncties en naleving

`author` — wie het document toebehoort

`subject` — wat voor type document dit is

`creator` vs `producer` — het meest verwarde paar