Lo que un PDF sabe sobre sí mismo: los metadatos y el paquete XMP

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

De un vistazo

Abra un PDF moderno y puede que le hable de sí mismo dos veces. Hay una lista pequeña y antigua de clave/valor llamada diccionario de información del documento, y puede haber un bloque de XML —el paquete XMP— que dice casi lo mismo en una forma más rica y estructurada. Esta página trata de esos dos sistemas paralelos, por qué ambos sobreviven y por qué las canalizaciones de archivado y de búsqueda insisten en que concuerden.

La respuesta breve al título: un PDF conoce su título, su autor, su asunto, sus palabras clave, la herramienta que lo creó y cuándo. Almacena ese conocimiento en dos lugares a la vez, y la ingeniería interesante está en mantenerlos honestos.

Por qué importa

Los metadatos son la parte de un documento que una persona rara vez ve y una máquina casi siempre lee. La vista previa de archivos de su sistema operativo, un gestor de activos digitales, un catálogo de biblioteca, un índice de búsqueda, una herramienta de descubrimiento legal: muchos de ellos leen los metadatos antes del texto del documento, o junto a él, y confían en lo que dicen.

Así que cuando los dos sistemas discrepan —el diccionario Info dice un autor y el paquete XMP dice otro— algo aguas abajo elige uno, y usted no decide cuál. Un índice de búsqueda puede mostrar el título equivocado. Un validador de archivado puede rechazar el archivo de plano. La discrepancia es invisible hasta que una canalización tropieza con ella, que es el peor momento para descubrirla.

La versión breve

• Un PDF puede transportar metadatos en dos sistemas paralelos: el heredado diccionario de información del documento y el moderno paquete XMP de RDF/XML.
• El paquete XMP se envuelve en una instrucción de procesamiento xpacket —una cabecera begin y un tráiler end— de modo que una herramienta pueda encontrarlo y, en su sitio, incluso reescribirlo sin volver a analizar todo el archivo.
• Las propiedades viven en espacios de nombres: dc (Dublin Core) para el título y el creador, xmp para las fechas de creación y modificación, pdf para el productor, xmpMM para la identidad y el historial del documento.
• PDF/A exige metadatos XMP, y las entradas de DocInfo que tienen equivalentes XMP deben coincidir con él: una discrepancia es un fallo de validación.
• NextPDF trata ambos como un único trabajo: escribe los dos, vuelve a leer el XMP y vigila el tamaño del paquete, fallando de forma cerrada en lugar de emitir un archivo malformado.

Cómo lo aborda NextPDF

El planteamiento honesto es que esto es un problema de sincronización disfrazado de problema de formato. El diccionario de información del documento (SpecSpec: ISO 32000-2, §14.3.3ISO 32000-2 §14.3.3), referenciado desde el tráiler por la entrada /Info, es una lista plana de cadenas: Title, Author, Subject, Keywords, Creator, Producer y un par de fechas. Es simple, es anterior a XML y aún viaja en casi todos los archivos porque muchas herramientas todavía lo leen primero.

El paquete XMP (SpecSpec: ISO 16684-1:2019, §7ISO 16684-1:2019 §7) es la mitad moderna. Es un documento XML —RDF/XML, para ser exactos— que modela el archivo como un conjunto de propiedades con nombre agrupadas en esquemas, cada esquema vinculado a un espacio de nombres (SpecSpec: ISO 16684-1:2019, §6ISO 16684-1:2019 §6). Esa estructura es lo que el diccionario plano no puede hacer: un valor puede ser una lista ordenada, una alternativa etiquetada por idioma («título en inglés, título en francés») o un registro estructurado. En un PDF, ese XML vive en un flujo de metadatos adjunto al catálogo del documento (SpecSpec: ISO 32000-2, §14.3.2ISO 32000-2 §14.3.2), que es el lugar canónico donde mira un lector actual.

Vale la pena diseccionar tres detalles, porque son donde las herramientas se equivocan con el paquete.

El envoltorio. Un paquete XMP se delimita con una instrucción de procesamiento para que, en formatos donde el paquete se almacena como bytes directamente buscables, un programa pueda localizar los metadatos sin un análisis completo; en PDF en concreto, el flujo de metadatos del catálogo es el localizador canónico. La cabecera begin lleva una marca de orden de bytes que declara la codificación de texto; el tráiler end lleva una bandera que indica si el paquete es de solo lectura o puede editarse en su sitio. Cuando es escribible, el serializador deja una tira de relleno de espacios en blanco después del XML para que un editor pueda hacer crecer el contenido ligeramente sin desplazar cada byte que le sigue. Ese relleno no es decoración: es lo que hace posible la edición de metadatos en su sitio.

Los espacios de nombres. Una propiedad solo es significativa frente a su espacio de nombres, y un puñado son casi universales. Dublin Core (dc) contiene el título y el creador. El esquema básico de XMP (xmp) contiene las fechas de creación y modificación y la herramienta de autoría. El esquema PDF (pdf) contiene la cadena del productor y las palabras clave. El esquema de gestión de medios (xmpMM) contiene la identidad del documento y su historial de derivación: el rastro que dice «este archivo procede de aquel». Ponerse de acuerdo sobre estos URI de espacio de nombres y nombres de propiedad —que suelen mostrarse con prefijos convencionales— es todo el sentido de los esquemas básicos (SpecSpec: ISO 16684-1:2019, Annex BISO 16684-1:2019 Annex B); dos herramientas que ambas hablan la propiedad de título de Dublin Core interoperan sin acuerdo previo.

La regla de consistencia. Como ambos sistemas pueden nombrar la misma propiedad, pueden discrepar. Los perfiles de archivado se niegan a permitirlo. Un archivo PDF/A debe transportar un flujo de metadatos XMP, y cualquier entrada de información del documento que tenga un equivalente XMP debe coincidir con él; una discrepancia es un fallo de validación. La conclusión práctica es directa: en una canalización de archivado, los dos no son campos independientes sino un único hecho escrito dos veces, y tienen que mantenerse acompasados.

NextPDF gestiona los tres como una sola preocupación. El flujo de metadatos es una ruta, no dos que compiten.

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.

Ejemplo práctico

La forma de abajo establece los metadatos una vez y deja que el motor los reparta a ambos sistemas, y luego vuelve a leer el título XMP para que una canalización pueda inspeccionarlo. La guarda de tamaño es la línea que convierte el «probablemente está bien» en «se rechaza de forma demostrable si no lo está».

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

Aquí no hay ninguna ruta por la que los dos sistemas diverjan en silencio: los valores entran una vez, ambos escritores consumen la misma fuente y el lector permite a una canalización comprobar el resultado.

Concepto erróneo habitual

La creencia frecuente es que el diccionario Info está obsoleto y puede ignorarse. No puede, todavía no. Una gran cantidad de software instalado, incluidas algunas vistas previas de archivos del sistema operativo y herramientas de archivado más antiguas, aún lee el diccionario Info primero, o solamente él. Eliminarlo no moderniza un archivo; hace que el archivo parezca sin título para cualquier cosa que no haya adoptado XMP.

El error espejo es tratar los dos como campos independientes que se rellenan por separado. Así es exactamente como divergen. Son dos serializaciones de un único hecho. Escríbalos desde una sola fuente, o acepte que algo aguas abajo elegirá la versión que usted no quería.

Límites y fronteras

• NextPDF escribe ambos sistemas y vuelve a leer el XMP. Su alcance es el constructor de metadatos XMP, el escritor de DocInfo y un lector de XMP. No promete ser un motor de consultas RDF/XML de propósito general.
• El paquete XMP está vigilado por tamaño y falla de forma cerrada. Un paquete que excede el límite del motor lanza una excepción tipada. El motor no emitirá un paquete truncado, rellenado más allá del límite o de otro modo malformado para hacer «encajar» una solicitud sobredimensionada.
• La consistencia se aplica en el momento de la escritura desde una sola fuente; no es una reconciliación mágica de un archivo que usted no produjo. Si importa un documento cuyos dos sistemas ya discrepan, resolverlo es su decisión, no una reescritura implícita.
• Los requisitos de metadatos de PDF/A forman parte del perfil de archivado. Esta página explica la regla; el veredicto de conformidad corresponde a un validador, como siempre en el trabajo de archivado. Consulte la página de archivado para esa frontera.

El constructor de metadatos, el escritor de DocInfo y el lector de XMP son capacidades de núcleo. El matiz honesto está en la guarda de tamaño, abajo.

Human-factors note:Human-factors note

La guarda de tamaño es una decisión de operabilidad, no una limitación de la que disculparse. Un paquete XMP se sitúa en un flujo de metadatos, y un paquete que crece sin límite es una superficie de denegación de servicio y un riesgo de corrupción para cualquier editor en su sitio que dependiera del relleno escribible. Por eso el motor establece un límite y, cuando una solicitud lo excedería, lanza una excepción tipada (SpecSpec: ISO 16684-1:2019, §7ISO 16684-1:2019 §7) en lugar de escribir un flujo malformado. El fallo es ruidoso, nombrado y en el momento de la escritura —donde puede recortar los metadatos deliberadamente— en lugar de silencioso y descubierto más tarde por un validador que simplemente rechaza el archivo.

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.

Documentos relacionados

• Archivado y PDF/A: donde el paquete XMP deja de ser opcional y la regla de consistencia entre DocInfo y XMP se convierte en un requisito de aprobado o suspenso.
• Conformidad que puede entregar a un auditor : por qué unos metadatos que hacen un viaje de ida y vuelta y concuerdan consigo mismos forman parte de un artefacto auditable.
• La anatomía de un archivo PDF: dónde se sitúan el tráiler, el catálogo y el flujo de metadatos en la estructura del archivo.
• Flujos y filtros: el flujo de metadatos es un flujo; así es como se codifican y se mantienen deterministas los flujos PDF.

Glosario

• Diccionario de información del documento: los metadatos heredados, planos, de clave/valor referenciados desde el tráiler por la entrada /Info: Title, Author, Subject, Keywords, Creator, Producer y fechas. Anterior a XMP; aún ampliamente leído.
• XMP: la Extensible Metadata Platform, un formato XML (RDF/XML) para describir un recurso con propiedades con nombre agrupadas en esquemas. Estandarizado como ISO 16684-1.
• xpacket: la instrucción de procesamiento que envuelve un paquete XMP, con una cabecera begin (marcador de codificación) y un tráiler end (bandera de solo lectura o escribible), de modo que una herramienta pueda localizar y editar el paquete sin un análisis completo.
• Espacio de nombres / esquema: un vocabulario de propiedades con nombre vinculado a un URI. Prefijos comunes: dc (Dublin Core), xmp (XMP básico), pdf (específico de PDF), xmpMM (gestión de medios / identidad del documento).
• Flujo de metadatos: el objeto PDF, adjunto al catálogo del documento, que transporta el paquete XMP. La ubicación canónica que un lector moderno comprueba primero.
• PDF/A: la familia de perfiles de archivado de PDF (ISO 19005). Exige un flujo de metadatos XMP y demanda que cualquier entrada de información del documento con un equivalente XMP coincida con él, o la validación falla.