יחידת הנתונים של GEUL היא מסמך (DOC) אחד. קובץ אחד (.geul, סוג מדיה application/vnd.geul) הוא מסמך אחד.
מבנה
DOC-* ← פותח את המסמך (אורך כולל)
Meta … ← HEAD: רשומות על המסמך
SOURCE … ← (המוצא של המסמך כולו וה-QUALIFIER שלו)
BODY ← מסיים את ה-HEAD ופותח את ה-BODY
Reference, Value, Edge …
END ← סוגר את המסמך
| רשומה | TAG | משמעות |
|---|---|---|
| DOC-1WORD | 1C01 + 1 WORD | פותח את המסמך ומציין את האורך הכולל ב-1 WORD |
| DOC-2WORD | 1C12 + 2 WORD | האורך הכולל ב-2 WORD |
| DOC-4WORD | 1C24 + 4 WORD | האורך הכולל ב-4 WORD |
| BODY | 1C30 | 1 WORD. מסיים את ה-HEAD ומתחיל את ה-BODY |
| END | 1C40 | 1 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. כולם תיאורים של המסמך שמכיל אותם.
- ב-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מכיל מספר שלם אחד בלבד, כדי שמפענח מכל גרסה יוכל לקרוא אותו (ב-v11C51 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 חדש. מכיוון שלמזהה אין משמעות של סדר, אין צורך בהכנסות כמו סעיף X-2. המספר החדש מתקבל מ-
- גם כלי שבונה מחדש מסמך מחומר מקור מציית לכלל זה. תיאור זהה לזה שבגרסה הקודמת מקבל אותו 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 לא יתאים).
- משחזרים את ה-snapshot של גרסת הבסיס. אם גם הבסיס הוא diff, משחזרים ברקורסיה.
- ה-HEAD מוחלף כולו ב-HEAD של ה-diff בניכוי
DELTA-BASEו-DELTA-REMOVE. גם HEAD Edge מוחלף יחד איתו (אינו נרשם ב-DELTA-REMOVE). - ה-BODY שומר על סדר הבסיס. מסירים את המזהים שב-
DELTA-REMOVE, ו-Edge ב-BODY של ה-diff שה-Edge Id שלו קיים בבסיס מחליף את הקיים באותו מקום. - Edge Id שאינו בבסיס מצורף בסוף לפי הסדר שבו הופיע ב-diff.
- hash התוכן של התוצאה חייב להיות זהה ל-hash של גרסה זו ברשימת הגרסאות. אחרת invalid.
- שימוש חוזר ב-diff ב-LOCAL ID שנמחק הוא invalid. גם Edge Id של HEAD Edge שהוסר אינו חוזר לשימוש.
- hash תוכן, רשימת גרסאות וחתימה מבוססים כולם על ה-snapshot המשוחזר.