ויקינתונים: מדיניות ממשק יציב

ממשקים ציבוריים יציבים לגישת נתונים הם מרכיב חיוני בכל מאגר ידע ציבורי. מדיניות ממשק יציב (באנגלית: Stable Interface Policy) מגדירה אילו ערבויות ניתנות ואינן ניתנות על ידי צוות הפיתוח של ויקינתונים לגבי היציבות של פורמטים וממשקי API שמסופקים על ידי ויקיבייס (Wikibase) כפי שנפרסו באתר www.wikidata.org.

הגדרות

סעיף זה מגדיר כמה מונחים מכריעים המשמשים במסמך זה.

• צרכן: תוכנה הקוראת ומפרשת נתונים המתקבלים מויקינתונים.
• לקוח: תוכנה הקוראת לממשקי API ציבוריים של ויקינתונים. לקוחות הם בדרך כלל גם צרכנים של נתונים.
• תואם לקוח/צרכן: לקוח או צרכן העומדים במפרט של הפורמטים והפרוטוקולים הבסיסיים שבהם הוא משתמש. לדוגמה, צרכן תואם שקורא נתוני JSON תואם את מפרט JSON, ויקבל כל קידוד המותר על פי מפרט JSON (RFC 7159). לקוח תואם המשתמש ב-API אינטרנט יתאים למפרט HTTP וכו'.
• לקוח/צרכן ה-מתנהג היטב: לקוח או צרכן (תואם) אשר מיושם ב-robust ו-forward-compatibility דרך, תוך התחשבות במפורש בערבויות ובמגבלות המפורטות במסמך זה. לדוגמה, לקוח שמתנהג היטב לא יישבר כאשר הוא נתקל בסוג נתונים חדש.
• שינוי שובר: שינוי ב-API או בפורמט נתונים שמפר ערבויות שניתנו או הנחה רחבה בעבר. שינויי שבירה כוללים הסרה של פונקציות API, פרמטרים או שדות נתונים ושינויים בפירוש או בפורמט של פרמטרים או שדות נתונים.
• שינוי משמעותי: שינוי ב-API או בפורמט נתונים שיועיל ללקוחות או לצרכנים להסתגל אליו, אך לא ישבור לקוח או צרכן שמתנהגים היטב. שינויים משמעותיים כוללים במיוחד תוספות, כגון הכנסת סוגי נתונים חדשים או סוגי ישויות, או הכללת מידע נוסף בפלט הנתונים. ראו הרחבה למטה.
• שינוי בלתי משמעותי: שינוי ב-API או בפורמט נתונים שלא צפוי להשפיע על לקוח שמתנהג היטב. שינויים בלתי משמעותיים כוללים שינויים ברווח הלבן מחוץ ליטרלים וכן את סדר השדות באובייקט JSON.
• ממשק יציב: ממשק API או פורמט נתונים שעבורם יוכרזו שינויים קלים ומשמעותיים בהתאם למדיניות שלהלן. אילו ממשקים נחשבים ליציבים מוגדרים ב-ממשקים יציבים בהמשך מסמך זה.

מדיניות התראות

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

• שינויים שוברים בממשקים יציבים יוכרזו מראש ברשימות התפוצה הרלוונטיות (wikidata-tech, wikidata ו-pywikibot) וב-מזנון. ההודעה תתפרסם בדרך כלל ארבעה שבועות לפני, אך לא פחות משבועיים לפני פריסת השינוי ב-https://www.wikidata.org/. השינוי יהיה זמין לבדיקה לפחות שבועיים לפני הפריסה ב-https://test.wikidata.org/. הודעות כאלה יופיעו בשורת הנושא את המילה BREAKING.
• שינויים משמעותיים בממשקים יציבים יפורסמו ברשימות התפוצה הרלוונטיות (wikidata-tech, wikidata ו-pywikibot) ובמזנון. ההודעה תתפרסם בדרך כלל לפחות שבועיים מראש, אך לא פחות משבוע לאחר פריסת השינוי ב-https://www.wikidata.org/. השינוי בדרך כלל יהיה זמין לבדיקה לפחות שבועיים לפני הפריסה באתר https://test.wikidata.org/.
• שינויים לא משמעותיים בממשקים יציבים בדרך כלל לא יוכרזו.
• ייתכן שלא יוכרזו שינויים בממשקים לא יציבים, גם אם הם מפרים שינויים.
• שינויים משמעותיים במדיניות זו יפורסמו ברשימות התפוצה הרלוונטיות (wikidata-tech ו-wikidata) ובמזנון תוך שבוע מביצוע השינוי.

הרחבה

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

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

באופן דומה, bindings כגון ייצוג JSON של מודל הנתונים של ויקיבייס מתוכננים להיות ניתנים להרחבה. ניתן להוסיף מבני נתונים בכל מקום המתאים מבחינה תחבירית כל עוד הם אינם משנים את המשמעות של שדות או מבני נתונים קיימים, וכל עוד הוספתם אינה מפרה כל ערבויות לגבי מבני הנתונים המכילים. זה בא בעקבות הרעיון של עקרון ההחלפה של ליסקוב: מה שהובטח לגבי מבנה נתונים לפני התוספת עדיין צריך להיות מובטח לאחר התוספת.

אם לא ניתנות הבטחות מפורשות לגבי המבנה והתוכן של מבנה נתונים, העקרונות הבאים צריכים לתת הנחיות לגבי האם יש לראות בשינוי כשינוי שובר:

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

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

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

במבנים דמויי DOM המבוססים על אלמנטים מקוננים עם מאפיינים, כמו ש-XML הוא, הוספת תכונה לא נחשבת לשינוי שבירה, כל עוד התכונה החדשה לא משנה את הפרשנות של שדות אחרים במבנה (וגם לא בשום מבנה שמסביב). הוספת סוג חדש של אלמנט לאלמנט אב גם לא נחשבת לשבירה, אם אלמנט האב הזה הוא הטרוגני ומתנהג בעצם כמו מפה. עם זאת, אם אלמנט האב מוגדר או משתמע כרשימה הומוגנית של סוג מסוים של אלמנט צאצא, הוספת סוג אחר של אלמנט נחשבת לשינוי שבירה.

עבור פורמטי נתונים המאפשרים ריווח שמות, כמו ש-XML עושה, צרכנים יכולים להתעלם משמות (שמות מאפיינים, שמות אלמנטים) השייכים למרחב שמות שלא הוזכר במפורש במפרט של פורמט הנתונים. הוספה ושינויים במבני נתונים ממרחבי שמות אחרים אינם נחשבים לשבירת שינויים.

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

פורמטי נתונים יציבים

סעיף זה מפרט את פורמטי הנתונים שאנו מחשיבים יציבים. פורמטים אלה של נתונים כפופים למדיניות ההתראות לעיל.

ה-מיפוי RDF של מודל הנתונים של ויקיבייס (Wikibase), כפי שמשמש ב-RDF dumps כמו גם בממשק הנתונים המקושרים ובשירות השאילתות, נחשב לפורמט נתונים יציב. אוצר המילים של ויקיבייס מוגדר רשמית על ידי http://wikiba.se/ontology. כל שינוי במבנה או בפרשנות המיפוי כפוף למדיניות ההודעות הנ"ל. בהתאם לעקרונות הכלליים של RDF, מידע נוסף המוכנס בכל עת, בכל מקום, על כל נושא, אינו נחשב לשינוי שבירה.

ה-JSON binding של מודל הנתונים של ויקיבייס (Wikibase) כפי שמשמש ב-JSON dumps, עם ה-API של האינטרנט ועם ממשק הנתונים המקושרים, נחשב לפורמט נתונים יציב. כל שינוי במבנה או בפרשנות המיפוי כפוף למדיניות ההודעות הנ"ל. בעקבות האופי הגמיש של JSON, הוספת שדות לאובייקטי JSON אינה נחשבת לשינוי שבירה. צרכנים המתנהגים היטב צריכים להיות מוכנים להתעלם מתחומים נוספים כאלה.

ממשקי API ציבוריים יציבים

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

Wikibase Web API הנגיש באמצעות https://www.wikidata.org/w/api.php נחשב לממשק יציב. שינויים בפרמטרים, בפעולה או במבנה הנתונים המוחזרים כפופים למדיניות ההודעות לעיל.

The Wikibase REST API is considered a stable interface. Changes to the parameters, operation, or returned data structure are subject to the above notification policy.

ממשק נתונים מקושרים הנגיש דרך https://www.wikidata.org/wiki/Special:EntityData ו-https://www.wikidata.org/entity/... נחשב לממשק יציב. שינויים בפרמטרים, בפעולה או במבנה הנתונים המוחזרים כפופים למדיניות ההודעות לעיל.

שירות שאילתות ויקינתונים הנגיש דרך https://query.wikidata.org/ נחשב לממשק יציב. הוא מספק נקודת קצה SPARQL מלאה. שינויים בפרמטרים, בפעולה או במבנה הנתונים המוחזרים כפופים למדיניות ההודעות לעיל.

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

כדי לאפשר אינטגרציה טובה יותר של גאדג'טים, hooks JavaScript המתועדים בקובץ hooks-js.md שנמסר יחד עם קוד המקור של ויקיבייס נחשבים ליציבים.

אנו מכירים בכך שכלי צד שלישי ב-Cloud VPS ו-Toolforge עשויים להסתמך על סכימת מסד הנתונים של ויקיבייס. בשל כך, שינויים בטבלאות ובשדות הזמינים כפופים למדיניות ההודעות לעיל. עם זאת, שימו לב שסכימת מסד הנתונים אינה מתוכננת להיות API ציבורי, ופחות תשומת לב ניתנת לתאימות לאחור.

ממשקים בלתי יציבים

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

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

תוכן גרסה גולמי כמוחזר על ידי MediaWiki core API אינו נחשב לממשק יציב, מכיוון שהוא משתמש בייצוג הפנימי של התוכן, בדיוק כמו השלכות נתוני XML. תוכן גרסה גולמי מוחזר משאילתות API כגון api.php?action=query&prop=revisions&titles=Q42&rvprop=timestamp|user|comment|content.

קוד PHP של Wikibase הוא לא נחשב לממשק יציב. למרות שפרויקט ויקיבייס מספק כעת מהדורות רשמיות, wikidata.org עדיין מקבלת פריסה מתגלגלת של קוד ויקיבייס. לכן אין נקודת זמן שבה ניתן להניח שכל מחלקה או ממשק PHP נתון נשאר יציב.

קוד JavaScript של Wikibase הוא לא נחשב לממשק יציב. למרות שפרויקט ויקיבייס מספק כעת מהדורות רשמיות, wikidata.org עדיין מקבלת פריסה מתגלגלת של קוד ויקיבייס. לכן אין נקודת זמן שבה ניתן להניח שקוד JavaScript יישאר יציב. המשמעות היא ש-גאדג'טים לא יכולים לסמוך על קוד JavaScript כדי להישאר יציבים.

מבנה HTML DOM שנוצר על ידי ויקיבייס לא נחשב לממשק יציב. המשמעות היא שגאדג'טים לא יכולים לסמוך על מבנה ה-DOM כדי להישאר יציבים.

תצפית

סעיף זה מספק מידע על שיפורים שמתוכננים או נשקלים לעתיד.

איגוד JSON צריך להיות בעל גרסה (באמצעות מוסכמה גרסאות סמנטיות), כדי שהצרכנים ידעו לאילו מבנים לצפות, וכיצד לפרש אותם. ראו phab:T92961.

קוד JavaScript של ויקיבייס צריך להצביע על ממשקים יציבים שניתן להשתמש בהם בבטחה על ידי גאדג'טים.

ויקיבייס צריך לספק כמה הבטחות בסיסיות לגבי מבנה ה-HTML DOM שהוא יוצר, כך שגאדג'טים יוכלו ליצור אינטראקציה בביטחון עם ה-DOM.

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

היסטוריה

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

• 2025-02-XX: [הודעה על שינוי שובר] גרף שירות שאילתות ויקינתונים מפוצל זמין בהפקה; שאילתות של ישויות אקדמיות דורשות העברה עד מרץ 2025 ​​הוכרז ב-2024-09-03
• 2024-11-13: [הודעה על שינויים שוברים] wbformatvalue API כבר לא מקבל את רוב האפשרויות הוכרז ב-2024-11-13
• 2024-07-15: [הודעה על שינויים משמעותיים] קוד שפה חדש של מונח "מול" בויקינתונים. הוכרז ב-2024-07-22
• 2024-07-02: [הודעה על שינויים משמעותיים] [DOT] שינויים קרובים בויקיבייס: סוג הנתונים של סכימת הישויות (EntitySchema). הוכרז ב-2024-06-19
• 2024-02-19: [הודעה על שינויים משמעותיים] שינויים קרובים למודולי API של ויקיבייס: הוספת פרמטרים חדשים. הוכרז ב-2024-02-19
• 2024-01-24: [הודעה על שינויים שוברים] חושים ריקים / רשימות טפסים מצגת בגיבויי יחידות מילוניות (Lexeme Dumps). הוכרז ב-2024-01-24, יצא לפועל ב-2024-01-08
• 2023-05-18: [הודעה על שינויים שוברים] תוויות ישויות נוספו לסיכומי עריכה מפורחים בבקשות API. הוכרז ב-2023-05-04
• 2023-05-18: [הודעה על שינויים שוברים] חוסר עקביות בתגובה של מודול שאילתת API של `list=wbsubscribers`. הוכרז ב-2023-05-04
• 2023-05-17: [הודעה על שינויים שוברים] שינויים במודול ה-API של wblistentityusage. הוכרז ב-03-05-2023
• 2022-07-26: פרמטר חדש של פרופיל חיפוש במודול ה-API של Wikidata wbsearchentities. הוכרז ב-2022-07-26
• 2021-09-06: שינוי שובר בממשק ה-API של האינטרנט: נורמליזציה של ערכי נתונים בשמירת עריכה. הוכרז ב-2021-08-23
• 2021-05-27: טפסי ויקינתונים ללא הצהרות משתמשים במערך JSON ריק במקום באובייקט JSON ריק. הוכרז ב-2021-05-27
• 2021-03-03: שינוי שובר בממשק ה-API של האינטרנט: תגובת wbeditentity משתמשת כעת בסריאליזציה רגילה. (שבירה רק עבור ישויות MediaInfo, משמעותי עבור סוגים אחרים של ישויות.) הוכרז ב-2021-02-08
• 2020-08-05: שינוי חדש בממשק ה-API של האינטרנט: הסרת התנהגות של מונחי דף מיוחדים ב-Repo Wiks, השתמש במקום זאת ב-entityterms. הוכרז ב-2020-07-15
• 2020-04-16: הוצאה משימוש של צומת ריק במודל WDQS & Wikibase RDF. הוכרז ב-2020-04-16
• 2019-05-06: שינוי שובר בממשק ה-API של התוסף WikibaseQualityConstraints: ערך ברירת המחדל של פרמטר status כולל כעת את סטטוס האילוץ החדש של "הצעה". הוכרז ב-2019-04-17
• 2019-04-30: שינוי שובר בסריאליזציה של JSON: מיכלים ריקים בפלטי JSON יסודרו כאובייקט ריק במקום מערך ריק. הוכרז ב-2019-04-02
• 2018-11-16: שינוי שובר לייצוג RDF: ה"בטא" בקידומת האונטולוגיה נמחקת. הוכרז ב-2018-10-17
• 2018-02-26: שינוי שובר בממשק ה-API של התוסף WikibaseQualityConstraints: ערך ברירת המחדל של פרמטר status השתנה. הוכרז ב-2018-01-29
• 2017-12-18: שינוי שובר בממשק ה-API של התוסף WikibaseQualityConstraints: פלט wbcheckconstraints אינו כולל עוד פרט וdetailHTML של אילוצים. הוכרז ב-2017-11-20
• 2017-10-10: שינוי שובר בממשק ה-API של התוסף WikibaseQualityConstraints: wbcheckconstraints מחזיר את התוצאות שלו בפורמט פלט חדש. הוכרז ב-2017-09-14
• 2016-11-25: שינוי חדש בממשק ה-API, JSON binding ומיפוי RDF: הגבול העליון והתחתון של ערכי הכמות הופכים לאופציונליים. הוכרז ב-2016-11-04
• 2015-09-09: שינוי שובר ייצוג XML של פלט API. הוכרז ב-2015-08-27
• 2015-06-15: שינוי שובר בסידרה של JSON, מחליף את type:claim עם type:statement. הוכרז ב-2015-06-15
• 2014-08-22: שינוי שובר ל-Special:Export לשימוש באותו פלט JSON כמו ה-API של האינטרנט. הוכרז ב-2014-08-15
• 2013-09-10: שינוי שובר בפלט ה-API של האינטרנט: מזהי Q-ID הם כעת באותיות רישיות. הוכרז ב-2013-09-10
• 2013-06-16: שינוי שובר בממשק ה-API של האינטרנט: wbeditentity דורש כעת שהפרמטר 'id' או הפרמטר 'חדש' יוגדרו. הוכרז ב-2013-06-16.