يحدد الـ codebook كيف يركّب Codec الـ Payload. والـ codebook في GEUL ليس صيغة منفصلة، بل مستند GEUL. لكل Codec مستند مواصفة واحد.
موضع مستند المواصفة
تنشر GEUL Issuer (0x00000000) مستندات مواصفة الرموز المباشرة. مستند المواصفة هو مستند Codec وليس له معرّف مستند. ومعرّف Codec هو TAG WORD الخاصة بذلك Codec (خانتا القسم وC الخاصتان بـ Codec فقط، وLength تساوي 0) مكتوبةً في 32 بتاً.
/.well-known/geul/0x00000000/codecs/0x0000<TAG>/<معرّف الإصدار>.geul
| Codec | TAG | مستند المواصفة |
|---|---|---|
| Reference LOCAL | 0050 | 0x00000000/codecs/0x00000050 |
| Value QUANTITY | 0660 | 0x00000000/codecs/0x00000660 |
| Edge TRIPLE | 0AA0 | 0x00000000/codecs/0x00000AA0 |
| Edge PUBLICATION | 0B80 | 0x00000000/codecs/0x00000B80 |
يبني الـ decoder عنوان مستند المواصفة من TAG WORD وحدها. وإذا صادف Codec مجهولاً فيكفيه أن يحصل على ذلك المستند ويقرأه.
<TAG>هي 4 خانات hex (بأحرف كبيرة) من TAG WORD المستهدفة. وخانة Length هي0000. مستند Codec واحد لكل رمز. ويُفرد نظام Reference 5Q أيضاً مستنداً لكل رمز تكميم (LOCAL Identified0050، LOCAL Generic0060). وتستخدم الرموز المباشرة وCodec الخاصة بـ Issuer قاعدة العنوان نفسها<Issuer>/codecs/<معرّف Codec>/(عنوان النشر وقائمة الإصدارات).- علامة الموضع (
0x0000و0x0010و0x0020) لها مستند مواصفة أيضاً. لا Payload لها، فيوجد DECLARE فقط ولا FIELD. ومعنى العلامة وقاعدة قبولها مضمَّنان في الـ decoder (الطبقة 0). وأي Codec لم يُحدَّد تخطيطه بعد يبدأ هو أيضاً بمستند مواصفة فيه DECLARE فقط. - يضع مستند المواصفة في
DOC-IDالرمز CODEC-POINTER (0x00000000و0x0000<TAG>و0). وسجل قائمة الإصدارات يستخدم CODEC-POINTER هذا أيضاً. - قواعد الإصدار والعنوان المرجعي والتوقيع هي نفسها في مستند النشر العام.
الـ codebook ونسخة المواصفة
- يمكن أيضاً استيراد مستند Codec بواسطة IMPORT-DOC. وعندئذ يُستخدم CODEC-POINTER في موضع المستند بدلاً من DOC-POINTER. وتحدد SPEC-VERSION في HEAD المستند أيَّ codebook يتبع.
- على كل decoder أن يضمّن الـ codebook الأساسي أو أن يحصل عليه من هذا العنوان.
- إذا اعتُمد اقتراح (Prefix
000) معياراً، يبقى التخطيط كما هو ويتغير Prefix فقط إلى001(نظرة عامة). ولأن TAG WORD المستهدفة تتغير، تصبح النسخة المعتمدة مستند مواصفة جديداً بمعرّف Codec آخر، ويبقى مستند الاقتراح ثابتاً لا يتغير.
أربعة مفردات
| Edge | Codec | وظيفته |
|---|---|---|
| DECLARE | 0x0BBL | يعلن تركيب Payload لـ Codec واحد. الهدف TAG WORD واحدة (1 WORD) |
| FIELD | 0x0BCL | حقل Payload واحد. DECLARE الذي ينتمي إليه والعرض |
| ENUM | 0x0BDL | يُسند معنى إلى قيمة رمز واحدة في حقل قيمة خام |
| CODEC | 0x0BEL | يحدد Kind وCodec واحداً يقبله الحقل |
- يُضمَّن تخطيط الـ Edge الأربعة في الـ decoder (الطبقة 0). فمستند المواصفة يجب أن يُقرأ دون codebook. ولا يحتاج قراءة مستند المواصفة إلى مستند مواصفة آخر.
- تُربط جميع الأسماء (اسم Codec، اسم الحقل، اسم قيمة الرمز) بـ BIND.
FIELD
Edge Id LOCAL
DECLARE LOCAL (الـ DECLARE الذي ينتمي إليه هذا الحقل)
العرض 1 WORD: 0 = سجل، n = قيمة خام من n WORD، 0xFFFF = قيمة خام للباقي
- الترتيب داخل المستند لـ FIELD التي تشير إلى DECLARE نفسه هو ترتيب حقول Payload.
- يبدأ حقل السجل بـ TAG WORD ويُقرأ بقدر Length الخاصة بها.
- حقل القيمة الخام عدد صحيح بلا إشارة يُقرأ بعدد WORD محدد. أما القيم التي تحتاج إلى تفسير كالإشارة والكسر والتاريخ فلا تكون قيمة خام، بل تُوضع في سجل Value.
- لا يجوز وجود أكثر من قيمة خام للباقي (
0xFFFF) واحدة، ولا يأتي بعدها إلا قيم خام ذات عرض ثابت. - لا يُعلَن Edge Id الخاص بالـ Edge على أنه FIELD. فهو العنصر الأول في كل Edge، فهو ضمني. وEDGE-ISSUER هو العنصر الأول بعد Issuer ورقم Codec (EDGE-ISSUER-2WORD).
- يجب أن يطابق الموضع الذي ينتهي إليه قراءة الحقول تباعاً نهايةَ السجل تماماً.
CODEC
يحدد الصيغة التي يقبلها الحقل. وتُستخدم WORD الهدف بخانة Codec في TAG WORD (القسم KKKK وC) كما هي.
| خانة Length | المعنى | مثال |
|---|---|---|
0000 | Codec بعينه | 0680 SIGNED-DECIMAL، 0050 LOCAL |
1111 | حرف بدل: القسم KKKK كله (32 خانة) بصرف النظر عن قيمة C. يُوصى بأول خانة في القسم (C = 0) | 000F القسم 0 كله، 060F القسم 3 كله |
إذا امتد Kind على عدة أقسام يُسرد CODEC لكل قسم. فأي Reference هي
000Fو020Fو040F، وأي Value هي060Fو080F.ما كان التكميم فيه غير مهم أو كان حزمة يُسرد فيه Codec بعينه. فمعرّف QID في ويكي بيانات (التكميم فيه غير مهم) خمسة:
0140و0150و0160و0170و0180.إذا لم يكن لحقل السجل أي CODEC قَبِل أي سجل (باستثناء علامة الموضع). وإذا كان له واحد أو أكثر وجب أن يكون السجل أحدها (قائمة مغلقة).
إذا وُضع CODEC واحد على حقل قيمة خام فُسِّرت تلك القيمة الخام على أنها تلك Value بلا TAG.
الحقل الاختياري وعلامة الموضع
علامة الموضع حزمة سجلات من 1 WORD خُصصت لأول ثلاث خانات 0x000L~0x002L في القسم 0 من Reference. ولا يجوز أن تأتي في موضع إلا إذا كانت قائمة CODEC للحقل تضع تلك الـ WORD هدفاً بعينه.
| هدف CODEC | العلامة | ذلك الحقل |
|---|---|---|
0000 | ABSENT، غير مكتوب | حقل اختياري. يمكن حذفه |
0010 | UNKNOWN-VALUE، غير معروف | يقبل تقريراً بأن القيمة موجودة لكنها غير معروفة |
0020 | NO-VALUE، لا قيمة | يقبل تقريراً بأن لا قيمة |
- قاعدة القبول: تصح العلامة فقط إذا وُجدت الـ WORD نفسها هدفاً بعينه في قائمة CODEC للحقل. أما حروف البدل (
000Fو060F…) والحقل الذي بلا CODEC (“أي سجل”) فلا يقبلان علامة. وفي موضعَي سجل HEAD وBODY وموضع Edge Id تكون غير صالحة (invalid). - عند حذف حقل اختياري تُكتب في موضعه WORD واحدة
0x0000(ABSENT). فالحقل الاختياري يشغل موضعه دائماً. ولهذا يكون لكل سجل تمثيل واحد، ويتحدد التفكيك بالموضع وحده. - للعلامة رمز Reference خاص بها فلا تتداخل مع سجل آخر، وحتى الـ decoder الذي لا يعرف المواصفة يتجاوزها على أنها سجل من 1 WORD.
- العلامات الثلاث أقوال مختلفة. ABSENT قول عن المستند (لم يُملأ هذا الموضع)، فلا يقرّ بشيء عن العالم. وUNKNOWN-VALUE تقرير بأن القيمة موجودة (
∃x)، وNO-VALUE تقرير بأن لا قيمة (¬∃x، داخل شرط تقييد). فالحذف ليس “لا قيمة” بل “غير مكتوب”. - ما تعنيه العلامة تحدده مواصفة Codec التي تقبلها (TRIPLE، QUALIFIER).
مثال: مستند مواصفة TRIPLE
هذا هو BODY في 0x00000000/codecs/0x00000AA0.
| Edge | المحتوى | الاسم (BIND) |
|---|---|---|
| #1 DECLARE | الهدف 0AA0 | TRIPLE |
| #2 FIELD | حقل من #1، سجل | predicate |
| #3 FIELD | حقل من #1، سجل | subject |
| #4 FIELD | حقل من #1، سجل | object |
| #5 FIELD | حقل من #1، قيمة خام 1 WORD | rank |
| #6~#8 ENUM | قيم الرمز 0 و1 و2 للحقل #5 | normal, preferred, deprecated |
| #17 CODEC | #5 يُفسَّر بـ UNSIGNED-INTEGER (0620) | |
| #18, #22, #23, #19, #24 CODEC | #4 أي Reference (000F·020F·040F) أو أي Value (060F·080F) | |
| #20, #21 CODEC | #4 يقبل أيضاً UNKNOWN-VALUE (0010) وNO-VALUE (0020) | |
| #25~#27 CODEC | #2 أي Reference (000F·020F·040F) | |
| #28~#30 CODEC | #3 أي Reference (000F·020F·040F) |
بهذا المستند الواحد يقسّم الـ decoder سجل TRIPLE إلى حقوله، ويعرضه مع أسماء الحقول، ويتحقق من صحة صيغته.
مثال: مستند مواصفة QUANTITY
Value QUANTITY (0660) حقوله الأربعة كلها سجلات.
| الحقل | CODEC |
|---|---|
amount | 0610 SIGNED-INTEGER، 0620 UNSIGNED-INTEGER، 0630 BINARY-FLOAT (القيم المنتهية فقط)، 0670 FRACTION، 0680 SIGNED-DECIMAL، 0690 UNSIGNED-DECIMAL |
unit | 000F·020F·040F أي Reference، 0000 اختياري |
lower | 0610·0620·0630·0670·0680·0690 (مثل amount)، 0000 اختياري |
upper | 0610·0620·0630·0670·0680·0690 (مثل amount)، 0000 اختياري |
القواعد
- في مستند مواصفة واحد DECLARE واحد. وهدف DECLARE هو نفسه TAG WORD الخاصة بمعرّف Codec.
- لا يُعلَن الهدف نفسه مرتين في مستند واحد.
- لا تُستخدم الصيغ المختلفة في تركيب الحقول فروعاً. يُعلَن كل Codec على حدة.
- لا يمكن إعلان تخطيط فيه قيمتان خامتان متغيرتان أو أكثر، أو يتوقف عرض القيمة الخام فيه على قيمة أخرى. تُغلَّف تلك الأجزاء في سجل.
- يُنشر مستند المواصفة بالإصدارات كغيره من المستندات. لكن التخطيط الثنائي لـ Codec لا يُنقَّح. ولتغييره يُخصَّص Codec جديد.
مسائل مفتوحة
- التناظر بين قيمة
SPEC-VERSION(v1 هي0x0001) وإصدار مستند الـ codebook. وMeta النسب التي تصل النسخة المعتمدة بنسخة الاقتراح.