تبدیل JSON به YAML؛ روش صحیح، مثال‌ها و نکات مهم

تبدیل JSON به YAML زمانی مفید است که داده‌ای ماشین‌خوان را به قالبی خواناتر برای فایل‌های تنظیمات، مستندات زیرساخت یا ویرایش دستی تبدیل می‌کنید. با اینکه هر دو فرمت می‌توانند Object، Array، String، Number، Boolean و مقدار null را نمایش دهند، تبدیل همیشه صرفاً جایگزینی علامت‌ها نیست؛ تفاوت در Quoteها، تورفتگی، نوع‌دهی ضمنی، کلیدهای خاص و ساختارهای چندخطی می‌تواند نتیجه را تغییر دهد.

پاسخ سریع: برای تبدیل JSON به YAML ابتدا JSON را Parse کنید، سپس همان ساختار داده را با یک Serializer معتبر YAML خروجی بگیرید. تبدیل مبتنی بر Replace خطرناک است، چون باید تورفتگی، Quote، نوع داده، Escape، Array و Objectهای تو‌در‌تو به‌درستی مدیریت شوند.

تبدیل JSON به YAML دقیقاً چه کاری انجام می‌دهد؟

JSON و YAML هر دو قالب Serialization داده هستند. هنگام تبدیل، هدف این است که ساختار معنایی داده حفظ شود، نه اینکه متن ورودی صرفاً ظاهری متفاوت پیدا کند. برای نمونه، Object در JSON به Mapping در YAML و Array به Sequence تبدیل می‌شود.

{
  "app": "xdflow",
  "debug": false,
  "ports": [3000, 3001],
  "database": {
    "host": "localhost",
    "enabled": true
  }
}

خروجی YAML معادل می‌تواند چنین باشد:

app: xdflow
debug: false
ports:
  - 3000
  - 3001
database:
  host: localhost
  enabled: true

مقدارها و رابطه میان آن‌ها حفظ شده‌اند، اما براکت‌ها، آکولادها و کاماها با تورفتگی و نشانه‌های YAML جایگزین شده‌اند.

تفاوت ساختاری JSON و YAML هنگام تبدیل

مفهوم	JSON	YAML
Object	آکولاد و کلیدهای Quoteشده	Mapping مبتنی بر تورفتگی
Array	براکت و کاما	خط‌های شروع‌شده با خط تیره
String	همیشه داخل Double Quote	گاهی بدون Quote مجاز است
Boolean	true و false	true و false؛ رفتار Parser نسخه‌محور است
null	null	null یا ~ بسته به Serializer
ساختار	نشانه‌محور	تورفتگی‌محور
Comment	پشتیبانی نمی‌کند	پشتیبانی می‌کند، اما در تبدیل از JSON کامنتی وجود ندارد

روش استاندارد تبدیل JSON به YAML

1. متن JSON را با Parser استاندارد بخوانید.
2. اگر Syntax نامعتبر است، تبدیل را متوقف و خطا را گزارش کنید.
3. داده Parseشده را به Serializer معتبر YAML بدهید.
4. تنظیمات Quote، تورفتگی، Line Width و ترتیب کلیدها را مشخص کنید.
5. خروجی YAML را دوباره Parse کنید تا از معتبر بودن آن مطمئن شوید.
6. در داده حساس یا پیکربندی عملیاتی، نتیجه را از نظر معنایی نیز بررسی کنید.

چرا تبدیل با Replace اشتباه است؟

حذف آکولادها، کاماها و Quoteها با چند Replace ساده فقط برای نمونه‌های بسیار محدود کار می‌کند. این روش در Stringهایی که شامل کاما، Colon، خط جدید، Quote یا کاراکتر Escape هستند خراب می‌شود.

{
  "message": "name: ali, role: admin",
  "path": "C:\temp\file.txt"
}

در این نمونه، Colon و کاما بخشی از مقدار String هستند و نباید به‌عنوان نشانه ساختاری تفسیر شوند. Parser و Serializer معتبر این تفاوت را تشخیص می‌دهند.

تبدیل انواع داده JSON به YAML

String

Serializer ممکن است String ساده را بدون Quote بنویسد، اما برای مقدارهای مبهم Quote ضروری است. رشته‌هایی مانند yes، no، تاریخ، عدد با صفر ابتدایی یا مقدارهای شبیه Boolean ممکن است در Parserهای مختلف معنای متفاوتی بگیرند.

status: "yes"
release: "2026-08-06"
code: "00125"

Number

Integer و عدد اعشاری معمولاً مستقیم منتقل می‌شوند. با این حال عددهای بسیار بزرگ، دقت اعشاری و نمایش علمی به محدودیت Runtime و کتابخانه وابسته‌اند. اگر رقم دقیق اهمیت دارد، مقدار را به‌صورت String نگه دارید.

Boolean و null

Booleanهای JSON باید به Boolean واقعی YAML تبدیل شوند، نه String. مقدار null نیز باید بدون تبدیل ناخواسته به رشته خالی حفظ شود.

Objectهای تو‌در‌تو

هر سطح Object با افزایش تورفتگی نمایش داده می‌شود. استفاده از Tab در YAML توصیه نمی‌شود؛ فاصله معمولی و تعداد ثابت Space انتخاب مطمئن‌تری است.

Array

هر عضو Array معمولاً با خط تیره نمایش داده می‌شود. Array می‌تواند شامل Scalar، Object یا Array دیگر باشد.

users:
  - id: 1
    name: Ali
  - id: 2
    name: Sara

مثال کامل تبدیل JSON به YAML

{
  "service": {
    "name": "api",
    "replicas": 3,
    "features": ["search", "export"],
    "limits": {
      "cpu": "500m",
      "memory": "256Mi"
    }
  }
}

service:
  name: api
  replicas: 3
  features:
    - search
    - export
  limits:
    cpu: 500m
    memory: 256Mi

در این تبدیل، مقدارهای 500m و 256Mi String باقی مانده‌اند، چون عدد خالص نیستند.

تبدیل JSON به YAML در JavaScript

در JavaScript باید از کتابخانه‌ای استفاده شود که Serialization استاندارد YAML را انجام دهد. روند کلی به این شکل است:

const input = '{"name":"xdflow","active":true}';
const data = JSON.parse(input);
const yamlText = yamlLibrary.stringify(data);
console.log(yamlText);

نام متد دقیق به کتابخانه بستگی دارد. مهم این است که ابتدا JSON.parse اجرا شود و سپس Object حاصل به Serializer YAML داده شود. برای ورودی کاربر، خطای Parse را مدیریت کنید.

تبدیل JSON به YAML در Python

import json
import yaml

with open('input.json', encoding='utf-8') as source:
    data = json.load(source)

with open('output.yaml', 'w', encoding='utf-8') as target:
    yaml.safe_dump(
        data,
        target,
        allow_unicode=True,
        sort_keys=False
    )

allow_unicode=True برای نمایش مستقیم متن فارسی مناسب است و sort_keys=False ترتیب ورودی را تا حد پشتیبانی کتابخانه حفظ می‌کند. برای Load کردن YAML غیرقابل اعتماد نیز از API امن کتابخانه استفاده کنید.

تبدیل در خط فرمان و Pipeline

در Pipeline بهتر است تبدیل به‌عنوان مرحله‌ای قطعی و قابل تکرار تعریف شود. ورودی باید Validate شود، خروجی با Encoding مشخص نوشته شود و شکست تبدیل باعث توقف Job یا ثبت خطای قابل ردیابی شود.

• Encoding ورودی و خروجی را UTF-8 قرار دهید.
• از نوشتن ناقص فایل مقصد با فایل موقت و Rename اتمیک جلوگیری کنید.
• نسخه Serializer را در پروژه ثابت نگه دارید.
• برای فایل‌های تولیدشده Test Snapshot یا Parse مجدد داشته باشید.

مشکل Quoteها و نوع‌دهی ضمنی

YAML نسبت به JSON قابلیت‌های بیشتری دارد و برخی Parserها Scalarها را به‌صورت ضمنی نوع‌دهی می‌کنند. به همین دلیل یک String در JSON ممکن است اگر بدون Quote نوشته شود، در YAML به Boolean، Date یا Number تعبیر شود.

{
  "enabledText": "false",
  "build": "0010",
  "dateLabel": "2026-08-06"
}

enabledText: "false"
build: "0010"
dateLabel: "2026-08-06"

Quoteها در اینجا برای حفظ نوع String ضروری هستند.

کلیدهای خاص و کاراکترهای مسئله‌ساز

کلیدهایی که Colon، Hash، فاصله ابتدایی، کاراکترهای کنترلی یا نشانه‌های ویژه دارند باید Quote شوند. Serializer معتبر این تصمیم را خودکار می‌گیرد.

"api:version": v1
"#label": internal
" spaced key ": value

String چندخطی در YAML

JSON خط جدید را با Escape داخل String نگه می‌دارد. YAML می‌تواند آن را با Block Scalar نمایش دهد، اما نحوه حفظ یا Fold شدن Line Breakها اهمیت دارد.

{"description":"line one
line two
line three"}

description: |-
  line one
  line two
  line three

علامت و سبک دقیق خروجی به Serializer بستگی دارد. برای متن‌هایی که Line Break باید دقیق حفظ شود، نتیجه را تست کنید.

ترتیب کلیدها در تبدیل

از نظر مدل داده JSON، ترتیب کلیدهای Object نباید مبنای منطق برنامه باشد. با این حال برای خوانایی فایل تنظیمات، حفظ ترتیب ورودی مفید است. بعضی Serializerها به‌صورت پیش‌فرض کلیدها را Sort می‌کنند؛ تنظیم مربوط به Sort را آگاهانه انتخاب کنید.

آیا Commentهای YAML تولید می‌شوند؟

JSON استاندارد Comment ندارد، بنابراین در تبدیل مستقیم اطلاعاتی برای تولید Comment وجود ندارد. اگر Commentهای YAML بخشی از مستندات پیکربندی هستند، باید آن‌ها را جداگانه از Template یا Metadata اضافه کنید. تبدیل رفت‌وبرگشتی ممکن است Commentها را حذف کند.

Anchor و Alias در YAML

YAML امکان Anchor و Alias برای بازاستفاده از ساختار مشترک دارد، اما JSON چنین مفهومی ندارد. Serializer ممکن است برای Referenceهای مشترک در حافظه Anchor بسازد، ولی این رفتار عمومی و ضروری نیست. اگر خروجی باید ساده و قابل حمل باشد، تولید Alias را غیرفعال یا کنترل کنید.

خطاهای رایج هنگام تبدیل JSON به YAML

ورودی JSON نامعتبر

کامای انتهایی، Quote تکی، کلید بدون Quote یا Escape ناقص باعث شکست Parse می‌شود. ابتدا JSON را با Validator بررسی کنید.

تغییر ناخواسته نوع داده

Stringهایی مانند عدد، Boolean یا تاریخ ممکن است بدون Quote به نوع دیگری تبدیل شوند. خروجی را دوباره Parse و نوع مقدارها را مقایسه کنید.

تورفتگی ناسازگار

ویرایش دستی خروجی و ترکیب دو و چهار Space می‌تواند ساختار را عوض کند. از Formatter و Validator YAML استفاده کنید.

استفاده از Tab

Tab در تورفتگی YAML معمولاً نامعتبر یا ناسازگار است. از Space استفاده کنید.

از دست رفتن دقت عددی

عددهای بزرگ ممکن است هنگام Parse شدن در Runtimeهای مبتنی بر Number دقت خود را از دست بدهند. برای شناسه‌ها و رقم‌های حساس از String یا Parser دقیق استفاده کنید.

تبدیل فایل بسیار بزرگ در حافظه

بسیاری از Serializerها کل ساختار را در حافظه نگه می‌دارند. برای داده حجیم، تبدیل Streaming یا تقسیم داده به چند سند کوچک‌تر را بررسی کنید.

اعتبارسنجی نتیجه تبدیل

معتبر بودن Syntax خروجی کافی نیست. روند مطمئن شامل چند سطح بررسی است:

1. Parse موفق JSON ورودی.
2. Serialization موفق YAML.
3. Parse مجدد YAML خروجی.
4. مقایسه ساختار داده قبل و بعد از تبدیل.
5. Schema Validation در صورت وجود قرارداد.
6. تست برنامه‌ای که فایل YAML را مصرف می‌کند.

مقایسه ساختاری پس از Round Trip

یک روش مفید این است که YAML خروجی را دوباره به ساختار داده تبدیل و با داده Parseشده از JSON مقایسه کنید. مقایسه باید روی نوع و مقدار انجام شود، نه روی متن خام؛ چون ترتیب کلیدها و Quoteها ممکن است متفاوت باشد.

نکات امنیتی

• YAML غیرقابل اعتماد را با Loader ناامن Parse نکنید.
• اندازه ورودی، عمق ساختار و تعداد اعضا را محدود کنید.
• خروجی را مستقیماً در مسیر دلخواه کاربر ننویسید؛ نام و مسیر فایل را کنترل کنید.
• اطلاعات محرمانه مانند Token و Password را در Log خطا چاپ نکنید.
• قبل از استفاده در Deploy، Schema و مقادیر حساس را Validate کنید.

نکات عملکرد

• برای فایل کوچک، تبدیل در حافظه ساده و کافی است.
• برای فایل بزرگ، مصرف RAM و زمان Serialization را اندازه‌گیری کنید.
• Pretty Output خواناتر است اما حجم بیشتری دارد.
• مرتب‌سازی کلیدها هزینه دارد و همیشه لازم نیست.
• در Batchهای بزرگ، تبدیل موازی را با سقف Concurrency انجام دهید.

چه زمانی تبدیل JSON به YAML مناسب است؟

• ساخت فایل تنظیمات قابل خواندن برای انسان.
• انتقال تنظیمات تولیدشده از API به قالب مورد انتظار ابزار دیگر.
• مستندسازی نمونه داده در قالبی کم‌نشانه‌تر.
• استفاده در Workflowهای زیرساخت و Automation که YAML می‌پذیرند.
• ویرایش دستی Mappingها و Listهای تو‌در‌تو.

چه زمانی JSON را نگه داریم؟

اگر داده مستقیماً میان سرویس‌ها ردوبدل می‌شود، Parserهای مصرف‌کننده فقط JSON می‌پذیرند، یا نیاز به قرارداد ساده‌تر و رفتار نوع‌دهی قابل پیش‌بینی‌تر دارید، نگه داشتن JSON منطقی‌تر است. YAML خواناتر است، اما حساسیت به تورفتگی و قابلیت‌های بیشتر آن پیچیدگی نیز ایجاد می‌کند.

چک‌لیست تبدیل مطمئن JSON به YAML

• JSON ورودی Parse و Validate شده است.
• از Serializer معتبر YAML استفاده شده است.
• Encoding روی UTF-8 تنظیم شده است.
• Stringهای مبهم Quote شده‌اند.
• دقت عددهای بزرگ بررسی شده است.
• ترتیب کلیدها مطابق نیاز تنظیم شده است.
• YAML خروجی دوباره Parse شده است.
• ساختار و نوع داده‌ها قبل و بعد مقایسه شده‌اند.
• برای داده غیرقابل اعتماد از API امن استفاده شده است.
• فایل نهایی در برنامه مقصد آزمایش شده است.

سناریوی واقعی: مهاجرت تنظیمات یک سرویس

فرض کنید تنظیمات یک سرویس ابتدا از یک API به‌صورت JSON دریافت می‌شود، اما سامانه Deploy فایل YAML می‌خواهد. در این حالت تبدیل باید بخشی از Pipeline باشد، نه کاری دستی و مقطعی. ابتدا JSON ورودی بر اساس قرارداد سرویس بررسی می‌شود، سپس فقط فیلدهای مجاز وارد ساختار مقصد می‌شوند. این مرحله مهم است، چون تبدیل فرمت به‌تنهایی فیلد ناشناخته، مقدار منقضی یا Secret ناخواسته را حذف نمی‌کند.

پس از Serialization، فایل YAML بهتر است با نام موقت نوشته شود. اگر Parse مجدد، Schema Validation و تست برنامه مقصد موفق بود، فایل موقت جایگزین نسخه فعال شود. این الگو از باقی ماندن فایل ناقص در صورت قطع شدن پردازش جلوگیری می‌کند.

service:
  name: api
  environment: production
  replicas: 3
  logging:
    level: info
  features:
    search: true
    export: false

در چنین پیکربندی‌ای باید مشخص شود کدام فیلدها String، Number یا Boolean هستند. برای مثال مقدار production یک String است، اما true باید Boolean باقی بماند. اگر همه مقدارها به String تبدیل شوند، برنامه مقصد ممکن است آن‌ها را نپذیرد یا رفتار متفاوتی نشان دهد.

تست خودکار تبدیل JSON به YAML

برای تبدیل‌های تکرارشونده، تست خودکار از بررسی چشمی قابل اعتمادتر است. یک Test مناسب ورودی‌های ساده، ساختارهای تو‌در‌تو، Array خالی، Object خالی، null، متن فارسی، String چندخطی، عدد اعشاری و Stringهای مبهم را پوشش می‌دهد.

1. نمونه JSON را Parse کنید.
2. آن را به YAML تبدیل کنید.
3. YAML را دوباره Parse کنید.
4. ساختار حاصل را با داده اولیه Deep Compare کنید.
5. برای خروجی‌های حساس، Snapshot خوانا نیز نگه دارید.

Deep Compare باید نوع مقدار را هم بررسی کند. مقدار عددی 10 با String برابر با "10" یکی نیست، حتی اگر هنگام نمایش شبیه هم باشند. همچنین null با رشته خالی یا نبودن کلید تفاوت دارد.

سازگاری نسخه‌های YAML

رفتار بعضی Scalarها میان نسخه‌ها و Parserهای YAML یکسان نیست. مقدارهایی مانند yes، no، on و off در برخی پیاده‌سازی‌های قدیمی ممکن است Boolean تلقی شوند، در حالی که در قراردادهای جدیدتر معمولاً String هستند. برای فایل قابل حمل، Serializer و Parser مقصد را مشخص کنید و Stringهای مبهم را Quote کنید.

بهترین کار این است که نسخه کتابخانه‌های تبدیل در پروژه Pin شود. ارتقای Serializer می‌تواند سبک Quote، نحوه نمایش null، Line Width یا ترتیب کلیدها را تغییر دهد و Diff بزرگی ایجاد کند، حتی اگر داده معنایی ثابت باشد.

مدیریت Secretها و داده حساس

تبدیل فرمت هیچ حفاظ امنیتی برای Secret ایجاد نمی‌کند. اگر JSON شامل Token، Password، کلید خصوصی یا اطلاعات شخصی باشد، YAML خروجی نیز همان داده را خواهد داشت. فایل مقصد باید مجوز دسترسی محدود داشته باشد و در Repository عمومی، Log یا Artifact غیرضروری ذخیره نشود.

• Secretها را پیش از تبدیل Redact نکنید مگر اینکه خروجی واقعاً نسخه عمومی باشد؛ در Pipeline عملیاتی بهتر است از Secret Manager استفاده شود.
• پیام خطا نباید کل ورودی را چاپ کند.
• فایل موقت را در مسیر امن ایجاد و پس از شکست حذف کنید.
• در محیط چندکاربره، نام فایل قابل حدس و مجوز باز ایجاد نکنید.

تبدیل رفت‌وبرگشتی و محدودیت‌های آن

تبدیل JSON به YAML و سپس YAML به JSON معمولاً داده پایه را حفظ می‌کند، اما متن دقیق حفظ نمی‌شود. Quoteها، Commentها، Anchorها، سبک Block Scalar، ترتیب کلیدها و Format عدد ممکن است تغییر کنند. بنابراین Round Trip را برای حفظ ساختار داده استفاده کنید، نه برای بازسازی بایت‌به‌بایت فایل اولیه.

اگر حفظ Comment و Layout اهمیت دارد، به ابزارهایی نیاز دارید که Abstract Syntax Tree یا Concrete Syntax Tree را نگه می‌دارند. Serializerهای معمولی فقط مدل داده را نگه می‌دارند و اطلاعات نمایشی را کنار می‌گذارند.

جمع‌بندی

تبدیل JSON به YAML یک فرایند Serialization است و باید با Parse واقعی JSON و Serializer معتبر YAML انجام شود. مهم‌ترین چالش‌ها حفظ نوع داده، Quote کردن Stringهای مبهم، مدیریت تورفتگی، دقت عددی و بررسی خروجی در برنامه مقصد هستند. ابزار تبدیل می‌تواند این فرایند را سریع کند، اما برای فایل‌های تنظیمات حساس باید نتیجه را Parse، Validate و از نظر معنایی آزمایش کنید.