האופן שבו Codec בונה את ה-Payload נקבע ב-codebook. ה-codebook של GEUL אינו פורמט נפרד אלא מסמך GEUL. לכל Codec יש מסמך מפרט אחד.

מיקום מסמך המפרט

מסמך המפרט של קוד ישיר מתפרסם על ידי ה-Issuer של GEUL (0x00000000). מסמך המפרט הוא מסמך Codec ואין לו מזהה מסמך. Codec ID הוא ה-TAG WORD של אותו Codec (רק מקומות הקטע וה-Codec ב-C, כש-Length הוא 0) כתוב כ-32 סיביות.

/.well-known/geul/0x00000000/codecs/0x0000<TAG>/<מזהה גרסה>.geul
CodecTAGמסמך מפרט
Reference LOCAL00500x00000000/codecs/0x00000050
Value QUANTITY06600x00000000/codecs/0x00000660
Edge TRIPLE0AA00x00000000/codecs/0x00000AA0
Edge PUBLICATION0B800x00000000/codecs/0x00000B80

המפענח בונה את כתובת מסמך המפרט מה-TAG WORD בלבד. כשהוא פוגש Codec שאינו מכיר, די בכך שיוריד את המסמך ויקרא אותו.

  • <TAG> הוא ארבע ספרות hex (אותיות גדולות) של ה-TAG WORD של היעד. מקום ה-Length הוא 0000. לכל קוד יש מסמך Codec אחד. גם במערך ה-Reference 5Q יש מסמך נפרד לכל קוד כימות (LOCAL Identified 0050, LOCAL Generic 0060). קוד ישיר ו-Codec של Issuer משתמשים באותו כלל כתובת <Issuer>/codecs/<Codec ID>/ (כתובות פרסום ורשימת גרסאות).
  • גם סמן מקום (0x0000, 0x0010, 0x0020) מקבל מסמך מפרט. אין לו Payload, ולכן יש בו DECLARE בלבד וללא FIELD. משמעות הסמן וכללי הקבלה שלו מובנים במפענח (שכבה 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 הוא נשען.
  • כל מפענח מכיל את ה-codebook הליבתי או מוריד אותו מכתובת זו.
  • כשהצעה (Prefix 000) מאומצת כתקן, הפריסה נשארת כפי שהיא ורק ה-Prefix משתנה ל-001 (סקירה). מכיוון ש-TAG WORD של היעד משתנה, הנוסח המאומץ הופך למסמך מפרט חדש עם Codec ID אחר, וההצעה נשארת בלתי משתנה.

ארבעה מונחי אוצר מילים

EdgeCodecתפקיד
DECLARE0x0BBLמצהיר על מבנה ה-Payload של Codec אחד. ה-TAG WORD של היעד, 1 WORD
FIELD0x0BCLשדה אחד ב-Payload. ה-DECLARE שאליו הוא שייך והרוחב
ENUM0x0BDLמצמיד משמעות לערך קוד אחד של שדה ערך גולמי
CODEC0x0BELמציין Kind·Codec אחד שהשדה מקבל
  • הפריסה של ארבע ה-Edge מובנית במפענח (שכבה 0), משום שיש לקרוא את מסמך המפרט ללא codebook. קריאת מסמך מפרט אינה דורשת מסמך מפרט אחר.
  • כל השמות (שם Codec, שם שדה, שם ערך קוד) נקשרים באמצעות BIND.

FIELD

Edge Id           LOCAL
DECLARE           LOCAL (ה-DECLARE שהשדה הזה שייך אליו)
רוחב              1 WORD: 0 = רשומה, n = ערך גולמי של n WORD, 0xFFFF = שאר הערך הגולמי
  • הסדר בתוך המסמך של ה-FIELD-ים המצביעים על אותו DECLARE הוא סדר שדות ה-Payload.
  • שדה רשומה מתחיל ב-TAG WORD וקורא כמספר ה-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משמעותדוגמה
0000Codec מדויק0680 SIGNED-DECIMAL, 0050 LOCAL
1111תו כללי: בלי קשר לערך C, הכוונה לכל הקטע KKKK (32 תאים). מומלץ התא הראשון בקטע (C = 0)000F כל קטע 0, 060F כל קטע 3
  • כש-Kind משתרע על כמה קטעים, מונים CODEC לכל קטע. כל Reference הוא 000F·020F·040F, וכל Value הוא 060F·080F.

  • כשהכימות אינו משנה או כשמדובר בקבוצה, מונים Codec מדויקים. QID של Wikidata (הכימות אינו משנה) הוא חמישה: 0140, 0150, 0160, 0170, 0180.

  • אם לשדה רשומה אין CODEC, הוא מקבל כל רשומה (פרט לסמן מקום). אם יש אחד או יותר, הרשומה חייבת להיות אחד מהם (רשימה סגורה).

  • אם לשדה ערך גולמי יש CODEC אחד, הערך הגולמי הזה מפורש כאותו Value ללא TAG.

שדה אופציונלי וסמן מקום

סמן מקום הוא קבוצת רשומות של 1 WORD המוקצית לשלושת התאים הראשונים 0x000L~0x002L בקטע 0 של Reference. הוא יכול לבוא באותו מקום רק אם רשימת ה-CODEC של השדה מציבה את אותו WORD כיעד מדויק.

יעד CODECסמןהשדה הזה
0000ABSENT, לא נכתבהוא שדה אופציונלי. אפשר להשמיט אותו
0010UNKNOWN-VALUE, אינו ידועמקבל טענה שיש ערך אך אינו ידוע מהו
0020NO-VALUE, איןמקבל טענה שאין ערך
  • כלל קבלה: סמן תקף רק אם אותו WORD מופיע ברשימת ה-CODEC של השדה כיעד מדויק. תו כללי (000F, 060F …) ושדה ללא CODEC (“כל רשומה”) אינם מקבלים סמן. במקום רשומת HEAD·BODY ובמקום Edge Id הוא invalid.
  • כשמשמיטים שדה אופציונלי, כותבים במקומו WORD אחד 0x0000 (ABSENT). גם שדה אופציונלי תופס את מקומו תמיד. לכן לרשומה אחת יש ייצוג אחד, והפירוק נקבע לפי המיקום בלבד.
  • הסמן נושא קוד Reference משלו ולכן אינו מתנגש ברשומות אחרות, וגם מפענח שאינו מכיר את המפרט מדלג עליו כעל רשומה של 1 WORD.
  • שלושת הסמנים הם אמירות שונות. ABSENT הוא אמירה על המסמך (המקום הזה לא מולא) ולכן אינו טוען דבר על העולם. UNKNOWN-VALUE הוא טענה שיש ערך (∃x), ו-NO-VALUE הוא טענה שאין ערך (¬∃x, בתוך תנאי מסייג). השמטה פירושה “לא נכתב” ולא “אין ערך”.
  • משמעות הסמן נקבעת במפרט ה-Codec המקבל אותו (TRIPLE, QUALIFIER).

דוגמה: מסמך מפרט של TRIPLE

ה-BODY של 0x00000000/codecs/0x00000AA0.

Edgeתוכןשם (BIND)
#1 DECLAREיעד 0AA0TRIPLE
#2 FIELDשדה של #1, רשומהpredicate
#3 FIELDשדה של #1, רשומהsubject
#4 FIELDשדה של #1, רשומהobject
#5 FIELDשדה של #1, ערך גולמי 1 WORDrank
#6~#8 ENUMערכי קוד 0, 1, 2 של #5normal, 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)

באמצעות מסמך אחד זה המפענח מפצל רשומת TRIPLE לשדות, מציג אותה עם שמות השדות ובודק שהצורה נכונה.

דוגמה: מסמך מפרט של QUANTITY

ב-Value QUANTITY (0660) כל ארבעת השדות הם רשומות.

שדהCODEC
amount0610 SIGNED-INTEGER, 0620 UNSIGNED-INTEGER, 0630 BINARY-FLOAT (ערכים סופיים בלבד), 0670 FRACTION, 0680 SIGNED-DECIMAL, 0690 UNSIGNED-DECIMAL
unit000F·020F·040F כל Reference, 0000 אופציונלי
lower0610·0620·0630·0670·0680·0690 (כמו amount), 0000 אופציונלי
upper0610·0620·0630·0670·0680·0690 (כמו amount), 0000 אופציונלי

כללים

  • במסמך מפרט אחד יש DECLARE אחד. יעד ה-DECLARE זהה ל-TAG WORD של ה-Codec ID.
  • אין להצהיר על אותו יעד פעמיים באותו מסמך.
  • גרסאות בעלות הרכב שדות שונה אינן משמשות כהסתעפות. מצהירים על כל Codec בנפרד.
  • לא ניתן להצהיר פריסה שיש בה שני ערכים גולמיים משתנים או שרוחב הערך הגולמי בה תלוי בערך אחר. חלקים כאלה עוטפים ברשומה.
  • מסמך מפרט מתפרסם בגרסאות כמו כל מסמך. עם זאת, הפריסה הבינארית של Codec אינה מתוקנת. כדי לשנותה מקצים Codec חדש.

בעיות פתוחות

  • ההתאמה מערך SPEC-VERSION (ב-v1 0x0001) לגרסת מסמך ה-codebook. Meta של שושלת המחברת בין הנוסח המאומץ לנוסח ההצעה.