Cosa un PDF sa di sé: i metadati e il pacchetto XMP

SpecSpec: ISO 16684-1:2019ISO 16684-1:2019SpecSpec: ISO 32000-2ISO 32000-2

In sintesi

Si apra un PDF moderno e potrebbe parlare di sé due volte. C’è una piccola, vecchia lista chiave/valore chiamata Document Information dictionary, e può esserci un blocco di XML — il pacchetto XMP — che dice più o meno la stessa cosa in una forma più ricca e strutturata. Questa pagina riguarda quei due sistemi paralleli, perché entrambi sopravvivono, e perché le pipeline di archiviazione e ricerca insistono che concordino.

La risposta breve al titolo: un PDF conosce il suo titolo, autore, oggetto, parole chiave, lo strumento che lo ha creato e quando. Memorizza quella conoscenza in due posti contemporaneamente, e l’ingegneria interessante sta nel tenerli onesti.

Perché è importante

I metadati sono la parte di un documento che un essere umano vede raramente e una macchina legge quasi sempre. L’anteprima dei file del sistema operativo, un digital-asset manager, un catalogo di biblioteca, un indice di ricerca, uno strumento di legal-discovery — molti di essi leggono i metadati prima, o accanto a, il testo del documento, e si fidano di ciò che dicono.

Così, quando i due sistemi non concordano — l’Info dictionary dice un autore e il pacchetto XMP ne dice un altro — qualcosa a valle ne sceglie uno, e non si ha voce in capitolo su quale. Un indice di ricerca può far emergere il titolo sbagliato. Un validatore di archiviazione può respingere il file del tutto. La deriva è invisibile finché una pipeline non ci inciampa, che è il momento peggiore per scoprirla.

In breve

• Un PDF può portare i metadati in due sistemi paralleli: il vecchio Document Information dictionary e il moderno pacchetto XMP di RDF/XML.
• Il pacchetto XMP è avvolto in un’istruzione di elaborazione xpacket — un header begin e un trailer end — così che uno strumento possa trovarlo e, sul posto, persino riscriverlo senza rianalizzare l’intero file.
• Le proprietà vivono in namespace: dc (Dublin Core) per il titolo e l’autore, xmp per le date di creazione e modifica, pdf per il producer, xmpMM per l’identità e la cronologia del documento.
• PDF/A richiede i metadati XMP, e le voci DocInfo che hanno equivalenti XMP devono coincidere con esso — un disaccordo è un fallimento di validazione.
• NextPDF tratta i due come un unico lavoro: scrive entrambi, rilegge l’XMP, e protegge la dimensione del pacchetto, fallendo in modo chiuso anziché emettere un file malformato.

Come NextPDF lo affronta

L’inquadramento onesto è che questo è un problema di sincronizzazione travestito da problema di formattazione. Il Document Information dictionary (SpecSpec: ISO 32000-2, §14.3.3ISO 32000-2 §14.3.3), referenziato dal trailer tramite la voce /Info, è una lista piatta di stringhe: Title, Author, Subject, Keywords, Creator, Producer e un paio di date. È semplice, precede l’XML, e viaggia ancora in quasi ogni file perché così tanti strumenti lo leggono ancora per primo.

Il pacchetto XMP (SpecSpec: ISO 16684-1:2019, §7ISO 16684-1:2019 §7) è la metà moderna. È un documento XML — RDF/XML, per essere esatti — che modella il file come un insieme di proprietà denominate raggruppate in schema, ciascuno schema vincolato a un namespace (SpecSpec: ISO 16684-1:2019, §6ISO 16684-1:2019 §6). Quella struttura è ciò che il dizionario piatto non può fare: un valore può essere una lista ordinata, un’alternativa con tag di lingua («titolo in inglese, titolo in francese»), o un record strutturato. In un PDF, quell’XML vive in un metadata stream allegato al document catalog (SpecSpec: ISO 32000-2, §14.3.2ISO 32000-2 §14.3.2), che è il posto canonico dove guarda un lettore attuale.

Vale la pena analizzare tre dettagli, perché sono dove gli strumenti sbagliano il pacchetto.

L’involucro. Un pacchetto XMP è racchiuso tra parentesi da un’istruzione di elaborazione affinché, nei formati dove il pacchetto è memorizzato come byte direttamente ricercabili, un programma possa localizzare i metadati senza un’analisi completa; nel PDF in particolare, il metadata stream del catalog è il localizzatore canonico. L’header begin porta un byte-order mark che dichiara la codifica del testo; il trailer end porta un flag che dichiara se il pacchetto è in sola lettura o può essere modificato sul posto. Quando è scrivibile, il serializzatore lascia una sequenza di spazi di padding dopo l’XML così che un editor possa far crescere leggermente il contenuto senza spostare ogni byte che segue. Quel padding non è decorazione — è ciò che rende possibile la modifica dei metadati sul posto.

I namespace. Una proprietà è significativa solo rispetto al suo namespace, e una manciata sono quasi universali. Dublin Core (dc) contiene il titolo e l’autore. Lo schema base XMP (xmp) contiene le date di creazione e modifica e lo strumento di authoring. Lo schema PDF (pdf) contiene la stringa del producer e le parole chiave. Lo schema di media-management (xmpMM) contiene l’identità del documento e la sua cronologia di derivazione — la traccia che dice «questo file è venuto da quello». Concordare su questi URI di namespace e nomi di proprietà — di solito mostrati con prefissi convenzionali — è l’intero scopo degli schema fondamentali (SpecSpec: ISO 16684-1:2019, Annex BISO 16684-1:2019 Annex B); due strumenti che parlano entrambi la proprietà titolo di Dublin Core interoperano senza accordo preliminare.

La regola di coerenza. Poiché entrambi i sistemi possono nominare la stessa proprietà, possono non concordare. I profili di archiviazione rifiutano di permetterlo. Un file PDF/A deve portare un metadata stream XMP, e qualsiasi voce del Document Information che abbia un equivalente XMP deve coincidere con esso; un disaccordo è un fallimento di validazione. La conclusione pratica è diretta: in una pipeline di archiviazione, i due non sono campi indipendenti ma un fatto solo scritto due volte, e devono restare al passo.

NextPDF gestisce tutti e tre come un’unica preoccupazione. Il flusso dei metadati è un solo percorso, non due in concorrenza.

1. Collect the values onceTitle, author, subject, keywords, creator, producer and dates are set on the document a single time, so there is one source of truth, not two.
2. Write the Info dictionaryThe DocInfo writer emits the legacy Title, Author, Subject, Keywords, Creator, Producer and date entries that older tools read first.
3. Build the XMP packetThe XMP builder serializes the same values as RDF/XML under dc, xmp, pdf and xmpMM, wrapped in the xpacket header and trailer with writable padding.
4. Guard the packet sizeBefore serialization is accepted, the engine checks the packet against a size bound and fails closed with a typed exception rather than emit a malformed or oversized stream.
5. Read XMP back to verifyThe XMP reader parses the packet so a pipeline can confirm the engine wrote the metadata it was given — the kind of check an archival validator builds on.

How NextPDF keeps a document's two metadata systems consistent: one set of values is written to both the Info dictionary and the XMP packet, the packet is size-guarded before it is serialized, and the same packet can be read back so a pipeline can confirm the metadata serialized as intended.

Esempio pratico

La forma qui sotto imposta i metadati una volta e lascia che il motore li diffonda a entrambi i sistemi, poi rilegge il titolo XMP così che una pipeline possa ispezionarlo. La protezione della dimensione è la riga che trasforma «probabilmente va bene» in «dimostrabilmente rifiutato se no».

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Metadata\Exception\XmpPacketTooLargeException;

$document = Document::createStandalone();

// Set the values ONCE. The engine writes them to both the Info dictionary
// and the XMP packet, so the two systems cannot drift apart at the source.
$document->setTitle('Annual Report 2026');
$document->setAuthor('Records Office');
$document->setSubject('Statutory annual filing');
$document->setKeywords('annual report, statutory, 2026');

try {
    // Building the document serializes the XMP packet. The engine guards the
    // packet size and fails closed: a packet that exceeds the bound is a
    // typed exception, never a silently truncated or malformed stream.
    $bytes = $document->getPdfData();
} catch (XmpPacketTooLargeException $e) {
    // Decide deliberately: trim the metadata, not the guarantees.
    error_log('XMP packet exceeded the size bound: ' . $e->getMessage());
    throw $e;
}

// Read the packet back. This confirms the XMP the engine serialized carries the
// value you set — the kind of integrity check an archival pipeline runs before
// it trusts the file. (Both systems are written from one source, so they agree
// by construction; reading the XMP back proves it serialized as intended.)
$xmp = $document->readXmpMetadata($bytes);
$xmpTitle = $xmp->get('dc', 'title'); // 'Annual Report 2026'

if ($xmpTitle !== $document->getTitle()) {
    throw new \RuntimeException('XMP title does not match the value that was set.');
}

Qui non c’è alcun percorso in cui i due sistemi divergano in silenzio: i valori entrano una volta, entrambi gli scrittori consumano la stessa sorgente, e il lettore lascia che una pipeline controlli il risultato.

Equivoco comune

Si crede spesso che l’Info dictionary sia obsoleto e lo si possa ignorare. Non si può — non ancora. Una grande quantità di software installato, incluse alcune anteprime file del sistema operativo e strumenti di archiviazione più datati, legge ancora l’Info dictionary per primo o soltanto. Eliminarlo non modernizza un file; fa apparire il file senza titolo a tutto ciò che non ha adottato l’XMP.

L’errore speculare è trattare i due come campi indipendenti che si compilano separatamente. È esattamente così che derivano. Sono due serializzazioni di un unico fatto. Li si scriva da un’unica sorgente, o si accetti che qualcosa a valle sceglierà la versione che non si intendeva.

Limiti e confini

• NextPDF scrive entrambi i sistemi e rilegge l’XMP. Il suo ambito è il builder dei metadati XMP, lo scrittore DocInfo e un lettore XMP. Non promette di essere un motore di query RDF/XML general-purpose.
• Il pacchetto XMP è protetto in dimensione e fallisce in modo chiuso. Un pacchetto che supera il limite del motore solleva un’eccezione tipizzata. Il motore non emetterà un pacchetto troncato, riempito oltre il limite o altrimenti malformato per far «entrare» una richiesta sovradimensionata.
• La coerenza è imposta al momento della scrittura da un’unica sorgente; non è una riconciliazione magica di un file che non si è prodotto. Se si importa un documento i cui due sistemi già non concordano, risolverlo è una decisione dell’utente, non una riscrittura implicita.
• I requisiti di metadati di PDF/A fanno parte del profilo di archiviazione. Questa pagina spiega la regola; il verdetto di conformità appartiene a un validatore, come sempre per il lavoro di archiviazione. Si veda la pagina sull’archiviazione per quel confine.

Il builder dei metadati, lo scrittore DocInfo e il lettore XMP sono capacità Core. Il qualificatore onesto sta con la protezione della dimensione, qui sotto.

Human-factors note:Human-factors note

La protezione della dimensione è una decisione di operabilità, non una limitazione di cui scusarsi. Un pacchetto XMP risiede in un metadata stream, e un pacchetto che cresce senza limiti è una superficie di denial-of-service e un rischio di corruzione per qualsiasi editor sul posto che si affidava al padding scrivibile. Così il motore imposta un limite e, quando una richiesta lo supererebbe, solleva un’eccezione tipizzata (SpecSpec: ISO 16684-1:2019, §7ISO 16684-1:2019 §7) invece di scrivere uno stream malformato. Il fallimento è rumoroso, denominato e al momento della scrittura — dove si può ridurre deliberatamente i metadati — anziché silenzioso e scoperto più tardi da un validatore che semplicemente respinge il file.

Metadata: Info dictionary and XMP packet — edition availability

Edition	Availability
Core	○ Il builder dei metadati XMP, lo scrittore del Document Information dictionary e il lettore XMP sono inclusi in Core, con la protezione della dimensione che fallisce in modo chiuso su un pacchetto sovradimensionato — incluso l’output di conformità PDF/A e la validazione che rendono obbligatorio il metadata stream XMP e richiedono che DocInfo coincida con esso.
Pro	○ Aggiunge flussi di lavoro di metadati in batch e su template sopra lo stesso scrittore e lettore Core.
Enterprise	○ Aggiunge la più ampia policy di conformità e la superficie di reporting su un parco documentale.

Documenti correlati

• Archiviazione e PDF/A — dove il pacchetto XMP smette di essere opzionale e la regola di coerenza DocInfo-verso-XMP diventa un requisito superato-o-fallito.
• Conformità da consegnare a un revisore — perché i metadati che fanno round-trip e concordano con sé stessi sono parte di un artefatto verificabile.
• L’anatomia di un file PDF — dove si trovano il trailer, il catalog e il metadata stream nella struttura del file.
• Stream e filtri — il metadata stream è uno stream; ecco come gli stream PDF sono codificati e mantenuti deterministici.

Glossario

• Document Information dictionary — i metadati vecchi e piatti chiave/valore referenziati dal trailer tramite la voce /Info: Title, Author, Subject, Keywords, Creator, Producer e date. Precede l’XMP; ancora ampiamente letto.
• XMP — l’Extensible Metadata Platform, un formato XML (RDF/XML) per descrivere una risorsa con proprietà denominate raggruppate in schema. Standardizzato come ISO 16684-1.
• xpacket — l’istruzione di elaborazione che avvolge un pacchetto XMP, con un header begin (marcatore di codifica) e un trailer end (flag di sola lettura o scrivibile), così che uno strumento possa localizzare e modificare il pacchetto senza un’analisi completa.
• Namespace / schema — un vocabolario denominato di proprietà vincolato a un URI. Prefissi comuni: dc (Dublin Core), xmp (XMP base), pdf (specifico PDF), xmpMM (media management / identità del documento).
• Metadata stream — l’oggetto PDF, allegato al document catalog, che porta il pacchetto XMP. La posizione canonica che un lettore moderno controlla per primo.
• PDF/A — la famiglia di profili PDF di archiviazione (ISO 19005). Richiede un metadata stream XMP ed esige che qualsiasi voce del Document Information con un equivalente XMP coincida con esso, altrimenti la validazione fallisce.