محول YAML إلى JSON

الصق ملف YAML صالحًا — ملف بيان Kubernetes، أو ملف Compose، أو دليل Ansible playbook، أو مواصفات OpenAPI، أو أي مستند YAML 1.2 — وسيقوم المحول بإصدار ما يعادله بتنسيق JSON في الوقت الفعلي.

يتم التحويل بالكامل داخل متصفحك باستخدام محلل YAML 1.2، ثم يمر عبر الشجرة المحللة ليصدر JSON عبر JSON.stringify (وفقًا للمعيار ECMA-404 / RFC 8259).

اختر نمط المخرجات الخاص بك:

• مسافتان (افتراضي، سهل القراءة للبشر)
• 4 مسافات (تستخدم في بعض قواعد الأكواد الخاصة بالشركات)
• مضغوط (لواجهات برمجة التطبيقات وحمولات الشبكة)

المخرجات جاهزة للصقها في ملف `.json` أو تمريرها إلى الأمر `kubectl apply -f -` (الذي يقبل JSON عبر الإدخال القياسي stdin). يعرض الجزء الأيمن عدد البايتات والأسطر المباشرة حتى تتمكن من التحقق من الحجم قبل الاعتماد.

يتطلب تحويل YAML إلى JSON ثلاث خطوات:

• الخطوة 1: الصق ملف YAML في المحرر. يقوم المحلل بالتحقق من الصلاحية أثناء الكتابة — يعرض ملف YAML غير الصالح خطأ التحليل الدقيق مع تحديد السطر والعمود.
• الخطوة 2: تظهر مخرجات JSON مباشرة في اللوحة اليمنى. لا حاجة للنقر على أي زر؛ فكل نقرة مفتاح تعيد التحليل تلقائيًا.
• الخطوة 3: انقر فوق نسخ (إلى الحافظة) أو تنزيل (ملف `.json`).

بالنسبة لخطوات العمل البرمجية (مثل برمجة تطبيق احسب ساعات العمل أو حساب الساعات أو حساب عدد الساعات)، يتم توفير نفس المنطق عبر نقطة النهاية `/api/calculate` — أرسل طلب POST يحتوي على YAML إليها واستلم JSON في جسم الاستجابة.

سلامة التحويل العكسي: قم بتحويل JSON مجددًا إلى YAML باستخدام المحول الشقيق من JSON إلى YAML؛ حيث يتم الحفاظ على نموذج البيانات تمامًا (التعليقات ونقاط الارتساء خاصة بـ YAML فقط ولا تنجو من التحويل العكسي).

يمثل كل من YAML و JSON نفس نموذج البيانات — الخرائط (الكائنات)، والتسلسلات (المصفوفات)، والقيم القياسية (نص/رقم/منطقي/null) — ولكن ببنية ظاهرية مختلفة تمامًا.

تعتمد لغة YAML على المسافات البادئة: يتم تضمين التداخل من خلال مسافة بادئة بمقدار مسافتين، وتستخدم التسلسلات البادئة `- `، ولا تحتاج معظم النصوص إلى علامات اقتباس. بينما تعتمد لغة JSON بشكل كبير على الأقواس وعلامات الاقتباس: يحصل كل مفتاح على `"`، وكل خريطة على `{}`، وكل مصفوفة على `[]`، ويكون كل فاصل صريحًا (`:` و `,`).

تدعم YAML التعليقات (`#`)، ونقاط الارتساء والأسماء المستعارة لإعادة الاستخدام (`&name` / `*name`)، وتدفقات المستندات المتعددة (`---`)، وعلامات النوع الصريحة (`!!str`، `!!int`) — وهي نقاط قوة تجعلها الخيار الأمثل لملفات التكوين الخاضعة للتحكم في الإصدارات (مثل إعدادات تطبيق حساب الوقت أو الحاسبة العلمية). بينما يتم تحليل JSON أسرع بمقدار 5 إلى 10 مرات، وخالٍ تمامًا من الغموض، وهو الخيار الأمثل لواجهات برمجة التطبيقات والتخزين.

قم بالتحويل عند الحدود: YAML للبشر، و JSON للآلات.

التداخل العميق هو المجال الذي يتألق فيه تحويل YAML إلى JSON — حيث إن تتبع المسافة البادئة يدويًا عند 5 مستويات أو أكثر يكون عرضة للأخطاء. يمر المحول عبر شجرة YAML المحللة بشكل متكرر.

• لكل خريطة كتلة، يتم إصدار المفاتيح بترتيب المصدر مع بناء جملة JSON `"key": value`؛ وتحصل القيم المتداخلة على أقواس `{...}`.
• لكل تسلسل كتلة، يتم إصدار العناصر كمصفوفات JSON `[...]`؛ وتصبح الكائنات المتداخلة تحت علامة `-` عناصر مصفوفة `{...}`.

تتحول جميع البنى المختلطة — تسلسلات الخرائط، والخرائط التي تحتوي على تسلسلات من الخرائط، بشكل متكرر — بشكل صحيح. الحد الأقصى للعمق محدود فقط بمكدس الاستدعاءات (call stack) لمتصفحك (أكثر من 10,000 إطار في المتصفحات الحديثة، وهو ما يتجاوز بكثير أي ملف تكوين واقعي).

اختبر ذلك بملفاتك وبياناتك الخاصة (مثل بيانات تطبيق حساب ساعات العمل أو عد تنازلي): قم بتحليل مخرجات JSON مجددًا إلى YAML وتأكد من التطابق الهيكلي مع المدخلات.

يعد استنتاج النوع المرن في YAML مصدرًا للعديد من الأخطاء في ملفات التكوين الواقعية. لقد ضيقت مواصفات YAML 1.2 (المعيار الحديث الذي يستهدفه هذا المحول) القواعد لتكون أكثر أمانًا.

• القيم المنطقية: فقط `true` و `false` (غير حساسة لحالة الأحرف). كانت مواصفات YAML 1.1 تعامل أيضًا `yes`/`no`/`on`/`off` كقيم منطقية، وهو ما تسبب في تعطل ملفات التكوين التي تحتوي على رمز دولة النرويج `NO` الشهير (حيث تم تحويله بصمت إلى `false`) — وهي "مشكلة النرويج". تعتمد معظم المحللات الحديثة (مثل js-yaml و PyYAML 6+ و Snakeyaml) سلوك 1.2 افتراضيًا.
• Null: تصبح كل من `null` أو `~` أو القيمة الفارغة قيمة JSON null.
• الأرقام: تصبح أنماط الأرقام التي تطابق صيغة الأعداد الصحيحة/العشرية في JSON أرقامًا في JSON؛ ويظل أي شيء آخر نصًا.
• النصوص: تظل القيم المقتبسة دائمًا نصوصًا؛ وتحتاج النصوص الرقمية مثل الرموز البريدية (`"01234"`) وتواريخ التقويم إلى اقتباس في YAML لتنجو من التحويل — عندما يحتوي ملف التكوين على تاريخ أو مدة قمت بحسابها مسبقًا باستخدام حاسبة الوقت أو برنامج حساب الوقت (مثل حساب عدد الساعات والدقائق أو حساب الوقت بالدقائق)، قم بلفها بعلامات اقتباس حتى يحتفظ بها المحلل حرفيًا بدلاً من إجباره على التحول لنوع آخر.
• يلتزم المحول بهذه القواعد بدقة.

يقبل Kubernetes كلاً من YAML و JSON عبر خادم واجهة برمجة التطبيقات (API server) الخاص به، وأداة kubectl، ومكتبات العملاء. تحتفظ معظم الفرق بملفات YAML في نظام التحكم في الإصدار (حيث يسهل مراجعة طلبات السحب PRs) ولكنها تمرر ملفات JSON إلى الأدوات البرمجية — مثل وحدات التحكم المخصصة (custom controllers)، أو مسارات GitOps، أو أدوات Helm post-renderers، أو خطافات الويب (webhooks).

قم بلصق البيان الخاص بك (Pod، Deployment، Service، ConfigMap، إلخ) وانسخ مخرجات JSON. يحافظ المحول على التسلسل الهرمي لـ apiVersion و kind و metadata و spec بنفس ترتيب الحقول — يتوقع Kubernetes مفاتيح بتنسيق camelCase دائماً، لذا إذا كنت تنقل حقولاً من مصدر يستخدم تنسيق snake_case، فإن محول حالة الأحرف سيصلح التسمية قبل اللصق.

تحقق من صحة الملف باستخدام الأمر `kubectl apply --dry-run=client -f -` (الذي يقبل JSON عبر الإدخال القياسي stdin) قبل الاعتماد. بالنسبة للبيانات متعددة الموارد المفصولة بـ `---`، قم بتقسيمها إلى مستندات فردية أولاً — حيث لا تدعم JSON صيغة المستندات المتعددة.

ثلاث حالات استخدام شائعة تتجاوز Kubernetes:

• Docker Compose: الصق ملف `docker-compose.yaml` وانسخ صيغة JSON لاستخدامها في أدوات مثل Kompose (التي تنقل Compose إلى K8s)، أو أدوات التنسيق المخصصة، أو التحويلات البرمجية للإعدادات.
• Ansible: قم بتحويل ملفات التشغيل (playbooks) إلى JSON لأدوات التوثيق، أو تكاملات CI المخصصة، أو واجهات برمجة تطبيقات REST/GraphQL التي تخزن تعريفات ملفات التشغيل.
• مسارات CI/CD: مثل GitHub Actions (`.github/workflows/*.yml`)، و GitLab CI (`.gitlab-ci.yml`)، و CircleCI، و Travis — قم بتحويل أي منها إلى JSON لأغراض التحليل، أو التعديلات البرمجية، أو أرشفة سجلات التدقيق. ونظراً لأن مشغلات `cron` المجدولة الخاصة بها تعتمد على توقيت UTC، فإن استخدام أداة تشبه حاسبة الوقت لتحويل المناطق الزمنية يمنعك من الخطأ في حساب الوقت الفعلي لتشغيل المسار بالتوقيت المحلي الخاص بك، مما يسهل عليك حساب عدد الساعات والدقائق بدقة.

مواصفات OpenAPI 3.x عادةً ما تُكتب بصيغة YAML (لأنها أكثر وضوحاً وقراءة لتسلسلات المسارات والمعاملات) ولكن يتم استهلاكها كصيغة JSON بواسطة الأدوات الأقدم — مثل إصدارات Swagger UI القديمة، وبوابات واجهة برمجة التطبيقات للمؤسسات، وبعض مولدات الأكواد.

الصق ملف `openapi.yaml` (أو `swagger.yaml`) وقم بتنزيل `openapi.json`. يحافظ المحول على مؤشرات `$ref` تماماً كما هي (دون حلها)، وتعاريف المخططات (schemas)، وأمثلة الاستجابة، ومخططات الأمان.

بعد التحويل، تحقق من الصحة باستخدام أداة التحقق الرسمية من OpenAPI (مثل Spectral CLI أو openapi-cli أو swagger-cli) لتأكيد التوافق مع المخطط. تحتفظ العديد من الفرق بملفات YAML في نظام التحكم في الإصدار وتنتج ملفات JSON في وقت البناء — حيث أن كلاً من `swagger.yaml` و `swagger.json` متكافئان تماماً لمستخدمي واجهة برمجة التطبيقات.

ستة أخطاء تتسبب في 95% من حالات فشل تحليل YAML:

• وجود علامات تبويب (Tabs) في أي مكان من المسافة البادئة — تمنع لغة YAML استخدام علامات التبويب تماماً، فحتى علامة تبويب واحدة تفسد التحليل.
• عدم اتساق المسافات البادئة — يجب محاذاة المفاتيح الشقيقة في نفس العمود تماماً.
• غياب المسافة بعد `:` في الخرائط (maps) — الصيغة `key:value` غير صالحة؛ والصيغة الصحيحة هي `key: value`.
• غياب المسافة بعد `-` في المتتاليات (sequences) — الصيغة `-item` تعتبر سلسلة نصية تبدأ بشرطة؛ بينما الصيغة `- item` هي عنصر متتالية صحيح.
• الرموز الخاصة غير المحاطة بعلامات اقتباس في بداية القيمة — مثل `@` و `` ` `` و `%` و `*` و `&` تحتاج إلى علامات اقتباس.
• الميزات غير المدعومة في المحول: المراسي (`&name`)، والأسماء المستعارة (`*name`)، وتدفقات المستندات المتعددة (`---`) — بالنسبة لهذه الحالات، استخدم مكتبة YAML كاملة مثل js-yaml أو PyYAML أو `yq`.

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

ثلاث ميزات في YAML ليس لها مكافئ مباشر في JSON وتتطلب معالجة خاصة:

• المراسي (`&name`) والأسماء المستعارة (`*name`): تسمح لـ YAML بالإشارة إلى عقدة وإعادة استخدامها في مكان آخر — وهو أمر شائع في ملفات Compose لقوالب الخدمات المشتركة وفي CloudFormation للمعاملات المشتركة. لا تحتوي JSON على صيغة مرجعية، لذا يقوم المحول بتوسيع الأسماء المستعارة داخلياً (يصبح كل اسم مستعار نسخة كاملة). يتم الحفاظ على البيانات ولكن حجم ملف JSON يصبح أكبر وتُفقد بنية المرجع المشترك.
• تدفقات المستندات المتعددة (فاصل `---`): تمثل قيمًا متعددة عالية المستوى في ملف واحد — وهو أمر شائع لتجميع موارد Kubernetes. تدعم JSON قيمة جذرية واحدة فقط لكل مستند. قم بتقسيم ملف YAML إلى ملفات منفصلة أولاً أو ضع المستندات داخل مصفوفة JSON مثل `[doc1, doc2, doc3]`.
• التعليقات (`#`): خاصة بـ YAML فقط — ويتم إزالتها تماماً أثناء التحويل. احتفظ بملف YAML كمصدر أساسي للمعلومات إذا كانت التعليقات مهمة بالنسبة لك.

خمسة اعتبارات للتحويل العكسي يجب على كل مطور معرفتها:

• نموذج البيانات: يحافظ التحويل من YAML ← JSON ← YAML على المفاتيح والقيم والأنواع والتداخل تماماً. البيانات متطابقة تماماً عند الإدخال وعند العودة.
• التعليقات: تُفقد نهائياً — لا تدعم JSON صيغة التعليقات. احتفظ بملف YAML كمصدر أساسي للمعلومات إذا كانت لديك توثيقات داخلية.
• المراسي/الأسماء المستعارة: يتم توسيعها عند التحويل إلى JSON، ولا يتم إعادة إنشائها عند العودة. ستحتوي مخرجات YAML على محتوى مكرر حيث كان للمصدر مراجع مشتركة.
• ترتيب المفاتيح: تحافظ YAML على ترتيب المصدر؛ ويحافظ المحول عليه حتى الوصول إلى JSON؛ كما يحافظ التحويل العكسي إلى YAML على نفس الترتيب.
• علامات النوع (`!!str`، `!!int`) — يتم إصدارها فقط عند الحاجة لإزالة الغموض. تنجو السلسلة النصية `"01234"` في التحويل العكسي لأن JSON تبقيها داخل علامات اقتباس؛ بينما يتم تحليل القيمة غير المقتبسة `01234` في YAML كعدد صحيح وتعود في التحويل العكسي كـ 1234، مما يفقدها الصفر البادئ.

ضع القيم الغامضة بين علامتي اقتباس بشكل وقائي.

مطابقة الأنواع لمحة سريعة:

• خريطة (map) في YAML ← كائن (object) في JSON
• متتالية (sequence) في YAML ← مصفوفة (array) في JSON
• قيمة مفردة (scalar) في YAML (حسب استنتاج النوع) ← سلسلة نصية/رقم/قيمة بولية/null في JSON
• علامة !!str في YAML ← سلسلة نصية في JSON (إجبارياً)
• null/~/فارغ في YAML ← null في JSON
• true/false في YAML ← قيمة بولية في JSON
• نمط العدد الصحيح في YAML ← عدد صحيح في JSON
• نمط العدد العشري في YAML ← رقم في JSON

مقارنة الأدوات:

• هذا المحول (يعمل على المتصفح، فوري، لا يتطلب التثبيت، تماماً مثل برنامج حساب الوقت السريع، ويدعم 95% من ملفات YAML الفعلية)
• أداة `yq -o json` (واجهة سطر الأوامر CLI، للملفات الكبيرة، استعلامات JSONPath)
• مكتبة `js-yaml`/`PyYAML` (مكتبة كاملة، تدعم المراسي والمستندات المتعددة، للاستخدام البرمجي)

أفضل الممارسات:

• ضع دائماً القيم الغامضة (مثل yes/no/on/off/null/المعرفات الرقمية) بين علامتي اقتباس في مصدر YAML.
• استخدم مسافة بادئة بمقدار مسافتين (المعيار الفعلي).
• تحقق من صحة مخرجات JSON مقابل مخطط المستهلك النهائي (JSON Schema، OpenAPI، K8s OpenAPI) — حيث تظهر أخطاء النوع هنا.
• احتفظ بملف YAML كمصدر أساسي وأعد إنشاء ملف JSON في وقت البناء كلما أمكن ذلك.