ويكي بيانات:سياسة الواجهة المستقرة

الواجهات العامة المستقرة للوصول إلى البيانات عنصر حاسم في أي مستودع للمعرفة العامة، تحدد سياسة الواجهة المستقرة هذه الضمانات التي يتم ولا يتم تقديمها بواسطة فريق تطوير ويكي بيانات بشأن استقرار تنسيقات البيانات و APIs المقدمة من قاعدة الويكي كما تم نشرها في www.wikidata.org.

تعريفات

يحدد هذا القسم بعض المصطلحات الأساسية المستخدمة في هذا المستند.

• المستهلك: برنامج يقوم بقراءة وتفسير البيانات المستلمة من ويكي بيانات.
• العميل: برنامج يقوم باستدعاء APIs ويكي بيانات العامة، عادة ما يكون العملاء مستهلكين للبيانات.
• العميل/المستهلك المتوافق: عميل أو مستهلك يلتزم بمواصفات التنسيقات والبروتوكولات الأساسية التي يستخدمها، على سبيل المثال، يتقيد المستهلك المطابق الذي يقرأ بيانات JSON بمواصفات JSON، وسيقبل أي تشفير تسمح به مواصفات JSON (RFC 7159)، سيتوافق العميل المتوافق مع API الويب مع مواصفات HTTP، وما إلى ذلك.
• العميل/المستهلك حسن التصرف: عميل أو مستهلك (متوافق) يتم تنفيذه بطريقة توافقية مستقبلية قوية، مع الأخذ بعين الاعتبار الضمانات والقيود المنصوص عليها في هذه الوثيقة، على سبيل المثال، لن ينكسر عميل حسن التصرف عند مواجهة نوع بيانات جديد.
• كسر التغير: تغيير في 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) وفي نقاش المشروع في غضون أسبوع من إجراء التغيير.

القابلية للتوسع

يشرح هذا القسم الطريقة التي يكون بها نموذج البيانات وتنسيقات البيانات القابلة للتوسعة، يجب على المستهلكين النظر في هذه المعلومات لاستيعاب الهياكل غير المعروفة التي قد يواجهونها في البيانات.

تم تصميم نموذج بيانات قاعدة الويكي ليكون قابلا للتوسع، على وجه الخصوص، من الممكن إدخال أنواع البيانات الجديدة وأنواع الكيانات الجديدة; ولذلك ينبغي أن يكون العملاء والمستهلكون حسني التصرف مستعدين لمجابهة أنواع البيانات وأنواع الكيانات غير المعروفة، والتعامل معها بأمان، بطريقة مناسبة للاستخدام في متناول اليد، في العديد من الحالات، من المناسب تجاهل مثل هذه البنى غير المعروفة.

وبالمثل، فإن الروابط مثل تمثيل JSON لنموذج بيانات قاعدة الويكي مصممة بحيث تكون قابلة للتوسع، يمكن إضافة هياكل البيانات في أي مكان مناسب من الناحية النحوية طالما أنها لا تقوم بتعديل معنى الحقول أو هياكل البيانات الموجودة مسبقا، وطالما أن إضافتها لا تؤدي إلى كسر أية ضمانات تتعلق بهياكل البيانات المحتوية، هذا يتبع فكرة مبدأ استبدال ليسكوف: ما كان مضمونا حول بنية البيانات قبل الإضافة يظل مضمونا بعد الإضافة.

في حالة عدم تقديم ضمانات صريحة فيما يتعلق بهيكل ومحتويات بنية البيانات، يجب أن تعطي المبادئ التالية إرشادات بشأن ما إذا كان التغيير يعتبر تغييرا:

في الهياكل القائمة على القوائم (العروفة أيضا باسم المصفوفات) والخرائط (العروفة أيضا باسم رمز الرقم أو الكائنات)، مثل JSON، فإن إضافة مفتاح إلى خريطة لا يُعتبَر كسر تغيير، طالما أن الحقل الجديد لا يغير تفسير أي من الحقول الأخرى في الهيكل (ولا في أي هيكل محيط)، ومع ذلك، فإن إضافة هيكل إلى قائمة أو مجموعة يُعتبَر كسر تغيير إذا خالف الافتراضات حول نوع الهيكل المتوقع في القائمة، أو تحت أي شروط سيتم تضمين البنية في القائمة.

بموجب الاتفاقية، تُعتبَر القوائم متجانسة، ويجب أن تحتوي فقط على نوع واحد من العناصر، ما لم يُنَص على خلاف ذلك، لذلك; فإن إضافة بنية بيانات إلى قائمة هو كسر تغيير إذا لم يكن هيكل البيانات هذا متوافقا مع نوع البنية التي تم تعريفها أو ضمانها مسبقا لاحتوائها.

في تمثيل البيانات المجدولة، مثل مخطط قاعدة البيانات العلائقي، لا تُعتبَر إضافة الحقول كسر تغيير، يُعتبَر أي تغيير في تفسير حقل، وكذلك إزالة الحقول، كسرا، تغييرات الفهارس الفريدة الموجودة أو المفاتيح الأساسية كسر تغييرات، تغييرات الفهارس الأخرى وكذلك إضافة الفهارس الجديدة ليست كسر تغييرات.

في الهياكل المشابهة لـ DOM القائمة على عناصر مكتوبة متداخلة ذات سمات، مثل XML، فإن إضافة سمة لا تُعتبَر كسر تغيير، طالما أن السمة الجديدة لا تغير تفسير أية حقول أخرى في البنية (ولا في أي هيكل محيط)، إن إضافة نوع جديد من العناصر إلى عنصر رئيسي لا يُعتبَر أيضا كسرا، إذا كان هذا العنصر الأصل غير متجانس ويعمل أساسا مثل الخريطة، ومع ذلك، إذا تم تعريف العنصر الأصل أو ضمنيا إلى قائمة متجانسة لنوع معين من العنصر الطفل، فإن إضافة نوع آخر من العنصر يُعتبَر كسر تغيير.

بالنسبة لتنسيقات البيانات التي تسمح بتحديد النطاقات، مثل XML، يمكن تجاهل أسماء (أسماء السمات، أسماء العناصر) التي تنتمي إلى نطاق غير مذكور بشكل صريح بواسطة مواصفات تنسيق البيانات من قبل المستهلكين، لا تُعتبَر الإضافة والتغييرات في هياكل البيانات من النطاقات الأخرى كسر تغييرات.

فى المقابل، فإن التعديلات التالية هي أمثلة كسر التغييرات، وبالتالي لا يمكن استخدامها لتوسيع صيغة: إزالة الحقول، وتغييرات نوع أو صيغة القيمة البدائية، وتغييرات تفسير أو دور حقل البيانات، وكذلك التغييرات على نوع عنصر مجموعة كما هو موضح أعلاه.

صيغ البيانات المستقرة

يسرد هذا القسم صيغ البيانات التي نعتبرها مستقرة، تخضع صيغ البيانات هذه لما ورد في للسياسة الإخطار أعلاه.

تعيين RDF لنموذج بيانات قاعدة الويكي كما هو مستخدم في تفريغات RDF وكذلك في واجهة البيانات المرتبطة وخدمة الاستعلام، يُعتبَر تنسيق بيانات ثابت، يتم تعريف المفردات في قاعدة الويكي رسميا بواسطة http://wikiba.se/ontology، تخضع أية تغييرات في هيكل أو تفسير تعيين لسياسة الإشعار أعلاه، وفقًا للمبادئ العامة لـRDF، لا تُعتبَر المعلومات الإضافية التي يتم تقديمها في أي وقت، في أي مكان، حول أي موضوع، كسر تغيير.

JSON الملزمة لنموذج بيانات قاعدة الويكي كما هو مستخدم في تفريغات RDF، مع API الويب، ومع واجهة البيانات المرتبطة، يُعتبَر تنسيق بيانات ثابت، تخضع أية تغييرات في هيكل أو تفسير التعيين لسياسة الإشعار أعلاه، باتباع الطبيعة المرنة لـ JSON، تُعتبَر إضافة الحقول إلى كائنات JSON غير ذلك، يجب أن يكون المستهلكون ذوو السلوك الجيد على استعداد لتجاهل هذه الحقول الإضافية.

APIs العامة المستقرة

يسرد هذا القسم الواجهات التي نعتبرها مستقرة، تخضع هذه الواجهات لما ورد في للسياسة الإخطار أعلاه.

تُعتبَر API الويب لقاعدة الويكي التي يمكن الوصول إليها عبر https://www.wikidata.org/w/api.php واجهة مستقرة، تخضع التغييرات التي يتم إجراؤها للوسائط أو العمليات أو بنية البيانات المرتجعة لسياسة الإشعار أعلاه.

تُعتبَر واجهة البيانات المرتبطة التي يمكن الوصول إليها عبر https://www.wikidata.org/wiki/Special:EntityData وhttps://www.wikidata.org/entity/... واجهة مستقرة، تخضع التغييرات التي يتم إجراؤها للوسائط أو العمليات أو بنية البيانات المرتجعة لسياسة الإشعار أعلاه.

تُعتبَر خدمة استعلام ويكي بيانات التي يمكن الوصول إليها عبر https://query.wikidata.org/ واجهة مستقرة، توفر كامل نقطة نهاية سباركل، تخضع التغييرات التي يتم إجراؤها للوسائط أو العمليات أو بنية البيانات المرتجعة لسياسة الإشعار أعلاه.

تُعتبَر مكتبة لوا قاعدة الويكي للويكيات العميلة واجهة مستقرة، تخضع التغييرات التي يتم إجراؤها للوسائط أو العمليات أو بنية البيانات المرتجعة لسياسة الإشعار أعلاه.

To allow better gadget integration JavaScript hooks documented in the hooks-js.md file delivered together with Wikibase source code are considered stable.

نحن نقر بأن أدوات الطرف الثالث في مختبرات ويكيميديا ومختبرات الأدوات قد تعتمد على مخطط قاعدة بيانات قاعدة الويكي، ولهذا السبب; تخضع التغييرات التي يتم إجراؤها على الجداول والحقول المتاحة لسياسة الإشعار أعلاه، ومع ذلك، لاحظ أن مخطط قاعدة البيانات غير مصمم ليكون API عامة، ويعطى أقل اعتبار للتوافق مع الإصدارات السابقة.

الواجهات غير المستقرة

يسرد هذا القسم بعض الواجهات التي لا نعتبرها مستقرة في الوقت الحالي ، وبالتالي قد تتغير بطرق غير متوافقة دون إخطار.

لا تُعتبَر تفريغات ميدياويكي XML واجهة مستقرة، تحتوي تفريغات ميدياويكي XML على البيانات الأولية لمراجعات الصفحات في تمثيلها الداخلي، التمثيل الداخلي لكيانات قاعدة الويكي ليس واجهة مستقرة، لقد تغيرت بشكل ملحوظ في الماضي، وقد تتغير مرة أخرى في المستقبل، قد توجد عدة تمثيلات مختلفة لمحتوى قاعدة الويكي في نفس ملف تفريغ XML.

لا يُعتبَر محتوى المراجعة الأولية كما تم إرجاعه بواسطة API نواة ميدياويكي واجهة مستقرة; حيث إنه يستخدم التمثيل الداخلي للمحتوى، تماما مثل عمليات تفريغ XML، يتم إرجاع محتوى المراجعة الأولية من استعلامات API مثل api.php?action=query&prop=revisions&titles=Q42&rvprop=timestamp|user|comment|content.

لا يُعتبَر كود PHP قاعدة الويكي واجهة مستقرة; حيث بما أنه لا توجد حاليا أية إصدارات رسمية من ملحق قاعددة الويكي، مجرد نشر متدرج إلى wikidata.org، فلا توجد نقطة في الوقت يمكن افتراض أن أي فئة أو واجهة PHP تبقى مستقرة.

لا يُعتبَر كود جافا سكريبت قاعدة الويكي واجهة مستقرة; نظرا لعدم وجود أية إصدارات رسمية حاليا لامتداد قاعدة الويكي، وهو مجرد نشر متدرج إلى wikidata.org، فلا توجد نقطة زمنية يمكن افتراض بقاء كود جافا سكريبت فيها مستقرة: يعني هذا أن الأدوات لا يمكنها الاعتماد على كود جافا سكريبت لتبقى مستقرة.

لا يُعتبَر HTML DOM structure الذي تم إنشاؤه بواسطة قاعدة الويكي واجهة مستقرة: هذا يعني أن الأدوات لا يمكنها الاعتماد على بنية DOM لتبقى مستقرة.

الآفاق

يقدم هذا القسم معلومات حول التحسينات التي تم التخطيط لها أو التفكير فيها في المستقبل.

يجب أن يكون إصدار JSON ملزما (باستخدام الاصطلاح الإصدار الدلالي); لذا فإن المستهلكين يعرفون ما هي الهياكل التي يجب توقعها وكيفية تفسيرها، انظر phab:T92961.

يجب أن يشير رمز جافا سكريبت قاعدة الويكي إلى واجهات ثابتة يمكن استخدامها بواسطة الأدوات بثقة.

يجب أن تقدم قاعدة الويكي بعض الضمانات الأساسية حول بنية HTML DOM التي تنشئها، بحيث يمكن للأدوات التفاعل بثقة مع DOM.

بالنسبة لتثبيتات الطرف الثالث، يجب أن تكون لقاعدة الويكي إصدارات منتظمة (باستخدام الاصطلاح الإصدار الدلالي) مثل ميدياويكي، سيواصل ويكي بيانات استخدام عمليات النشر المتدرجة لأحدث إصدار تطوير.

التاريخ

يسرد هذا القسم التغييرات السابقة والمحددة للفواصل، قد تكون قائمة التغييرات السابقة قبل تنفيذ هذه السياسة غير مكتملة، يجب سرد كل تغيير مع تاريخ الإعلان وتاريخ النشر، يُرافَق بشكل مثالي مع وصلة للإعلان وأية تذاكر ذات صلة.

• 2013-06-16: كسر تغيير API الويب:يتطلب wbeditentity الآن تعيين إما الوسيط 'id' أو الوسيط 'new'. أُعِلن في 2013-06-16.
• 2013-09-10: كسر تغيير مخرجات API الويب: أصبحت معرفات Q الآن بأحرف كبيرة. أُعِلن في 2013-09-10
• 2014-08-22: كسر تغيير Special:Export لاستخدام نفس مخرجات JSON مثل API الويب API. أُعِلن في 2014-08-15
• 2015-06-15: كسر تغيير تسلسل JSON، استبدل type:claim بـtype:statement. أُعِلن في 2015-06-15