محول JSON ↔ YAML

ما هو مُحوِّل YAML / JSON؟#

YAML و JSON طريقتان لكتابة النوع نفسه من البيانات — خرائط متداخلة، وقوائم، وسلاسل، وأرقام، وقيم منطقية، وnull. JSON صارم ومُثقَل بعلامات الترقيم (كل سلسلة بموجدات، وأقواس في كل مكان)؛ ويستبدل YAML تلك الموجدات والأقواس بالإزاحة والشرطات، مما يجعله مقروءًا بما يكفي ليكتبه البشر يدويًّا لملفات الإعداد، وخطوط CI، وبيانات الحاويات.

تحتاج دائمًا للعبور بين الاثنين لأن أدواتًا مختلفة تفضّل صيغًا مختلفة. مخطط Kubernetes يُكتب بـ YAML لكن الواجهة البرمجية تتحدث JSON. إعداد CI هو YAML؛ والمُنقِّح الذي تريد تغذيته يتوقع JSON. يلصق زميل كتلة YAML في دردشة؛ ويريد سكربتك JSON.parse. فعل هذا يدويًّا — إعادة إزاحة، وإعادة اقتباس، وتبديل شرطات بأقواس — هو بالضبط نوع العمل المُمل الذي يُدخل فاصلة شاردة أو مسافة غير محاذاة، ثم لا شيء يُحلَّل.

تُحوِّل هذه الصفحة في كلا الاتجاهين في متصفحك. من YAML إلى JSON حين تحتاج صرامة ملائمة للآلة؛ ومن JSON إلى YAML حين تريد ملف إعداد يستطيع الإنسان قراءته فعلًا. تُحلَّل بمخطط YAML 1.2 الأساسي (دون تهيئة كائنات خطرة)، وتُثبَّت الأخطاء بصف وعمود دقيقين، وترفض طي الأسطر الطويلة لتبقى المخرجات صديقة للـ diff.

كيفية الاستخدام#

1. اختر اتجاهًا من مفتاح الزرّين أعلى يسار شريط الأدوات:
   • YAML → JSON (الافتراضي): الصق YAML على اليسار، احصل على JSON صارم على اليمين.
   • JSON → YAML: الصق JSON على اليسار، احصل على YAML مُزاح على اليمين.
2. اختر المسافة البادئة — 2 أو 4 مسافات. يتحكم هذا في عمق تداخل المخرجات على الجانبين.
3. انقر مثال لتحميل مثال قصير إن أردت رؤية السلوك قبل لصق بياناتك، أو مسح لمسح اللوحتين.
4. تتحدّث اللوحة اليمنى أثناء جريان التحويل. يُبلِّغ شريط الحالة أسفلها واحدًا من ثلاثة: سطر نجاح بحجم مخرجات البايتات، أو تلميح إدخال فارغ، أو خطأ تحليل بصف وعمود يبدأ من 1 يشير إلى الرمز المُخطئ تمامًا.
5. انقر نسخ في ترويسة المخرجات لأخذ النتيجة.

يجري التحويل لحظة تحلَّل المدخلات. لا يوجد زر توليد لتضغطه — أصلح الإدخال ويُحدَّث المخرج.

الميزات الرئيسية#

• ثنائي الاتجاه، بلوحة واحدة. تخطيط الإدخال/الإخراج نفسه يتعامل مع كلا الاتجاهين؛ المفتاح يقرر أي محلّل يجري.
• مخطط YAML 1.2 الأساسي. تُحلّ null، وtrue/false، والأعداد الصحيحة، والعشرية، والسلاسل المُحاطة تمامًا كما يحلّها محلّل مطابق للمعيار — لا بكتلة تقريبية فضفاضة.
• تعطيل طي الأسطر. لا تُلفّ أسطر المخرجات الطويلة ولا تُختصَر أبدًا، فيُظهر الـ diff مقابل ملف مُودَع التغييرات الحقيقية فقط.
• موقع خطأ دقيق. إزاحة غير محاذية أو : شارد يُبلَّغ عنه كـ row:col، لا كـ “تعذّر التحليل” عام.
• محمي ضد العمق. الإدخال العميق التداخل (توسيع “billion-laughs” الكلاسيكي لـ YAML) محدود السقف، فلا يستطيع ملف عدائي أو متكرر عرضيًّا تجميد التبويب.
• محلي فقط. لا تغادر إعداداتك الصفحة — فلا خادم خلفي لإرسالها إليه. بعد ميغابايت، يُسلَّم التحليل الثقيل إلى عامل خلفي ليبقى الواجهة مستجيبة.

مثال عملي#

مهمة حقيقية شائعة: إعداد خدمة مكتوب كـ YAML يحتاج للذهاب إلى متن طلب JSON. الصق هذا في اللوحة اليسرى مع YAML → JSON وإزاحة 2:

name: api-gateway
port: 8080
replicas: 3
targets:
  - host: example.com
    port: 443
  - host: cdn.example.com
    port: 8443
features:
  retries: true
  timeout_ms: 2500

تُنتج اللوحة اليمنى JSON صارمًا جاهزًا للتحليل:

{
  "name": "api-gateway",
  "port": 8080,
  "replicas": 3,
  "targets": [
    {
      "host": "example.com",
      "port": 443
    },
    {
      "host": "cdn.example.com",
      "port": 8443
    }
  ],
  "features": {
    "retries": true,
    "timeout_ms": 2500
  }
}

لاحظ أن قيم YAML غير المُحاطة 8080، وtrue، و3 صارت على التوالي رقم JSON، وقيمة منطقية، ورقم — كتبها المخطط الأساسي، ولم يكن عليك فعل ذلك. اعكس الاتجاه (JSON → YAML) وألصق JSON عودةً: تحصل على البنية المتداخلة نفسها مُعاد إزاحتها بشرطات لعناصر القائمة، وهي الصورة التي تُودِعها في مستودع إعدادات.

الأسئلة الشائعة#

هل تُحفظ تعليقات YAML عبر رحلة الذهاب والإياب؟#

لا. ليس لـ JSON صياغة تعليقات أصلًا، فأي # comment في YAML تُقرأ ثم تُسقَط في طريقها إلى JSON — فلا مكان لوضعها ببساطة. تُتسامَح التعليقات في الإدخال (لا تُسبّب خطأً أبدًا)، لكنها لا تنجو من العبور. إن كانت التعليقات مهمة، أبقِ YAML مصدرًا للحقيقة وولّد JSON منه كل مرة.

هل يتعامل مع YAML متعدد المستندات (ملفات مفصولة بـ ---)؟#

يُعالَج تيار المستندات ويُعاد المستند الرئيسي. معظم ملفات الإعداد والبيانات أحادية المستند، فنادرًا ما يكون هذا مشكلة؛ إن كان لديك تيار متعدد المستندات، قسّمه على فواصل --- وحوّل كل جزء.

YAML أم JSON لملف إعدادي — أيهما أختار؟#

استخدم YAML حين يحرّره إنسان يدويًّا وتريد قابلية قراءة شبيهة بالتعليقات مع مراسي وتداخل بالإزاحة. واستخدم JSON حين تُنتجه آلة ويستهلكه محلّل، أو حين تهم الصرامة (لـ JSON طريقة قانونية واحدة تمامًا لكتابة كل قيمة، فلا غموض لتتنقّحه). وُجدت هذه الأداة لئلا تضطر للالتزام بواحدة فقط.

يقول الخطأ “row 4, col 5” لكن ذلك السطر يبدو سليمًا. ما المشكلة؟#

تقريبًا دائمًا الإزاحة. يقرر YAML البنية من المسافات البادئة، فابن متبقّي بمسافة بعيدة جدًا يسارًا أو يمينًا — أو مزيج تبويبات ومسافات — يظهر كخطأ على السطر بعد المُخطئ الحقيقي، لأن المحلّل يلاحظ التناقض فقط حين يقرأ الرمز التالي. تحقّق من إزاحة السطر فوق الصف المُبلَّغ عنه أولًا.