Co PDF wie o samym sobie: metadane i pakiet XMP

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

W skrócie

Otwórz nowoczesny PDF, a może opowiedzieć ci o sobie dwukrotnie. Jest mała, stara lista klucz/wartość zwana słownikiem informacji o dokumencie, a może być też blok XML — pakiet XMP — który mówi w dużej mierze to samo w bogatszej, ustrukturyzowanej postaci. Ta strona dotyczy tych dwóch równoległych systemów, tego, dlaczego oba przetrwały, oraz dlaczego potoki archiwalne i wyszukiwania nalegają, by się zgadzały.

Krótka odpowiedź na tytuł: PDF zna swój tytuł, autora, temat, słowa kluczowe, narzędzie, które go stworzyło, oraz kiedy. Przechowuje tę wiedzę w dwóch miejscach naraz, a ciekawa inżynieria tkwi w utrzymaniu ich w uczciwości.

Dlaczego to ma znaczenie

Metadane to ta część dokumentu, którą człowiek rzadko widzi, a maszyna prawie zawsze czyta. Podgląd plików twojego systemu operacyjnego, menedżer zasobów cyfrowych, katalog biblioteczny, indeks wyszukiwania, narzędzie do ujawniania dowodów prawnych — wiele z nich czyta metadane przed tekstem dokumentu lub obok niego i ufa temu, co mówią.

Więc gdy oba systemy się nie zgadzają — słownik Info mówi o jednym autorze, a pakiet XMP o innym — coś dalej w potoku wybiera jeden, a ty nie masz wpływu na to, który. Indeks wyszukiwania może wyświetlić niewłaściwy tytuł. Walidator archiwalny może odrzucić plik wprost. Rozjazd jest niewidoczny, dopóki jakiś potok się o niego nie potknie, co jest najgorszym momentem, by go odkryć.

Wersja skrócona

• PDF może nieść metadane w dwóch równoległych systemach: przestarzałym słowniku informacji o dokumencie oraz nowoczesnym pakiecie XMP w RDF/XML.
• Pakiet XMP jest opakowany w instrukcję przetwarzania xpacket — nagłówek begin i trailer end — dzięki czemu narzędzie może go odnaleźć i, w miejscu, nawet przepisać bez ponownego parsowania całego pliku.
• Właściwości żyją w przestrzeniach nazw: dc (Dublin Core) dla tytułu i twórcy, xmp dla dat utworzenia i modyfikacji, pdf dla producenta, xmpMM dla tożsamości i historii dokumentu.
• PDF/A wymaga metadanych XMP, a wpisy DocInfo, które mają odpowiedniki w XMP, muszą się z nim zgadzać — niezgodność to niepowodzenie walidacji.
• NextPDF traktuje oba jako jedno zadanie: zapisuje oba, odczytuje XMP z powrotem i pilnuje rozmiaru pakietu, zawodząc bezpiecznie, zamiast wytworzyć zniekształcony plik.

Jak podchodzi do tego NextPDF

Uczciwe ujęcie jest takie, że to problem synchronizacji przebrany za problem formatowania. Słownik informacji o dokumencie (SpecSpec: ISO 32000-2, §14.3.3ISO 32000-2 §14.3.3), wskazywany z trailera przez wpis /Info, to płaska lista łańcuchów: Title, Author, Subject, Keywords, Creator, Producer oraz para dat. Jest prosty, jest starszy od XML i nadal jedzie razem niemal w każdym pliku, ponieważ tak wiele narzędzi wciąż czyta go jako pierwszy.

Pakiet XMP (SpecSpec: ISO 16684-1:2019, §7ISO 16684-1:2019 §7) to nowoczesna połowa. To dokument XML — a dokładniej RDF/XML — który modeluje plik jako zbiór nazwanych właściwości zgrupowanych w schematy, z których każdy jest związany z przestrzenią nazw (SpecSpec: ISO 16684-1:2019, §6ISO 16684-1:2019 §6). Ta struktura to coś, czego płaski słownik nie potrafi: wartość może być uporządkowaną listą, alternatywą oznaczoną językiem („tytuł po angielsku, tytuł po francusku”) lub ustrukturyzowanym rekordem. W PDF ten XML żyje w strumieniu metadanych dołączonym do katalogu dokumentu (SpecSpec: ISO 32000-2, §14.3.2ISO 32000-2 §14.3.2), co jest kanonicznym miejscem, w które zagląda współczesny czytnik.

Trzy szczegóły warto rozłożyć na czynniki, ponieważ to tam narzędzia mylą się co do pakietu.

Opakowanie. Pakiet XMP jest objęty instrukcją przetwarzania, dzięki czemu w formatach, w których pakiet jest przechowywany jako bezpośrednio przeszukiwalne bajty, program może zlokalizować metadane bez pełnego parsowania; konkretnie w PDF kanonicznym lokalizatorem jest strumień metadanych katalogu. Nagłówek begin niesie znacznik kolejności bajtów, który deklaruje kodowanie tekstu; trailer end niesie flagę stwierdzającą, czy pakiet jest tylko do odczytu, czy może być edytowany w miejscu. Gdy jest zapisywalny, serializator pozostawia za XML serię dopełnienia białymi znakami, aby edytor mógł nieco powiększyć zawartość bez przesuwania każdego następującego dalej bajta. To dopełnienie nie jest ozdobą — to ono umożliwia edycję metadanych w miejscu.

Przestrzenie nazw. Właściwość ma znaczenie tylko względem swojej przestrzeni nazw, a garstka jest niemal uniwersalna. Dublin Core (dc) trzyma tytuł i twórcę. Podstawowy schemat XMP (xmp) trzyma daty utworzenia i modyfikacji oraz narzędzie tworzące. Schemat PDF (pdf) trzyma łańcuch producenta oraz słowa kluczowe. Schemat zarządzania mediami (xmpMM) trzyma tożsamość dokumentu i jego historię wyprowadzenia — ślad mówiący „ten plik powstał z tamtego”. Uzgodnienie tych URI przestrzeni nazw i nazw właściwości — zwykle pokazywanych z umownymi prefiksami — to cały sens schematów rdzeniowych (SpecSpec: ISO 16684-1:2019, Annex BISO 16684-1:2019 Annex B); dwa narzędzia, które oba mówią właściwością tytułu Dublin Core, współdziałają bez wcześniejszej umowy.

Reguła spójności. Ponieważ oba systemy mogą nazwać tę samą właściwość, mogą się nie zgadzać. Profile archiwalne odmawiają na to zgody. Plik PDF/A musi nieść strumień metadanych XMP, a każdy wpis informacji o dokumencie, który ma odpowiednik w XMP, musi się z nim zgadzać; niezgodność to niepowodzenie walidacji. Praktyczny wniosek jest bezpośredni: w potoku archiwalnym oba nie są niezależnymi polami, lecz jednym faktem zapisanym dwukrotnie, i muszą pozostawać w zgodzie.

NextPDF obsługuje wszystkie trzy jako jedną troskę. Przepływ metadanych to jedna ścieżka, a nie dwie konkurujące.

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.

Jak NextPDF utrzymuje spójność dwóch systemów metadanych dokumentu: jeden zestaw wartości jest zapisywany zarówno do słownika Info, jak i do pakietu XMP, pakiet jest pilnowany pod kątem rozmiaru przed serializacją, a ten sam pakiet można odczytać z powrotem, aby potok mógł potwierdzić, że metadane zostały zserializowane zgodnie z zamiarem.

Praktyczny przykład

Poniższy kształt ustawia metadane raz i pozwala silnikowi rozprowadzić je do obu systemów, a następnie odczytuje tytuł XMP z powrotem, aby potok mógł go zbadać. Strażnik rozmiaru to wiersz, który zamienia „prawdopodobnie w porządku” w „dowodnie odrzucone, jeśli nie”.

<?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.');
}

Nie ma tu ścieżki, na której oba systemy po cichu się rozjeżdżają: wartości wchodzą raz, oba zapisujące korzystają z tego samego źródła, a czytnik pozwala potokowi sprawdzić wynik.

Częste nieporozumienie

Częstym przekonaniem jest, że słownik Info jest przestarzały i można go zignorować. Nie można — jeszcze nie. Mnóstwo zainstalowanego oprogramowania, w tym niektóre podglądy plików systemu operacyjnego oraz starsze narzędzia archiwalne, wciąż czyta słownik Info jako pierwszy lub jedyny. Porzucenie go nie unowocześnia pliku; sprawia, że plik wygląda jak bez tytułu dla wszystkiego, co nie przyjęło XMP.

Lustrzanym odbiciem tego błędu jest traktowanie obu jako niezależnych pól, które wypełniasz osobno. To dokładnie tak się rozjeżdżają. To dwie serializacje jednego faktu. Zapisz je z jednego źródła albo pogódź się z tym, że coś dalej w potoku wybierze wersję, której nie miałeś na myśli.

Ograniczenia i granice

• NextPDF zapisuje oba systemy i odczytuje XMP z powrotem. Jego zakres to konstruktor metadanych XMP, zapisujący DocInfo oraz czytnik XMP. Nie obiecuje być ogólnego przeznaczenia silnikiem zapytań RDF/XML.
• Pakiet XMP jest pilnowany pod kątem rozmiaru i zawodzi bezpiecznie. Pakiet, który przekracza granicę silnika, zgłasza typowany wyjątek. Silnik nie wytworzy obciętego, dopełnionego ponad granicę ani w inny sposób zniekształconego pakietu, by „zmieścić” nadwymiarowe żądanie.
• Spójność jest wymuszana przy zapisie z jednego źródła; to nie magiczne uzgadnianie pliku, którego nie wytworzyłeś. Jeśli zaimportujesz dokument, którego oba systemy już się nie zgadzają, rozstrzygnięcie tego jest twoją decyzją, a nie domyślnym przepisaniem.
• Wymagania metadanych PDF/A są częścią profilu archiwalnego. Ta strona wyjaśnia regułę; werdykt zgodności należy do walidatora, jak zawsze w pracy archiwalnej. Zobacz stronę o archiwizacji, by poznać tę granicę.

Konstruktor metadanych, zapisujący DocInfo oraz czytnik XMP to możliwości edycji podstawowej (Core). Uczciwe zastrzeżenie tkwi przy strażniku rozmiaru, poniżej.

Human-factors note:Human-factors note

Strażnik rozmiaru to decyzja operacyjna, a nie ograniczenie, za które trzeba przepraszać. Pakiet XMP siedzi w strumieniu metadanych, a pakiet, który rośnie bez granicy, to powierzchnia ataku typu odmowa usługi oraz ryzyko uszkodzenia dla każdego edytora w miejscu, który polegał na zapisywalnym dopełnieniu. Więc silnik ustawia granicę i, gdy żądanie miałoby ją przekroczyć, zgłasza typowany wyjątek (SpecSpec: ISO 16684-1:2019, §7ISO 16684-1:2019 §7) zamiast zapisywać zniekształcony strumień. Niepowodzenie jest głośne, nazwane i przy zapisie — tam, gdzie możesz świadomie przyciąć metadane — a nie ciche i odkrywane później przez walidator, który po prostu odrzuca plik.

Metadata: Info dictionary and XMP packet — edition availability

Edition	Availability
Core	○ The XMP metadata builder, the Document Information dictionary writer, and the XMP reader ship in Core, with the size guard that fails closed on an oversized packet — including the PDF/A conformance output and validation that make the XMP metadata stream mandatory and require DocInfo to match it.
Pro	○ Adds batch and templated metadata workflows over the same Core writer and reader.
Enterprise	○ Adds the broader conformance policy and reporting surface across a document estate.

Powiązane dokumenty

• Archiwizacja i PDF/A — gdzie pakiet XMP przestaje być opcjonalny, a reguła spójności DocInfo-do-XMP staje się wymaganiem typu zaliczone-lub-nie.
• Zgodność, którą możesz wręczyć audytorowi — dlaczego metadane, które przechodzą podróż w obie strony i zgadzają się ze sobą, są częścią artefaktu nadającego się do audytu.
• Anatomia pliku PDF — gdzie w strukturze pliku znajdują się trailer, katalog oraz strumień metadanych.
• Strumienie i filtry — strumień metadanych jest strumieniem; oto jak strumienie PDF są kodowane i utrzymywane deterministycznie.

Słownik pojęć

• Słownik informacji o dokumencie — przestarzałe, płaskie metadane klucz/wartość wskazywane z trailera przez wpis /Info: Title, Author, Subject, Keywords, Creator, Producer oraz daty. Starszy od XMP; nadal szeroko czytany.
• XMP — Extensible Metadata Platform, format XML (RDF/XML) do opisu zasobu nazwanymi właściwościami zgrupowanymi w schematy. Ustandaryzowany jako ISO 16684-1.
• xpacket — instrukcja przetwarzania, która opakowuje pakiet XMP, z nagłówkiem begin (znacznik kodowania) i trailerem end (flaga tylko-do- odczytu lub zapisywalny), dzięki czemu narzędzie może zlokalizować i edytować pakiet bez pełnego parsowania.
• Przestrzeń nazw / schemat — nazwany słownik właściwości związany z URI. Częste prefiksy: dc (Dublin Core), xmp (podstawowy XMP), pdf (charakterystyczny dla PDF), xmpMM (zarządzanie mediami / tożsamość dokumentu).
• Strumień metadanych — obiekt PDF, dołączony do katalogu dokumentu, który niesie pakiet XMP. Kanoniczna lokalizacja, którą nowoczesny czytnik sprawdza jako pierwszą.
• PDF/A — rodzina archiwalnych profili PDF (ISO 19005). Wymaga strumienia metadanych XMP i żąda, by każdy wpis informacji o dokumencie z odpowiednikiem w XMP się z nim zgadzał, w przeciwnym razie walidacja zawodzi.