gPdf
المدونة

شرح حقول البيانات الوصفية لـ PDF: title وlanguage وauthor وsubject وcreator وproducer

شرح حقلًا حقلًا للحقول القياسية الستّة للبيانات الوصفية في PDF التي تكشفها gPdf —— title وlanguage وauthor وsubject وcreator وproducer. وظيفة كلٍّ منها، ومَن يقرؤها، والأخطاء الشائعة، وكيف تتحقق ممّا شحنته.

gPdf Engineering
#بيانات-pdf-الوصفية#مواصفة-pdf#مرجع-تقني

هذا الجزء المُكمِّل لـ خصائص ملف PDF يجب أن تُظهر علامتك التجارية، لا أداة شخصٍ آخر —— ذلك المقال طرح أسباب الاهتمام بالبيانات الوصفية للـ PDF. هذا المقال هو دليل التشغيل: ماذا يُمثّل كل حقل في مواصفة PDF، ومَن يقرؤه، والأخطاء الشائعة، وكيف تتحقق من أن مخرجك يحتوي حقًا ما قصدت شحنه.

تكشف gPdf الحقول القياسية الستة التي تُعرّفها مواصفة PDF للبيانات الوصفية على مستوى المستند. وتقع تحت settings.metadata في JSON الخاص بـ DocumentRequest. كل حقل اختياري —— إن لم تضبطه، تعود gPdf إلى default_metadata الخاص بالرمز (ميزة سياسات Enterprise) أو إلى الافتراض النظامي.

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

بقية المقال قِسم واحد لكل حقل. كل قِسم يتبع البنية نفسها: ما الحقل، أين يظهر، الأخطاء الشائعة، قاعدة عملية. الترتيب يعكس ما يجب أن تملأه أولًا → ثانيًا → … → آخرًا.

title —— ما هو المستند

تصف مواصفة PDF هذا الحقل بأنه “عنوان المستند”.

أين يظهر:

  • شريط العنوان في قارئات PDF (Adobe Reader وPreview وFoxit وقارئ Chromium جميعها تُظهره).
  • علامة تبويب المتصفح حين يُفتح PDF بطريقة مدمجة (Content-Disposition: inline).
  • فهارس البحث —— Spotlight وOutlook وSharePoint ومُفهرس النص الكامل في Google Drive جميعها تقرأ title وتُعطيه وزنًا كبيرًا.

الأخطاء الشائعة:

  • ❌ ضبط title باسم الملف. invoice-20260318.pdf هو اسم الملف. أما العنوان فينبغي أن يكون شيئًا يقرؤه الإنسان، مثل Invoice INV-2026-3401. اسم الملف والعنوان غرضان مختلفان: اسم الملف لأنظمة الملفات، والعنوان للقارئات والبحث.
  • ❌ ترك title فارغًا. تعود القارئات إلى اسم الملف، فيُقرأ المخرج كأنه مُولَّد آليًا.
  • ❌ حشر العلامة في title. Acme Logistics — Invoice INV-2026-3401 يُربك شريط العنوان. العلامة موضعها author، لا title.

قاعدة عملية: يجب أن يطابق title الـ H1 في الصفحة المُصيَّرة. إذا كان السطر الأعلى من قالب الفاتورة “Invoice INV-2026-3401”، فهذا هو title.

language —— لإمكانية الوصول والبحث والامتثال

language هو وسم لغة بصيغة BCP-47: en، de، zh-Hans، pt-BR، ar-SA. اضبطه لكل مستند. من بين الحقول الستة هو الذي له أكثر العواقب اللاحقة ملموسية وأقلها تكلفة تنفيذ —— لذلك يقع في الموضع الثاني لا في القاع.

أين يظهر:

  • قارئات الشاشة —— JAWS وNVDA وVoiceOver تستخدمه لاختيار مجموعة الصوتيات المناسبة. قارئ شاشة إنجليزي يقرأ ملف PDF فيه language: "de" سينطق الكلمات الألمانية صحيحًا؛ من دون الوسم يُحرَّف الإيقاع الصوتي.
  • محركات البحث والمُفهرسات —— تُحدّد قواعد التجذير وقائمة كلمات التوقف لأي لغة تنطبق. فاتورة فيها language: "zh-Hans" تُفهرس بتقطيع صيني؛ غياب الوسم يُحال غالبًا إلى الإنجليزية افتراضيًا فيصبح الفهرس عديم الفائدة.
  • امتثال PDF/A —— يتطلب ملفان شخصيان PDF/A-2a و PDF/A-3a (الإمكانية على الوصول) وسم اللغة. بدونه يفشل تحقق veraPDF صراحةً.

الأخطاء الشائعة:

  • ❌ عدم ضبطه. الافتراض ينبغي أن يكون “لغة المستلم”، لا “الافتراض على مستوى المنصة”. أكثر المكدّسات المُسرِّبة لا تكتب الحقل أصلًا؛ النتيجة قارئات شاشة تُخطئ النطق ومُفهرسات بحث تُخطئ التجذير.
  • ❌ استخدام سلسلة ليست BCP-47 مثل "english" أو "EN-US". مواصفة PDF تتوقع وسوم RFC 5646: en، en-US، de، pt-BR.
  • ❌ ترميز الافتراض على مستوى المنصة بشكل ثابت (مثلًا "en" دائمًا) بصرف النظر عن لغة المحتوى الفعلية. فاتورة برتغالية موسومة "en" أسوأ من مستند غير موسوم —— فهي تُضلّل المُفهرس بنشاط.

قاعدة عملية: يجب أن يطابق الوسم لغة المحتوى الفعلية. لعميل في البرازيل يستلم فاتورة بالبرتغالية، اضبط "language": "pt-BR"، لا "en". للمستندات متعددة اللغات، اختر اللغة السائدة واستخدم سمة Lang على عناصر المحتوى المُفردة للبقية —— هذه ميزة إمكانية وصول في PDF الموسوم تتجاوز حقل language على مستوى المستند.

author —— مَن يملك المستند

في مواصفة PDF، author هو “اسم الشخص أو المنظمة التي أنشأت المستند”. في مستندات الأعمال التي تُشحَن إلى مستلمين، تكون الإجابة دائمًا تقريبًا المنظمة —— لكن الشكل الصحيح يتباين فعلًا بحسب السياق.

أين يظهر:

  • مربع الخصائص في كل قارئ PDF، مع وسم بارز “Author”.
  • مُفهرسات DMS / الأرشيف، تُستخدم كثيرًا كمرشِّح.
  • تيار بيانات XMP في PDF/A، حيث يُنقَل إلى الأرشيف طويل الأمد.

الأخطاء الشائعة:

  • ❌ "author": "[email protected]" —— يُسرّب عرضًا بريد المُشغِّل إلى كل ملف PDF، وينتهي في كل فهرس بحث، فيتحوّل إلى مشكلة PII طويلة الأمد.
  • ❌ "author": "PDF Generator Service" —— اسم أداة داخلية؛ لا يعني شيئًا للمستلم.
  • ❌ فارغ —— يُظهر Preview ومعظم القارئات حرفيًا “(no author)” في مربع الخصائص، ويُقرأ ذلك كأن “لا أحد يملك هذا المستند”.

أشكال صالحة:

  • ✅ "author": "Acme Logistics, Inc." —— منظمة مباشرة.
  • ✅ "author": "Acme Logistics — Billing" —— منظمة + قسم، للمستندات التي تُحوَّل إلى مكتبٍ بعينه.
  • ✅ "author": "Bridge Capital Partners — Fund III" —— مفيد في المالية / القانون حيث يكون الإسناد إلى كيان محدد.
  • ✅ "author": "Maria López, RICS Surveyor" —— لنشر بمؤلف منفرد (تقارير، تقييمات، آراء قانونية) حيث الشخص نفسه هو الإسناد التحريري.

قاعدة عملية: author هو الكيان الذي ينبغي أن يربط المستلم المستند به. في SaaS متعدد المستأجرين حيث تُنتج المنصة ملفات PDF نيابةً عن العملاء، يجب أن يكون author اسم منظمة العميل، لا اسم المنصة. (اسم المنصة موضعه creator —— انظر أدناه.) لسياقات الاستشارة / النشر / القانون حيث الأفراد هم العلامة، لا بأس بإدراج الأفراد.

subject —— أي نوع من المستندات هذا

subject هو وصف قصير للمستند. لا تُبرزه القارئات —— لن يراه معظم المستخدمين إلا إذا فتحوا مربع الخصائص. لكن أنظمة إدارة المستندات وأنظمة الأرشفة وقواعد توجيه البريد / الملفات تستخدمه.

أين يظهر:

  • مربع الخصائص، في موقع ثانوي.
  • قواعد توجيه DMS، ومنطق تجميع الأرشيف.
  • تيار بيانات XMP (PDF/A).

الأخطاء الشائعة:

  • ❌ "subject": "Invoice for Acme on 2026-03-18 for $4,532.10" —— هذا وصف لنسخة مستند، لا لنوع. موضعه title.
  • ❌ فارغ —— يُهدر خطّاف توجيه مجاني لأنظمة المراحل اللاحقة.
  • ❌ خلط الفئات بشكل غير متّسق ("Invoice" مقابل "Invoice/2026-03" مقابل "Monthly invoice") —— مرشِّحات DMS لا يمكنها التجميع على هدف متحرّك.

أشكال صالحة:

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

قاعدة عملية: التحبيب الصحيح هو فئة المستند، لا نسخة المستند. DMS يستقبل آلاف ملفات PDF يوميًا يمكنه التوجيه بناءً على subject إن أعطيته مفردات ثابتة. اختر لمنصّتك مجموعة محدودة من الفئات ولا تحِد عنها —— كل فاتورة تُنتجها منصتك يجب أن تحمل "subject": "Invoice" بالضبط.

creator مقابل producer —— الزوج الأكثر التباسًا

هنا تتوقف معظم الفرق عن قراءة مواصفة PDF وتشرع في التخمين. المواصفة دقيقة؛ الحقلان يعنيان أمرين مختلفين.

  • creator —— التطبيق الذي أنتج المحتوى المصدري (النظام الأعلى الذي قرّر ماذا يقول المستند).
  • producer —— التطبيق الذي أنتج بايتات PDF (محرّك التصيير الذي حوّل المحتوى إلى ملف PDF).

لمنصة فوترة SaaS تُنتج فواتير عبر API من نوع JSON-to-PDF مثل gPdf:

  • creator = منصة الفوترة SaaS مع رقم إصدارها. هي التي قرّرت أن هذا ينبغي أن يكون فاتورة لـ Acme بقيمة 4,532.10 دولار.
  • producer = المُصيّر. افتراضًا هو “gPdf”. لكن لأن طبقة التصيير بنية تحتية اختارها SaaS، يمكن لـ SaaS بشكل مشروع أن يضبط producer على اسم منصّته —— فبمعنى حقيقي، أنتجت منصته بايتات PDF بتفويض ذلك إلى gPdf كبنية تحتية.
{
  "creator":  "Acme Billing Platform v7.2",
  "producer": "Acme Billing Platform"
}

أين يظهران:

  • مربع الخصائص، كلاهما موسوم.
  • مخرج pdfinfo، جنبًا إلى جنب.
  • تيار XMP في PDF/A (يجب أن يكون كلا الحقلين غير فارغين في PDF/A).

الأخطاء الشائعة:

  • ❌ creator مضبوط على سلسلة User-Agent من Chromium / Mozilla. يحدث عندما يُمرّر مكدّس PDF القائم على متصفح headless الـ User-Agent تلقائيًا إلى creator. هذا إصدار المتصفح، لا نظام مصدر الحقيقة. تجاوزه.
  • ❌ producer متروك على اسم المُصيّر الافتراضي. معظم الفرق لا تتجاوزه أبدًا، فيقول كل ملف PDF “Skia/PDF m120” أو “wkhtmltopdf” —— انظر مقالة العلامة البيضاء لمعرفة لماذا يهمّ هذا لـ B2B.
  • ❌ وضع نفس القيمة في الحقلين. مقبول لكنه مهدور —— الحقلان موجودان تحديدًا ليستطيع القارئ التمييز بين “تطبيق المصدر” و“محرّك التصيير“. استخدمهما.

قاعدة عملية: creator هو اسم تطبيقك مع رقم الإصدار (مثلًا "Acme Billing Platform v7.2")؛ producer هو اسم العلامة أو المنصة بدون رقم إصدار (مثلًا "Acme Billing Platform"). كلتا القيمتين يجب أن يستطيع المستلم التعرف عليهما.

الحقول الفارغة، الافتراضات حسب الرمز، مفاجآت المراحل اللاحقة

ثلاث تفاصيل تنفيذ تستحق المعرفة قبل النشر:

  1. السلاسل الفارغة أو التي تحتوي مسافات بيضاء فقط تُعامَل كأنها غير مُقدَّمة. إرسال "title": "" يعادل حذف title —— لا يُكتب سلسلة فارغة في PDF، بل يسير السلوك بسلسلة الاحتياط (افتراض الرمز → افتراض النظام). هذا سبب أكثر بلاغات الأخطاء شيوعًا من نوع “ضبطته ولم يأخذ”.
  2. سياسات الرمز يمكن أن تجرّد حقول البيانات الوصفية أو تضبط لها افتراضات. SaaS متعدد المستأجرين يستخدم gPdf يمكنه ضبط default_metadata على كل رمز API بحيث يحمل كل ملف PDF يُنتجه ذلك الرمز قيمتي author وproducer للعميل دون الاعتماد على كل مطوّر بضبطهما في كل طلب. الطبقة الصحيحة لفرض “كل ملف PDF لـ Acme يجب أن يقول Acme” هي الافتراض على مستوى الرمز.
  3. خطوط الأنابيب اللاحقة قد تُعيد كتابة بياناتك الوصفية. أدوات تُجري معالجة لاحقة لملف PDF بعد رجوعه من gPdf —— Ghostscript دون أعلام صريحة لحفظ البيانات الوصفية، بعض أدوات DRM المؤسسية، بعض “محسّنات PDF” —— يمكنها استبدال Producer باسمها وإلغاء العلامة التي ضبطتها للتو. تحقق مقابل خط إنتاجك الفعلي، لا مجرد استجابة gPdf الخام.

تحقّق من بياناتك الوصفية

بعد تطبيق التغييرات أعلاه، إليك ثلاث طرق سريعة للتحقق من أن ملف PDF شحن فعلًا ما قصدت شحنه:

سطر الأوامر (macOS / Linux، يتطلب 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. تظهر الحقول الستة جميعها، ويظهر Title في شريط العنوان أعلى القارئ.

macOS Preview: ⌘+I (الحصول على معلومات). يُظهر جزء فاحص “PDF” الحقول نفسها.

إن ظهر أي حقل فارغًا أو خاليًا أو يحمل اسم أداة لم تضبطه، فعُد إلى جسم الطلب —— السبب الأكثر شيوعًا هو إرسال "" (سلسلة فارغة)، التي تعاملها الواجهة بوصفها “غير مُقدَّمة” فتسير في سلسلة الاحتياط إلى قيمة افتراضية. والسبب الثاني شيوعًا أن خط أنابيب لاحق (Ghostscript أو DRM أو مُحسِّن) أعاد كتابة الحقل بعد رجوع gPdf؛ اختبر مقابل الإنتاج، لا مجرد استجابة التصيير الخام.

البيانات الوصفية في أرشيف PDF/A

إذا كنت تُصيّر للحفظ طويل الأمد بـ settings.profile: "pdfa-2b" (أو -2a أو -3a أو -3b)، فالبيانات الوصفية تتوقف عن كونها اختيارية وتصبح حاملةً للوزن:

  • لا يمكن أن يكون حقل producer فارغًا في ملف متوافق مع PDF/A —— على الأقل يُكتب افتراض النظام.
  • language مطلوب للملفّات الشخصية المتعلقة بإمكانية الوصول (PDF/A-2a و PDF/A-3a). بدونه يفشل تحقق veraPDF صراحةً.
  • يُولَّد تيار بيانات XMP الذي يتطلبه PDF/A تلقائيًا من الحقول الستة أعلاه؛ لست بحاجة إلى بنائه بنفسك.
  • title وauthor وsubject وcreator وproducer وlanguage جميعها تدخل تيار XMP، لذا يستطيع مُفهرس البيانات الوصفية للأرشيف اللاحق (Preservica، Archivematica) بناء كتالوجه منها دون إعادة تحليل جسم المستند.

لمستند أرشيفي، البيانات الوصفية المُعلَّمة ليست مجرد لمسة علامة —— هي جزء من ديمومة القطعة. الجمارك الألمانية، أو هيئة الضرائب البرازيلية، أو أي أرشيف طويل الأمد يفتح ملف PDF خاصك بعد عشر سنوات سيرى ما كان في تلك الحقول يوم التصيير. ضبطها عمدًا وقت التصيير هو الفرصة الوحيدة المتاحة لك.

ما لا تكشفه gPdf (بعد)

توخيًا للصدق بشأن سطح اليوم: تُعرّف مواصفة PDF أيضًا Keywords (مصطلحات بحث حرّة) وتيار بيانات XMP يدعم أزواج مفتاح/قيمة مخصّصة اعتباطية. لا تكشف gPdf أيًا منهما في الواجهة الحالية.

إن احتجت إلى تخزين بيانات أعمال اعتباطية داخل PDF (UUID لطلب، رمز مستودع، إصدار قالب)، فالحلول الالتفافية اليوم هي:

  • ضبط subject على سلسلة قصيرة مهيكلة يستطيع نظام لاحق تحليلها.
  • الإبقاء على بيانات الأعمال في قاعدة بياناتك مُفهرسةً بحسب اسم الملف أو تجزئة المحتوى.
  • الانتظار —— حقول XMP المخصّصة في خارطة الطريق، وعندما تصل ستكون الإجابة الصحيحة لسياق سير العمل المخفي القابل للقراءة آليًا.

الخلط بين “البيانات الوصفية المُعلَّمة” (الحقول الستة القياسية المتاحة الآن) و“البيانات الوصفية المخصّصة للأعمال“ (حقول XMP المخصّصة المستقبلية) هو أسهل طريقة للوعد بأكثر ممّا هو ممكن اليوم. يستحق فصلهما في تخطيطك.

مثال كامل

منصة فوترة SaaS (Acme Billing Platform) تُنتج فاتورة لعميل ألماني (Müller Versand GmbH)، جاهزة للأرشفة بصيغة 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 على ملف PDF الناتج:

$ 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

العنوان بالألمانية، وauthor هو Müller Versand (كيان GmbH للعميل، المستلم للمستند)، وcreator هو Acme Billing Platform (النظام التحريري الذي قرّر ماذا يضع على الصفحة)، وproducer هو علامة Acme Billing Platform، وlanguage موسوم بشكل صحيح لقارئ الشاشة الألماني ولمُفهرس النص الكامل الألماني الذي سيلتقط هذا لاحقًا في DMS الخاص بـ Müller. ملف PDF/A-3b يعني أن مجموعة البيانات الوصفية هذه تُسلسَل أيضًا في تيار XMP للحفظ طويل الأمد.

لا شيء في خصائص الملف يذكر gPdf أو Chromium أو أي أداة لم يخترها العميل. وهذا تحديدًا هو المقصود.

أصغر ترقية ممكنة

إذا كنت تُرسل POST إلى /api/v1/pdf/render بالفعل، ولا يحتوي طلبك الحالي على settings.metadata، فإن أصغر تحسين هو إضافة ثلاثة أسطر إلى JSON الذي ترسله أصلًا:

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

حقلان، مفتاح جديد واحد. يمكن التحقق من ذلك بواسطة pdfinfo في ثوانٍ. بعد أن يهبط هذان الحقلان، يمكنك ملء title وlanguage وsubject وcreator حين يتوفر الوقت.

أين يقع هذا