gPdf
Blog

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

Passeio campo a campo pelos seis metadados PDF padrão que o gPdf expõe — title, language, author, subject, creator, producer. Para que serve cada um, quem os lê, erros comuns e como verificar o que foi entregue.

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

O companheiro de As propriedades do PDF devem exibir a sua marca, não a ferramenta de outra pessoa — aquele post defendeu por que se importar com metadados de PDF. Este é o manual de operação: para que serve cada campo na especificação PDF, quem o lê, os erros comuns e como verificar se a sua saída realmente entregou o que você queria.

O gPdf expõe os seis campos padrão que a especificação PDF define para metadados em nível de documento. Eles vivem em settings.metadata no JSON DocumentRequest. Todo campo é opcional — se você não definir um, o gPdf recorre ao default_metadata do token (recurso de política Enterprise) ou a um valor padrão do sistema.

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

O restante deste post é uma seção por campo. Cada seção segue a mesma forma: o que é o campo, onde aparece, erros comuns, regra prática. A ordem é o que preencher primeiro → depois → … → por último.

title — o que o documento é

A especificação PDF descreve isso como o “título do documento”.

Onde aparece:

  • A barra de título nos visualizadores de PDF (Adobe Reader, Preview, Foxit, o visualizador de PDF do Chromium — todos mostram).
  • A aba do navegador quando o PDF abre inline (Content-Disposition: inline).
  • Índices de busca — Spotlight, Outlook, SharePoint e o indexador full-text do Google Drive leem title e dão peso considerável.

Erros comuns:

  • ❌ Definir title como o nome do arquivo. invoice-20260318.pdf é o nome do arquivo. O title deveria ser algo que um humano lê, como Invoice INV-2026-3401. Nome de arquivo e title são preocupações diferentes; o nome de arquivo é para sistemas de arquivos, o title é para visualizadores e busca.
  • ❌ Deixar o title vazio. Os visualizadores recorrem ao nome do arquivo. O resultado é lido como autogerado e emitido por máquina.
  • ❌ Colocar a marca no title. Acme Logistics — Invoice INV-2026-3401 polui a barra de título. A marca vai em author, não em title.

Regra prática: o title deveria bater com o H1 da página renderizada. Se a linha de topo do seu template de fatura é “Invoice INV-2026-3401”, esse é o title.

language — para acessibilidade, busca e compliance

language é uma tag de idioma BCP-47: en, de, zh-Hans, pt-BR, ar-SA. Defina-o para cada documento. Dos seis campos, é o que tem as consequências downstream mais concretas pelo menor custo de implementação — por isso ele está na posição 2 e não enterrado mais abaixo.

Onde aparece:

  • Leitores de tela — JAWS, NVDA, VoiceOver usam para escolher o conjunto certo de fonemas. Um leitor de tela em inglês lendo um PDF com language: "de" pronunciará palavras alemãs corretamente; sem a tag, a prosódia sai errada.
  • Motores de busca e indexadores — afeta quais regras de stemming e lista de stopwords do locale se aplicam. Uma fatura com language: "zh-Hans" é indexada com segmentação chinesa; sem a tag, costuma cair em inglês por padrão e o índice fica inutilizável.
  • Compliance PDF/A — PDF/A-2a e PDF/A-3a (perfis de acessibilidade) exigem a tag de idioma. Sem ela, a validação do veraPDF falha.

Erros comuns:

  • ❌ Deixar sem definir. Tenha como padrão “o locale do destinatário”, não “o padrão da plataforma”. A maioria dos stacks que vazam simplesmente não escreve o campo; o resultado são leitores de tela que pronunciam errado e índices de busca que segmentam errado.
  • ❌ Usar uma string fora do BCP-47 como "english" ou "EN-US". A especificação PDF espera tags RFC 5646: en, en-US, de, pt-BR.
  • ❌ Codificar fixo o padrão da plataforma (por exemplo, sempre "en") sem levar em conta o idioma real do conteúdo do documento. Uma fatura em português etiquetada como "en" é pior do que um documento sem tag — ela ativamente engana o indexador.

Regra prática: a tag deve bater com o idioma real do conteúdo. Para um cliente no Brasil recebendo uma fatura em português, defina "language": "pt-BR", não "en". Para documentos multilíngues, escolha o idioma dominante e use o atributo Lang em elementos de conteúdo individuais para o resto — isso é um recurso de acessibilidade de PDF marcado, além do campo language em nível de documento.

author — quem é dono do documento

Na especificação PDF, author é “o nome da pessoa ou organização que criou o documento”. Para PDFs de negócio entregues a destinatários, a resposta é quase sempre a organização — mas a forma certa genuinamente varia conforme o contexto.

Onde aparece:

  • Diálogo de propriedades em todo visualizador de PDF, rotulado em destaque como “Author”.
  • Indexadores de DMS / arquivo, frequentemente usado como filtro.
  • Stream de metadados XMP do PDF/A, onde ele viaja para arquivos de longo prazo.

Erros comuns:

  • ❌ "author": "[email protected]" — vaza acidentalmente o e-mail do operador em todo PDF, acaba em todo índice de busca, vira um problema de PII de longo prazo.
  • ❌ "author": "PDF Generator Service" — nome de ferramenta interna; não significa nada para o destinatário.
  • ❌ Vazio — Preview e a maioria dos visualizadores literalmente mostram “(no author)” no diálogo de propriedades, o que se lê como “ninguém é dono disso”.

Formas que funcionam:

  • ✅ "author": "Acme Logistics, Inc." — organização direta.
  • ✅ "author": "Acme Logistics — Billing" — organização + departamento, para documentos que vão para uma mesa específica.
  • ✅ "author": "Bridge Capital Partners — Fund III" — útil em finanças/jurídico onde a atribuição é para uma entidade específica.
  • ✅ "author": "Maria López, RICS Surveyor" — para publicação de autor único (relatórios, avaliações, pareceres jurídicos) onde o indivíduo É a atribuição editorial.

Regra prática: author é a entidade com a qual o destinatário deve associar o documento. Em um SaaS multi-tenant onde a plataforma gera PDFs em nome de clientes, author deveria ser o nome da organização do cliente, não o nome da plataforma. (O nome da plataforma vai em creator — veja abaixo.) Para contextos de consultoria / publicação / jurídicos em que indivíduos são a marca, indivíduos estão bem.

subject — que tipo de documento é

subject é a descrição-curta-do-documento. Visualizadores não o exibem em destaque — a maioria dos usuários nunca vai vê-lo a menos que abra o diálogo de propriedades. Mas sistemas de gestão documental, sistemas de arquivamento e o roteamento de e-mail/arquivo baseado em regras o usam.

Onde aparece:

  • Diálogo de propriedades, posição secundária.
  • Regras de roteamento em DMS, lógica de balde no arquivo.
  • Stream de metadados XMP (PDF/A).

Erros comuns:

  • ❌ "subject": "Invoice for Acme on 2026-03-18 for $4,532.10" — isso é uma descrição de instância do documento, não de tipo. Vai em title.
  • ❌ Vazio — você perde um gancho gratuito de roteamento para sistemas downstream.
  • ❌ Misturar classes de forma inconsistente ("Invoice" vs "Invoice/2026-03" vs "Monthly invoice") — filtros de DMS não conseguem agrupar em um alvo móvel.

Formas que funcionam:

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

Regra prática: a granularidade certa é a classe do documento, não a instância do documento. Um DMS com milhares de PDFs chegando pode rotear por subject se você der a ele um vocabulário consistente. Escolha um conjunto finito de classes para a sua plataforma e nunca desvie — toda fatura que a sua plataforma gerar deve ter exatamente "subject": "Invoice".

creator vs producer — o par mais confundido

É aqui que a maioria dos times para de ler a especificação PDF e começa a adivinhar. A especificação é precisa; os dois campos significam coisas diferentes.

  • creator — a aplicação que produziu o conteúdo de origem (o sistema upstream que decidiu o que o documento deveria dizer).
  • producer — a aplicação que produziu os bytes do PDF (o motor de renderização que transformou esse conteúdo em um arquivo PDF).

Para uma plataforma SaaS de faturamento que gera faturas por uma API de JSON para PDF como o gPdf:

  • creator = a plataforma SaaS de faturamento com a sua versão. Essa é a aplicação que decidiu que isto deveria ser uma fatura para a Acme no valor de $4.532,10.
  • producer = o renderizador. Por padrão, é “gPdf”. Mas, como a camada de renderização é infraestrutura que o SaaS escolheu, o SaaS pode legitimamente definir producer como o nome da sua própria plataforma — a plataforma dele, em um sentido real, produziu os bytes do PDF ao delegar para o gPdf como infraestrutura.
{
  "creator":  "Acme Billing Platform v7.2",
  "producer": "Acme Billing Platform"
}

Onde aparecem:

  • Diálogo de propriedades, ambos rotulados.
  • Saída de pdfinfo, lado a lado.
  • Stream XMP do PDF/A (ambos os campos devem ser não vazios em PDF/A).

Erros comuns:

  • ❌ creator definido com uma string user-agent do Chromium / Mozilla. Acontece quando um stack de PDF baseado em navegador headless passa o User-Agent para creator automaticamente. É a versão do navegador, não o sistema fonte da verdade. Sobrescreva.
  • ❌ producer deixado como o nome do renderizador padrão. A maioria dos times nunca sobrescreve, então todo PDF diz “Skia/PDF m120” ou “wkhtmltopdf” — veja o post sobre white-label para entender por que isso importa em B2B.
  • ❌ Colocar o mesmo valor nos dois. Aceitável, mas desperdício — os dois campos existem justamente para que um visualizador possa distinguir “app de origem” de “motor de render”. Use-os.

Regra prática: creator é o nome da sua aplicação com versão (por exemplo, "Acme Billing Platform v7.2"); producer é a marca ou nome de plataforma da sua aplicação sem versão (por exemplo, "Acme Billing Platform"). Ambos deveriam ser valores que o destinatário reconheceria.

Campos vazios, padrões por token, surpresas downstream

Três detalhes de implementação que vale a pena conhecer antes de subir:

  1. Strings vazias ou só com espaços em branco são tratadas como não fornecidas. Enviar "title": "" é o mesmo que omitir title — não escreve uma string vazia no PDF, percorre a cadeia de fallback (padrão do token → padrão do sistema). Essa é a causa do relato de bug “eu defini, não pegou” mais comum.
  2. Políticas de token podem remover ou definir padrões para campos de metadados. Um SaaS multi-tenant usando o gPdf pode definir um default_metadata em cada token de API, de forma que todo PDF gerado por esse token leve o author e o producer do cliente sem ter que confiar que todo desenvolvedor vai defini-los em cada requisição. O padrão em nível de token é a camada certa de aplicação para “todo PDF da Acme deve dizer Acme”.
  3. Pipelines downstream podem reescrever os seus metadados. Ferramentas que pós-processam PDFs depois que o gPdf os devolve — Ghostscript sem flags explícitas de preservação de metadados, algumas ferramentas corporativas de DRM, alguns “otimizadores de PDF” — podem sobrescrever Producer com o próprio nome e desfazer a marca que você acabou de definir. Verifique contra o seu pipeline real de produção, não apenas contra a resposta crua do gPdf.

Verifique os seus metadados

Depois de implementar as mudanças acima, três formas rápidas de checar se o PDF realmente entregou o que você queria:

Linha de comando (macOS / Linux, exige 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: Arquivo → Propriedades → aba Descrição. Os seis campos aparecem, com Title mostrado na barra de título do visualizador no topo.

Preview do macOS: ⌘+I (Obter Informações). O painel inspetor “PDF” mostra os mesmos campos.

Se algum campo aparecer vazio, em branco, ou com um nome de ferramenta que você não definiu, volte ao corpo da requisição — a causa mais comum é enviar "" (string vazia), que a API trata como “não fornecido” e percorre a cadeia de fallback até um valor padrão. A segunda causa mais comum é um pipeline downstream (Ghostscript, DRM, otimizador) sobrescrevendo o campo depois que o gPdf devolveu; teste contra a produção, não apenas contra a resposta crua de render.

Metadados no arquivamento PDF/A

Se você está renderizando para arquivamento de longo prazo com settings.profile: "pdfa-2b" (ou -2a, -3a, -3b), os metadados deixam de ser opcionais e se tornam de carga:

  • O campo producer não pode ser vazio em um arquivo PDF/A conforme — no mínimo o padrão do sistema é entregue.
  • language é obrigatório para os perfis de acessibilidade (PDF/A-2a, PDF/A-3a). Sem ele, a validação do veraPDF falha sem rodeios.
  • O stream de metadados XMP que o PDF/A exige é gerado automaticamente a partir dos seis campos acima; você não precisa construí-lo manualmente.
  • title, author, subject, creator, producer e language todos viajam para o stream XMP, então o indexador de metadados de um arquivo downstream (Preservica, Archivematica) pode construir o seu catálogo a partir deles sem reparsear o corpo do documento.

Para um documento de arquivo, metadados com marca não são só polimento — fazem parte da durabilidade do artefato. O escritório aduaneiro alemão, a Receita brasileira, ou qualquer arquivo de longo prazo que abra o seu PDF daqui a dez anos verá o que estava nesses campos no dia em que você o renderizou. Definir esses campos deliberadamente no momento do render é a única chance que você tem.

O que o gPdf não expõe (ainda)

Para sermos honestos sobre a superfície atual: a especificação PDF também define Keywords (termos de busca em texto livre) e um stream de metadados XMP que suporta pares chave-valor customizados arbitrários. O gPdf não expõe nenhum dos dois na API atual.

Se você precisa guardar dados de negócio arbitrários dentro do PDF (UUID de pedido, código de depósito, versão de template), os contornos hoje são:

  • Definir subject como uma string curta estruturada que sistemas downstream parseiam.
  • Manter os dados de negócio no seu próprio banco, indexados por nome de arquivo ou hash de conteúdo.
  • Esperar — campos customizados XMP estão no roadmap e, quando chegarem, serão a resposta certa para contexto de fluxo oculto e legível por máquina.

Confundir “metadados com marca” (os seis campos padrão, disponíveis agora) com “metadados de negócio customizados” (campos customizados XMP, futuros) é a forma mais fácil de prometer demais sobre o que é possível hoje. Vale a pena mantê-los separados no seu próprio planejamento.

Um exemplo completo

Uma plataforma SaaS de faturamento (Acme Billing Platform) gerando uma fatura para um cliente alemão (Müller Versand GmbH), pronta para ser arquivada 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 contra o 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

Title em alemão, author como Müller Versand (a entidade GmbH do cliente, destinatária do documento), creator como Acme Billing Platform (o sistema editorial que decidiu o que colocar na página), producer como a marca da Acme Billing Platform, idioma etiquetado corretamente para o leitor de tela alemão e para o indexador full-text alemão que mais tarde pegará isso no DMS da Müller. O perfil PDF/A-3b significa que esse conjunto de metadados também é serializado no stream XMP para arquivamento de longo prazo.

Nada nas propriedades do arquivo nomeia gPdf, Chromium, ou qualquer ferramenta que o cliente não escolheu. O que é exatamente o ponto.

A menor melhoria possível

Se você já faz POST em /api/v1/pdf/render e a sua chamada atual não tem settings.metadata, a menor melhoria são três linhas adicionadas ao JSON que você já envia:

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

Dois campos, uma nova chave. Verificável com pdfinfo em segundos. Depois que isso entrar, preencha title, language, subject e creator quando tiver tempo.

Onde isso aparece