gPdf
Blog

Campos de metadatos PDF, explicados: title, language, author, subject, creator, producer

Recorrido campo por campo de los seis campos estándar de metadatos PDF que expone gPdf: title, language, author, subject, creator, producer. Para qué sirve cada uno, quién los lee, errores comunes y cómo verificar lo enviado.

gPdf Engineering
#pdf-metadata#pdf-spec#technical-reference

Este es el artículo complementario de Las propiedades del PDF deberían mostrar su marca, no la herramienta de otro: aquel explicaba por qué merece la pena cuidar los metadatos del PDF. Este es el manual operativo: para qué sirve cada campo en la especificación PDF, quién lo lee, los errores comunes y cómo verificar que su salida realmente incluyó lo que pretendía.

gPdf expone los seis campos estándar que la especificación PDF define para los metadatos a nivel de documento. Viven bajo settings.metadata en el JSON DocumentRequest. Cada campo es opcional: si no establece uno, gPdf recurre al default_metadata del token (función de política Enterprise) o a un valor predeterminado del sistema.

{
  "settings": {
    "metadata": {
      "title":    "...",
      "language": "...",
      "author":   "...",
      "subject":  "...",
      "creator":  "...",
      "producer": "..."
    }
  }
}

El resto del artículo es una sección por campo. Cada sección sigue la misma estructura: qué es el campo, dónde aparece, errores comunes, regla práctica. El orden es qué rellenar primero → segundo → … → último.

title — qué es el documento

La especificación PDF lo describe como el «título del documento».

Dónde aparece:

  • La barra de título en los visores de PDF (Adobe Reader, Preview, Foxit y el visor PDF de Chromium lo muestran).
  • La pestaña del navegador cuando el PDF se abre en línea (Content-Disposition: inline).
  • Índices de búsqueda — Spotlight, Outlook, SharePoint y el indexador de texto completo de Google Drive leen title y le dan mucho peso.

Errores comunes:

  • ❌ Poner el nombre de archivo como título. invoice-20260318.pdf es el nombre de archivo. El título debería ser algo que un humano lea, como Invoice INV-2026-3401. Nombre de archivo y título son cuestiones distintas; el nombre de archivo es para los sistemas de ficheros, el título es para los visores y la búsqueda.
  • ❌ Dejar el título vacío. Los visores recurren al nombre de archivo. El resultado se lee como autogenerado y emitido por máquina.
  • ❌ Meter la marca en el título. Acme Logistics — Invoice INV-2026-3401 satura la barra de título. La marca va en author, no en title.

Regla práctica: el título debería coincidir con el H1 de la página renderizada. Si la línea superior de su plantilla de factura es «Invoice INV-2026-3401», ese es el título.

language — para accesibilidad, búsqueda y cumplimiento

language es una etiqueta de idioma BCP-47: en, de, zh-Hans, pt-BR, ar-SA. Defínalo para cada documento. De los seis campos, es el que tiene las consecuencias más concretas en sistemas posteriores con el menor coste de implementación — por eso está en la posición 2 y no enterrado más abajo.

Dónde aparece:

  • Lectores de pantalla — JAWS, NVDA, VoiceOver lo usan para elegir el conjunto correcto de fonemas. Un lector de pantalla inglés que lee un PDF con language: "de" pronunciará correctamente las palabras alemanas; sin la etiqueta, la prosodia sale mal.
  • Motores de búsqueda e indexadores — afecta a qué reglas de stemming y lista de palabras vacías del idioma se aplican. Una factura con language: "zh-Hans" se indexa con segmentación china; sin etiqueta, suele caer en inglés por defecto y el índice se vuelve inutilizable.
  • Cumplimiento PDF/A — PDF/A-2a y PDF/A-3a (perfiles de accesibilidad) requieren la etiqueta de idioma. Sin ella, la validación de veraPDF falla.

Errores comunes:

  • ❌ Dejarlo sin establecer. Por defecto use “el idioma del destinatario”, no “el valor predeterminado de la plataforma”. Muchas pilas simplemente no escriben el campo; el resultado son lectores de pantalla que pronuncian mal e índices de búsqueda que segmentan mal.
  • ❌ Usar una cadena no BCP-47 como "english" o "EN-US". La especificación PDF espera etiquetas RFC 5646: en, en-US, de, pt-BR.
  • ❌ Codificar a fuego el valor por defecto de la plataforma (por ejemplo, siempre "en") sin tener en cuenta el idioma real del contenido del documento. Una factura en portugués etiquetada "en" es peor que un documento sin etiqueta — engaña activamente al indexador.

Regla práctica: la etiqueta debe coincidir con el idioma real del contenido. Para un cliente en Brasil que recibe una factura en portugués, establezca "language": "pt-BR", no "en". Para documentos multilingües, elija el idioma dominante y use el atributo Lang en elementos de contenido individuales para el resto — eso es una función de accesibilidad de PDF etiquetado, más allá del campo language a nivel de documento.

author — quién respalda el documento

En la especificación PDF, author es «el nombre de la persona u organización que creó el documento». Para PDF empresariales que se envían a destinatarios, la respuesta es casi siempre la organización — pero la forma adecuada varía genuinamente según el contexto.

Dónde aparece:

  • Diálogo de propiedades en todos los visores de PDF, etiquetado de forma destacada como «Author».
  • Indexadores de DMS / archivo, a menudo usado como filtro.
  • Flujo de metadatos XMP de PDF/A, donde se traslada a archivos documentales de largo plazo.

Errores comunes:

  • ❌ "author": "[email protected]" — filtra accidentalmente el correo del operador en cada PDF, acaba en todos los índices de búsqueda, se convierte en un problema de PII a largo plazo.
  • ❌ "author": "PDF Generator Service" — nombre de herramienta interna; no significa nada para el destinatario.
  • ❌ Vacío — Preview y la mayoría de los visores muestran literalmente “(no author)” en el diálogo de propiedades, lo que se lee como “nadie responde por esto”.

Formas que funcionan:

  • ✅ "author": "Acme Logistics, Inc." — organización directa.
  • ✅ "author": "Acme Logistics — Billing" — organización + departamento, para documentos que se enrutan a un equipo específico.
  • ✅ "author": "Bridge Capital Partners — Fund III" — útil en finanzas/jurídico donde la atribución es a una entidad específica.
  • ✅ "author": "Maria López, RICS Surveyor" — para publicación de un solo autor (informes, valoraciones, opiniones jurídicas) donde el individuo ES la atribución editorial.

Regla práctica: author es la entidad con la que el destinatario debe asociar el documento. En un SaaS multi-tenant en el que la plataforma genera PDF en nombre de los clientes, author debería ser el nombre de la organización del cliente, no el nombre de la plataforma. (El nombre de la plataforma va en creator — véase más abajo.) En contextos de consultoría, publicación o servicios jurídicos donde la persona es la marca, también puede usarse una persona.

subject — qué tipo de documento es

subject es la descripción corta del documento. Los visores no lo muestran de forma destacada — la mayoría de los usuarios nunca lo verán a menos que abran el diálogo de propiedades. Pero los sistemas de gestión documental, los sistemas de archivo y el enrutamiento de correo/archivos por reglas lo usan.

Dónde aparece:

  • Diálogo de propiedades, posición secundaria.
  • Reglas de enrutamiento de DMS, lógica de agrupación de archivos.
  • Flujo de metadatos XMP (PDF/A).

Errores comunes:

  • ❌ "subject": "Invoice for Acme on 2026-03-18 for $4,532.10" — eso es una descripción de instancia de documento, no de tipo. Va en title.
  • ❌ Vacío — pierde un gancho gratuito de enrutamiento para sistemas posteriores.
  • ❌ Mezclar clases de forma inconsistente ("Invoice" vs "Invoice/2026-03" vs "Monthly invoice") — los filtros de DMS no pueden agrupar sobre un objetivo móvil.

Formas que funcionan:

  • ✅ "subject": "Invoice"
  • ✅ "subject": "Monthly account statement"
  • ✅ "subject": "Shipping label — 4×6 thermal"
  • ✅ "subject": "Q3 2026 board pack"

Regla práctica: la granularidad correcta es la clase de documento, no la instancia de documento. Un DMS con miles de PDF entrantes puede enrutar por subject si le da un vocabulario consistente. Elija un conjunto finito de clases para su plataforma y no se desvíe — cada factura que su plataforma genere debe tener exactamente "subject": "Invoice".

creator vs producer — el par más confundido

Aquí es donde la mayoría de los equipos dejan de leer la especificación PDF y empiezan a adivinar. La especificación es precisa; los dos campos significan cosas distintas.

  • creator — la aplicación que produjo el contenido fuente (el sistema de origen que decidió qué debía decir el documento).
  • producer — la aplicación que produjo los bytes del PDF (el motor de renderizado que convirtió ese contenido en un archivo PDF).

Para una plataforma SaaS de facturación que genera facturas mediante una API de JSON a PDF como gPdf:

  • creator = la plataforma SaaS de facturación con su versión. Esa es la aplicación que decidió que esto debía ser una factura para Acme por 4.532,10 USD.
  • producer = el renderizador. Por defecto es «gPdf». Pero como la capa de renderizado es infraestructura que el SaaS eligió, el SaaS puede legítimamente establecer producer con el nombre de su propia plataforma — su plataforma, en un sentido real, produjo los bytes del PDF al delegar en gPdf como infraestructura.
{
  "creator":  "Acme Billing Platform v7.2",
  "producer": "Acme Billing Platform"
}

Dónde aparecen:

  • Diálogo de propiedades, ambos etiquetados.
  • Salida de pdfinfo, uno al lado del otro.
  • Flujo XMP de PDF/A (ambos campos deben ser no vacíos en PDF/A).

Errores comunes:

  • ❌ creator establecido en una cadena User-Agent de Chromium / Mozilla. Ocurre cuando una pila de PDF basada en un navegador sin interfaz gráfica pasa el User-Agent a creator automáticamente. Es la versión del navegador, no el sistema de referencia. Sobrescríbalo.
  • ❌ producer dejado como el nombre del renderizador por defecto. La mayoría de los equipos nunca lo sobrescribe, así que cada PDF dice «Skia/PDF m120» o «wkhtmltopdf» — vea el artículo sobre marca blanca para entender por qué esto importa en B2B.
  • ❌ Poner el mismo valor en ambos. Aceptable pero desperdiciado — los dos campos existen precisamente para que un visor pueda distinguir “aplicación fuente” de “motor de renderizado”. Úselos.

Regla práctica: creator es el nombre de su aplicación con versión (por ejemplo, "Acme Billing Platform v7.2"); producer es la marca o el nombre de la plataforma de su aplicación sin versión (por ejemplo, "Acme Billing Platform"). Ambos deberían ser valores que el destinatario reconocería.

Campos vacíos, valores predeterminados por token, sorpresas posteriores

Tres detalles de implementación que vale la pena conocer antes de enviar:

  1. Las cadenas vacías o de solo espacios en blanco se tratan como no proporcionadas. Enviar "title": "" es lo mismo que omitir title — no escribe una cadena vacía en el PDF, sino que recorre la cadena de valores alternativos (valor predeterminado del token → valor predeterminado del sistema). Esta es la causa del reporte de bug “lo configuré y no se aplicó” más común.
  2. Las políticas de token pueden eliminar o aplicar valores por defecto a los campos de metadatos. Un SaaS multi-tenant usando gPdf puede establecer un default_metadata en cada token de API para que cada PDF que ese token genere lleve el author y producer del cliente sin tener que confiar en que cada desarrollador los establezca en cada solicitud. El valor por defecto a nivel de token es la capa de aplicación adecuada para «cada PDF de Acme debe decir Acme».
  3. Los procesos posteriores pueden reescribir sus metadatos. Herramientas que posprocesan PDF después de que gPdf los devuelve — Ghostscript sin banderas explícitas de preservación de metadatos, algunas herramientas corporativas de DRM, algunos “optimizadores de PDF” — pueden sobrescribir Producer con su propio nombre y deshacer la marca que acaba de establecer. Verifique contra su proceso de producción real, no solo contra la respuesta cruda de gPdf.

Verifique sus metadatos

Tras implementar los cambios anteriores, tres formas rápidas de comprobar que el PDF realmente incluyó lo que pretendía:

Línea de comandos (macOS / Linux, requiere poppler-utils):

$ pdfinfo your-output.pdf | head -10
Title:           Invoice INV-2026-3401
Subject:         Monthly invoice — 2026-03
Author:          Acme Logistics, Inc.
Creator:         Acme Billing Platform v7.2
Producer:        Acme Billing Platform
Language:        en

Acrobat / Adobe Reader: Archivo → Propiedades → pestaña Descripción. Aparecen los seis campos, con Title mostrado en la barra de título del visor en la parte superior.

Vista Previa de macOS: ⌘+I (Obtener información). El panel del inspector «PDF» muestra los mismos campos.

Si algún campo aparece vacío, en blanco o con un nombre de herramienta que no estableció, vuelva a revisar el cuerpo de la solicitud — la causa más común es enviar "" (cadena vacía), que la API trata como “no proporcionado” y recorre la cadena de valores alternativos hasta un valor predeterminado. La segunda causa más común es un proceso posterior (Ghostscript, DRM, optimizador) que sobrescribe el campo después de que gPdf lo devolvió; pruebe contra producción, no solo contra la respuesta cruda de renderizado.

Metadatos en el archivo PDF/A

Si renderiza para archivo a largo plazo con settings.profile: "pdfa-2b" (o -2a, -3a, -3b), los metadatos dejan de ser opcionales y pasan a ser determinantes:

  • El campo producer no puede estar vacío en un archivo conforme a PDF/A — como mínimo se envía el valor por defecto del sistema.
  • language es obligatorio para los perfiles de accesibilidad (PDF/A-2a, PDF/A-3a). Sin él, la validación de veraPDF falla de plano.
  • El flujo de metadatos XMP que requiere PDF/A se genera automáticamente a partir de los seis campos de arriba; no tiene que construirlo usted.
  • title, author, subject, creator, producer y language viajan todos al flujo XMP, por lo que el indexador de metadatos de un archivo documental posterior (Preservica, Archivematica) puede construir su catálogo a partir de ellos sin volver a analizar el cuerpo del documento.

Para un documento de archivo, los metadatos de marca no son solo pulido de marca — forman parte de la durabilidad del artefacto. La oficina de aduanas alemana, la autoridad fiscal brasileña o cualquier archivo a largo plazo que abra su PDF dentro de diez años verá lo que estuviera en esos campos el día que lo renderizó. Establecerlos deliberadamente en el momento del renderizado es la única oportunidad que tiene.

Lo que gPdf (todavía) no expone

Para ser honestos sobre la superficie actual: la especificación PDF también define Keywords (términos de búsqueda de forma libre) y un flujo de metadatos XMP que soporta pares clave-valor personalizados arbitrarios. gPdf no expone ninguno de los dos en la API actual.

Si necesita incluir datos empresariales arbitrarios dentro del PDF (UUID de pedido, código de almacén, versión de plantilla), las soluciones provisionales hoy son:

  • Poner en subject una cadena corta estructurada que los sistemas posteriores puedan analizar.
  • Mantener los datos empresariales en su propia base de datos, indexados por nombre de archivo o hash del contenido.
  • Esperar — los campos personalizados XMP están en la hoja de ruta, y cuando lleguen serán la respuesta correcta para el contexto oculto de flujo operativo y legible por máquina.

Confundir “metadatos de marca” (los seis campos estándar, disponibles ya) con “metadatos empresariales personalizados” (campos personalizados XMP, futuros) es la forma más fácil de prometer en exceso lo que es posible hoy. Vale la pena mantenerlos separados en su propia planificación.

Un ejemplo completo

Una plataforma SaaS de facturación (Acme Billing Platform) generando una factura para un cliente alemán (Müller Versand GmbH), lista para archivar como PDF/A:

{
  "settings": {
    "profile": "pdfa-3b",
    "metadata": {
      "title":    "Rechnung RE-2026-0412",
      "language": "de",
      "author":   "Müller Versand GmbH",
      "subject":  "Monatsrechnung — März 2026",
      "creator":  "Acme Billing Platform v7.2",
      "producer": "Acme Billing Platform"
    }
  }
}

pdfinfo sobre el PDF resultante:

$ pdfinfo invoice-2026-0412.pdf | head -10
Title:           Rechnung RE-2026-0412
Subject:         Monatsrechnung — März 2026
Author:          Müller Versand GmbH
Creator:         Acme Billing Platform v7.2
Producer:        Acme Billing Platform
Language:        de

Título en alemán, author como Müller Versand (la entidad GmbH del cliente, destinatario del documento), creator como Acme Billing Platform (el sistema editorial que decidió qué poner en la página), producer como la marca de Acme Billing Platform, idioma etiquetado correctamente para el lector de pantalla alemán y para el indexador de texto completo alemán que más tarde recogerá esto en el DMS de Müller. El perfil PDF/A-3b implica que este conjunto de metadatos también se serializa en el flujo XMP para el archivo a largo plazo.

Nada en las propiedades del archivo nombra a gPdf, Chromium, ni a ninguna herramienta que el cliente no eligió. Que es exactamente el objetivo.

La mejora más pequeña posible

Si ya hace POST a /api/v1/pdf/render y su llamada actual no tiene settings.metadata, la mejora más pequeña son tres líneas añadidas al JSON que ya envía:

 {
   "pages": [...],
   "settings": {
+    "metadata": {
+      "author":   "Your customer's organisation",
+      "producer": "Your platform"
+    }
   }
 }

Dos campos, una nueva clave. Verificable con pdfinfo en segundos. Una vez que estén aplicados, rellene title, language, subject y creator cuando tenga tiempo.

Dónde encaja esto