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

تبدیل YAML به JSON زمانی لازم می‌شود که فایل تنظیمات، Manifest یا داده‌ای خوانا برای انسان باید وارد API، پایگاه داده، ابزار تحلیل یا سامانه‌ای شود که فقط JSON می‌پذیرد. این تبدیل در ظاهر ساده است، اما تفاوت‌های مهم YAML با JSON—از Comment و Anchor گرفته تا نوع‌دهی ضمنی، کلیدهای غیررشته‌ای و چندسندی بودن—باعث می‌شود تبدیل دقیق فقط با Parse و Serialization استاندارد انجام شود.

پاسخ سریع: برای تبدیل YAML به JSON، متن YAML را با Loader امن Parse کنید، ساختار حاصل را از نظر نوع داده و محدودیت‌های JSON بررسی کنید و سپس با Serializer استاندارد JSON خروجی بگیرید. تبدیل با Replace یا حذف تورفتگی قابل اعتماد نیست.

تبدیل YAML به JSON دقیقاً چیست؟

YAML و JSON هر دو برای نمایش داده ساخت‌یافته استفاده می‌شوند، اما YAML امکانات بیشتری برای ویرایش انسانی دارد. در فرایند تبدیل، Mappingهای YAML به Object، Sequenceها به Array و Scalarها به String، Number، Boolean یا null در JSON تبدیل می‌شوند.

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

خروجی JSON معادل:

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

هدف اصلی حفظ معنا و نوع داده‌هاست؛ نه حفظ شکل ظاهری فایل.

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

ویژگی	YAML	JSON
ساختار	تورفتگی‌محور	آکولاد، براکت و کاما
کلید	می‌تواند انواع بیشتری داشته باشد	عملاً باید String باشد
Comment	پشتیبانی می‌شود	پشتیبانی نمی‌شود
Anchor و Alias	پشتیبانی می‌شود	معادل مستقیم ندارد
چند سند	ممکن است در یک فایل باشد	یک مقدار ریشه استاندارد
Quote	برای بسیاری از Stringها اختیاری	String و کلید Object با Double Quote
نوع‌دهی	ممکن است ضمنی و نسخه‌محور باشد	مجموعه نوع محدودتر و صریح‌تر

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

1. Encoding ورودی را مشخص کنید؛ UTF-8 انتخاب معمول است.
2. YAML را با Loader امن و سازگار با نسخه مورد انتظار Parse کنید.
3. خطاهای Syntax، تورفتگی و نوع‌دهی را قبل از تولید خروجی رفع کنید.
4. کلیدها، تاریخ‌ها، Binary، Anchorها و مقدارهای ویژه را برای سازگاری با JSON نرمال کنید.
5. ساختار حاصل را با JSON Serializer معتبر تبدیل کنید.
6. JSON خروجی را دوباره Parse و در صورت وجود با Schema اعتبارسنجی کنید.

چرا تبدیل با Replace کار نمی‌کند؟

جایگزین کردن Colon با ساختار Object، حذف خط تیره‌ها یا افزودن Quote به‌صورت Regex، در داده واقعی شکست می‌خورد. Colon می‌تواند داخل String باشد، تورفتگی سطح ساختار را مشخص می‌کند و خط تیره ممکن است بخشی از مقدار باشد.

message: "name: ali, role: admin"
path: "C:\temp\file.txt"
items:
  - "a:b"
  - "x-y"

فقط Parser می‌تواند تفاوت نشانه ساختاری و متن واقعی را تشخیص دهد.

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

Mapping به Object

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

1: one
true: enabled

تبدیل خودکار این کلیدها به "1" و "true" ممکن است باعث برخورد یا تغییر معنا شود.

Sequence به Array

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

این ساختار به Arrayی از Objectها تبدیل می‌شود. ترتیب اعضای Sequence باید حفظ شود.

Stringهای مبهم

مقدارهایی مانند yes، no، on، تاریخ و عدد دارای صفر ابتدایی در نسخه‌ها و Parserهای مختلف ممکن است نوع متفاوتی بگیرند. برای حفظ String بودن، آن‌ها را Quote کنید.

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

Number

Integer و Float معمولاً مستقیم منتقل می‌شوند؛ اما Infinity، NaN، عددهای بسیار بزرگ و قالب‌های خاص YAML با JSON استاندارد سازگار نیستند. در این موارد باید مقدار رد، نرمال یا به String تبدیل شود.

Boolean و null

Boolean و null استاندارد قابل تبدیل‌اند. با این حال Scalar خالی YAML ممکن است به null تعبیر شود؛ این موضوع باید با قرارداد داده شما هماهنگ باشد.

Commentها چه می‌شوند؟

JSON استاندارد Comment ندارد. بیشتر Loaderها هنگام Parse کردن YAML، Commentها را دور می‌اندازند. اگر Comment بخشی از مستندات یا دانش عملیاتی است، آن را در فایل جداگانه، فیلد توضیحی یا ابزار Round-trip-aware نگه دارید. تبدیل معمولی YAML به JSON برگشت‌پذیر از نظر Comment نیست.

Anchor، Alias و Merge Key

defaults: &defaults
  timeout: 30
  retries: 3

service:
  <<: *defaults
  timeout: 60

JSON Anchor و Alias ندارد. Loader معمولاً Alias را Resolve و داده نهایی را تکرار می‌کند. در نتیجه ارتباط اشتراکی و نام Anchor از بین می‌رود. Merge Key نیز باید پیش از Serialization به Mapping نهایی تبدیل شود.

YAML چندسندی و JSON

یک فایل YAML می‌تواند چند سند با جداکننده --- داشته باشد، در حالی که JSON استاندارد یک مقدار ریشه دارد. برای تبدیل باید سیاست روشن داشته باشید:

• هر سند را در فایل JSON جداگانه بنویسید.
• همه سندها را در یک Array قرار دهید.
• اگر فقط یک سند مجاز است، ورودی چندسندی را رد کنید.

---
name: first
---
name: second

[
  {"name": "first"},
  {"name": "second"}
]

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

const yamlText = `name: xdflow
active: true`;
const data = yamlLibrary.load(yamlText, { schema: safeSchema });
const jsonText = JSON.stringify(data, null, 2);
console.log(jsonText);

نام متد و تنظیمات دقیق به کتابخانه وابسته است. نکته اصلی استفاده از Loader امن، مدیریت خطا و سپس JSON.stringify است. برای ورودی ناشناس، محدودیت اندازه و عمق نیز اعمال کنید.

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

import json
import yaml

with open("input.yaml", encoding="utf-8") as source:
    data = yaml.safe_load(source)

with open("output.json", "w", encoding="utf-8") as target:
    json.dump(
        data,
        target,
        ensure_ascii=False,
        indent=2
    )

safe_load از ساخت Objectهای دلخواه جلوگیری می‌کند. برای فایل چندسندی باید از API مخصوص Load همه سندها استفاده و سیاست خروجی را مشخص کنید.

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

در CI/CD بهتر است تبدیل قطعی و قابل تکرار باشد. نسخه Parser را ثابت کنید، خروجی را در فایل موقت بنویسید و فقط پس از Validation آن را جایگزین فایل مقصد کنید.

• شکست Parse باید Job را متوقف کند.
• Warningهای نوع‌دهی یا کلید ناسازگار ثبت شوند.
• JSON خروجی دوباره Parse شود.
• برای داده قراردادی، Schema Validation اجرا شود.
• فایل‌های تولیدی در Diff و Review قابل مشاهده باشند.

مثال واقعی: تبدیل تنظیمات سرویس

service:
  name: api
  replicas: 3
  features:
    - search
    - export
  limits:
    cpu: "500m"
    memory: "256Mi"
  environment:
    DEBUG: false
    BUILD_ID: "0017"

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

Quote در BUILD_ID مانع تبدیل آن به Number می‌شود و واحدهای CPU و Memory نیز String باقی می‌مانند.

خطاهای رایج YAML پیش از تبدیل

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

YAML به تورفتگی حساس است. مخلوط کردن سطح‌ها یا استفاده از Tab می‌تواند ساختار را تغییر دهد یا Parse را متوقف کند.

Colon بدون فاصله یا Quote

Colon در مقدارهای متنی ممکن است نیازمند Quote باشد. پیام‌ها، URLهای داخلی و زمان‌ها را با دقت بررسی کنید.

Duplicate Key

بعضی Parserها آخرین مقدار کلید تکراری را نگه می‌دارند و برخی خطا می‌دهند. برای جلوگیری از از دست رفتن داده، Duplicate Key را خطا در نظر بگیرید.

نوع‌دهی ناخواسته

رشته‌ای که شبیه تاریخ، Boolean یا Number است ممکن است با نوع دیگری وارد JSON شود. قرارداد نوع را با Schema یا تست صریح کنترل کنید.

مقدارهای ناسازگار با JSON

NaN، Infinity، Timestamp اختصاصی، Binary و Tag سفارشی معادل استاندارد مستقیم ندارند. سیاست نرمال‌سازی باید از قبل مشخص باشد.

اعتبارسنجی پس از تبدیل

1. JSON تولیدشده باید با Parser استاندارد قابل خواندن باشد.
2. نوع و مقدار فیلدهای مهم با داده Parseشده YAML مقایسه شود.
3. کلیدهای Object همگی String و یکتا باشند.
4. هیچ مقدار غیرقابل نمایش در JSON باقی نمانده باشد.
5. در صورت وجود، JSON Schema روی خروجی اجرا شود.
6. برنامه مصرف‌کننده فایل در تست Integration اجرا شود.

Round Trip چه چیزی را تضمین می‌کند؟

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

نکات امنیتی مهم

• برای YAML غیرقابل اعتماد از Loader امن استفاده کنید.
• Tagهای سفارشی و ساخت Object دلخواه را غیرفعال کنید.
• اندازه فایل، عمق Nesting، تعداد Alias و تعداد اعضا را محدود کنید.
• از Alias Bomb و مصرف بیش از حد حافظه جلوگیری کنید.
• Secretها را در پیام خطا یا Log کامل چاپ نکنید.
• مسیر فایل خروجی را از ورودی کاربر بدون اعتبارسنجی نسازید.

نکات عملکرد برای فایل‌های بزرگ

بسیاری از Loaderها کل YAML را در حافظه می‌سازند. برای فایل بزرگ، مصرف RAM می‌تواند چند برابر اندازه فایل شود. YAML به‌طور عمومی مثل NDJSON برای Streaming رکوردبه‌رکورد طراحی نشده است، بنابراین بهتر است سند را تقسیم یا فرمت ورودی را بازطراحی کنید.

• قبل از Parse سقف اندازه تعیین کنید.
• برای چند سند، هر سند را مستقل پردازش کنید.
• Pretty Print را فقط در خروجی انسانی فعال کنید.
• مرتب‌سازی کلیدها را در صورت نیاز واقعی انجام دهید.
• در Batch، Concurrency را محدود و مصرف حافظه را اندازه‌گیری کنید.

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

• ارسال فایل تنظیمات به API یا سرویس JSON-based.
• ورود داده YAML به ابزارهای تحلیل، Query یا Diff JSON.
• ذخیره ساختار در دیتابیس Document.
• ساخت Fixture و داده تست برای برنامه‌های JavaScript.
• یکسان‌سازی فرمت داده در Pipeline.

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

اگر Commentها، Anchorها، خوانایی دستی یا ساختار چندسندی اهمیت دارد، YAML را منبع اصلی نگه دارید و JSON را به‌عنوان Artifact تولیدی بسازید. ویرایش مستقیم هر دو نسخه باعث Drift می‌شود؛ یک Source of Truth مشخص کنید.

بهترین روش‌ها

• تبدیل را Parse → Normalize → Serialize انجام دهید.
• نسخه و Schema Parser YAML را ثابت نگه دارید.
• Duplicate Key را خطا تلقی کنید.
• کلیدهای غیررشته‌ای را بدون سیاست مشخص تبدیل نکنید.
• Comment و Anchor را اطلاعات از دست‌رفتنی در نظر بگیرید.
• JSON خروجی را Parse و Schema Validate کنید.
• برای فایل عملیاتی، تست مصرف‌کننده را اجرا کنید.

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

• YAML با Loader امن Parse شده است.
• Encoding ورودی UTF-8 یا مشخص است.
• Duplicate Key بررسی شده است.
• Stringهای مبهم Quote شده‌اند.
• کلیدهای غیررشته‌ای مدیریت شده‌اند.
• Anchor و Alias Resolve شده‌اند.
• سیاست فایل چندسندی مشخص است.
• NaN، Infinity و Tagهای سفارشی مدیریت شده‌اند.
• JSON خروجی دوباره Parse شده است.
• Schema و تست برنامه مقصد اجرا شده‌اند.

مهاجرت مرحله‌ای از YAML به JSON در پروژه واقعی

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

در مرحله بعد یک ابزار تولید قطعی تعریف کنید تا JSON همیشه از YAML منبع ساخته شود. ویرایش دستی نسخه JSON را ممنوع یا در Pipeline کنترل کنید، چون وجود دو فایل قابل ویرایش به‌سرعت باعث اختلاف می‌شود. برای هر تغییر در YAML، تست تبدیل و Schema Validation اجرا شود و Diff خروجی در Code Review دیده شود. پس از مدتی که همه مصرف‌کننده‌ها از JSON استفاده کردند، می‌توان درباره تغییر Source of Truth تصمیم گرفت.

تست برابری داده قبل و بعد از تبدیل

مقایسه متن YAML و JSON معنی ندارد، چون Syntax آن‌ها متفاوت است. تست درست باید روی درخت داده انجام شود. YAML را Parse کنید، آن را طبق سیاست پروژه نرمال کنید، JSON را تولید و دوباره Parse کنید؛ سپس مقدارها و نوع‌ها را به‌صورت بازگشتی مقایسه کنید. ترتیب Array باید دقیقاً یکسان باشد، اما ترتیب کلیدهای Object معمولاً نباید معیار برابری باشد.

• برای Numberهای بزرگ، مقایسه را با نوع دقیق انجام دهید.
• برای Timestamp مشخص کنید خروجی String است یا مقدار نرمال‌شده.
• برای Alias بررسی کنید نتیجه Resolveشده همان مقدار مورد انتظار باشد.
• برای null، String خالی و Scalar خالی تست‌های جدا بنویسید.
• برای Unicode و متن فارسی، Encoding و عدم Escape ناخواسته را بررسی کنید.

سیاست پیشنهادی برای قابلیت‌های بدون معادل مستقیم

قابلیت YAML	سیاست پیشنهادی
Comment	حذف آگاهانه یا انتقال به Metadata جدا
Anchor و Alias	Resolve کردن و ثبت احتمال افزایش حجم
Merge Key	تبدیل به Mapping نهایی پیش از Serialization
Tag سفارشی	رد کردن، یا تبدیل با Handler محدود و صریح
Binary	تبدیل به String با Encoding قراردادی
Timestamp	تبدیل به String استاندارد و مستند
چند سند	Array، فایل‌های جدا یا رد ورودی طبق قرارداد

مهم‌تر از انتخاب هر سیاست، ثابت و مستند بودن آن است. اگر دو سرویس یک مقدار YAML را با سیاست متفاوت تبدیل کنند، داده ظاهراً مشابه می‌تواند رفتار متفاوتی ایجاد کند. قرارداد تبدیل باید همراه نسخه ابزار، Schema و تست‌ها در مخزن پروژه نگهداری شود.

جمع‌بندی

تبدیل YAML به JSON زمانی قابل اعتماد است که بر مبنای Parser و Serializer استاندارد انجام شود. مهم‌ترین چالش‌ها Comment، Anchor، نوع‌دهی ضمنی، کلیدهای غیررشته‌ای، چندسندی بودن و مقدارهای ناسازگار با JSON هستند. با Loader امن، نرمال‌سازی آگاهانه و Validation خروجی می‌توان ساختار داده را بدون تغییر ناخواسته به JSON منتقل کرد.