محول JSON ↔ YAML — التحويل بين JSON و YAML عبر الإنترنت _

ما هو التحويل بين JSON و YAML؟

JSON (JavaScript Object Notation، RFC 8259) صيغة نصية صارمة محدّدة بأقواس معقوفة للبيانات المنظمة؛ YAML (YAML Ain't Markup Language، الإصدار 1.2) امتداد فائق لـ JSON يستخدم المسافات البادئة وفواصل الأسطر وصياغة قابلة للقراءة البشرية لنفس نموذج القيمة. التحويل بينهما يتيح لك تدوير الإعداد نفسه بين شكل ملائم للآلة (JSON لواجهات APIs، والتحقق من المخطط، والتحويلات البرمجية) وشكل ملائم للإنسان (YAML لمراجعة الكود، و Kubernetes manifests، و GitHub Actions workflows) دون إعادة كتابة مفتاح واحد.

كيف يعمل التحويل بين JSON و YAML؟

كل تحويل يجري محلياً داخل متصفحك باستخدام مكتبة js-yaml المرفقة (MIT، الإصدار 4.1.0). الخطوات الرئيسية هي:

1. محدد الوضع (اكتشاف تلقائي / JSON → YAML / YAML → JSON) يقرر أي خط أنابيب يعمل. في وضع الاكتشاف التلقائي يحدد أول حرف غير فارغ في المدخل الاتجاه — { أو [ يعني JSON؛ أي شيء آخر يعني YAML.
2. JSON → YAML: JSON.parse يتحقق من المدخل وينتج قيمة جافاسكربت؛ ثم jsyaml.dump(value, { indent, lineWidth: -1, sortKeys: false }) يكتب شكل YAML 1.2. عند تفعيل الوثائق المتعددة، يُصدَر كل عنصر في مصفوفة المدخل كوثيقة مستقلة مع فواصل ---.
3. YAML → JSON: jsyaml.loadAll يحلل كل وثيقة في المدخل (مع التعامل تلقائياً مع فواصل ---) إلى مصفوفة؛ المدخلات أحادية الوثيقة تُفكَّك بحيث يكون مخرج JSON هو الوثيقة نفسها، وليس مصفوفة من عنصر واحد.
4. المسافة البادئة (مسافتان أو أربع) والتنسيق الجميل قابلان للتكوين. عند إيقاف التنسيق الجميل يُصدَر JSON مضغوط عبر JSON.stringify(value) بلا أي مسافات.
5. تُكتب النتيجة في حقل نصي للقراءة فقط. عند فشل تحليل YAML تتضمن رسالة الخطأ رقم السطر والعمود بدءاً من 1 الذي يبلغ عنه e.mark في js-yaml لتقفز مباشرة إلى موضع المشكلة.

لماذا نحوّل JSON و YAML بهذه الأداة؟

• الخصوصية: كل عملية تحليل وتحويل وإصدار تجري داخل متصفحك. لا تصل البيانات — بما فيها أسرار Kubernetes ورموز JWT الموقعة والإعدادات الخاصة — إلى خوادمنا أبداً.
• وثائق YAML المتعددة: jsyaml.loadAll يتعرف على فواصل --- ويعيد مصفوفة من الوثائق، يفكّكها المحول للحالات أحادية الوثيقة أو يحتفظ بها كمصفوفة JSON للحالات متعددة الوثائق.
• حل المراسي والأسماء المستعارة: آلية &anchor / *alias في YAML يعالجها المخطط الافتراضي في js-yaml. القيمة المعرَّفة مرة واحدة والمشار إليها مرتين تجتاز جولة الذهاب والإياب إلى كائن JSON تحمل فيه كل المراجع قيماً متساوية.
• بلا CDN ولا قياسات عن بُعد: تُحمّل مكتبة js-yaml.min.js من نفس مصدر الصفحة، فتعمل الأداة دون اتصال، خلف بروكسيات الشركات، وداخل البيئات المعزولة.

ما هي التطبيقات الشائعة للتحويل بين JSON و YAML؟

التنقل بين JSON و YAML يظهر عبر DevOps وهندسة المنصات وأدوات واجهات APIs:

• Kubernetes manifests: تحويل YAML لـ Deployment أو ConfigMap أو HelmRelease إلى JSON ليتمكن مدقق سياسات داخلي (Joi، Ajv، OPA Rego) من فحصه برمجياً، ثم العودة إلى YAML لتطبيق العنقود.
• تدفقات CI/CD: جولة ذهاب وإياب لـ workflow.yml في GitHub Actions عبر JSON ليتمكن مولد كود من إعادة كتابة المصفوفة أو تبعيات المهام، ثم إصدار YAML المنظف لطلب السحب.
• مواصفات OpenAPI: لصق openapi.json الصادر تلقائياً من توثيق الخلفية وتحويله إلى openapi.yaml ليكون المرجع المُحرَّر يدوياً والمحفوظ في المستودع.

كيف يبدو مثال جولة ذهاب وإياب JSON ↔ YAML؟

لصق {"apiVersion":"apps/v1","kind":"Deployment","metadata":{"name":"web"},"spec":{"replicas":3,"selector":{"matchLabels":{"app":"web"}}}} والضغط على CONVERT في وضع JSON → YAML يُنتج ثمانية أسطر من YAML بمسافات بادئة، أولها apiVersion: apps/v1. تغذية ذلك YAML مرة أخرى في وضع YAML → JSON مع تفعيل التنسيق الجميل يعيد الكائن الأصلي بايتاً ببايت بعد JSON.stringify(value, null, 2) ثابت، مع الحفاظ على ترتيب المفاتيح لأن المخطط الافتراضي في js-yaml يحترم ترتيب الإدراج في الاتجاهين.

هل يعمل محول JSON ↔ YAML هذا داخل متصفحي بالكامل؟

نعم. كل عمليات التحليل والتحويل والإصدار تجري محلياً كجافاسكربت داخل تبويب متصفحك. مكتبة js-yaml المرفقة تُحمَّل من نفس مصدر الصفحة — لا CDN، ولا fetch، ولا XMLHttpRequest، ولا navigator.sendBeacon على المدخل. كما تعمل الأداة دون اتصال بمجرد تحميل الصفحة، لأنها حزمة ثابتة من HTML/CSS/JS مع نسخة من المكتبة بجوارها. أسرار Kubernetes وحمولات JWT و CloudFormation YAML الموقعة والإعدادات الخاصة تبقى على جهازك.

كيف يتعامل المحول مع YAML متعدد الوثائق؟

يدعم YAML وثائق متعددة في تيار واحد تفصلها أسطر تحوي فقط ---. عند YAML → JSON يستدعي المحول jsyaml.loadAll الذي يعيد كل وثيقة كقيمة جافاسكربت. إذا وُجدت وثيقة واحدة فقط يكون مخرج JSON هو الوثيقة مباشرة؛ وإذا وُجد اثنان أو أكثر يكون المخرج مصفوفة. عند JSON → YAML، إذا كان المدخل مصفوفة JSON وكانت خيار الوثائق المتعددة مفعّلاً، يُصدَر كل عنصر كوثيقته الخاصة مع فواصل --- بينها — مفيد لإنشاء حزمة جاهزة لـ kubectl apply من مصفوفة JSON للموارد.

هل المراسي والأسماء المستعارة في YAML مدعومة؟

نعم — تُحل تعريفات &anchor ومراجع *alias عبر المخطط الافتراضي في js-yaml خلال خطوة التحميل. مدخل YAML مثل defaults: &d\n retries: 3\n timeout: 30\njob_a:\n <<: *d\njob_b:\n <<: *d يُحلَّل إلى كائن JSON يحوي فيه job_a و job_b كلاهما retries: 3, timeout: 30. مفتاح الدمج << (امتداد YAML 1.1 لا يزال js-yaml يحترمه) مدعوم أيضاً في المخطط الافتراضي.

هل تُحفظ تعليقات YAML عند التحويل إلى JSON والعودة؟

لا — تجرّد js-yaml التعليقات خلال خطوة التحليل، لذا جولة YAML → JSON → YAML ستفقد كل سطر مسبوق بـ #. هذا قيد معروف لنموذج التحميل/الإصدار؛ إذا كان الحفاظ على التعليقات حرجاً، استخدم مكتبة واعية بالتعليقات مثل حزمة yaml على npm (تشحن واجهة CST + AST مصممة للحفاظ على المعلومات الإضافية) بدلاً من js-yaml. في معظم تدفقات تحويل الإعداد، التضحية مقبولة: تحتفظ جولة YAML بكل مفتاح وقيمة ومرسى واسم مستعار، فقط بدون التعليقات المكتوبة بشرياً.

ماذا يحدث للوسوم المخصصة في YAML؟

يستخدم المحول DEFAULT_SCHEMA في js-yaml الذي يفهم !!str، !!int، !!float، !!bool، !!null، !!seq، !!map، !!binary، و !!timestamp — كل وسم في مخططَي YAML 1.2 الأساسي و JSON. الوسوم المخصصة أو الخاصة بتطبيق (مثل !Ref في CloudFormation، أو !vault في Ansible) غير معروفة وتظهر كخطأ واضح يشير إلى الوسم غير المدعوم. لـ CloudFormation تحديداً، استخدم تدفق aws cloudformation package + --output-template-file لتوسيع الوسوم المخصصة قبل اللصق في هذا المحول.

يأتي محول JSON ↔ YAML هذا مع js-yaml@4.1.0 مرفقاً من نفس المصدر، ويدعم التيارات متعددة الوثائق والمراسي/الأسماء المستعارة جاهزاً، ويبلغ عن أخطاء تحليل YAML بالسطر والعمود لتُصلح المصدر. بلا رفع، بلا CDN، بلا قياسات عن بُعد — كل بايت يبقى داخل متصفحك.