بيانات التغيير الوصفية (.openspec.yaml)

الحقول المدعومة وقواعد التحقق للبيانات الوصفية المخزنة مع كل تغيير.

الموقع

يحتفظ كل تغيير ببياناته الوصفية في openspec/changes/<change-name>/.openspec.yaml، بجوار مخرجاته. عند إنشاء تغيير يُكتب الملف مع تعبئة schema و created.

الحقول

المفتاح	النوع	مطلوب	التأثير
schema	string	نعم	مخطط سير العمل الذي يتبعه هذا التغيير
created	string, YYYY-MM-DD	لا	يسجل تاريخ إنشاء التغيير
goal	string	لا	يسجل ما ينوي التغيير القيام به
affected_areas	list of strings	لا	يسجل المجالات التي يتوقع التغيير أن يمسها
initiative	map: store و id	لا	يسجل المبادرة التي ينتمي إليها هذا التغيير
skip_specs	boolean	لا	يعلن أن التغيير لا ينتج فروقات للمواصفات، لذا فإن صفر فروقات يعد صالحاً
retire_capabilities	boolean	لا	يفوض الأرشفة بحذف قدرة يفرغها هذا التغيير

schema

مخطط سير العمل الذي يتبعه هذا التغيير. يتم تعيينه عند إنشاء التغيير ويتغلب على إعدادات المشروع، لذا يحتفظ التغيير بمخططه حتى لو تغير openspec/config.yaml لاحقاً. شغّل openspec schemas لسرد أسماء المخططات المتاحة.

initiative

المبادرة التي ينتمي إليها هذا التغيير، كمعرف متجر ومعرف مبادرة، كلاهما بصيغة kebab-case:

initiative:
  store: platform-specs
  id: unify-billing

المفاتيح الأخرى غير store و id يتم رفضها. لا يوجد أمر يقرأ الرابط حالياً.

skip_specs

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

retire_capabilities

يفوض الأرشفة بإنهاء قدرة. عندما تُزيل فروقات REMOVED في هذا التغيير آخر متطلب لدى القدرة، تحذف الأرشفة المواصفة الرئيسية لتلك القدرة بدلاً من التوقف. توجد هذه العلامة لأن الحذف لا يمكن استرجاعه إلا من git، لذا تبقى قراراً يعود للمؤلف.

مفاتيح الامتداد

المفتاح ذو المستوى الأعلى الذي يبدأ بـ x- صغير هو ملكك، لبيانات تحتفظ بها أداة أخرى أو فريقك بجوار التغيير، مثل معرف متتبع أو مالك:

schema: spec-driven
x-tracker: SB-5497
x-jiraKey: ABC-1
x-owner:
  team: payments

• الاسم: بادئة x- صغيرة يتبعها حرف واحد على الأقل، دون أي مسافات بيضاء في أي مكان. أي حالة أو تهجئة تصلح بعد البادئة، لذا فإن x-jiraKey و x-trackerID مؤهلان. أما X-Tracker و x- وحده و x- tracker فغير مؤهلة، وتُبلغ كمفاتيح غير معروفة.
• القيمة: أي قيمة YAML. لا يقرأ OpenSpec هذه القيمة ولا يتحقق منها، وهي لا تغير أي سلوك.
• النطاق: المستوى الأعلى فقط. مفتاح x- داخل initiative لا يزال مرفوضاً، مثل أي مفتاح آخر هناك.
• التحقق: مفاتيح الامتداد لا تُبلغ أبداً كغير معروفة، لذا ينجح الأمر openspec validate --strict على تغيير يحملها.
• الأرشفة: ينتقل الملف مع التغيير دون تغيير، بما في ذلك مفاتيح الامتداد.

مثال

ملف .openspec.yaml مُعبأ:

schema: spec-driven
created: 2026-08-14
goal: Add magic-link login to the API
affected_areas:
  - auth
  - api

التحقق

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

على عكس config.yaml، القيم السيئة لا تُسقط أبداً مع تحذير. خطأ البيانات الوصفية يوقف الأمر.

• مفاتيح المستوى الأعلى غير المعروفة: يتجاهلها OpenSpec. تُقر status و instructions و validate و archive بأنها بلا تأثير. يحمل ناتج JSON التحذير في نتيجته المهيكلة. مفاتيح الامتداد ليست غير معروفة ولا تُبلغ أبداً.
• التحقق الصارم: يعتبر openspec validate --strict تحذير المفتاح غير المعروف فشلاً. التغيير الذي تكون مفاتيحه الإضافية الوحيدة هي مفاتيح امتداد ينجح.