जहाँ उद्धरण चिह्न हटाते ही मान बदल जाता है
बिना उद्धरण चिह्न वाले मान का प्रकार YAML खुद तय करता है, और गड़बड़ी यहीं से शुरू होती है।
version: 1.10 संख्या के रूप में पढ़ा जाता है और 1.1 बन जाता है — आख़िरी शून्य ग़ायब, और वर्ज़न का मतलब ही बदल गया। zip: 01234 भी संख्या 1234 बन जाता है और शुरुआत का शून्य गिर जाता है। पिन कोड, कर्मचारी संख्या और फ़ोन नंबर जैसे मान, जहाँ शुरुआती शून्य मायने रखता है, हमेशा "01234" की तरह उद्धरण चिह्न में लिखें।
12:30 जैसा समय और no, yes, on इस टूल में स्ट्रिंग ही रहते हैं। पर पुराने नियमों पर चलने वाले पार्सर, जैसे PyYAML और Ruby, no को असत्य पढ़ते हैं — इसी वजह से देश कोड NO का false बन जाना मशहूर है। अगर कॉन्फ़िग कई टूल से होकर गुज़रती है, तो इन शब्दों को भी उद्धरण चिह्न में रख दें।
इंडेंट के नियम
इंडेंट सिर्फ़ स्पेस से करें। टैब सीधे सिंटैक्स त्रुटि है। एडिटर टैब डालता हो तो YAML फ़ाइलों के लिए उसे स्पेस पर कर लें।
एक ही स्तर की प्रविष्टियाँ बिलकुल एक सीध में होनी चाहिए। एक कॉलम का फ़र्क़ भी वहीं पढ़ना रोक देता है। यह टूल बताता है कि वह किस पंक्ति और कॉलम पर रुका।
ऐंकर और मर्ज की
&नाम से किसी हिस्से को नाम मिलता है और *नाम से वह वापस चिपक जाता है। साथ में <<: लगा दें तो वह हिस्सा किसी दूसरे मैप में उड़ेल दिया जाता है।
defaults: &d
retry: 2
image: node
job:
<<: *d
script: testयह टूल मर्ज की को खोल देता है, इसलिए निकलने वाले JSON में job के भीतर retry और image दोनों मिलते हैं। न खोला जाए तो "<<" नाम की एक की बची रह जाती है, जिसका आगे कोई उपयोग नहीं। GitLab CI और Docker Compose की फ़ाइलों में यह लेखन बार-बार दिखता है।
JSON तक पहुँचते-पहुँचते क्या छूट जाता है
टिप्पणियाँ मिट जाती हैं। JSON में टिप्पणी का कोई सिंटैक्स नहीं है, इसलिए कॉन्फ़िग बदलकर उसी फ़ाइल पर सहेजने से पहले लिखी सारी बातें चली जाती हैं। मूल फ़ाइल बचाकर रखें।
कई दस्तावेज़ भी नहीं समाते। किसी फ़ाइल में --- से अलग किए कई दस्तावेज़ हों, तो यह टूल त्रुटि देता है — चुपचाप पहला निकालकर बाक़ी को ग़ायब कर देना ठीक नहीं होता, क्योंकि किसी को पता ही नहीं चलेगा। Kubernetes जैसी बहु-दस्तावेज़ फ़ाइल को अलग-अलग करके एक-एक बदलें।
तारीख़ स्ट्रिंग बन जाती है। YAML तारीख़ को एक प्रकार मानता है, JSON में उसका कोई जोड़ नहीं।
उल्टी दिशा में
JSON से YAML बनाने पर ज़्यादातर उद्धरण चिह्न हट जाते हैं और पढ़ना आसान हो जाता है। पर जिन स्ट्रिंग के आगे शून्य है या जो true जैसी दिखती हैं, उन पर चिह्न बने रहते हैं। वहाँ हटाने से अर्थ बदल जाता, इसलिए बने रहना ही सही है।