JSON से YAML कमांड-लाइन: एक yq कमांड के पीछे के चार जाल

निचोड़: हिंदी और अंग्रेज़ी ट्यूटोरियल में सबसे ज़्यादा मिलने वाली yq -P input.json > output.yaml, yq v4 पर असल में JSON ही बनाती है। YAML चाहिए तो -o=yaml (या -oy) स्पष्ट रूप से लिखना होगा; -P --prettyPrint का छोटा रूप है, जो इंडेंटेशन और ब्लॉक शैली संभालता है, आउटपुट फॉर्मैट नहीं।

JSON को YAML में बदलना कभी भी "फ़ाइल का एक्सटेंशन बदलना" जितना आसान नहीं रहा। असल कीमत चार जगह छिपी है: आउटपुट फॉर्मैट इनपुट एक्सटेंशन तय करता है, उद्धरण के नियम चुपचाप आपकी स्ट्रिंग बदल देते हैं, sequence इंडेंटेशन आगे के टूल को प्रभावित करता है, और yq से गुज़रा बड़ा पूर्णांक हमेशा के लिए परिशुद्धता खो देता है।

1. सबसे लोकप्रिय कमांड को पहले एक बार चला कर देखें

एक साफ मशीन पर yq v4.44.6 इंस्टॉल करें और एक न्यूनतम इनपुट बनाएँ:

复制printf '{"a":1,"b":{"c":2}}' > s.json
yq -P '.' s.json

जो मिलता है वह YAML नहीं, बल्कि इंडेंट किया हुआ JSON है:

复制{
  "a": 1,
  "b": {
    "c": 2
  }
}

अगर आप ट्यूटोरियल के मुताबिक इस कमांड को output.yaml में रीडायरेक्ट करते हैं, तो आपको .yaml एक्सटेंशन वाली एक फ़ाइल मिलती है जिसके अंदर JSON है। हर YAML 1.2 parser इसे खुशी से पढ़ लेता है (YAML 1.2 में JSON सबसेट है — इस समावेश की पूरी व्युत्पत्ति JSON, YAML और XML रूपांतरण की सीमाएँ में दी गई है), इसलिए तुरंत कुछ टूटता नहीं — जिस दिन कोई उसमें टिप्पणी या anchor जोड़ेगा, या CI में yamllint truthy value should be one of की एक पूरी दीवार उगलने लगेगा, उसी दिन जाँच शुरू होगी।

असल में YAML बनाने वाली कमांड वह है जो आउटपुट फॉर्मैट स्पष्ट रूप से बताए:

复制yq -o=yaml '.' s.json
# a: 1
# b:
#   c: 2

2. ऐसा क्यों होता है: एक्सटेंशन आउटपुट फॉर्मैट तय करता है

yq v4 का नियम है "इनपुट फॉर्मैट आउटपुट फॉर्मैट तय करता है"। यह इनपुट फ़ाइल के एक्सटेंशन से फॉर्मैट का अनुमान लगाता है, और -o न होने पर उसी अनुमान को आगे बढ़ा देता है। .json इनपुट → JSON आउटपुट; .yaml इनपुट → YAML आउटपुट; stdin से पढ़ते समय जब कोई एक्सटेंशन नहीं होता, डिफ़ॉल्ट YAML चलता है।

एक ही इनपुट पर चार तरीकों का मापा गया परिणाम:

तीसरी पंक्ति एक बात बताती है: -o=yaml मौजूद होने पर -P हमेशा ज़रूरी नहीं होता, लेकिन वह हानिरहित भी नहीं है — भाग 6 के समय के आँकड़े देखें। चौथी पंक्ति समझाती है कि "ट्यूटोरियल कॉपी करने से काम क्यों चल जाता है": बहुत लोग डेटा पाइप से देते हैं, जो संयोगवश एक्सटेंशन वाली शाखा से बच निकलता है।

इस व्यवहार का व्यावहारिक मतलब और खोल कर कहा जा सकता है। मान लें एक रिपोज़िटरी में configs/prod.json और configs/base.yaml साथ-साथ हैं; तब एक ही yq '.' कमांड दोनों फ़ाइलों पर अलग-अलग फॉर्मैट का आउटपुट देगा। अगर कोई उस आउटपुट को वापस कमिट कर दे, तो diff में मिश्रण दिखेगा: एक फ़ाइल JSON शैली में, दूसरी YAML शैली में। उपाय सीधा है — हर कमांड में -o स्पष्ट लिखें, अनुमान पर मत टिकें।

3. बैच रूपांतरण: तीन शेल तरीके

एक फ़ाइल बदलना तो सिर्फ़ शुरुआत है। कमांड-लाइन पर यह काम करने की असल वजह लगभग हमेशा बैच होती है: एक डायरेक्टरी की सारी कॉन्फ़िगरेशन, सारे API स्नैपशॉट एक साथ YAML में चाहिए।

bash / zsh लूप (सबसे सीधा, एक डायरेक्टरी के लिए):

复制for f in configs/*.json; do
  yq -o=yaml '.' "$f" > "${f%.json}.yaml"
done

find से रिकर्सिव (जब सब-डायरेक्टरी भी चाहिए):

复制find . -name '*.json' -exec sh -c 'yq -o=yaml "." "$1" > "${1%.json}.yaml"' _ {} \;

PowerShell (Windows CI पर):

复制Get-ChildItem *.json | ForEach-Object { yq -o=yaml '.' $_.FullName > ($_.BaseName + '.yaml') }

तीनों तरीकों की एक ही कड़ी पूर्व-शर्त है: पहले पक्का करें कि स्रोत JSON वैध है। रूपांतरण करने वाला टूल parser नहीं है; सिंटैक्स त्रुटि मिलने पर कई कनवर्टर सिर्फ़ एक अस्पष्ट स्थान बताते हैं, वह लाइन-स्तर का विवरण नहीं देते जो एक validator देता है। लूप के अंदर एक गार्ड लगाने की लागत लगभग शून्य है:

复制for f in configs/*.json; do
  jq empty "$f" || { echo "invalid: $f"; continue; }
  yq -o=yaml '.' "$f" > "${f%.json}.yaml"
done

jq empty सिर्फ़ पार्स करता है, कुछ प्रिंट नहीं करता; अवैध JSON पर नॉन-ज़ीरो exit code देता है। set -euo pipefail के साथ मिला कर पूरी पाइपलाइन पहली खराब फ़ाइल पर रुक जाती है, आधे-अधूरे आउटपुट का ढेर नहीं लगाती।

एक और बात ध्यान में रखें: for f in configs/*.json लूप फ़ाइल नाम में स्पेस होने पर सुरक्षित है, क्योंकि "$f" कोट किया गया है; लेकिन अगर कोई फ़ाइल मेल न खाए तो ग्लोब शाब्दिक रूप से configs/*.json बन कर लूप में घुस जाता है। बड़ी रिपोज़िटरी में shopt -s nullglob या find-आधारित तरीका चुनना ज़्यादा सुरक्षित है।

4. चार आउटपुट पैरामीटर, चार अलग-अलग काम

yq की पैरामीटर सूची लंबी है, लेकिन JSON → YAML रास्ते पर असल में याद रखने लायक केवल चार हैं:

मल्टी-डॉक्यूमेंट वाली बात अलग से कहने लायक है। Kubernetes मैनिफ़ेस्ट में परंपरा है कि कई रिसोर्स को --- से अलग किया जाए। JSON array से बनाते समय:

复制yq -P -o=yaml '.[] | splitDoc' --split-exp 'true' kubernetes-list.json

--split-exp के बिना आपको एक YAML sequence मिलता है; इसके साथ हर array तत्व --- से अलग किया हुआ स्वतंत्र दस्तावेज़ बन जाता है। kubectl apply दोनों फ़ाइलें खा लेता है, लेकिन diff की पठनीयता में एक पूरी श्रेणी का अंतर होता है।

5. उद्धरण: छह तरह की स्ट्रिंग जिनमें उद्धरण अनिवार्य है

YAML का प्रकार-अनुमान अंतर्निहित है। कोई स्ट्रिंग मान जो संख्या या boolean जैसा दिखे, उद्धरण के बिना उसे किसी और प्रकार में पार्स कर लिया जाता है। यह सैद्धांतिक जोखिम नहीं है — yq v4.44.6 पर माप कर देखने पर नीचे दी छहों श्रेणियों में अपने आप उद्धरण लग जाते हैं, जो साबित करता है कि parser सचमुच उन्हें ग़लत पढ़ सकता था:

复制printf '{"version":"1.0","enabled":"true","port":"8080","empty":"","colon":"host: value","hash":"v # c","unicode":"端口 8080","ts":"2026-11-03"}' | yq -P -o=yaml '.'

复制version: "1.0"
enabled: "true"
port: "8080"
empty: ""
colon: 'host: value'
hash: 'v # c'
unicode: 端口 8080
ts: "2026-11-03"

परिणाम एक-एक कर के:

आख़िरी वाली सबसे चालाक है। JSON में दिनांक बस एक स्ट्रिंग है; रूपांतरण के बाद वह YAML का दिनांक प्रकार बन जाता है, और कई मॉडल उसे वापस लिखते समय मूल स्ट्रिंग नहीं बल्कि ISO फॉर्मैट का दिनांक ऑब्जेक्ट देते हैं — round-trip संगति टूट जाती है। PyYAML और yq दोनों इन मानों पर उद्धरण लगाना चुनते हैं, जो मानो इस जोखिम को स्वीकार करना है।

साथ ही ध्यान दें, unicode: 端口 8080 लाइन में कोई उद्धरण नहीं लगा — YAML में चीनी और देवनागरी अक्षर सुरक्षित हैं। चिंता का विषय वह नहीं, बल्कि अगले भाग की key-क्रम और परिशुद्धता है। हालाँकि एक सावधानी ज़रूर रखें: अगर आपका एडिटर या टर्मिनल एन्कोडिंग ठीक से नहीं संभालता, तो बहुभाषी स्ट्रिंग के साथ अजीब व्यवहार हो सकता है — LANG में UTF-8 हमेशा पक्का करें।

6. Python और Node के समतुल्य तरीके तथा मापा गया समय

हर मशीन पर yq इंस्टॉल नहीं किया जा सकता (ऑफ़लाइन वातावरण, बंधी हुई CI इमेज, पैकेज मैनेजर रहित Windows)। Python और Node के समतुल्य तरीकों के अपने-अपने डिफ़ॉल्ट जाल हैं। तीनों रास्तों में से किस परिस्थिति में कौन चुनें, उसकी पूरी तुलनात्मक तालिका JSON कमांड-लाइन टूल और एडिटर चयन में है; यह लेख सिर्फ़ JSON → YAML दिशा पर टिका है।

Python + PyYAML (तीन आर्ग्युमेंट, एक भी वैकल्पिक नहीं):

复制import json, yaml

with open("config.json", encoding="utf-8") as f:
    data = json.load(f)

with open("config.yaml", "w", encoding="utf-8") as f:
    yaml.safe_dump(
        data, f,
        default_flow_style=False,  # ब्लॉक शैली, {a: 1, b: 2} नहीं
        allow_unicode=True,        # देवनागरी/चीनी \u092A\u0930-एस्केप नहीं होगा
        sort_keys=False,           # JSON की मूल key-क्रम बनी रहे
    )

इन तीनों का डिफ़ॉल्ट False / False / True है, यानी डिब्बे से निकला PyYAML key को वर्णानुक्रम में सजा देता है और देवनागरी-चीनी को \uXXXX में बदल देता है। उसी इनपुट पर डिफ़ॉल्ट पैरामीटर के साथ आउटपुट:

复制apiVersion: v1
data:
  LOG_LEVEL: info
  colon: 'host: value'
  unicode: "\u7AEF\u53E3 8080"
kind: ConfigMap
metadata:
  labels:
    app: web
  name: app-config

ध्यान दें कि kind अब apiVersion के बाद और metadata से पहले चला गया है — Kubernetes मैनिफ़ेस्ट में apiVersion का kind से पहले होना समुदाय की परंपरा है; key-क्रम बिगड़ने से पार्सिंग नहीं टूटती, पर समीक्षा करने वाले के लिए बहुत कष्टदायक हो जाता है।

Node + js-yaml:

复制const fs = require("fs");
const yaml = require("js-yaml");

const data = JSON.parse(fs.readFileSync("config.json", "utf8"));
fs.writeFileSync(
  "config.yaml",
  yaml.dump(data, { lineWidth: -1, noRefs: true, sortKeys: false })
);

lineWidth: -1 लंबी पंक्तियों का folding बंद करता है (वरना लंबे URL बीच से टूट जाते हैं), noRefs: true anchor और alias बनने से रोकता है — जब उपभोक्ता kubectl हो या कोई ऐसा टूल जो उन्हें हल नहीं करता, तब इसे बंद करना अनिवार्य है।

मापा गया समय (नमूना: 2.39 MB JSON, 12000 रिकॉर्ड, हर एक में नेस्टेड ऑब्जेक्ट और दो array; मशीन इस काम के लिए इस्तेमाल हुआ सैंडबॉक्स है):

दो विपरीत-अंतर्ज्ञान वाले नतीजे। पहला, -P जोड़ने से yq लगभग 9 गुना धीमा हो जाता है (0.45 s → 4.16 s), जबकि इस नमूने पर आउटपुट के बाइट बिलकुल समान हैं (दोनों ही तरह 2,326,895 बाइट) — -P एक पूरा पुनः-सजावट पास चलाता है, और सैकड़ों फ़ाइलों के बैच में यह कीमत जमा हो जाती है। दूसरा, PyYAML का उल्टा पार्स (8.01 s) उसके सीधे रूपांतरण (3.26 s) से दुगने से भी अधिक धीमा है; अगर आपकी पाइपलाइन YAML को बार-बार वापस पढ़ेगी, तो Python अच्छा विकल्प नहीं है।

एक और बात: 2.39 MB JSON ब्लॉक शैली YAML बन कर 2.33 MB हो गया, यानी लगभग 3% छोटा। प्रचलित कहावत "YAML हमेशा JSON से बड़ा होता है" सही नहीं है — गहरे नेस्टिंग में JSON के उद्धरण, अल्पविराम और curly brace जितनी जगह लेते हैं, वह YAML के इंडेंटेशन व्हाइटस्पेस से अधिक हो सकता है।

7. जो तीन चीज़ें वापस नहीं आतीं

पिछले भागों ने बताया "सही कैसे बदलें"। यह भाग बताता है "क्या खो जाता है"। विशेष रूप से गढ़े गए इनपुट पर माप:

复制printf '{"order_id":12345678901234567890,"zip":"0150","ts":"2026-11-03","f":1.0e6}' > t.json
yq -o=yaml '.' t.json

yq का आउटपुट:

复制order_id: 1.2345678901234567e+19
zip: "0150"
ts: "2026-11-03"
f: 1000000

और वापस JSON में: {"order_id":12345678901234567000,"zip":"0150","ts":"2026-11-03","f":1000000}।

20 अंकों वाला ऑर्डर आईडी 12345678901234567890 बन गया 12345678901234567000 — आख़िरी तीन अंक शून्य, और कोई चेतावनी तक नहीं। कारण यह है कि yq Go के float64 पार्स मार्ग से जाता है; 2^53 से बड़े पूर्णांकों को शुद्ध रूप में दर्शाया नहीं जा सकता, इसलिए वह वैज्ञानिक संकेतन में आउटपुट देता है और वापस लौटते समय मूल मान जा चुका होता है।

वही इनपुट PyYAML को दें:

复制order_id: 12345678901234567890
zip: '0150'
ts: '2026-11-03'
f: 1000000.0

Python के पूर्णांक मनचाही परिशुद्धता के होते हैं, इसलिए 20 अंक पूरे बचे रहते हैं और वापस पढ़ने पर भी 12345678901234567890 मिलता है। अगर आपके डेटा में ऑर्डर आईडी, snowflake आईडी या राष्ट्रीय पहचान संख्या जैसे लंबे अंक हैं, तो yq मत इस्तेमाल करें, Python इस्तेमाल करें, या पहले ही फ़ील्ड को स्ट्रिंग बना लें। इस श्रेणी की परिशुद्धता समस्या की पूरी कार्यप्रणाली JSON में बड़े पूर्णांक की परिशुद्धता क्यों खो जाती है में विस्तार से दी गई है।

दूसरी चीज़ जो खोती है वह float और int का भेद है: 1.0e6 yq के आउटपुट में 1000000 (पूर्णांक) बन जाता है, PyYAML 1000000.0 रखता है। तीसरी है key-क्रम — PyYAML डिफ़ॉल्ट रूप से सजाता है, yq और js-yaml डिफ़ॉल्ट रूप से बनाए रखते हैं; अलग-अलग भाषाओं की टीमों के साथ काम करते समय यह मतभेद का छिपा स्रोत है।

वास्तविक परियोजना में इन तीनों में सबसे हानिकारक पहली है, क्योंकि वह मौन है। ऑर्डर आईडी, लेन-देन आईडी, snowflake आईडी — इनके आख़िरी कुछ अंक बदल जाने पर भी फ़ाइल देखने में बिलकुल ठीक लगती है। इसलिए रूपांतरण से पहले एक छोटे नमूना समूह पर round-trip जाँच चलाना, भविष्य के घंटों के डिबगिंग को बचाना है।

8. CI में सिर्फ़ convert नहीं: सत्यापन → रूपांतरण → lint

रूपांतरण को ही एकमात्र चरण मानना सबसे आम पाइपलाइन दोष है। रूपांतरण सफल होने पर exit code 0 मिलता है, जिसका अर्थ केवल इतना है कि "इनपुट JSON पार्स हो गया" — इसका यह अर्थ नहीं कि आउटपुट सही है, या आउटपुट उपभोक्ता की ज़रूरत पूरी करता है। सही तीन-चरणीय रूप:

复制#!/usr/bin/env bash
set -euo pipefail

# 1. स्रोत सत्यापन: सिंटैक्स परत
jq empty deployment.json

# 2. रूपांतरण: आउटपुट फॉर्मैट स्पष्ट रूप से बताएँ
yq -o=yaml '.' deployment.json > deployment.yaml

# 3. परिणाम सत्यापन: YAML parser पढ़ सके, और lint साफ़ हो
yq -o=json -I=0 '.' deployment.yaml > /dev/null
yamllint deployment.yaml

चरण 3 की वह yq -o=json ... > /dev/null लाइन देखने में अनावश्यक लगती है, पर असल में पूरे ब्लॉक की सबसे उपयोगी पंक्ति है: यह परिणाम को जबरन दोबारा पार्स करवाती है। इंडेंटेशन की ग़लती, anchor हल न हो पाना, प्रकार का बदल जाना — सब इसी चरण में उजागर होते हैं। इसे छोड़ दें तो समस्या kubectl apply या ऐप के शुरू होने तक टल जाती है।

अगर परिणाम मनुष्य द्वारा रखरखाव वाली कॉन्फ़िगरेशन है (Helm values, Docker Compose, GitHub Actions वर्कफ़्लो), तो तीन और बातें पक्की करें: key-क्रम बिगड़ा नहीं है, लंबे अंकों की परिशुद्धता बनी है, और टिप्पणियाँ हाथ से जोड़नी होंगी — JSON में टिप्पणी का कोई स्थान नहीं, कोई भी टीका रूपांतरण के बाद ही लिखा जा सकता है; कोई कनवर्टर आपके लिए उसे नहीं गढ़ेगा।

अक्सर पूछे जाने वाले प्रश्न

yq -P और -o=yaml में आख़िर कौन सा लिखूँ?

-o=yaml तय करता है कि "आउटपुट YAML है भी या नहीं", -P तय करता है कि "YAML दिखता कैसा है"। इनपुट .json फ़ाइल होने पर -o=yaml अनिवार्य है; -P तब लगेगा जब आपको ब्लॉक शैली या sequence इंडेंटेशन जबरन चाहिए। stdin से पढ़ते समय जहाँ कोई एक्सटेंशन नहीं, yq पहले से YAML देता है, इसलिए वहाँ -P अकेला काफ़ी है।

रूपांतरित YAML सीधे Kubernetes को दी जा सकती है?

सिंटैक्स की दृष्टि से हाँ, पर तीन शर्तों के साथ: पक्का करें कि apiVersion जैसी क्रम-परंपरा वाली key दोबारा सजाई नहीं गईं (PyYAML डिफ़ॉल्ट रूप से सजाता है, sort_keys=False देना होगा), पक्का करें कि कोई anchor या alias नहीं बना (js-yaml में noRefs: true दें), और पक्का करें कि लंबे अंकों की परिशुद्धता बनी है। मल्टी-रिसोर्स मैनिफ़ेस्ट के लिए --split-exp से ----विभाजित दस्तावेज़ बनाना होगा।

मेरा बदला हुआ YAML {a: 1, b: 2} एक पंक्ति में है, इंडेंटेड क्यों नहीं?

यह flow शैली है; वैध ज़रूर है, पर इसने रूपांतरण का उद्देश्य ही मार दिया। -P से ब्लॉक शैली जबरन लागू करें; PyYAML इस्तेमाल कर रहे हों तो पक्का करें कि default_flow_style=False है (PyYAML 5.1 से इसका डिफ़ॉल्ट False है, पुराने संस्करण में स्पष्ट लिखना पड़ता है)।

20 अंकों वाले ऑर्डर आईडी के आख़िरी अंक YAML में 0 हो गए, बचाया जा सकता है?

वापस नहीं मिल सकते, सिर्फ़ पहले से रोका जा सकता है। yq float64 से पार्स करता है, इसलिए 2^53 से बड़े पूर्णांक की परिशुद्धता संरचनात्मक रूप से जाती है। या तो Python पर जाएँ (पूर्णांक मनचाही परिशुद्धता के, माप में अक्षुण्ण सिद्ध), या JSON में ही लंबे अंकों को स्ट्रिंग के रूप में रखें — दूसरा तरीका ज़्यादा सुरक्षित है, क्योंकि वह JavaScript पक्ष की JSON.parse की इसी श्रेणी की समस्या को भी एक साथ सुलझा देता है।

ऑनलाइन रूपांतरण टूल या कमांड-लाइन?

गोपनीय कॉन्फ़िगरेशन और टोकन वाले API स्नैपशट के लिए लोकल कमांड-लाइन या शुद्ध फ़्रंटएंड टूल इस्तेमाल करें, अपलोड मत कीजिए। एक बार के, छोटे आकार के, जहाँ आँखों से देख कर पक्का करना हो, वहाँ ऑनलाइन टूल तेज़ है; इस साइट का /convert/yaml पूरी तरह ब्राउज़र में चलता है और डेटा मशीन से बाहर नहीं जाता। बैच, CI में जाने वाला, पुनरुत्पादन योग्य — इन सब के लिए कमांड-लाइन ही लें, और सत्यापन के चरण भी उसी स्क्रिप्ट में लिख दें।