GEUL מצביעה על מסמך לא באמצעות מחרוזת URL אלא באמצעות ID (Issuer, מזהה מסמך, מזהה גרסה). הכתובת נקבעת מה-ID. דף זה קובע את כללי הפרסום הדרושים כדי שמקודדים, מפענחים ומפרשים יפעלו יחד. דרגות ה-Issuer ואופני החשיפה נקבעים ב-Issuer ופרסום.

ייצוג ID

ID המשמש בכתובת נכתב ב-hex.

  • התחילית היא 0x באותיות קטנות. ספרות hex נכתבות באותיות גדולות A-F. המפרש ממיר גם כתובת שנכתבה באותיות קטנות לגדולות לפני החיפוש.
  • מספר הספרות קבוע ברוחב × 4. אין להשמיט אפסים מובילים, ומספר הספרות הוא הרוחב עצמו.
  • בכתיבת כתובת, Issuer נכתב במספר הספרות של רוחב ההנפקה שלו: 8 ספרות ל-2 WORD, 16 ל-4 WORD, 64 ל-16 WORD.
  • בקריאה מתקבלים Issuer בן 8, 16 ו-64 ספרות. ייצוג ארוך של Issuer ID קצר עם אפסים מובילים נמצא כאותו Issuer (0x00000001 ו-0x0000000000000001 הם אותו Issuer, Issuer ופרסום).
יעדרוחבספרותדוגמה
Issuer2 WORD80x00000001
Issuer4 WORD160x0000000100000000
Issuer16 WORD640x + 64 ספרות
Codec ID2 WORD80x00000AA0
מזהה מסמך4 WORD160x0000000000000000
מזהה גרסה2 WORD80x00000003
hash תוכן16 WORD640x + 64 ספרות
  • Codec ID של קוד ישיר ב-GEUL הוא ה-TAG WORD שלו (L=0) כתוב כ-32 סיביות (TRIPLE ‏0x0AAL ← 0x00000AA0). ה-Kind כלול ב-TAG ולכן אין התנגשות.
  • Codec בפורמט ISSUER של Issuer אחר ממוקם תחת codecs/ של אותו Issuer במספר ה-Codec של הרשומה. לדוגמה: IETF CRC32C הוא 0x00000007/codecs/0x0000C000/.
  • Codec ID של Codec של Issuer הוא מספר ה-Codec של הרשומה (2 WORD). Issuer מקצה מספרי Codec כך שלא יתנגשו בתוך <Issuer>/codecs/ שלו, בלי קשר ל-Kind (Reference, Value, Edge). הכתובת אינה מחולקת לפי Kind (אין תיקיות כמו references/, values/, edges/).
  • המפרש רואה כשגיאה מצב שבו ה-Kind של הרשומה שונה מה-Kind של יעד DECLARE במסמך ה-Codec שלה.
  • הפרסום דוחה העלאת Codec אחר ל-Codec ID זהה.
  • כללי מזהה הגרסה (מ-1, 0 הוא האחרונה, הקצאה בידי גוף הפרסום, כשנגמר מקבלים מזהה מסמך חדש) נקבעים ב-מסמך.

כתובות פרסום

/.well-known/geul/issuers/latest.geul                              רשימת Issuer, האחרונה
/.well-known/geul/issuers/<מזהה גרסה>.geul                         רשימת Issuer, גרסה מסוימת
/.well-known/geul/issuers/versions.geul                            רשימת הגרסאות של רשימת Issuer
/.well-known/geul/<Issuer>/codecs/<Codec ID>/latest.geul           Codec, האחרון
/.well-known/geul/<Issuer>/codecs/<Codec ID>/<מזהה גרסה>.geul      Codec, גרסה מסוימת
/.well-known/geul/<Issuer>/codecs/<Codec ID>/versions.geul         רשימת הגרסאות של Codec
/.well-known/geul/<Issuer>/docs/<מזהה מסמך>/latest.geul            מסמך, האחרון
/.well-known/geul/<Issuer>/docs/<מזהה מסמך>/<מזהה גרסה>.geul       מסמך, גרסה מסוימת
/.well-known/geul/<Issuer>/docs/<מזהה מסמך>/versions.geul          רשימת הגרסאות של מסמך
/.well-known/geul/<Issuer>/hashes/<hash תוכן>.geul                 חיפוש לפי hash תוכן

דוגמה: /.well-known/geul/0x00000002/docs/0x0000000000000000/latest.geul

  • הנתיב עוקב אחר .well-known של RFC 8615. geul.org ופרסום פרטי משתמשים באותו נתיב ורק הדומיין שונה. הסיומת שיש לרשום היא geul אחת.
  • רשימת Issuer היא issuers/. Codec, מסמך רגיל ו-hash מתפצלים תחת תיקיית ה-Issuer ל-codecs/<Codec ID>/, ‏docs/<מזהה מסמך>/ ו-hashes/. גם לרשימת Issuer יש גרסה 1 ואילך ו-versions.geul (מסמכי רשימה).
  • latest.geul הוא שם שמור וכינוי. הוא אינו נשמר. מחפשים ב-versions.geul באותו מקום את הגרסה האחרונה ומוציאים את הבייטים של אותה גרסה כפי שהם. אין ניתוב מחדש (redirect). כל latest.geul של רשימת Issuer, Codec ומסמך הם כך.
  • הכתובת הקנונית של גרסה אחת היא /<Issuer>/docs/<מזהה מסמך>/<מזהה גרסה>.geul. ל-Codec היא /<Issuer>/codecs/<Codec ID>/<מזהה גרסה>.geul. כתובת אחרת שמחזירה אותו תוכן מצביעה על הכתובת הקנונית ב-Link: rel=canonical.
  • כתובת של גרסה מסוימת וכתובת של hash תוכן הן בלתי משתנות. אפשר להציב כתובת בלתי משתנה במטמון קבוע וב-CDN. הצד המקבל מאמת באמצעות hash התוכן שברשימת הגרסאות (או ברשומת הנעילה).
  • כדי לחפש לפי hash תוכן צריך להכיר את ה-Issuer. אין חיפוש גלובלי לפי hash בלבד.
  • למסמך Codec אין מזהה מסמך. הוא מצביע על עצמו ועל גרסתו באמצעות CODEC-POINTER (Issuer, Codec ID, מזהה גרסה).
  • ID מתחיל תמיד ב-0x. לכן שמות שמורים (issuers, ‏codecs, ‏docs, ‏hashes, ‏latest.geul, ‏versions.geul) או שמות שאדם נתן אינם מתנגשים ב-ID, גם אם הם מילים שכולן hex כמו add ו-cafe.
  • המיקום (מאיזה שרת מורידים) אינו נכנס לתוכן המסמך. אם ייכנס, hash התוכן ישתנה כשהכתובת תשתנה. המיקום נקבע בהגדרות של הצד המוריד את המסמך.

צורת הפרסום והחיפוש

  • הכתובת היא כתובת לוגית. גוף הפרסום יכול להוציא קבצים בודדים או pack, ואם זה pack אי אפשר להוריד אותו ישירות בכתובת ה-URL אלא קוראים אותו במפרש GEUL.
  • בין אם נשמר כקבצים בודדים, כ-pack או כ-zstd pack, מוצאים אותו באותה כתובת. כתובת מחוץ לעשרת הפורמטים שלעיל וכתובת שאינה קיימת הן 404 (לא קיים).

כלי שורת הפקודה geul (gogeul):

geul get <כתובת>     מוציא את הבינארי של מסמך GEUL טהור לפלט הסטנדרטי
geul show <כתובת>    מציג את המסמך כטקסט
  • geul get מקבל כתובות file:// ו-https://. כתובת מחוץ לעשרת הפורמטים וכתובת שאינה קיימת מסתיימות ב-404 (לא קיים).

ב-pkg/resolve של ספריית Go ‏gogeul יש פונקציית חיפוש לכל כתובת. כולן מחזירות בינארי GEUL טהור ([]byte). מכיוון שמזהה הגרסה מתחיל ב-1, Latest (0) הוא האחרון. כתובת שאינה קיימת היא שגיאת אי-קיום (ErrNotFound).

const Latest uint32 = 0

Issuers(ctx, v)               / IssuersVersions(ctx)
Codec(ctx, issuer, codec, v)  / CodecVersions(ctx, issuer, codec)
Doc(ctx, issuer, doc, v)      / DocVersions(ctx, issuer, doc)
Hash(ctx, issuer, hash)

ParseAddr(s string) (Addr, error)   // פורמט שאינו אחד מ-10 הוא 404 (לא קיים)
Fetch(ctx, Addr) ([]byte, error)    // geul get = ParseAddr → Fetch → פלט סטנדרטי

ציון פורמט

  • כתובת פרסום מסתיימת ב-.geul והיא בינארית (application/vnd.geul).
  • הנוסח הבינארי הוא הנוסח הקנוני של המסמך. hash תוכן וחתימה מחושבים מהבינארי בלבד.

מסמכי רשימה

מסמך הרשימה הוא רשימת ה-Issuer issuers/ בלבד. הוא מקשר Issuer ודומיין (רשימת Issuer). הוא מתחיל בגרסה 1 ויש לו versions.geul. מזהה המסמך של הרשימה הוא מזהה המסמך השמור 0xFFFFFFFFFFFFFFFF (Issuer geul.org ‏0x00000000). כל Issuer שומר את מזהי המסמך 0x0000000000000000 ו-0xFFFFFFFFFFFFFFFF (Issuer ופרסום).

  • latest.geul הוא כינוי שאינו נשמר. מחפשים ב-versions.geul את הגרסה האחרונה ומוציאים את הבייטים שלה.
  • PUBLICATION‏·DEPRECATION‏·TOMBSTONE ב-issuers/versions.geul מצביעים על גרסת הרשימה באמצעות DOC-POINTER (0x00000000, ‏0xFFFFFFFFFFFFFFFF, מזהה גרסה). לכן גם כשמורידים דרך hashes/ יודעים של מה זו רשימה (PUBLICATION).
  • מזהה המסמך 0xFFFFFFFFFFFFFFFF אינו מתקבל בכתובת <Issuer>/docs/<מזהה מסמך>/ באף Issuer (404). מזהה המסמך השמור האחר 0x0000000000000000 הוא מסמך אינדקס הגדרות המונחים של אותו Issuer וממוקם תחת docs/ (Issuer ופרסום).
  • במסמך רשימה לא מציבים DOC-ID. של מה זו רשימה אומר ה-DOC-POINTER ברשומה (DOC-ID).
  • מסמכים ו-Codec נמצאים ישירות לפי ID שחושב מהרשומה, בלי רשימה (שם מסמך).

שם דומיין

שם דומיין אינו כתובת URL של פרסום. כתובת שבה כתבו דומיין במקום <Issuer> או שם במקום ID היא מחוץ לעשרת הפורמטים שלעיל ולכן 404 (לא קיים). גם אין ניתוב מחדש (redirect) משם לכתובת ID.

  • שם דומיין הוא קלט של המפרש ושל ה-CLI. המפרש ממיר דומיין ל-Issuer ID באמצעות ה-BIND ברשימת ה-Issuer issuers/. ה-ID שהומר נרשם ברשומת הנעילה. אין כתובת של שם מסמך (שם מסמך).
  • הכתובת הקנונית, מפתח המטמון ויעד החתימה הם כתובת ה-ID.
  • דומיין נכתב באותיות קטנות, ודומיין בינלאומי (IDN) נכתב בצורת IDNA (punycode). לא מוסיפים . בסוף.
  • Issuer של 16 WORD, שאין לו רישום, וסביבה מנותקת רשת שאינה מגיעה ל-geul.org אינם יכולים להשתמש בשם דומיין. משתמשים ב-ID.

רשימת Issuer

רשימת ה-Issuer היא מסמך תחת /.well-known/geul/issuers/ (האחרונה ב-issuers/latest.geul). היא מקשרת Issuer לשמו (דומיין).

BODY
  BIND   Subject = ISSUER-POINTER(Issuer)   שם = "geul.org"
  …
  • ה-Subject הוא ISSUER-POINTER (ה-Issuer עצמו) והשם נקשר ב-BIND.
  • השם הוא דומיין שעבר הוכחת בעלות על דומיין. הוא באותיות קטנות, ודומיין בינלאומי (IDN) נכתב ב-IDNA (punycode). שם אחד נקשר ל-Issuer אחד בלבד.
  • שם התצוגה של ה-Issuer שנקרא בידי בני אדם (לפי שפה) מוצמד לאותו Subject כ-LABEL של היגד.
  • geul.org (ה-Issuer GEUL) חותמת, ובעת שינוי מוסיפים ואין מתקנים (אותו כלל שרשרת כמו ברשימת גרסאות).

שם מסמך

אין כתובת של שם מסמך. מסמכים ו-Codec נמצאים לפי ID.

  • אין אינדקס שממיר שם מסמך או שם Codec ל-ID. גם ברשימת הגרסאות לא מציבים BIND של שם מסמך (PUBLICATION).
  • אינדקס שבני אדם מעיינים בו נבנה בידי כלי (viewer) מתוך מצאי ה-pack.
  • הכתובת הקנונית, מפתח המטמון ויעד החתימה הם כתובת ה-ID. IMPORT וציטוט בתוך מסמך נעשים באמצעות ID בלבד.
  • כותרת הנקראת בידי בני אדם (לפי שפה) מוצמדת כ-LABEL של היגד.

מסמך שנמחק

  • גם כתובת של גרסה שבוטלה במחיקה משפטית או במחיקה מכוח סמכות (TOMBSTONE) היא 404 (לא קיים), כמו כל כתובת שאינה קיימת.
  • גרסה שהומלץ להפסיק את השימוש בה (DEPRECATION) אינה 404. היא ממשיכה להיות מוגשת בכתובת הגרסה שלה.
  • מחיקה נשארת ברשימת הגרסאות כרשומת TOMBSTONE (DOC-POINTER של אותה גרסה, קטגוריית הסיבה).

שכבה

GEUL מבטאת כמסמכי GEUL גם מוצא, Meta ורשימות. המינימום הדרוש לקריאתם מובנה במפענח כדי לשבור את המעגליות. כל שכבה נשענת רק על השכבות שמתחתיה.

שכבהתוכןנשענת על
שכבה 0כללים מובנים במפענח: מסגור, hash תוכן, אימות חתימה, Codec של רשומות רשימת גרסאות (PUBLICATION·DEPRECATION·TOMBSTONE), אוצר המילים של מפרט Codec (DECLARE·FIELD·ENUM·CODEC), סמן מקום (0x0000, ‏0x0010, ‏0x0020), מפתח אמון שמתקבל מחוץ למסמךכלום. לא מחפשים
שכבה 1מסמך רשימת גרסאותשכבה 0
שכבה 2מסמך רגיל, codebook, מסמך מפרט Codec, מסמך מפתח אימות של Issuerמוצאים באמצעות שכבה 1 ומאמתים באמצעות שכבה 0
  • אף שכבה אינה נשענת על עצמה או על שכבה שמעליה.
  • מבחינים בין מה שמבוטא ב-GEUL לבין מה שאפשר לקרוא רק בפירוש של GEUL. שכבה 0 אפשר לבטא ב-GEUL, אך פירושה אינו מצריך חיפוש.
  • גם הליבה הקבועה שאי אפשר להמירה למסמך TOULMIN, כמו משמעות פסק הדין, ממוקמת כאן (TOULMIN).

רשימת גרסאות

גוף הפרסום ממשיך לכתוב מסמך רשימת גרסאות אחד לכל מסמך (/<Issuer>/docs/<מזהה מסמך>/versions.geul, ל-Codec /<Issuer>/codecs/<Codec ID>/versions.geul, לרשימת Issuer issuers/versions.geul). פורמט הרשומות ומבנה המסמך נקבעים ב-PUBLICATION.

DOC-*
  SPEC-VERSION
  PARENT          hash התוכן של רשימת הגרסאות הקודמת
  RECORDED-AT     הזמן שבו הוצאה הרשימה הזו
  NEXT-LOCAL-ID   ה-LOCAL ID הבא להקצאה
  SIGNATURE       חתימת גוף הפרסום
BODY
  PUBLICATION     #1  מסמך@1  hash תוכן
  PUBLICATION     #2  מסמך@2  hash תוכן
  DEPRECATION     #3  מסמך@1
  …
END
Edgeמשמעות
PUBLICATIONמפרסם גרסה אחת של מסמך ואת hash התוכן שלה
DEPRECATIONמסמן המלצה להפסיק שימוש בגרסה שפורסמה. היא ממשיכה להתפרש
TOMBSTONEמוחק גרסה שפורסמה (מחיקה משפטית או מכוח סמכות). רושם קטגוריית סיבה
  • הרשומות רק מתווספות. אין מתקנים, מוחקים או משנים סדר. גם deprecate ומחיקה מוסיפים רשומה. רשימה חדשה משאירה בראשה את ה-BODY של הרשימה הקודמת כפי שהוא ומוסיפה רשומות, והרשימות מתחברות בשרשרת hash של PARENT.
  • הכוונה היא שאין מתקנים את רישום הפרסום, וזה שונה מתיקון תוכן המסמך (מסמך). המצב הנוכחי של גרסה מחושב מהחלת הרשומות לפי הסדר.
  • מזהי הגרסה עולים מ-1 ללא חורים. אין מפרסמים אותו תוכן שוב.
  • הגרסה האחרונה היא הגרסה הגבוהה ביותר שאינה מומלצת להפסקה ואינה נמחקה.
  • ברשומה לא מציבים זמן. זמן הפרסום הוא ה-RECORDED-AT של הרשימה הראשונה שבה נכללה הרשומה.
  • ברשימת גרסאות לא מציבים DOC-ID. ה-DOC-POINTER ברשומה (מזהה מסמך, ולרשימת Issuer מזהה המסמך השמור) אומר של מה זו רשימה.
  • רשימת גרסאות אינה מציבה IMPORT ומשתמשת רק ב-Codec של שכבה 0. ב-BODY יש רק PUBLICATION‏·DEPRECATION‏·TOMBSTONE.
  • רשימות גרסאות קודמות מצוינות רק באמצעות hash תוכן (<Issuer>/hashes/<hash תוכן>.geul), וההיסטוריה מתחברת בשרשרת PARENT.
  • הכתובות המשתנות הן latest.geul ו-versions.geul. מכיוון שאי אפשר ליצור מסמך ממצביע משתנה, מאמתים באמצעות החתימה, ה-RECORDED-AT וה-PARENT של הרשימה שהתקבלה.

גורם החתימה

חתימהגורםיעד
חתימת מסמךה-Issuer של המסמךhash התוכן של המסמך (Issuer ופרסום)
חתימת רשימהגוף הפרסום שהקצה את מזהי הגרסהhash התוכן של רשימת הגרסאות
  • בפרסום ב-geul.org, geul.org (ה-Issuer GEUL), ובפרסום פרטי, אותו Issuer, מקצה את מזהי הגרסה וחותם על הרשימה.
  • המחבר אחראי לתוכן, וגוף הפרסום אחראי למספר ולסדר.

אימות

  • החתימה יוצאת מ-hash התוכן, ולכן גם אם מוחקים אותה ה-hash נשאר. לכן מאמתים לא ב״אם יש חתימה בודקים״ אלא ב״חייבת להיות חתימה של המפתח שנקבע״. המפתח הנדרש נקבע בהגדרות האמון של המפרש וברשומת הנעילה.
  • המפרש רושם ברשומת הנעילה את hash התוכן של הרשימה האחרונה שראה. אם ה-hash הזה אינו בשרשרת PARENT של רשימה חדשה שהתקבלה, דוחים אותה (מניעת הרצה לאחור והסתעפות).
  • מראות וסביבות מנותקות רשת מעתיקות יחד את שרשרת רשימות הגרסאות. די במפתח ציבורי כדי לאמת במצב לא מקוון.
  • מסמך שהתקבל מאומת באמצעות hash התוכן, מכל מוצא שבא. אין צורך לסמוך על המוצא.

פתרון תלויות

  • מסמך רושם מסמכי תלות ב-IMPORT-DOC ב-HEAD.
  • גרסה חדשה אינה מתחייבת לתאימות עם הגרסה הקודמת. לכן לא ממזגים את גרסת המסמך לגרסה אחת בכל הגרף (אין משתמשים בבחירת גרסה מינימלית).
  • כל IMPORT-DOC קשור לנוסח שנעל. כמה נוסחים של אותו מסמך יכולים להיות יחד בגרף אחד (פסק דין שציטט את החוק הישן ופסק דין שציטט את החוק הנוכחי). הפניה נפתרת לפי (מסמך, גרסה, LOCAL ID).
  • ייבוא של האחרונה (גרסה 0) קשור לנוסח האחרון בזמן הפירוש. אם מפרשים בזמן מוגדר, הוא קשור לנוסח שהיה בתוקף באותו זמן (מסמך).
  • ייבוא שננעל במזהה גרסה ניתן לשחזור (תוכן מזהה הגרסה בלתי משתנה ומאומת ברשומת הנעילה).

סוג מדיה

  • סוג המדיה של מסמך GEUL הוא application/vnd.geul. הסיומת היא .geul.
  • גם אם עוברים לעץ הסטנדרטי application/geul, ממשיכים לקבל application/vnd.geul.

בעיות פתוחות

  • הטיפול במצב שבו מזהי הגרסה מתפצלים (אותו מזהה גרסה, תוכן שונה) בפרסום פרטי, ב-Issuer של 16 WORD ובסביבות מנותקות רשת.
  • מבנה ה-HEAD של רשימת ה-Issuer issuers/ ופורמט החתימה והשרשרת. כללי שמות ל-Issuer ללא דומיין (4 WORD), טיפול בסכסוכי שמות ותקרת אורך.
  • המועד והפורמט למעבר מהשרשרת המלאה ליומן Merkle (הוכחות הכללה ועקביות) כשהרשימה גדלה.
  • Meta הרושם ב-HEAD את ה-Issuer שמספק מיקום.