परिवर्तन का मेटाडेटा (.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 से पुनर्प्राप्त किया जा सकता है, इसलिए यह लेखक का निर्णय बना रहता है।

Extension keys

लोअरकेस 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 इसे न पढ़ता है न वैलिडेट करता है, और यह किसी व्यवहार को नहीं बदलता।
• स्कोप: केवल टॉप-लेवल। initiative के अंदर x- कुंजी भी वहाँ की किसी अन्य कुंजी की तरह अस्वीकार की जाती है।
• वैलिडेशन: एक्सटेंशन कुंजियाँ कभी अज्ञात के रूप में रिपोर्ट नहीं की जाती हैं, इसलिए उन्हें रखने वाला परिवर्तन 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 अज्ञात-कुंजी चेतावनी को विफलता मानता है। जिस परिवर्तन की केवल अतिरिक्त कुंजियाँ एक्सटेंशन कुंजियाँ हों, वह पास हो जाता है।