יחידת הנתונים של GEUL היא מסמך (DOC) אחד. קובץ אחד (.geul, סוג מדיה application/vnd.geul) הוא מסמך אחד.

מבנה

DOC-*            ← פותח את המסמך (אורך כולל)
  Meta …         ← HEAD: רשומות על המסמך
  SOURCE …       ←   (המוצא של המסמך כולו וה-QUALIFIER שלו)
BODY             ← מסיים את ה-HEAD ופותח את ה-BODY
  Reference, Value, Edge …
END              ← סוגר את המסמך
רשומהTAGמשמעות
DOC-1WORD1C01 + 1 WORDפותח את המסמך ומציין את האורך הכולל ב-1 WORD
DOC-2WORD1C12 + 2 WORDהאורך הכולל ב-2 WORD
DOC-4WORD1C24 + 4 WORDהאורך הכולל ב-4 WORD
BODY1C301 WORD. מסיים את ה-HEAD ומתחיל את ה-BODY
END1C401 WORD. סוגר את המסמך
  • הערך של DOC-* הוא מספר ה-WORD הכולל מתחילת הרשומה הפותחת ועד סוף ה-END. משתמשים ברוחב הצר ביותר שהערך נכנס בו.
  • END הוא חובה. אם מיקום ה-END אינו מתאים לאורך של DOC-*, המסמך נדחה. אם הקלט נגמר בלי END, המסמך קטוע.
  • המפענח יכול לדלג על המסמך כולו בבת אחת לפי האורך של DOC-*.
  • אין דרך לפתוח מסמך בלי לדעת את אורכו. נתונים בזמן אמת שסופם אינו ידוע מראש נחתכים ליחידות שאורכן ידוע ונשלחים כמסמכים רבים.
  • אם ה-HEAD ריק, ה-BODY מושמט. מסמך ללא רשומת BODY הוא כולו BODY. ה-BODY מופיע פעם אחת בלבד. אם יש ב-HEAD ולו רשומה אחת (Meta או HEAD Edge), חייב להיות BODY.
  • מסמכים אינם מקוננים. מסמך אחר מצוין באמצעות IMPORT או Reference מצביע.

HEAD ו-BODY

  • ב-HEAD יש רק Meta ו-HEAD Edge. כולם תיאורים של המסמך שמכיל אותם.
    • Meta: מבנה, הגדרה, מוצא, שושלת, אימות, מדיניות ו-IMPORT של המסמך.
    • HEAD Edge: Edge של ראיות SOURCE (Target 0) הרושם את המקור של המסמך כולו, ו-QUALIFIER שה-SOURCE הזה הוא ה-Target שלו (hash של המקור, זמן הקבלה, טווח המקור וכדומה). ה-QUALIFIER בא אחרי ה-SOURCE.
  • ב-BODY יש רק Reference, Value ו-Edge. המוצא של רשומה בודדת נכתב ב-Edge של ראיות SOURCE בתוך ה-BODY, וראיות אחרות כמו מהימנות נכתבות ב-QUALIFIER הנצמד לרשומה. SOURCE עם Target 0 ו-QUALIFIER ש-HEAD SOURCE הוא ה-Target שלו אינם יכולים להופיע ב-BODY.
  • המפענח קורא את ה-HEAD מההתחלה ומסווג. Meta שייך ל-HEAD. SOURCE עם Target 0 שייך ל-HEAD, והמפענח זוכר את ה-Edge Id שלו. QUALIFIER שה-Target שלו הוא ה-SOURCE הזכור שייך ל-HEAD. כשמגיעה רשומה אחרת, אם ה-HEAD ריק, ה-BODY הושמט (מאותה רשומה מתחיל ה-BODY), ואחרת המסמך invalid בגלל BODY חסר.
  • Edge Id ב-HEAD וב-BODY חולקים מרחב מספרים אחד. הוא ייחודי בתוך המסמך, ומתקבל מ-NEXT-LOCAL-ID כמו Edge ב-BODY. אם ה-Origin של HEAD Edge הוא LOCAL, ההגדרה שלו נמצאת ב-BODY (LOCAL חל על המסמך כולו).
  • Meta יכול להכיל רשומת Value בתוך ה-Payload שלו. ה-Value המוכל אינו רשומה עצמאית אלא חלק מאותו Meta.
  • היקף ההצהרה (מחלקת ההגדרה של Meta) הוא אותו מסמך.

הצהרות ברירת מחדל

שתי ההצהרות מופיעות לכל היותר פעם אחת. התנאי שלהלן קובע באילו מסמכים הן חייבות להופיע.

Metaמשמעותמסמכים שחייבים להכיל
SPEC-VERSIONגרסת המפרט שהמסמך נשען עליה. קובעת איך לקרוא את שאר הרשומות. אם הגרסה אינה מוכרת, דוחים או מזהירים. הערך במסמך v1 הוא 0x0001מסמך מפורסם. אם חסר, המפענח קורא לפי הגרסה שהוא מכיר
DOC-IDהמזהה של המסמך עצמו. נדרש כדי להצביע מחוץ למסמך על המסמך ועל הפריטים שבתוכומסמכי גרסה תחת docs/<מזהה מסמך>/·codecs/<Codec ID>/ ב-.well-known/geul/ (כולל מסמכי מפרט). לא ברשימת הגרסאות versions.geul ולא במסמכי רשימה (issuers/)
  • SPEC-VERSION מכיל מספר שלם אחד בלבד, כדי שמפענח מכל גרסה יוכל לקרוא אותו (ב-v1 1C51 0001). אינו נשען על קוד Value.
  • DOC-ID הוא DOC-POINTER שמצביע על עצמו (Issuer, מזהה מסמך, גרסה 0). מזהה מסמך הוא 4 WORD. למסמך Codec אין מזהה מסמך, ולכן משתמשים ב-CODEC-POINTER (Issuer, Codec ID, גרסה 0). כל Issuer שומר את מזהי המסמך 0x0000000000000000 ו-0xFFFFFFFFFFFFFFFF (Issuer ופרסום).
  • מסמך ללא DOC-ID הוא מסמך ללא שם. אפשר להצביע עליו רק באמצעות hash תוכן.

hash תוכן

עותק של מסמך מצוין באמצעות hash תוכן (תפקיד זהה למזהה commit ב-git).

  • זה SHA-256 מהרשומה הפותחת (DOC-*) ועד רגע לפני END. 16 WORD.
  • Meta ממחלקת האימות (חתימה וכדומה, רשומות בקטע 15 עם C >= 5, כלומר w >= 0x1E50) מוחרג מהחישוב. לכן אפשר להניח את החתימה בתוך המסמך בלי ליצור מעגליות.
  • בעת החישוב, האורך ב-DOC-* מוחלף באורך ללא רשומות האימות, והרוחב מוחלף ברוחב הצר ביותר המתאים לאורך זה. לכן hash התוכן זהה לפני הצמדת החתימה ואחריה.
  • hash התוכן אינו נרשם במסמך אלא מחושב. הוא נכתב כערך רק כשמצביעים על גרסה אחרת (PARENT וכדומה).
  • גם PARENT שבתוך המסמך נכנס לחישוב, ולכן hash התוכן הוא שרשרת hash המחברת את כל ההיסטוריה.
  • Meta שמוצמד מחוץ למסמך בדיעבד (הערה במאגר נפרד וכדומה) אינו משנה את hash התוכן (כמו git notes).
  • הנוסח הבינארי הוא הנוסח הקנוני של המסמך. hash תוכן וחתימה מחושבים מהבינארי בלבד.

גרסה

למסמך בעל שם (מסמך עם DOC-ID) יש גרסאות.

  • מזהה גרסה הוא מספר שלם של 2 WORD המונה מ-1 לפי סדר הפרסום בתוך מסמך אחד. 0 פירושו “גרסה לא נרשמה” ומטופל כגרסה האחרונה.
  • מזהה הגרסה מוקצה על ידי גוף הפרסום בעת הפרסום. ההתאמה בין מזהה גרסה ל-hash תוכן נמצאת ברשימת הגרסאות החתומה על ידי גוף הפרסום (כתובות פרסום ורשימת גרסאות).
  • אין מפרסמים אותו תוכן שוב. אם hash התוכן כבר קיים, מוחזר מזהה הגרסה שלו.
  • כשכל 2 ה-WORD נוצלו, מפרסמים תחת מזהה מסמך חדש.
  • בגרסאות מ-v2 ואילך רושמים ב-HEAD את PARENT (hash התוכן של הגרסה הקודמת). מאחר שהוא נכנס ל-hash התוכן, הגרסאות מתחברות בשרשרת hash. בגרסה הראשונה לא מציבים אותו.

תיקון

מסמכי GEUL מתוקנים כמו חקיקה.

  • גרסה היא בלתי משתנה. גרסה שפורסמה אינה משתנה ואינה נמחקת. היוצאים מן הכלל הם רק מחיקה משפטית ומחיקה מכוח סמכות (TOMBSTONE).
  • ההיסטוריה אינה נמחקת. תיקון מתפרסם כגרסה חדשה ואינו דורס את הגרסה המקורית (שימור החוק הישן). גרסה מתוקנת מתחברת לגרסה המקורית באמצעות REPLACES.
  • מצביעים משתנים כמו branch, HEAD ו-reflog אינם מוצבים במסמך. מנהלים אותם מחוץ למסמך (מאגר, אינדקס).
  • גרסה חדשה יכולה להוסיף הגדרות, לתקן אותן ולמחוק אותן. אין התחייבות לתאימות עם הגרסה הקודמת. גם שינוי ההגדרה של אותו מונח הוא תיקון (למשל בחוק האזרחי הקוריאני המונח 성년 (בגיר) השתנה מגיל 20 ל-19, ובחוק העונשין הקוריאני אובייקט עבירת האונס 부녀 (אישה) השתנה ל-사람 (אדם)).
  • LOCAL ID הוא זהות החוצה גרסאות (כמו מספר סעיף). אותו LOCAL ID מצביע על אותו פריט גם בגרסאות שונות.
    • הוספה: מקבלים LOCAL ID חדש. מכיוון שלמזהה אין משמעות של סדר, אין צורך בהכנסות כמו סעיף X-2. המספר החדש מתקבל מ-NEXT-LOCAL-ID ברשימת הגרסאות (auto increment).
    • תיקון: משנים את תוכנו של אותו LOCAL ID.
    • מחיקה: מוציאים את ה-LOCAL ID מהגרסה החדשה. מזהה שנמחק אינו חוזר לשימוש.
    • העברה, פיצול, איחוד: מקבלים LOCAL ID חדש, ומצמידים לרשומה החדשה QUALIFIER P1365 (replaces, הערך הוא ה-LOCAL ID הישן) כדי לחבר למזהה הישן. מכיוון שהמזהה הישן אינו חוזר לשימוש, הוא מצביע על אותה רשומה בגרסה הקודמת.
  • גם כלי שבונה מחדש מסמך מחומר מקור מציית לכלל זה. תיאור זהה לזה שבגרסה הקודמת מקבל אותו LOCAL ID, ורק תיאור ששונה או חדש מקבל מספר חדש. אסור למספר מחדש מ-1 בכל פעם.
  • ציטוט מציין נוסח. ציטוט שננעל לגרסה קשור לגרסה זו, וציטוט של האחרונה (גרסה 0) קשור לגרסה התקפה בזמן הפירוש. מסמך העוסק באירוע בעבר מצטט בנעילה לגרסה שהייתה בתוקף באותה עת.
  • פרסום ואכיפה הם דברים שונים. זמן הפרסום נרשם ברשימת הגרסאות, ותקופת האכיפה נרשמת במסמך.
    • EFFECTIVE-FROM·EFFECTIVE-UNTIL: תקופת האכיפה של הגרסה כולה
    • P580 (התחלה)·P582 (סיום) ב-QUALIFIER של Edge סעיף: כשיום האכיפה שונה מסעיף לסעיף
  • הנוסח שבתוקף בזמן T הוא הגרסה הגבוהה ביותר שיום האכיפה שלה קודם ל-T או שווה לו. אם יש QUALIFIER P580·P582 לפי סעיף, הוא גובר. נוסח שתקופת התוקף שלו (EFFECTIVE-UNTIL) חלפה אינו בתוקף.
  • כללים הקובעים איזה נוסח להחיל, כמו הוראות מעבר (המחייבות לפעול לפי ההוראה הקודמת), חוק בזמן המעשה, ובחירת החוק החדש המיטיב עם הנאשם, מופקדים בידי פסק דין (TOULMIN). מידע האכיפה הוא חומר הגלם לכך.
  • צמצום או הרחבה של פירוש מונח על ידי פרשנות או פסיקה אינם תיקון מסמך אלא כלל פסק דין. כשהפירוש נקבע בחקיקה (למשל הוספת הגדרת 1주 (שבוע אחד) בחוק תקני העבודה הקוריאני), זה תיקון.
  • הפריסה הבינארית (wire) של Codec ושל מספר Codec אינה מתוקנת. הסיבה היא שרשומה המקודדת במספר Codec נקראת בלי לנעול גרסת codebook. כדי לשנות פריסה מקצים מספר חדש. מספר Codec שנמחק אינו חוזר לשימוש עבור פורמט אחר.

אחסון diff

גרסה מוגדרת תמיד כמסמך שלם (snapshot). diff הוא רק פורמט לאחסון והעברה של ה-snapshot בנפח קטן.

  • רק מסמך שיש לו DOC-ID ושכל ה-BODY שלו הוא Edge יכול להישמר כ-diff. רשימת הגרסאות versions.geul שאין בה DOC-ID, מסמכי רשימה (גרסאות ב-issuers/) ומסמכים ללא שם אינם נשמרים כ-diff.
  • מסמך diff הוא מסמך GEUL רגיל, ובו ב-HEAD DELTA-BASE (מזהה גרסת הבסיס).
  • מחיקה נרשמת ב-DELTA-REMOVE (רשימת LOCAL ID להסרה), והוספה ותיקון נרשמים כ-Edge ב-BODY. אין סימון נפרד להוספה או לתיקון. אם ה-Edge Id קיים בבסיס זה תיקון, ואם לא זו הוספה.
  • שחזור ה-snapshot חייב להיות דטרמיניסטי (אחרת ה-hash לא יתאים).
    1. משחזרים את ה-snapshot של גרסת הבסיס. אם גם הבסיס הוא diff, משחזרים ברקורסיה.
    2. ה-HEAD מוחלף כולו ב-HEAD של ה-diff בניכוי DELTA-BASE ו-DELTA-REMOVE. גם HEAD Edge מוחלף יחד איתו (אינו נרשם ב-DELTA-REMOVE).
    3. ה-BODY שומר על סדר הבסיס. מסירים את המזהים שב-DELTA-REMOVE, ו-Edge ב-BODY של ה-diff שה-Edge Id שלו קיים בבסיס מחליף את הקיים באותו מקום.
    4. Edge Id שאינו בבסיס מצורף בסוף לפי הסדר שבו הופיע ב-diff.
    5. hash התוכן של התוצאה חייב להיות זהה ל-hash של גרסה זו ברשימת הגרסאות. אחרת invalid.
  • שימוש חוזר ב-diff ב-LOCAL ID שנמחק הוא invalid. גם Edge Id של HEAD Edge שהוסר אינו חוזר לשימוש.
  • hash תוכן, רשימת גרסאות וחתימה מבוססים כולם על ה-snapshot המשוחזר.