محوّل JSON إلى YAML

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

// Convert JSON to YAML in Node.js using the eemeli/yaml library
import { Document } from 'yaml';

const data = JSON.parse('{"apiVersion":"apps/v1","kind":"Deployment"}');

// version: '1.1' ensures Norway-problem strings (yes/no/on/off/y/n)
// are automatically quoted in the output for YAML 1.1 parser safety
const doc = new Document(data, { version: '1.1' });

const yamlString = doc.toString({
  indent: 2,
  lineWidth: 0,         // disable line wrapping
  defaultStringType: 'PLAIN',   // Auto mode: only quote when needed
});

console.log(yamlString);
// apiVersion: apps/v1
// kind: Deployment

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

أمثلة

{"apiVersion":"apps/v1","kind":"Deployment","metadata":{"name":"my-app","namespace":"production","labels":{"app":"my-app","version":"1.0.0"}},"spec":{"replicas":3,"selector":{"matchLabels":{"app":"my-app"}},"template":{"metadata":{"labels":{"app":"my-app"}},"spec":{"containers":[{"name":"my-app","image":"my-app:1.0.0","ports":[{"containerPort":8080}],"resources":{"requests":{"memory":"64Mi","cpu":"250m"},"limits":{"memory":"128Mi","cpu":"500m"}}}]}}}}

{"version":"3.9","services":{"web":{"image":"nginx:1.25-alpine","ports":["80:80","443:443"],"environment":{"NGINX_HOST":"example.com","NGINX_PORT":"80"},"depends_on":["db"],"restart":"unless-stopped"},"db":{"image":"postgres:16-alpine","environment":{"POSTGRES_DB":"mydb","POSTGRES_USER":"admin","POSTGRES_PASSWORD":"secret"},"volumes":["pgdata:/var/lib/postgresql/data"]}},"volumes":{"pgdata":{}}}

{"name":"CI","on":{"push":{"branches":["main"]},"pull_request":{"branches":["main"]}},"jobs":{"build":{"runs-on":"ubuntu-latest","steps":[{"uses":"actions/checkout@v4"},{"name":"Set up Node.js","uses":"actions/setup-node@v4","with":{"node-version":"20","cache":"pnpm"}},{"name":"Install dependencies","run":"pnpm install --frozen-lockfile"},{"name":"Run tests","run":"pnpm test"}]}}}

{"openapi":"3.0.3","info":{"title":"User API","version":"1.0.0","description":"Manage application users"},"paths":{"/users":{"get":{"summary":"List users","operationId":"listUsers","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/User"}}}}}}}},"/users/{id}":{"get":{"summary":"Get user","operationId":"getUser","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}}}},"components":{"schemas":{"User":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"}}}}}}

{"name":"my-app","version":"1.0.0","description":"A sample Node.js application","private":true,"scripts":{"dev":"vite","build":"tsc && vite build","preview":"vite preview","test":"vitest","lint":"eslint . --ext .ts,.tsx"},"dependencies":{"react":"^18.3.0","react-dom":"^18.3.0"},"devDependencies":{"typescript":"^5.4.0","vite":"^5.2.0","vitest":"^1.5.0","eslint":"^8.57.0","@types/react":"^18.3.0"},"engines":{"node":">=20.0.0","pnpm":">=9.0.0"}}

{"format_version":"1.0","terraform_version":"1.7.4","variables":{"region":{"value":"us-east-1"}},"planned_values":{"root_module":{"resources":[{"address":"aws_s3_bucket.main","mode":"managed","type":"aws_s3_bucket","name":"main","values":{"bucket":"my-app-assets","force_destroy":false,"tags":{"Environment":"production","ManagedBy":"terraform"}}}]}},"resource_changes":[{"address":"aws_s3_bucket.main","mode":"managed","type":"aws_s3_bucket","name":"main","change":{"actions":["create"],"before":null,"after":{"bucket":"my-app-assets","force_destroy":false}}}]}

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

1. 1

   الصق بيانات JSON

   أدخل أو الصق بيانات JSON في حقل الإدخال أعلاه. يمكنك أيضاً النقر على «تحميل مثال» لتجربة عينة كنشر Kubernetes أو ملف Docker Compose أو خطة Terraform.

2. 2

   شاهد إخراج YAML مباشرة

   يظهر YAML فوراً في لوحة الإخراج. اضبط الخيارات (المسافة البادئة 2/4، الاقتباس تلقائي/مزدوج/مفرد، الأسلوب كتلة/تدفق) لتتطابق مع متطلبات الأداة المستهدفة.

3. 3

   انسخ أو حمّل

   انقر على «انسخ» لنقل YAML إلى الحافظة، أو «تحميل» لحفظه كملف .yaml جاهز لاستخدامه مع kubectl apply أو docker compose up أو أي أداة أخرى.

أخطاء التحويل الشائعة

{"name": "Alice", "role": "admin",}

{"name": "Alice", "role": "admin"}

{'name': 'Alice', 'active': true}

{"name": "Alice", "active": true}

{name: "Alice", role: "admin"}

{"name": "Alice", "role": "admin"}

{"port": 8080 // HTTP port}

{"port": 8080}

# JSON input: {"country": "no", "enabled": "yes"}
# YAML without quoting (dangerous):
country: no
enabled: yes
# YAML 1.1 parser reads: country=false, enabled=true

# YAML with Auto quoting (safe):
country: 'no'
enabled: 'yes'
# YAML 1.1 parser reads: country="no", enabled="yes"

// JSON input (resourceVersion is int64 on K8s server)
{"resourceVersion": 9007199254740993}
// JavaScript reads it as: 9007199254740992 (precision lost)
// YAML output will contain the wrong number

// Store large integers as strings to preserve precision
{"resourceVersion": "9007199254740993"}
// YAML output: resourceVersion: '9007199254740993' (exact)

حالات الاستخدام الشائعة

بيانات Kubernetes

تحويل استجابات JSON API من kubectl get -o json أو Kubernetes API إلى بيانات YAML لسير عمل GitOps وطبقات Kustomize ونشرات kubectl apply -f.

ملفات Docker Compose

تحويل إخراج docker inspect JSON أو إعدادات الخدمات المُنشأة برمجياً إلى ملفات docker-compose.yaml متوافقة مع docker compose up ونشرات Docker Stack.

قيم Helm Chart

تحويل تصديرات إعداد JSON إلى ملفات قيم YAML لنشرات Helm chart، مما يتيح إعداد البنية التحتية المُتحكَّم في إصداراته بصيغة YAML نظيفة.

سير عمل GitHub Actions

بناء تعريفات سير عمل GitHub Actions برمجياً بـ JSON وتحويلها إلى صيغة .github/workflows/*.yaml المطلوبة لمشغّل GitHub Actions.

مواصفات OpenAPI

تحويل مواصفات OpenAPI/Swagger من صيغة JSON التي تُعيدها كثير من الأُطر البرمجية (FastAPI، SpringDoc) إلى صيغة YAML المفضلة لـ Swagger UI وRedoc وأدوات بوابة API.

ترحيل الإعدادات

ترحيل إعداد التطبيق المُخزَّن في JSON (appsettings.json، config.json) إلى صيغة YAML للأدوات التي تتطلب أو تفضل YAML، مع إمكانية إضافة تعليقات للتوثيق.

تفاصيل تقنية

تحليل JSON متوافق مع RFC 8259

يُحلَّل مدخل JSON باستخدام JSON.parse() الأصلي في المتصفح، المتوافق كلياً مع RFC 8259. يوفر رسائل خطأ دقيقة في الصياغة تتضمن معلومات الموضع (رقم السطر والعمود بأفضل جهد ممكن)، ويتعامل مع جميع أنواع بيانات JSON: السلاسل النصية والأرقام والقيم المنطقية وnull والمصفوفات والكائنات.

إخراج YAML 1.2 عبر واجهة Document API من eemeli/yaml مع مخطط YAML 1.1

يُولَّد YAML باستخدام مكتبة eemeli/yaml (الإصدار v2.8+، آمن من الثغرات) عبر Document API مع version: '1.1'. ينتج هذا التوليف إخراجاً متوافقاً مع YAML 1.2 مع تطبيق قواعد اقتباس YAML 1.1 — أي أن سلاسل مشكلة Norway (yes/no/on/off/y/n) تُقتبَس تلقائياً في الإخراج، مما يجعله آمناً لمحللات YAML 1.1 وYAML 1.2.

100% قائم على المتصفح — بدون رفع ملفات أو خادم

تتم جميع المعالجة كلياً في محرك JavaScript بمتصفحك. لا تُرسَل أي بيانات عبر الشبكة في أي وقت. تتحول المدخلات الأكبر من 200 كيلوبايت تلقائياً من الوضع المباشر إلى الوضع اليدوي (مطلوب نقر «تحويل» صريح) للحفاظ على استجابة المتصفح ومنع تعطّل مسار التنفيذ الرئيسي أثناء التسلسل الثقيل.

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

استخدم دائماً وضع الاقتباس التلقائي لإعدادات DevOps

عند تحويل JSON للاستخدام في Kubernetes أو Helm أو Ansible أو Docker Compose أو GitHub Actions، استخدم دائماً وضع الاقتباس الافتراضي «التلقائي (آمن من مشكلة Norway)». ستُفسَّر السلاسل النصية المجردة yes وno وon وoff وy وn بصمت كقيم منطقية بواسطة محللات YAML 1.1 في هذه الأدوات — يمنع وضع التلقائي هذا بشفافية.

استخدم مسافة بادئة مسافتين للأدوات السحابية الحديثة

تستخدم Kubernetes وDocker Compose وGitHub Actions وHelm بالاتفاقية مسافتين للمسافة البادئة. استخدام 4 مسافات في هذه الملفات صالح بصيغة YAML لكنه يُنشئ عدم اتساق مع الأمثلة المجتمعية والإعدادات المُنشأة تلقائياً وبيانات فريقك الحالية.

خزّن الأعداد الصحيحة الكبيرة كسلاسل نصية قبل التحويل

يمكن أن تتجاوز حقول Kubernetes مثل resourceVersion وuid وحقول int64 الأخرى من خادم API نطاق الأعداد الصحيحة الآمنة في JavaScript (2^53 - 1). إذا كنت بحاجة إلى دقة عددية تامة، خزّن هذه القيم كسلاسل نصية في JSON قبل التحويل.

تحقق من JSON أولاً

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

فضّل أسلوب الكتلة للملفات في التحكم بالإصدارات

يُنتج YAML بأسلوب الكتلة فروقات نظيفة ومقروءة بشرياً في Git لأن كل حقل يظهر في سطره الخاص. يجعل أسلوب التدفق (المضغوط، المتضمن) الفروقات أصعب قراءةً ومراجعة. احتفظ بأسلوب التدفق لتضمين مقاطع YAML الصغيرة في التوثيق أو للأدوات التي تتطلب إخراجاً مضغوطاً.

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