Apa yang PDF ketahui tentang dirinya: metadata dan paket XMP

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

Sekilas

Buka sebuah PDF modern dan ia mungkin memberi tahu Anda tentang dirinya dua kali. Ada sebuah daftar key/value lama yang kecil bernama Document Information dictionary, dan bisa ada sebuah blok XML — paket XMP — yang menyatakan kurang lebih hal yang sama dalam bentuk yang lebih kaya dan terstruktur. Halaman ini membahas kedua sistem paralel itu, mengapa keduanya bertahan, dan mengapa pipeline pengarsipan serta pencarian menuntut keduanya sepakat.

Jawaban singkat atas judulnya: sebuah PDF tahu judulnya, pengarangnya, subjeknya, kata kuncinya, alat yang membuatnya, dan kapan. Ia menyimpan pengetahuan itu di dua tempat sekaligus, dan rekayasa yang menariknya ada pada menjaga keduanya tetap jujur.

Mengapa ini penting

Metadata adalah bagian dari sebuah dokumen yang jarang dilihat manusia dan hampir selalu dibaca mesin. Pratinjau berkas pada sistem operasi Anda, sebuah digital-asset manager, sebuah katalog perpustakaan, sebuah indeks pencarian, sebuah alat legal-discovery — banyak di antaranya membaca metadata sebelum, atau bersamaan dengan, teks dokumen, dan mempercayai apa yang dinyatakannya.

Jadi ketika kedua sistem itu tidak sepakat — Info dictionary menyebut satu pengarang dan paket XMP menyebut yang lain — sesuatu di hilir memilih salah satu, dan Anda tidak dapat memilih yang mana. Sebuah indeks pencarian mungkin memunculkan judul yang salah. Sebuah validator arsip mungkin menolak berkasnya begitu saja. Penyimpangan itu tidak terlihat sampai sebuah pipeline tersandung padanya, yang merupakan waktu terburuk untuk menemukannya.

Versi singkat

Sebuah PDF dapat membawa metadata dalam dua sistem paralel: Document Information dictionary lawas dan paket XMP RDF/XML yang modern.
Paket XMP dibungkus dalam sebuah processing instruction xpacket — sebuah header begin dan sebuah trailer end — sehingga sebuah alat dapat menemukan dan, di tempat, bahkan menulis ulang paket itu tanpa mengurai ulang seluruh berkas.
Properti berada dalam namespace: dc (Dublin Core) untuk judul dan pencipta, xmp untuk tanggal pembuatan dan modifikasi, pdf untuk producer, xmpMM untuk identitas dan riwayat dokumen.
PDF/A mengharuskan metadata XMP, dan entri DocInfo yang memiliki padanan XMP harus cocok dengannya — sebuah ketidaksepakatan adalah kegagalan validasi.
NextPDF memperlakukan keduanya sebagai satu pekerjaan: ia menulis keduanya, membaca XMP kembali, dan menjaga ukuran paket, gagal-tertutup alih-alih mengeluarkan berkas yang cacat.

Bagaimana NextPDF menanganinya

Pembingkaian yang jujur adalah bahwa ini adalah masalah sinkronisasi yang disamarkan sebagai masalah pemformatan. Document Information dictionary (Spec: ISO 32000-2, §14.3.3), yang dirujuk dari trailer oleh entri /Info, adalah sebuah daftar string yang datar: Title, Author, Subject, Keywords, Creator, Producer, dan sepasang tanggal. Ia sederhana, ia mendahului XML, dan ia masih ikut menumpang di hampir setiap berkas karena begitu banyak alat yang masih membacanya lebih dahulu.

Paket XMP (Spec: ISO 16684-1:2019, §7) adalah separuh yang modern. Ia adalah sebuah dokumen XML — RDF/XML, tepatnya — yang memodelkan berkas sebagai seperangkat properti bernama yang dikelompokkan ke dalam schema, setiap schema terikat pada sebuah namespace (Spec: ISO 16684-1:2019, §6). Struktur itulah yang tidak dapat dilakukan dictionary yang datar: sebuah nilai dapat berupa daftar terurut, sebuah alternatif yang ditandai bahasa (“judul dalam bahasa Inggris, judul dalam bahasa Prancis”), atau sebuah rekaman terstruktur. Dalam sebuah PDF, XML itu berada di sebuah metadata stream yang dilampirkan ke document catalog (Spec: ISO 32000-2, §14.3.2), yang merupakan tempat kanonis yang dicari sebuah pembaca masa kini.

Tiga detail layak dibedah, karena di situlah alat-alat salah menangani paketnya.

Pembungkusnya. Sebuah paket XMP diapit oleh sebuah processing instruction sehingga, pada format-format yang menyimpan paketnya sebagai byte yang dapat dicari langsung, sebuah program dapat menemukan metadata tanpa pengurai penuh; pada PDF secara khusus, metadata stream katalog adalah pelokasi kanonisnya. Header begin membawa sebuah byte-order mark yang mendeklarasikan pengodean teks; trailer end membawa sebuah flag yang menyatakan apakah paket itu hanya-baca atau boleh disunting di tempat. Ketika ia dapat ditulis, serializer meninggalkan sederet padding whitespace setelah XML sehingga sebuah editor dapat menumbuhkan kontennya sedikit tanpa menggeser setiap byte yang menyusul. Padding itu bukan dekorasi — itulah yang membuat penyuntingan metadata di tempat menjadi mungkin.

Namespace-nya. Sebuah properti hanya bermakna terhadap namespace-nya, dan segelintir darinya nyaris universal. Dublin Core (dc) menyimpan judul dan pencipta. XMP basic schema (xmp) menyimpan tanggal pembuatan dan modifikasi serta alat penulisan. PDF schema (pdf) menyimpan string producer dan kata kunci. Media-management schema (xmpMM) menyimpan identitas dokumen dan riwayat penurunannya — jejak yang menyatakan “berkas ini berasal dari berkas itu.” Menyepakati URI namespace dan nama properti ini — biasanya ditampilkan dengan prefiks konvensional — adalah inti dari core schemas (Spec: ISO 16684-1:2019, Annex B); dua alat yang sama-sama berbicara properti judul Dublin Core dapat saling beroperasi tanpa pengaturan sebelumnya.

Aturan konsistensinya. Karena kedua sistem dapat menamai properti yang sama, keduanya dapat tidak sepakat. Profil arsip menolak mengizinkan hal itu. Sebuah berkas PDF/A harus membawa sebuah metadata stream XMP, dan setiap entri Document Information yang memiliki padanan XMP harus cocok dengannya; sebuah ketidaksepakatan adalah kegagalan validasi. Intisari praktisnya jelas: dalam sebuah pipeline pengarsipan, keduanya bukan dua bidang yang independen melainkan satu fakta yang ditulis dua kali, dan keduanya harus tetap selaras.

NextPDF menangani ketiganya sebagai satu perhatian. Alur metadata adalah satu jalur, bukan dua jalur yang bersaing.

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.
Write the Info dictionaryThe DocInfo writer emits the legacy Title, Author, Subject, Keywords, Creator, Producer and date entries that older tools read first.
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.
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.
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.

Contoh praktis

Bentuk di bawah ini menyetel metadata satu kali dan membiarkan mesin menyebarkannya ke kedua sistem, lalu membaca judul XMP kembali sehingga sebuah pipeline dapat memeriksanya. Penjaga ukuran adalah baris yang mengubah “mungkin baik-baik saja” menjadi “terbukti ditolak jika tidak.”

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

Tidak ada jalur di sini tempat kedua sistem diam-diam menyimpang: nilai masuk satu kali, kedua penulis mengonsumsi sumber yang sama, dan pembacanya membiarkan sebuah pipeline memeriksa hasilnya.

Kesalahpahaman umum

Keyakinan yang sering muncul adalah bahwa Info dictionary sudah usang dan Anda dapat mengabaikannya. Anda tidak bisa — belum. Sejumlah besar perangkat lunak terpasang, termasuk beberapa pratinjau berkas sistem operasi dan perkakas arsip yang lebih tua, masih membaca Info dictionary lebih dahulu atau hanya membacanya. Membuangnya tidak memodernkan sebuah berkas; ia membuat berkas itu tampak tak berjudul bagi apa pun yang belum mengadopsi XMP.

Kesalahan kebalikannya adalah memperlakukan keduanya sebagai bidang independen yang Anda isi secara terpisah. Itulah persis bagaimana keduanya menyimpang. Keduanya adalah dua serialisasi dari satu fakta. Tulis keduanya dari satu sumber, atau terima bahwa sesuatu di hilir akan memilih versi yang tidak Anda maksudkan.

Batasan dan ruang lingkup

NextPDF menulis kedua sistem dan membaca XMP kembali. Ruang lingkupnya adalah XMP metadata builder, DocInfo writer, dan sebuah XMP reader. Ia tidak menjanjikan untuk menjadi sebuah mesin kueri RDF/XML serbaguna.
Paket XMP dijaga ukurannya dan gagal-tertutup. Sebuah paket yang melampaui batas mesin memunculkan sebuah eksepsi bertipe. Mesin tidak akan mengeluarkan paket yang terpotong, ber-padding-melampaui-batas, atau yang sebaliknya cacat untuk membuat sebuah permintaan yang berukuran berlebih “pas.”
Konsistensi ditegakkan pada waktu tulis dari satu sumber; ini bukan rekonsiliasi ajaib atas sebuah berkas yang tidak Anda hasilkan. Jika Anda mengimpor sebuah dokumen yang dua sistemnya sudah tidak sepakat, menyelesaikannya adalah keputusan Anda, bukan sebuah penulisan-ulang implisit.
Persyaratan metadata PDF/A adalah bagian dari profil arsip. Halaman ini menjelaskan aturannya; keputusan kesesuaian menjadi milik sebuah validator, sebagaimana selalu begitu untuk pekerjaan pengarsipan. Lihat halaman pengarsipan untuk batas itu.

XMP metadata builder, DocInfo writer, dan XMP reader adalah kapabilitas Core. Kualifikasi yang jujur ada pada penjaga ukuran, di bawah.

Penjaga ukuran adalah sebuah keputusan operabilitas, bukan keterbatasan yang perlu diminta maaf. Sebuah paket XMP berada di dalam sebuah metadata stream, dan sebuah paket yang tumbuh tanpa batas adalah sebuah permukaan denial-of-service dan sebuah risiko korupsi bagi editor in-place mana pun yang mengandalkan padding yang dapat ditulis itu. Maka mesin menetapkan sebuah batas dan, ketika sebuah permintaan akan melampauinya, memunculkan sebuah eksepsi bertipe (Spec: ISO 16684-1:2019, §7) alih-alih menulis sebuah stream yang cacat. Kegagalannya keras, bernama, dan pada waktu tulis — tempat Anda dapat memangkas metadata dengan sengaja — alih-alih senyap dan ditemukan kemudian oleh sebuah validator yang begitu saja menolak berkasnya.

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.

Dokumen terkait

Archival and PDF/A — tempat paket XMP berhenti menjadi opsional dan aturan konsistensi DocInfo-ke-XMP menjadi sebuah persyaratan lulus-atau-gagal.
Compliance you can hand to an auditor — mengapa metadata yang berputar bolak-balik dengan baik dan sepakat dengan dirinya sendiri adalah bagian dari sebuah artefak yang dapat diaudit.
The anatomy of a PDF file — tempat trailer, katalog, dan metadata stream berada dalam struktur berkas.
Streams and filters — metadata stream adalah sebuah stream; inilah bagaimana stream PDF dikodekan dan dijaga tetap deterministik.

Glosarium

Document Information dictionary — metadata key/value lawas yang datar, dirujuk dari trailer oleh entri /Info: Title, Author, Subject, Keywords, Creator, Producer, dan tanggal. Mendahului XMP; masih banyak dibaca.
XMP — Extensible Metadata Platform, sebuah format XML (RDF/XML) untuk menggambarkan sebuah sumber daya dengan properti bernama yang dikelompokkan ke dalam schema. Distandarkan sebagai ISO 16684-1.
xpacket — processing instruction yang membungkus sebuah paket XMP, dengan sebuah header begin (penanda pengodean) dan sebuah trailer end (flag hanya-baca atau dapat ditulis), sehingga sebuah alat dapat menemukan dan menyunting paketnya tanpa pengurai penuh.
Namespace / schema — sebuah kosakata properti bernama yang terikat pada sebuah URI. Prefiks umum: dc (Dublin Core), xmp (XMP basic), pdf (khusus-PDF), xmpMM (media management / identitas dokumen).
Metadata stream — objek PDF, dilampirkan ke document catalog, yang membawa paket XMP. Lokasi kanonis yang diperiksa lebih dahulu oleh sebuah pembaca modern.
PDF/A — keluarga profil PDF arsip (ISO 19005). Ia mengharuskan sebuah metadata stream XMP dan menuntut agar setiap entri Document Information dengan padanan XMP cocok dengannya, atau validasi gagal.