gPdf
Blog

Campi dei metadati PDF, spiegati: title, language, author, subject, creator, producer

Percorso campo per campo dei sei metadati PDF standard esposti da gPdf — title, language, author, subject, creator, producer. A cosa serve ciascuno, chi li legge, errori comuni e come verificare quanto consegnato.

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

L’articolo collegato, Le proprietà del PDF devono mostrare il vostro brand, non lo strumento di qualcun altro, spiegava perché vale la pena occuparsi dei metadati PDF. Questo è il manuale operativo: a cosa serve ciascun campo nella specifica PDF, chi lo legge, gli errori comuni e come verificare che il vostro output abbia davvero consegnato quanto previsto.

gPdf espone i sei campi standard che la specifica PDF definisce per i metadati a livello documento. Stanno sotto settings.metadata nel JSON DocumentRequest. Ogni campo è opzionale — se non ne impostate uno, gPdf ricade sul default_metadata del token (funzionalità di policy Enterprise) o su un valore di default di sistema.

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

Il resto di questo post è una sezione per campo. Ogni sezione segue la stessa forma: cos’è il campo, dove emerge, errori comuni, regola pratica. L’ordine è cosa riempire prima → poi → … → per ultimo.

title — cos’è il documento

La specifica PDF lo descrive come il “titolo del documento”.

Dove emerge:

  • La barra del titolo nei visualizzatori PDF (Adobe Reader, Preview, Foxit, il visualizzatore PDF di Chromium lo mostrano tutti).
  • La scheda del browser quando il PDF si apre inline (Content-Disposition: inline).
  • Indici di ricerca — Spotlight, Outlook, SharePoint, l’indicizzatore full-text di Google Drive leggono tutti title e gli danno molto peso.

Errori comuni:

  • ❌ Impostare title come nome file. invoice-20260318.pdf è il nome file. Il title dovrebbe essere qualcosa che un umano legge, come Invoice INV-2026-3401. Nome file e title sono questioni diverse; il nome file è per i filesystem, il title è per i visualizzatori e la ricerca.
  • ❌ Lasciare title vuoto. I visualizzatori ricadono sul nome file. Il risultato si legge come autogenerato ed emesso da macchina.
  • ❌ Aggiungere il brand nel title. Acme Logistics — Invoice INV-2026-3401 ingombra la barra del titolo. Il brand va in author, non in title.

Regola pratica: il title dovrebbe corrispondere all’H1 della pagina renderizzata. Se la riga in cima del vostro template di fattura è “Invoice INV-2026-3401”, quello è il title.

language — per accessibilità, ricerca e conformità

language è un tag di lingua BCP-47: en, de, zh-Hans, pt-BR, ar-SA. Impostatelo per ogni documento. Tra i sei campi, è quello con le conseguenze downstream più concrete e il minor costo di implementazione — è il motivo per cui è in posizione 2 e non sepolto più in basso.

Dove emerge:

  • Screen reader — JAWS, NVDA, VoiceOver lo usano per scegliere l’insieme corretto di fonemi. Uno screen reader inglese che legge un PDF con language: "de" pronuncerà correttamente le parole tedesche; senza il tag, la prosodia esce sbagliata.
  • Motori di ricerca e indicizzatori — incide su quali regole di stemming e elenco di stopword della locale si applicano. Una fattura con language: "zh-Hans" viene indicizzata con la segmentazione cinese; senza tag, spesso ricade sull’inglese di default e l’indice diventa inutilizzabile.
  • Conformità PDF/A — PDF/A-2a e PDF/A-3a (profili di accessibilità) richiedono il tag di lingua. Senza, la validazione veraPDF fallisce.

Errori comuni:

  • ❌ Lasciarlo non impostato. Il default deve essere “la locale del destinatario”, non “il default della piattaforma”. La maggior parte degli stack che perdono semplicemente non scrive il campo; il risultato sono screen reader che pronunciano male e indici di ricerca che fanno stemming sbagliato.
  • ❌ Usare una stringa non BCP-47 come "english" o "EN-US". La specifica PDF si aspetta tag RFC 5646: en, en-US, de, pt-BR.
  • ❌ Cablare il default della piattaforma (per esempio, sempre "en") senza tenere conto della lingua reale del contenuto. Una fattura in portoghese etichettata "en" è peggio di un documento senza tag — inganna attivamente l’indicizzatore.

Regola pratica: il tag deve corrispondere alla lingua reale del contenuto. Per un cliente in Brasile che riceve una fattura in portoghese, impostate "language": "pt-BR", non "en". Per documenti multilingue, scegliete la lingua dominante e usate l’attributo Lang su singoli elementi di contenuto per il resto — è una funzionalità di accessibilità del PDF taggato, oltre al campo language a livello documento.

author — di chi è il documento

Nella specifica PDF, author è “il nome della persona o organizzazione che ha creato il documento”. Per PDF di business che vengono consegnati a destinatari, la risposta è quasi sempre l’organizzazione — ma la forma giusta varia genuinamente per contesto.

Dove emerge:

  • Finestra delle proprietà in ogni visualizzatore PDF, etichettato in evidenza come “Author”.
  • Indicizzatori DMS / archivio, spesso usato come filtro.
  • Stream di metadati XMP del PDF/A, dove viene portato negli archivi a lungo termine.

Errori comuni:

  • ❌ "author": "[email protected]" — fa sfuggire accidentalmente l’email dell’operatore in ogni PDF, finisce in ogni indice di ricerca, diventa un problema di PII a lungo termine.
  • ❌ "author": "PDF Generator Service" — nome di strumento interno; non significa nulla per il destinatario.
  • ❌ Vuoto — Preview e la maggior parte dei visualizzatori mostrano letteralmente “(no author)” nella finestra delle proprietà, che si legge come “nessuno possiede questo”.

Forme che funzionano:

  • ✅ "author": "Acme Logistics, Inc." — organizzazione diretta.
  • ✅ "author": "Acme Logistics — Billing" — organizzazione + dipartimento, per documenti che vengono instradati a un ufficio specifico.
  • ✅ "author": "Bridge Capital Partners — Fund III" — utile in finanza/legale dove l’attribuzione è a un’entità specifica.
  • ✅ "author": "Maria López, RICS Surveyor" — per pubblicazione mono-autore (report, perizie, pareri legali) dove l’individuo È l’attribuzione editoriale.

Regola pratica: author è l’entità a cui il destinatario dovrebbe associare il documento. In un SaaS multi-tenant in cui la piattaforma genera PDF per conto di clienti, author dovrebbe essere il nome dell’organizzazione del cliente, non il nome della piattaforma. (Il nome della piattaforma sta in creator — vedi sotto.) Per contesti di consulenza / pubblicazione / legali in cui gli individui sono il brand, gli individui vanno bene.

subject — che tipo di documento è

subject è la breve-descrizione-del-documento. I visualizzatori non lo fanno emergere in evidenza — la maggior parte degli utenti non lo vedrà mai a meno che non apra la finestra delle proprietà. Ma i sistemi di gestione documentale, i sistemi di archiviazione e l’instradamento di email/file basato su regole lo usano.

Dove emerge:

  • Finestra delle proprietà, posizione secondaria.
  • Regole di instradamento DMS, logica di raggruppamento in archivio.
  • Stream di metadati XMP (PDF/A).

Errori comuni:

  • ❌ "subject": "Invoice for Acme on 2026-03-18 for $4,532.10" — è una descrizione di istanza di documento, non di tipo. Va in title.
  • ❌ Vuoto — vi costa un gancio gratuito di instradamento per i sistemi downstream.
  • ❌ Mescolare le classi in modo incoerente ("Invoice" vs "Invoice/2026-03" vs "Monthly invoice") — i filtri DMS non possono raggruppare su un bersaglio mobile.

Forme che funzionano:

  • ✅ "subject": "Invoice"
  • ✅ "subject": "Monthly account statement"
  • ✅ "subject": "Etichetta di spedizione — 4×6 termica"
  • ✅ "subject": "Q3 2026 board pack"

Regola pratica: la granularità giusta è la classe di documento, non l’istanza di documento. Un DMS con migliaia di PDF in ingresso può instradare per subject se gli date un vocabolario coerente. Scegliete un insieme finito di classi per la vostra piattaforma e non deviate mai — ogni fattura che la vostra piattaforma genera deve avere esattamente "subject": "Invoice".

creator vs producer — la coppia più confusa

È qui che la maggior parte dei team smette di leggere la specifica PDF e tira a indovinare. La specifica è precisa; i due campi significano cose diverse.

  • creator — l’applicazione che ha prodotto il contenuto sorgente (il sistema upstream che ha deciso cosa dovesse dire il documento).
  • producer — l’applicazione che ha prodotto i byte del PDF (il motore di rendering che ha trasformato quel contenuto in un file PDF).

Per una piattaforma SaaS di fatturazione che genera fatture tramite un’API JSON-to-PDF come gPdf:

  • creator = la piattaforma SaaS di fatturazione con la sua versione. Quella è l’applicazione che ha deciso che questa dovesse essere una fattura per Acme di 4.532,10 $.
  • producer = il motore di rendering. Di default è “gPdf”. Ma poiché il livello di rendering è infrastruttura che il SaaS ha scelto, il SaaS può legittimamente impostare producer al nome della propria piattaforma — la propria piattaforma ha, in un senso reale, prodotto i byte del PDF delegando a gPdf come infrastruttura.
{
  "creator":  "Acme Billing Platform v7.2",
  "producer": "Acme Billing Platform"
}

Dove emergono:

  • Finestra delle proprietà, entrambi etichettati.
  • Output di pdfinfo, fianco a fianco.
  • Stream XMP del PDF/A (entrambi i campi devono essere non vuoti in PDF/A).

Errori comuni:

  • ❌ creator impostato a una stringa user-agent di Chromium / Mozilla. Succede quando uno stack PDF basato su browser headless passa lo User-Agent in creator automaticamente. È la versione del browser, non il sistema fonte-di-verità. Sovrascrivetelo.
  • ❌ producer lasciato come nome del motore di rendering di default. La maggior parte dei team non lo sovrascrive mai, quindi ogni PDF dice “Skia/PDF m120” o “wkhtmltopdf” — vedi il post sul marchio bianco per capire perché conta in B2B.
  • ❌ Mettere lo stesso valore in entrambi. Accettabile ma spreco — i due campi esistono proprio perché un visualizzatore possa distinguere “app sorgente” da “motore di render”. Usateli.

Regola pratica: creator è il nome della vostra applicazione con versione (per esempio, "Acme Billing Platform v7.2"); producer è il brand o nome di piattaforma della vostra applicazione senza versione (per esempio, "Acme Billing Platform"). Entrambi dovrebbero essere valori che il destinatario riconoscerebbe.

Campi vuoti, default per token, sorprese downstream

Tre dettagli implementativi che vale la pena conoscere prima di pubblicare:

  1. Stringhe vuote o composte solo da spazi vengono trattate come non fornite. Inviare "title": "" equivale a omettere title — non scrive una stringa vuota nel PDF, percorre la catena di fallback (default del token → default di sistema). È la causa della segnalazione di bug “l’ho impostato, non ha attecchito” più comune.
  2. Le policy di token possono rimuovere o impostare valori di default per i campi dei metadati. Un SaaS multi-tenant che usa gPdf può impostare un default_metadata su ciascun token API, in modo che ogni PDF generato da quel token porti l’author e il producer del cliente senza fidarsi che ogni sviluppatore li imposti a ogni richiesta. Il default a livello token è il livello di enforcement giusto per “ogni PDF di Acme deve dire Acme”.
  3. Le pipeline downstream possono riscrivere i vostri metadati. Strumenti che post-elaborano i PDF dopo che gPdf li restituisce — Ghostscript senza flag espliciti di preservazione dei metadati, alcuni strumenti aziendali di DRM, alcuni “ottimizzatori PDF” — possono sovrascrivere Producer con il proprio nome e annullare il brand che avete appena impostato. Verificate contro la vostra pipeline di produzione reale, non solo contro la risposta grezza di gPdf.

Verificate i vostri metadati

Dopo aver implementato i cambiamenti di cui sopra, tre modi rapidi per controllare che il PDF abbia davvero consegnato quanto previsto:

Riga di comando (macOS / Linux, richiede 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: File → Proprietà → scheda Descrizione. Compaiono tutti e sei i campi, con Title mostrato nella barra del titolo del visualizzatore in alto.

Anteprima macOS: ⌘+I (Ottieni informazioni). Il pannello ispettore “PDF” mostra gli stessi campi.

Se un campo appare vuoto, in bianco o con un nome di strumento che non avete impostato, ripercorrete il corpo della richiesta — la causa più comune è inviare "" (stringa vuota), che l’API tratta come “non fornito” e percorre la catena di fallback fino a un valore di default. La seconda causa più comune è una pipeline downstream (Ghostscript, DRM, ottimizzatore) che sovrascrive il campo dopo che gPdf ha restituito; testate contro la produzione, non solo contro la risposta grezza di render.

Metadati nell’archiviazione PDF/A

Se renderizzate per archiviazione a lungo termine con settings.profile: "pdfa-2b" (o -2a, -3a, -3b), i metadati cessano di essere opzionali e diventano portanti:

  • Il campo producer non può essere vuoto in un file conforme PDF/A — al minimo viene consegnato il default di sistema.
  • language è richiesto per i profili di accessibilità (PDF/A-2a, PDF/A-3a). Senza, la validazione veraPDF fallisce senza appello.
  • Lo stream di metadati XMP richiesto da PDF/A viene generato automaticamente dai sei campi di cui sopra; non dovete costruirlo voi.
  • title, author, subject, creator, producer e language finiscono tutti nello stream XMP, in modo che l’indicizzatore di metadati di un archivio downstream (Preservica, Archivematica) possa costruire il proprio catalogo a partire da essi senza ri-parsare il corpo del documento.

Per un documento d’archivio, i metadati brandizzati non sono solo cura del brand — fanno parte della durabilità dell’artefatto. L’ufficio doganale tedesco, l’agenzia fiscale brasiliana, o qualunque archivio a lungo termine che apra il vostro PDF tra dieci anni vedrà ciò che era in quei campi il giorno in cui lo avete renderizzato. Impostarli deliberatamente al momento del render è l’unica occasione che avete.

Cosa gPdf non espone (ancora)

Per restare onesti sulla superficie odierna: la specifica PDF definisce anche Keywords (termini di ricerca in forma libera) e uno stream di metadati XMP che supporta coppie chiave-valore custom arbitrarie. gPdf non espone nessuno dei due nell’API attuale.

Se avete bisogno di nascondere dati di business arbitrari dentro il PDF (UUID ordine, codice magazzino, versione template), gli aggiri di oggi sono:

  • Impostare subject su una stringa breve strutturata che i sistemi downstream parsano.
  • Tenere i dati di business nel vostro database, indicizzati per nome file o hash del contenuto.
  • Attendere — i campi custom XMP sono nella roadmap, e quando arriveranno saranno la risposta giusta per il contesto di processo nascosto e leggibile da macchina.

Confondere “metadati brandizzati” (i sei campi standard, disponibili ora) con “metadati di business custom” (campi custom XMP, futuri) è il modo più facile per sovra-promettere ciò che è possibile oggi. Vale la pena tenerli separati nella vostra pianificazione.

Un esempio completo

Una piattaforma SaaS di fatturazione (Acme Billing Platform) che genera una fattura per un cliente tedesco (Müller Versand GmbH), pronta a essere archiviata come 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 sul PDF risultante:

$ 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 tedesco, author come Müller Versand (l’entità GmbH del cliente, destinatario del documento), creator come Acme Billing Platform (il sistema editoriale che ha deciso cosa mettere nella pagina), producer come brand di Acme Billing Platform, lingua etichettata correttamente per lo screen reader tedesco e per l’indicizzatore full-text tedesco che più tardi riprenderà tutto questo nel DMS di Müller. Il profilo PDF/A-3b implica che anche questo set di metadati venga serializzato nello stream XMP per l’archiviazione a lungo termine.

Nulla nelle proprietà del file nomina gPdf, Chromium o qualunque strumento che il cliente non abbia scelto. Che è esattamente il punto.

Il più piccolo upgrade possibile

Se già fate POST a /api/v1/pdf/render e la vostra chiamata attuale non ha settings.metadata, il miglioramento più piccolo sono tre righe aggiunte al JSON che già inviate:

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

Due campi, una nuova chiave. Verificabile con pdfinfo in pochi secondi. Una volta che questi atterrano, riempite title, language, subject e creator quando avete tempo.

Dove questo atterra