O que um PDF sabe sobre si mesmo: metadados e o pacote XMP

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

Visão geral

Abra um PDF moderno e ele pode falar sobre si mesmo duas vezes. Há uma pequena e antiga lista de chave/valor chamada Document Information dictionary, e pode haver um bloco de XML — o pacote XMP — que diz mais ou menos a mesma coisa de uma forma mais rica e estruturada. Esta página é sobre esses dois sistemas paralelos, por que ambos sobrevivem, e por que os pipelines de arquivamento e busca insistem que eles concordem.

A resposta curta para o título: um PDF sabe seu título, autor, assunto, palavras-chave, a ferramenta que o produziu, e quando. Ele armazena esse conhecimento em dois lugares ao mesmo tempo, e a engenharia interessante está em mantê-los honestos.

Por que isso importa

Metadados são a parte de um documento que um humano raramente vê e uma máquina quase sempre lê. A pré-visualização de arquivos do seu sistema operacional, um gerenciador de ativos digitais, um catálogo de biblioteca, um índice de busca, uma ferramenta de descoberta legal — muitos deles leem os metadados antes do, ou ao lado do, texto do documento, e confiam no que eles dizem.

Então, quando os dois sistemas discordam — o Info dictionary diz um autor e o pacote XMP diz outro — algo lá adiante escolhe um, e você não decide qual. Um índice de busca pode trazer à tona o título errado. Um validador de arquivamento pode rejeitar o arquivo de imediato. A divergência é invisível até que um pipeline tropece nela, que é o pior momento para descobri-la.

A versão resumida

• Um PDF pode carregar metadados em dois sistemas paralelos: o legado Document Information dictionary e o moderno pacote XMP de RDF/XML.
• O pacote XMP é embrulhado em uma instrução de processamento xpacket — um cabeçalho begin e um trailer end — de modo que uma ferramenta pode encontrá-lo e, no lugar, até reescrevê-lo sem refazer o parsing do arquivo inteiro.
• As propriedades vivem em namespaces: dc (Dublin Core) para título e criador, xmp para datas de criação e modificação, pdf para o produtor, xmpMM para identidade e histórico do documento.
• O PDF/A exige metadados XMP, e as entradas do DocInfo que têm equivalentes XMP devem coincidir com ele — uma discordância é uma falha de validação.
• O NextPDF trata os dois como um único trabalho: ele escreve ambos, lê o XMP de volta, e protege o tamanho do pacote, falhando de forma fechada em vez de emitir um arquivo malformado.

Como o NextPDF aborda isso

O enquadramento honesto é que isto é um problema de sincronização disfarçado de problema de formatação. O Document Information dictionary (SpecSpec: ISO 32000-2, §14.3.3ISO 32000-2 §14.3.3), referenciado a partir do trailer pela entrada /Info, é uma lista plana de strings: Title, Author, Subject, Keywords, Creator, Producer, e algumas datas. É simples, antecede o XML, e ainda vai junto em quase todo arquivo porque tantas ferramentas ainda o leem primeiro.

O pacote XMP (SpecSpec: ISO 16684-1:2019, §7ISO 16684-1:2019 §7) é a metade moderna. É um documento XML — RDF/XML, para ser exato — que modela o arquivo como um conjunto de propriedades nomeadas agrupadas em schemas, cada schema vinculado a um namespace (SpecSpec: ISO 16684-1:2019, §6ISO 16684-1:2019 §6). Essa estrutura é o que o dicionário plano não consegue fazer: um valor pode ser uma lista ordenada, uma alternativa com tag de idioma (“título em inglês, título em francês”), ou um registro estruturado. Em um PDF, esse XML vive em um metadata stream anexado ao catálogo do documento (SpecSpec: ISO 32000-2, §14.3.2ISO 32000-2 §14.3.2), que é o lugar canônico onde um leitor atual procura.

Três detalhes valem ser dissecados, porque são onde as ferramentas erram o pacote.

O invólucro. Um pacote XMP é delimitado por uma instrução de processamento de modo que, em formatos onde o pacote é armazenado como bytes diretamente pesquisáveis, um programa possa localizar os metadados sem um parse completo; no PDF especificamente, o metadata stream do catálogo é o localizador canônico. O cabeçalho begin carrega um byte-order mark que declara a codificação de texto; o trailer end carrega um flag declarando se o pacote é somente-leitura ou pode ser editado no lugar. Quando ele é gravável, o serializador deixa uma sequência de preenchimento de espaços em branco após o XML para que um editor possa crescer o conteúdo ligeiramente sem deslocar cada byte que se segue. Esse preenchimento não é decoração — é o que torna possível a edição de metadados no lugar.

Os namespaces. Uma propriedade só é significativa em relação ao seu namespace, e um punhado deles é quase universal. O Dublin Core (dc) mantém o título e o criador. O XMP basic schema (xmp) mantém as datas de criação e modificação e a ferramenta de autoria. O PDF schema (pdf) mantém a string do produtor e as palavras-chave. O media-management schema (xmpMM) mantém a identidade do documento e seu histórico de derivação — a trilha que diz “este arquivo veio daquele”. Concordar nessas URIs de namespace e nomes de propriedade — geralmente mostrados com prefixos convencionais — é todo o ponto dos core schemas (SpecSpec: ISO 16684-1:2019, Annex BISO 16684-1:2019 Annex B); duas ferramentas que ambas falam a propriedade de título do Dublin Core interoperam sem combinação prévia.

A regra de consistência. Como ambos os sistemas podem nomear a mesma propriedade, eles podem discordar. Os perfis de arquivamento se recusam a permitir isso. Um arquivo PDF/A precisa carregar um metadata stream XMP, e qualquer entrada do Document Information que tenha um equivalente XMP deve coincidir com ele; uma discordância é uma falha de validação. A conclusão prática é direta: em um pipeline de arquivamento, os dois não são campos independentes, mas um fato escrito duas vezes, e eles têm de andar em sincronia.

O NextPDF lida com os três como uma única preocupação. O fluxo de metadados é um caminho, não dois caminhos concorrentes.

1. Coletar os valores uma vezTítulo, autor, assunto, palavras-chave, criador, produtor e datas são definidos no documento uma única vez, de modo que há uma fonte da verdade, não duas.
2. Escrever o Info dictionaryO escritor do DocInfo emite as entradas legadas Title, Author, Subject, Keywords, Creator, Producer e de data que ferramentas mais antigas leem primeiro.
3. Construir o pacote XMPO construtor de XMP serializa os mesmos valores como RDF/XML sob dc, xmp, pdf e xmpMM, embrulhados no cabeçalho e no trailer do xpacket com preenchimento gravável.
4. Proteger o tamanho do pacoteAntes de a serialização ser aceita, o motor verifica o pacote contra um limite de tamanho e falha de forma fechada com uma exceção tipada em vez de emitir um stream malformado ou superdimensionado.
5. Ler o XMP de volta para verificarO leitor de XMP faz parsing do pacote para que um pipeline possa confirmar que o motor escreveu os metadados que recebeu — o tipo de verificação sobre a qual um validador de arquivamento se apoia.

Como o NextPDF mantém consistentes os dois sistemas de metadados de um documento: um conjunto de valores é escrito tanto no Info dictionary quanto no pacote XMP, o pacote é protegido por tamanho antes de ser serializado, e o mesmo pacote pode ser lido de volta para que um pipeline possa confirmar que os metadados foram serializados como pretendido.

Exemplo prático

A forma abaixo define metadados uma vez e deixa o motor distribuí-los para ambos os sistemas, depois lê o título XMP de volta para que um pipeline possa inspecioná-lo. A proteção de tamanho é a linha que transforma “provavelmente tudo bem” em “comprovadamente recusado se não estiver”.

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

Não há caminho aqui em que os dois sistemas divirjam silenciosamente: os valores entram uma vez, ambos os escritores consomem a mesma fonte, e o leitor permite que um pipeline verifique o resultado.

Equívoco comum

A crença frequente é que o Info dictionary está obsoleto e você pode ignorá-lo. Você não pode — ainda não. Uma boa parte do software instalado, incluindo algumas pré-visualizações de arquivos do sistema operacional e ferramentas de arquivamento mais antigas, ainda lê o Info dictionary primeiro ou somente ele. Descartá-lo não moderniza um arquivo; faz o arquivo parecer sem título para qualquer coisa que não tenha adotado o XMP.

O erro espelhado é tratar os dois como campos independentes que você preenche separadamente. É exatamente assim que eles divergem. Eles são duas serializações de um único fato. Escreva-os a partir de uma fonte, ou aceite que algo lá adiante escolherá a versão que você não quis dizer.

Limites e fronteiras

• O NextPDF escreve ambos os sistemas e lê o XMP de volta. Seu escopo é o construtor de metadados XMP, o escritor do DocInfo, e um leitor de XMP. Ele não promete ser um mecanismo de consulta RDF/XML de propósito geral.
• O pacote XMP é protegido por tamanho e falha de forma fechada. Um pacote que excede o limite do motor levanta uma exceção tipada. O motor não vai emitir um pacote truncado, preenchido além do limite, ou de outra forma malformado para fazer uma requisição superdimensionada “caber”.
• A consistência é imposta no momento da escrita a partir de uma fonte; não é reconciliação mágica de um arquivo que você não produziu. Se você importa um documento cujos dois sistemas já discordam, resolver isso é decisão sua, não uma reescrita implícita.
• Os requisitos de metadados do PDF/A fazem parte do perfil de arquivamento. Esta página explica a regra; o veredito de conformidade pertence a um validador, como sempre acontece no trabalho de arquivamento. Veja a página de arquivamento para essa fronteira.

O construtor de metadados, o escritor do DocInfo, e o leitor de XMP são recursos do Core. O qualificador honesto fica com a proteção de tamanho, abaixo.

Human-factors note:Human-factors note

A proteção de tamanho é uma decisão de operabilidade, não uma limitação a se desculpar. Um pacote XMP fica em um metadata stream, e um pacote que cresce sem limite é uma superfície de negação de serviço e um risco de corrupção para qualquer editor no-lugar que tenha se apoiado no preenchimento gravável. Então o motor define um limite e, quando uma requisição o excederia, levanta uma exceção tipada (SpecSpec: ISO 16684-1:2019, §7ISO 16684-1:2019 §7) em vez de escrever um stream malformado. A falha é alta, nomeada, e no momento da escrita — onde você pode aparar os metadados deliberadamente — em vez de silenciosa e descoberta depois por um validador que simplesmente rejeita o arquivo.

Metadata: Info dictionary and XMP packet — edition availability

Edition	Availability
Core	○ O construtor de metadados XMP, o escritor do Document Information dictionary, e o leitor de XMP vêm no Core, com a proteção de tamanho que falha de forma fechada em um pacote superdimensionado — incluindo a saída de conformidade PDF/A e a validação que tornam o metadata stream XMP obrigatório e exigem que o DocInfo coincida com ele.
Pro	○ Adiciona fluxos de trabalho de metadados em lote e por template sobre o mesmo escritor e leitor do Core.
Enterprise	○ Adiciona a política de conformidade mais ampla e a superfície de relatórios ao longo de um conjunto de documentos.

Documentos relacionados

• Arquivamento e PDF/A — onde o pacote XMP deixa de ser opcional e a regra de consistência DocInfo-para-XMP se torna um requisito de passa-ou-falha.
• Conformidade que você pode entregar a um auditor — por que metadados que fazem round-trip e concordam consigo mesmos fazem parte de um artefato auditável.
• A anatomia de um arquivo PDF — onde o trailer, o catálogo e o metadata stream ficam na estrutura do arquivo.
• Streams e filtros — o metadata stream é um stream; é assim que os streams do PDF são codificados e mantidos determinísticos.

Glossário

• Document Information dictionary — os metadados legados, planos, de chave/valor, referenciados a partir do trailer pela entrada /Info: Title, Author, Subject, Keywords, Creator, Producer, e datas. Antecede o XMP; ainda amplamente lido.
• XMP — a Extensible Metadata Platform, um formato XML (RDF/XML) para descrever um recurso com propriedades nomeadas agrupadas em schemas. Padronizado como ISO 16684-1.
• xpacket — a instrução de processamento que embrulha um pacote XMP, com um cabeçalho begin (marcador de codificação) e um trailer end (flag somente-leitura ou gravável), de modo que uma ferramenta pode localizar e editar o pacote sem um parse completo.
• Namespace / schema — um vocabulário nomeado de propriedades vinculado a uma URI. Prefixos comuns: dc (Dublin Core), xmp (XMP basic), pdf (específico de PDF), xmpMM (media management / identidade do documento).
• Metadata stream — o objeto PDF, anexado ao catálogo do documento, que carrega o pacote XMP. A localização canônica que um leitor moderno verifica primeiro.
• PDF/A — a família de perfis de arquivamento do PDF (ISO 19005). Ela exige um metadata stream XMP e demanda que qualquer entrada do Document Information com um equivalente XMP coincida com ele, ou a validação falha.