gPdf
Blog

PDF metadata fields, dijelaskan: title, language, author, subject, creator, producer

Walkthrough enam standard PDF metadata field yang gPdf expose — title, language, author, subject, creator, producer. Untuk apa masing-masing, siapa membaca, common mistakes, dan cara verify apa yang Anda kirim.

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

Pendamping dari PDF properties harus menampilkan brand Anda, bukan tool orang lain — post itu membuat case mengapa peduli pada PDF metadata. Ini adalah operating manual: untuk apa setiap field dalam PDF specification, siapa membaca, common mistakes, dan cara verify bahwa output Anda benar-benar mengirim apa yang Anda maksudkan.

gPdf expose enam standard field yang didefinisikan PDF spec untuk document-level metadata. Mereka tinggal di bawah settings.metadata dalam DocumentRequest JSON. Setiap field bersifat optional — jika Anda tidak men-set satu, gPdf akan fall back ke default_metadata token (Enterprise policy feature) atau sebuah system default.

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

Sisa post ini adalah satu section per field. Setiap section mengikuti shape yang sama: field itu apa, muncul di mana, common mistakes, rule of thumb. Urutannya adalah apa yang harus diisi pertama → kedua → … → terakhir.

title — dokumen itu apa

PDF spec menggambarkannya sebagai “document title.”

Muncul di mana:

  • Title bar di PDF viewer (Adobe Reader, Preview, Foxit, Chromium PDF viewer semua menampilkannya).
  • Browser tab ketika PDF terbuka inline (Content-Disposition: inline).
  • Search indexes — Spotlight, Outlook, SharePoint, full-text indexer Google Drive semua membaca title dan memberinya bobot tinggi.

Common mistakes:

  • ❌ Men-set title sebagai filename. invoice-20260318.pdf adalah filename. Title seharusnya sesuatu yang dibaca manusia, seperti Invoice INV-2026-3401. Filename dan title adalah concern yang berbeda; filename untuk filesystem, title untuk viewer dan search.
  • ❌ Membiarkan title kosong. Viewer fall back ke filename. Hasilnya terbaca sebagai auto-generated dan machine-emitted.
  • ❌ Menambahkan brand ke title. Acme Logistics — Invoice INV-2026-3401 mengacaukan title bar. Brand termasuk di author, bukan title.

Rule of thumb: title harus cocok dengan H1 halaman yang di-render. Jika top line template invoice Anda adalah “Invoice INV-2026-3401,” itulah title-nya.

language — untuk accessibility, search dan compliance

language adalah BCP-47 language tag: en, de, zh-Hans, pt-BR, ar-SA. Set untuk setiap dokumen. Dari enam field, ia memiliki downstream consequences paling konkret dan implementation cost terkecil — itulah mengapa ia duduk di posisi 2 daripada terkubur lebih bawah.

Muncul di mana:

  • Screen reader — JAWS, NVDA, VoiceOver menggunakannya untuk memilih phoneme set yang benar. Screen reader English yang membaca PDF language: "de" akan mengucapkan kata Jerman dengan benar; tanpa tag ia salah prosody.
  • Search engine dan indexer — mempengaruhi locale stemming dan stopword list mana yang berlaku. Invoice language: "zh-Hans" di-index dengan Chinese segmentation; tag yang hilang sering default ke English dan index menjadi tidak dapat digunakan.
  • PDF/A compliance — PDF/A-2a dan PDF/A-3a (accessibility profiles) membutuhkan language tag. Tanpa itu, veraPDF validation fail.

Common mistakes:

  • ❌ Membiarkan unset. Default ke “locale penerima,” bukan “default platform.” Kebanyakan leaky stack hanya tidak menulis field; hasilnya adalah screen reader yang salah mengucapkan dan search index yang salah stem.
  • ❌ Menggunakan string non-BCP-47 seperti "english" atau "EN-US". PDF spec mengharapkan RFC 5646 tags: en, en-US, de, pt-BR.
  • ❌ Hard-coding default platform (misalnya selalu "en") tanpa memperhatikan bahasa content aktual dokumen. Invoice Portugis yang di-tag "en" lebih buruk dari dokumen tanpa tag — ia secara aktif menyesatkan indexer.

Rule of thumb: tag harus cocok dengan bahasa content aktual. Untuk customer di Brazil yang menerima invoice dalam Portugis, set "language": "pt-BR", bukan "en". Untuk dokumen multibahasa, pilih bahasa dominan dan gunakan atribut Lang pada content element individu untuk sisanya — itu adalah fitur accessibility tagged-PDF di luar field language tingkat dokumen.

author — siapa pemilik dokumen

Dalam PDF spec, author adalah “the name of the person or organisation that created the document.” Untuk PDF bisnis yang dikirim ke penerima, jawabannya hampir selalu adalah organisation — tetapi shape yang benar benar-benar bervariasi menurut context.

Muncul di mana:

  • Properties dialog di setiap PDF viewer, dengan label menonjol “Author.”
  • DMS / archive indexer, sering digunakan sebagai filter.
  • PDF/A XMP metadata stream, di mana ia dibawa ke long-term archive.

Common mistakes:

  • ❌ "author": "[email protected]" — secara tidak sengaja membocorkan email operator ke setiap PDF, berakhir di setiap search index, menjadi long-term PII issue.
  • ❌ "author": "PDF Generator Service" — nama internal tool; tidak berarti apa-apa bagi penerima.
  • ❌ Kosong — Preview dan kebanyakan viewer secara harfiah menampilkan “(no author)” di dialog properties, yang terbaca sebagai “tidak ada yang memiliki ini.”

Shape yang bekerja:

  • ✅ "author": "Acme Logistics, Inc." — organisation langsung.
  • ✅ "author": "Acme Logistics — Billing" — organisation + departemen, untuk dokumen yang di-route ke desk tertentu.
  • ✅ "author": "Bridge Capital Partners — Fund III" — berguna di finance/legal di mana atribusi ke entity tertentu.
  • ✅ "author": "Maria López, RICS Surveyor" — untuk single-author publishing (laporan, valuasi, opini hukum) di mana individu ADALAH atribusi editorial.

Rule of thumb: author adalah entity yang harus penerima asosiasikan dengan dokumen. Dalam multi-tenant SaaS di mana platform men-generate PDF atas nama customer, author harus nama organisation customer, bukan nama platform. (Nama platform termasuk di creator — lihat di bawah.) Untuk konteks consultancy / publishing / legal di mana individu adalah brand, individu OK.

subject — ini jenis dokumen apa

subject adalah deskripsi-singkat-dokumen. Viewer tidak surface secara menonjol — kebanyakan user tidak akan pernah melihatnya kecuali mereka membuka Properties dialog. Tetapi document management systems, archive systems, dan rules-based email/file routing menggunakannya.

Muncul di mana:

  • Properties dialog, posisi sekunder.
  • DMS routing rules, archive bucketing logic.
  • XMP metadata stream (PDF/A).

Common mistakes:

  • ❌ "subject": "Invoice for Acme on 2026-03-18 for $4,532.10" — itu adalah deskripsi instance dokumen, bukan tipe. Itu termasuk di title.
  • ❌ Kosong — menghilangkan free routing hook untuk downstream systems.
  • ❌ Mencampur class secara tidak konsisten ("Invoice" vs "Invoice/2026-03" vs "Monthly invoice") — DMS filter tidak dapat bucket pada target yang bergerak.

Shape yang bekerja:

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

Rule of thumb: granularity yang benar adalah document class, bukan document instance. DMS dengan ribuan PDF masuk dapat me-route berdasarkan subject jika Anda memberinya vocabulary yang konsisten. Pilih set class hingga untuk platform Anda dan jangan pernah menyimpang — setiap invoice yang di-generate platform Anda harus memiliki tepat "subject": "Invoice".

creator vs producer — pasangan yang paling sering tertukar

Inilah tempat kebanyakan tim berhenti membaca PDF spec dan menebak. Spec itu tepat; dua field berarti hal yang berbeda.

  • creator — application yang memproduksi source content (sistem upstream yang memutuskan apa yang harus dikatakan dokumen).
  • producer — application yang memproduksi PDF bytes (rendering engine yang mengubah content tersebut menjadi PDF file).

Untuk SaaS billing platform yang men-generate invoice melalui JSON-to-PDF API seperti gPdf:

  • creator = SaaS billing platform dengan versinya. Itu adalah application yang memutuskan ini harus menjadi invoice untuk Acme sebesar $4,532.10.
  • producer = renderer. Secara default itu adalah “gPdf.” Tetapi karena rendering layer adalah infrastructure yang dipilih SaaS, SaaS dapat secara sah men-set producer ke nama platform-nya sendiri — platform-nya, dalam arti nyata, memproduksi PDF bytes dengan men-delegate ke gPdf sebagai infrastructure.
{
  "creator":  "Acme Billing Platform v7.2",
  "producer": "Acme Billing Platform"
}

Muncul di mana:

  • Properties dialog, keduanya berlabel.
  • pdfinfo output, berdampingan.
  • PDF/A XMP stream (kedua field diperlukan non-empty dalam PDF/A).

Common mistakes:

  • ❌ creator di-set ke string user-agent Chromium / Mozilla. Terjadi ketika headless-browser PDF stack mem-pass User-Agent ke creator secara otomatis. Itu adalah versi browser, bukan sistem source-of-truth. Override.
  • ❌ producer dibiarkan sebagai nama renderer default. Kebanyakan tim tidak pernah meng-override ini, sehingga setiap PDF mengatakan “Skia/PDF m120” atau “wkhtmltopdf” — lihat white-label post untuk alasan mengapa ini penting untuk B2B.
  • ❌ Meletakkan value yang sama di keduanya. Dapat diterima tetapi sia-sia — kedua field ada justru agar viewer dapat membedakan “source app” dari “render engine.” Gunakan keduanya.

Rule of thumb: creator adalah nama application Anda dengan versi (misalnya "Acme Billing Platform v7.2"); producer adalah brand atau nama platform application Anda tanpa versi (misalnya "Acme Billing Platform"). Keduanya harus value yang penerima recognise.

Empty fields, per-token defaults, downstream surprises

Tiga detail implementation yang layak diketahui sebelum ship:

  1. String empty atau hanya whitespace di-treat sebagai not provided. Mengirim "title": "" sama dengan omit title — itu tidak menulis empty string ke PDF, itu walk fallback chain (token default → system default). Ini adalah penyebab bug report paling umum “saya set, tidak diambil.”
  2. Token policies dapat strip atau default metadata fields. Multi-tenant SaaS yang menggunakan gPdf dapat men-set default_metadata pada setiap API token sehingga setiap PDF yang di-generate token tersebut membawa author dan producer customer tanpa harus mempercayai setiap developer untuk men-set mereka pada setiap request. Token-level default adalah enforcement layer yang tepat untuk “setiap Acme PDF harus mengatakan Acme.”
  3. Downstream pipelines dapat menulis ulang metadata Anda. Tool yang post-process PDF setelah gPdf mengembalikannya — Ghostscript tanpa explicit metadata-preservation flag, beberapa enterprise DRM tool, beberapa “PDF optimiser” — dapat menimpa Producer dengan nama mereka sendiri dan membatalkan branding yang baru Anda set. Verify terhadap production pipeline aktual Anda, bukan hanya raw gPdf response.

Verify metadata Anda

Setelah Anda implement perubahan di atas, tiga cara cepat untuk memeriksa bahwa PDF benar-benar mengirim apa yang Anda maksudkan:

Command line (macOS / Linux, membutuhkan 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: File → Properties → Description tab. Keenam field muncul, dengan Title ditampilkan di title bar viewer di atas.

macOS Preview: ⌘+I (Get Info). Pane inspector “PDF” menampilkan field yang sama.

Jika ada field yang muncul kosong, blank, atau dengan nama tool yang tidak Anda set, walk kembali melalui request body — penyebab paling umum adalah mengirim "" (empty string), yang di-treat API sebagai “not provided” dan walk fallback chain ke value default. Penyebab paling umum kedua adalah downstream pipeline (Ghostscript, DRM, optimiser) yang menimpa field setelah gPdf mengembalikannya; test terhadap production, bukan hanya raw render response.

Metadata dalam PDF/A archival

Jika Anda me-render untuk long-term archival dengan settings.profile: "pdfa-2b" (atau -2a, -3a, -3b), metadata berhenti menjadi optional dan menjadi load-bearing:

  • Field producer tidak boleh kosong dalam PDF/A-conformant file — minimal system default akan dikirim.
  • language diperlukan untuk accessibility profiles (PDF/A-2a, PDF/A-3a). Tanpa itu, veraPDF validation fail langsung.
  • XMP metadata stream yang PDF/A butuhkan di-generate secara otomatis dari keenam field di atas; Anda tidak perlu mengonstruksinya sendiri.
  • title, author, subject, creator, producer dan language semua naik ke XMP stream, sehingga metadata indexer downstream archive (Preservica, Archivematica) dapat membangun catalog-nya dari mereka tanpa harus mem-parse ulang document body.

Untuk dokumen archival, branded metadata bukan hanya polish brand — itu bagian dari durabilitas artefak. Kantor pabean Jerman, otoritas pajak Brazil, atau long-term archive apa pun yang membuka PDF Anda dalam sepuluh tahun akan melihat apa pun yang ada di field tersebut pada hari Anda me-render. Men-set mereka secara deliberate pada render time adalah satu-satunya kesempatan yang Anda dapatkan.

Apa yang belum gPdf expose

Untuk tetap jujur tentang surface hari ini: PDF spec juga mendefinisikan Keywords (search term bentuk bebas) dan XMP metadata stream yang mendukung arbitrary custom key-value pairs. gPdf tidak expose salah satu dari ini di API saat ini.

Jika Anda perlu menyimpan arbitrary business data di dalam PDF (order UUID, warehouse code, template version), workaround hari ini:

  • Set subject ke string pendek terstruktur yang di-parse downstream systems.
  • Simpan business data di database Anda sendiri, di-key dengan filename atau content hash.
  • Tunggu — XMP custom fields ada di roadmap, dan ketika ship akan menjadi jawaban yang tepat untuk hidden machine-readable workflow context.

Mencampur “branded metadata” (enam standard field, available sekarang) dengan “custom business metadata” (XMP custom fields, masa depan) adalah cara termudah untuk over-promise apa yang mungkin hari ini. Layak menjaga keduanya tetap terpisah di planning Anda sendiri.

Contoh lengkap

SaaS billing platform (Acme Billing Platform) men-generate invoice untuk customer Jerman (Müller Versand GmbH), siap di-archive sebagai 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 terhadap PDF yang dihasilkan:

$ 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 dalam Jerman, author sebagai Müller Versand (entity GmbH customer, penerima dokumen), creator sebagai Acme Billing Platform (sistem editorial yang memutuskan apa yang ditaruh di halaman), producer sebagai brand Acme Billing Platform, language di-tag dengan benar untuk German screen reader dan untuk German full-text indexer yang nantinya akan mengambil ini di DMS Müller. Profile PDF/A-3b berarti set metadata ini juga di-serialise ke XMP stream untuk long-term archival.

Tidak ada di file properties yang menamai gPdf, Chromium, atau tool apa pun yang tidak dipilih customer. Itulah tepatnya point-nya.

Upgrade terkecil yang mungkin

Jika Anda sudah POST ke /api/v1/pdf/render dan call Anda saat ini tidak memiliki settings.metadata, perbaikan terkecil adalah tiga baris yang ditambahkan ke JSON yang sudah Anda kirim:

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

Dua field, satu key baru. Dapat di-verify dengan pdfinfo dalam hitungan detik. Setelah ini landed, isi title, language, subject dan creator saat Anda ada waktu.

Di mana ini terletak