gPdf
Blog

PDF metadata alanları, açıklandı: title, language, author, subject, creator, producer

gPdf'in yüzeyleştirdiği altı standart PDF metadata alanı — title, language, author, subject, creator, producer. Her birinin ne için olduğu, kimin okuduğu, sık yapılan hatalar ve çıktıyı nasıl doğrulayacağınız.

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

PDF özelliklerinde başkasının aracı değil, sizin markanız görünmeli yazısının tamamlayıcısı — o yazı PDF metadata’ya neden önem vermeniz gerektiğinin gerekçesiydi. Bu, kullanım kılavuzu: her alanın PDF spesifikasyonunda ne için olduğu, kimin okuduğu, sık yapılan hatalar ve çıktınızın gerçekten amaçladığınızı gönderdiğini nasıl doğrulayacağınız.

gPdf, PDF spec’inin doküman düzeyi metadata için tanımladığı altı standart alanı yüzeyleştirir. DocumentRequest JSON’unda settings.metadata altında yaşarlar. Her alan opsiyoneldir — birini ayarlamazsanız, gPdf token’ın default_metadata’sına (Enterprise policy feature) ya da sistem varsayılanına geri düşer.

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

Yazının geri kalanı alan başına bir bölümdür. Her bölüm aynı şekli izler: alan nedir, nerede yüzeyleşir, sık yapılan hatalar, kural. Sıra önce → sonra → … → son olarak ne doldurulacağıdır.

title — doküman nedir

PDF spec’i bunu “document title” olarak tanımlar.

Nerede yüzeyleşir:

  • PDF görüntüleyicilerindeki başlık çubuğu (Adobe Reader, Preview, Foxit, Chromium PDF viewer hepsi gösterir).
  • PDF inline olarak açıldığında tarayıcı sekmesi (Content-Disposition: inline).
  • Arama indeksleri — Spotlight, Outlook, SharePoint, Google Drive’ın tam metin indeksleyicisi hepsi title’ı okur ve ona yüksek ağırlık verir.

Sık yapılan hatalar:

  • ❌ Title’ı dosya adına eşitlemek. invoice-20260318.pdf dosya adıdır. Title bir insanın okuyacağı bir şey olmalı, mesela Invoice INV-2026-3401. Dosya adı ve title farklı meselelerdir; dosya adı dosya sistemleri içindir, title görüntüleyiciler ve arama içindir.
  • ❌ Title’ı boş bırakmak. Görüntüleyiciler dosya adına geri düşer. Sonuç otomatik üretilmiş ve makine tarafından çıkarılmış gibi okunur.
  • ❌ Title’a markayı eklemek. Acme Logistics — Invoice INV-2026-3401 başlık çubuğunu doldurur. Marka author’a aittir, title’a değil.

Kural: title render edilen sayfanın H1’iyle eşleşmeli. Fatura şablonunuzun üst satırı “Invoice INV-2026-3401” ise, title odur.

language — erişilebilirlik, arama ve uyum için

language bir BCP-47 dil etiketidir: en, de, zh-Hans, pt-BR, ar-SA. Her doküman için ayarlayın. Altı alan içinde en somut downstream sonuçlarına ve en küçük uygulama maliyetine sahiptir — bu yüzden aşağıya gömülmek yerine pozisyon 2’de yer alır.

Nerede yüzeyleşir:

  • Ekran okuyucular — JAWS, NVDA, VoiceOver doğru fonem setini seçmek için kullanır. İngilizce bir ekran okuyucu language: "de" bir PDF’i okurken Almanca kelimeleri doğru telaffuz eder; etiket olmadan prozodiyi yanlış yapar.
  • Arama motorları ve indeksleyiciler — hangi locale’ın stemming ve stopword listesinin uygulanacağını etkiler. language: "zh-Hans" bir fatura Çince segmentasyon ile indekslenir; eksik bir etiket genellikle İngilizceye varsayılır ve indeks kullanılamaz hale gelir.
  • PDF/A uyumu — PDF/A-2a ve PDF/A-3a (accessibility profiles) dil etiketini gerektirir. Onsuz veraPDF doğrulaması doğrudan başarısız olur.

Sık yapılan hatalar:

  • ❌ Ayarlanmamış bırakmak. “Alıcının locale’ına” varsayın, “platformun varsayılanına” değil. Çoğu sızdıran yığın alanı hiç yazmaz; sonuç yanlış telaffuz eden ekran okuyucular ve yanlış stem yapan arama indeksleri.
  • ❌ BCP-47 olmayan bir dize kullanmak, "english" veya "EN-US" gibi. PDF spec’i RFC 5646 etiketleri bekler: en, en-US, de, pt-BR.
  • ❌ Platformun varsayılanını sabit kodlamak (örn. dokümanın gerçek içerik dilinden bağımsız olarak her zaman "en"). "en" etiketli Portekizce bir fatura, etiketsiz bir dokümandan daha kötüdür — indeksleyiciyi aktif olarak yanıltır.

Kural: etiket gerçek içerik diliyle eşleşmeli. Brezilya’da Portekizce bir fatura alan bir müşteri için "language": "pt-BR" ayarlayın, "en" değil. Çok dilli dokümanlar için baskın dili seçin ve geri kalanı için tek tek içerik elementleri üzerinde Lang özniteliğini kullanın — bu, doküman düzeyi language alanının ötesinde bir tagged-PDF accessibility özelliğidir.

author — doküman kime ait

PDF spec’inde author “the name of the person or organisation that created the document“dur. Alıcılara gönderilen iş PDF’leri için cevap neredeyse her zaman organizasyondur — ama doğru biçim bağlama göre gerçekten değişir.

Nerede yüzeyleşir:

  • Her PDF görüntüleyicisindeki Özellikler diyaloğu, belirgin biçimde “Author” etiketli.
  • DMS / arşiv indeksleyicileri, genellikle filtre olarak kullanılır.
  • PDF/A XMP metadata stream’i, uzun vadeli arşivlere taşınır.

Sık yapılan hatalar:

  • ❌ "author": "[email protected]" — operatörün e-postasını her PDF’e yanlışlıkla sızdırır, her arama indeksine girer, uzun vadeli bir PII sorunu olur.
  • ❌ "author": "PDF Generator Service" — dahili araç adı; alıcıya hiçbir şey ifade etmez.
  • ❌ Boş — Preview ve çoğu görüntüleyici özellikler diyaloğunda kelimenin tam anlamıyla “(no author)” gösterir, bu “buna kimse sahip değil” olarak okunur.

İşe yarayan biçimler:

  • ✅ "author": "Acme Logistics, Inc." — düz organizasyon.
  • ✅ "author": "Acme Logistics — Billing" — organizasyon + departman, belirli bir masaya yönlendirilen dokümanlar için.
  • ✅ "author": "Bridge Capital Partners — Fund III" — atfın belirli bir varlığa olduğu finans/hukukta faydalı.
  • ✅ "author": "Maria López, RICS Surveyor" — bireyin editöryal atıf OLDUĞU tek yazarlı yayıncılık (raporlar, değerlendirmeler, hukuki görüşler) için.

Kural: author, alıcının dokümanı ilişkilendirmesi gereken varlıktır. Platformun adına PDF ürettiği müşteriler için multi-tenant bir SaaS’te, author müşterinin organizasyon adı olmalı, platformun adı değil. (Platformun adı creator’a aittir — aşağıya bakın.) Bireylerin marka olduğu danışmanlık / yayıncılık / hukuki bağlamlarda bireyler uygundur.

subject — bu nasıl bir doküman

subject, dokümanın-kısa-açıklamasıdır. Görüntüleyiciler bunu belirgin biçimde yüzeyleştirmez — çoğu kullanıcı, Özellikler diyaloğunu açmazsa asla görmez. Ama doküman yönetim sistemleri, arşiv sistemleri ve kurallara dayalı e-posta/dosya yönlendirmesi bunu kullanır.

Nerede yüzeyleşir:

  • Özellikler diyaloğu, ikincil konum.
  • DMS yönlendirme kuralları, arşiv kovalama mantığı.
  • XMP metadata stream’i (PDF/A).

Sık yapılan hatalar:

  • ❌ "subject": "Invoice for Acme on 2026-03-18 for $4,532.10" — bu bir doküman örneği açıklamasıdır, bir tür değil. title’a aittir.
  • ❌ Boş — downstream sistemler için bedava bir yönlendirme kancası kaybedersiniz.
  • ❌ Sınıfları tutarsız karıştırmak ("Invoice" vs "Invoice/2026-03" vs "Monthly invoice") — DMS filtreleri hareket eden bir hedef üzerinde kovalama yapamaz.

İşe yarayan biçimler:

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

Kural: doğru taneliklik doküman sınıfıdır, doküman örneği değil. Binlerce gelen PDF’i olan bir DMS, ona tutarlı bir kelime dağarcığı verirseniz subject’a göre yönlendirebilir. Platformunuz için sonlu bir sınıf seti seçin ve asla sapmayın — platformunuzun ürettiği her fatura tam olarak "subject": "Invoice" taşımalı.

creator vs producer — en sık karıştırılan çift

Çoğu ekibin PDF spec’ini okumayı bırakıp tahmin etmeye başladığı yer burasıdır. Spec kesindir; iki alan farklı şeyler ifade eder.

  • creator — kaynak içeriği üreten uygulama (dokümanın ne söylemesi gerektiğine karar veren upstream sistem).
  • producer — PDF byte’larını üreten uygulama (o içeriği bir PDF dosyasına dönüştüren render motoru).

gPdf gibi bir JSON-to-PDF API üzerinden faturalar üreten bir SaaS faturalandırma platformu için:

  • creator = sürümüyle birlikte SaaS faturalandırma platformu. Acme için $4,532.10’luk bir fatura olması gerektiğine karar veren o uygulama.
  • producer = renderer. Varsayılan olarak bu “gPdf“dir. Ama render katmanı, SaaS’in seçtiği altyapı olduğu için, SaaS producer’ı kendi platform adına meşru biçimde ayarlayabilir — gerçek anlamda, platformu PDF byte’larını gPdf’e altyapı olarak delege ederek üretti.
{
  "creator":  "Acme Billing Platform v7.2",
  "producer": "Acme Billing Platform"
}

Nerede yüzeyleşirler:

  • Özellikler diyaloğu, ikisi de etiketli.
  • pdfinfo çıktısı, yan yana.
  • PDF/A XMP stream’i (PDF/A’da her iki alanın da boş olmaması gerekir).

Sık yapılan hatalar:

  • ❌ creator bir Chromium / Mozilla user-agent dizesine ayarlanmış. Bir headless-browser PDF yığını User-Agent’ı otomatik olarak creator’a geçirdiğinde olur. Bu, kaynak-doğruluk sistemi değil, tarayıcı sürümüdür. Geçersiz kılın.
  • ❌ producer varsayılan renderer adı olarak bırakılmış. Çoğu ekip bunu hiç geçersiz kılmaz, bu yüzden her PDF “Skia/PDF m120” veya “wkhtmltopdf” der — B2B için bunun neden önemli olduğunu görmek için white-label yazısına bakın.
  • ❌ İkisine de aynı değeri koymak. Kabul edilebilir ama israf — iki alan tam olarak bir görüntüleyicinin “kaynak uygulama“yı “render motoru“ndan ayırt edebilmesi için var. Onları kullanın.

Kural: creator sürümlü uygulama adınızdır (örn. "Acme Billing Platform v7.2"); producer uygulamanızın sürümsüz markası veya platform adıdır (örn. "Acme Billing Platform"). Her ikisi de alıcının tanıyacağı değerler olmalı.

Boş alanlar, token başına varsayılanlar, downstream sürprizler

Göndermeden önce bilinmeye değer üç uygulama detayı:

  1. Boş veya yalnızca boşluk içeren dizeler sağlanmamış olarak ele alınır. "title": "" göndermek title’ı atlamakla aynıdır — PDF’e boş bir dize yazmaz, fallback zincirini izler (token varsayılanı → sistem varsayılanı). En yaygın “ayarladım, geçmedi” bug raporunun nedeni budur.
  2. Token politikaları metadata alanlarını çıkarabilir veya varsayılan değer atayabilir. gPdf kullanan multi-tenant bir SaaS, her API token’ında bir default_metadata ayarlayabilir, böylece o token’ın ürettiği her PDF, her geliştiricinin her istekte ayarlamasına güvenmeden müşterinin author ve producer’ını taşır. Token düzeyi varsayılan, “her Acme PDF’i Acme demeli” için doğru uygulama katmanıdır.
  3. Downstream pipeline’lar metadata’nızı yeniden yazabilir. gPdf onları döndürdükten sonra PDF’leri post-process eden araçlar — açık metadata-koruma flag’leri olmadan Ghostscript, bazı kurumsal DRM araçları, bazı “PDF optimizers” — Producer’ı kendi adıyla üzerine yazabilir ve az önce ayarladığınız markalamayı geri alabilir. Yalnızca ham gPdf yanıtına değil, gerçek production pipeline’ınıza karşı doğrulayın.

Metadata’nızı doğrulayın

Yukarıdaki değişiklikleri uyguladıktan sonra, PDF’in gerçekten amaçladığınızı gönderdiğini kontrol etmenin üç hızlı yolu:

Komut satırı (macOS / Linux, poppler-utils gerektirir):

$ 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 sekmesi. Altı alan da görünür, Title üstte görüntüleyicinin başlık çubuğunda gösterilir.

macOS Preview: ⌘+I (Get Info). “PDF” inspector paneli aynı alanları gösterir.

Herhangi bir alan boş, boş ya da ayarlamadığınız bir araç adıyla görünüyorsa, istek gövdesini geri yürüyün — en yaygın neden "" (boş dize) göndermektir, ki API bunu “sağlanmadı” olarak ele alır ve fallback zincirini bir varsayılan değere kadar izler. İkinci en yaygın neden bir downstream pipeline’ın (Ghostscript, DRM, optimizer) gPdf döndürdükten sonra alanı üzerine yazmasıdır; yalnızca ham render yanıtına değil, production’a karşı test edin.

PDF/A arşivlemede metadata

settings.profile: "pdfa-2b" (veya -2a, -3a, -3b) ile uzun vadeli arşivleme için render ediyorsanız, metadata opsiyonel olmaktan çıkıp yük taşıyıcı olur:

  • PDF/A uyumlu bir dosyada producer alanı boş olamaz — en azından sistem varsayılanı gönderilir.
  • language accessibility profiles (PDF/A-2a, PDF/A-3a) için gereklidir. Onsuz veraPDF doğrulaması doğrudan başarısız olur.
  • PDF/A’nın gerektirdiği XMP metadata stream’i yukarıdaki altı alandan otomatik olarak üretilir; kendiniz oluşturmanıza gerek yoktur.
  • title, author, subject, creator, producer ve language hepsi XMP stream’e geçer, böylece bir downstream arşivin metadata indeksleyicisi (Preservica, Archivematica) doküman gövdesini yeniden parse etmeden onlardan katalogunu oluşturabilir.

Bir arşiv dokümanı için, markalı metadata sadece marka cilası değildir — eserin dayanıklılığının bir parçasıdır. Alman gümrük dairesi, Brezilya vergi otoritesi veya on yıl sonra PDF’inizi açacak herhangi bir uzun vadeli arşiv, render ettiğiniz gün o alanlarda ne varsa onu görecek. Render zamanında bunları kasıtlı olarak ayarlamak, sahip olduğunuz tek şans.

gPdf’in (henüz) yüzeyleştirmedikleri

Bugünün yüzeyi hakkında dürüst kalmak için: PDF spec’i ayrıca Keywords’ı (serbest formda arama terimleri) ve isteğe bağlı özel anahtar-değer çiftlerini destekleyen bir XMP metadata stream’i de tanımlar. gPdf mevcut API’da bunların hiçbirini yüzeyleştirmez.

PDF’in içine isteğe bağlı iş verisi (sipariş UUID’si, depo kodu, şablon sürümü) yerleştirmeniz gerekiyorsa, bugün geçici çözümler:

  • subject’i downstream sistemlerin parse ettiği yapılandırılmış kısa bir dizeye ayarlayın.
  • İş verisini kendi veritabanınızda, dosya adı veya içerik hash’i ile anahtarlanmış olarak tutun.
  • Bekleyin — XMP custom fields roadmap’tedir ve geldiklerinde gizli, makine-okunabilir workflow bağlamı için doğru cevap olacak.

“Markalı metadata“yı (altı standart alan, şimdi mevcut) “özel iş metadata’sı” ile (XMP custom fields, gelecek) karıştırmak, bugün mümkün olanı fazla vaat etmenin en kolay yoludur. Kendi planlamanızda bunları ayrı tutmaya değer.

Eksiksiz bir örnek

Alman bir müşteri (Müller Versand GmbH) için fatura üreten bir SaaS faturalandırma platformu (Acme Billing Platform), PDF/A olarak arşivlenmeye hazır:

{
  "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"
    }
  }
}

Sonuçtaki PDF üzerinde pdfinfo:

$ 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 Almanca, author Müller Versand olarak (müşterinin GmbH varlığı, dokümanın alıcısı), creator Acme Billing Platform olarak (sayfaya ne konulacağına karar veren editöryal sistem), producer Acme Billing Platform’un markası olarak, language Alman ekran okuyucusu ve daha sonra Müller’in DMS’inde bunu alacak Alman tam metin indeksleyicisi için doğru etiketlenmiş. PDF/A-3b profili, bu metadata setinin uzun vadeli arşivleme için XMP stream’e de serileştirildiği anlamına gelir.

Dosya özelliklerinde hiçbir şey gPdf’i, Chromium’u veya müşterinin seçmediği herhangi bir aracı adlandırmaz. Mesele tam olarak budur.

Mümkün olan en küçük iyileştirme

Eğer zaten /api/v1/pdf/render’a POST atıyorsanız ve mevcut çağrınızda settings.metadata yoksa, en küçük iyileştirme zaten gönderdiğiniz JSON’a eklenmiş üç satırdır:

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

İki alan, bir yeni anahtar. Saniyeler içinde pdfinfo ile doğrulanabilir. Bunlar yerleştikten sonra, zamanınız olduğunda title, language, subject ve creator’ı doldurun.

Bu nerede yer alır