التحويل بين YAML وJSON: احفظ معنى البيانات لا شكل الملف
قد تكتب الإعدادات في YAML ثم تحتاجها بصيغة JSON لتبادلها مع خدمة. التشابه بين الشكلين لا يعني أن كل ما في الملف الأصلي له مقابل يمكن نقله بلا قرار.
نوع القيمة أهم من شكلها
السلسلة النصية "003" ليست الرقم 3، و"false" بين علامتي اقتباس ليست القيمة المنطقية false. اجعل المعرفات نصوصًا عندما تكون الأصفار أو الكتابة الأصلية جزءًا من معناها.
يعتمد المحول بيانات YAML 1.2 Core المناسبة لـJSON. لا تنقل توقعات نظام قديم تلقائيًا؛ بعض الكلمات التي كان يفسرها قارئ بطريقة قد تقرأ بشكل آخر في إصدار مختلف.
المراجع: YAML 1.2.2 — Core types and comments as presentation
التعليق موجه للقارئ، وليس قيمة بيانات
التعليقات في YAML تساعد من يصون الملف لكنها ليست جزءًا من بياناته. لا تنتقل تعليقاتك إلى JSON هنا، ولا تعود تلقائيًا إذا حولت الناتج إلى YAML مرة أخرى.
احتفظ بالمصدر المشروح في مكانه، وتعامل مع النسخة المحولة كمخرج بيانات. لا تعتمد على لون المحرر أو ترتيب الأسطر وحده للتأكد من بقاء الأنواع كما قصدتها.
المراجع: YAML 1.2.2 — Core types and comments as presentation
رفض البنية المعقدة أفضل من فقدها بصمت
المسار الحالي يقبل مستندًا واحدًا ومفاتيح نصية، ويرفض التكرار والمراجع والمرساة والوسوم المخصصة والخصائص غير القابلة للنقل بأمان إلى النطاق المدعوم.
الأرقام غير القابلة للتمثيل ضمن الحدود تُرفض بدل تقريبها خفية. للمعرفات الطويلة استخدم نصًا، ولا تعتبر التحويل تشغيلًا لإعداداتك أو إثباتًا لصحتها لدى الخدمة المستقبلة.
مثال: ثلاثة أنواع لا ينبغي الخلط بينها
الأسطر code: "003" وenabled: false وretries: 3 تنتج قيمًا هي نص "003"، وقيمة منطقية false، ورقم 3. تظل الأصفار لأن الرمز مكتوب كنص، لا لأن المحول خمن أنه معرف.
إضافة التعليق # staging قبل الأسطر لا تضيف حقلًا إلى JSON. عند العودة إلى YAML يمكن أن تتغير طريقة الاقتباس والتنسيق، بينما تبقى هذه القيم وأنواعها نفسها؛ التعليق الأصلي لا يُستعاد.