مبدل JSON ↔ YAML — تبدیل بین JSON و YAML آنلاین _

تبدیل JSON ↔ YAML چیست؟

JSON (نمادگذاری شیء JavaScript، RFC 8259) یک فرمت متنی دقیق و محدود‌شده با آکولاد برای داده‌های ساختاریافته است؛ YAML (YAML Ain't Markup Language، نسخه ۱.۲) یک superset از JSON است که از تورفتگی، شکست خط و سینتکس خوانا برای همان مدل مقدار استفاده می‌کند. تبدیل بین آن‌ها به شما امکان می‌دهد همان پیکربندی را بین یک فرمت ماشین‌دوست (JSON برای API ها، اعتبارسنجی schema، تبدیل‌های برنامه‌نویسی) و یک فرمت انسان‌دوست (YAML برای code review، manifest های Kubernetes، workflow های GitHub Actions) بدون تایپ مجدد هیچ کلیدی جابجا کنید.

تبدیل JSON ↔ YAML چگونه کار می‌کند؟

هر تبدیل به صورت محلی در مرورگر شما با استفاده از کتابخانه js-yaml همراه‌شده (MIT، نسخه ۴.۱.۰) اجرا می‌شود. مراحل سطح بالا:

1. انتخاب‌گر حالت (تشخیص خودکار / JSON → YAML / YAML → JSON) تصمیم می‌گیرد کدام خط لوله اجرا شود. در حالت تشخیص خودکار اولین کاراکتر غیر فاصله ورودی جهت را مشخص می‌کند — { یا [ به معنای JSON است؛ هر چیز دیگری به معنای YAML است.
2. JSON → YAML: JSON.parse ورودی را اعتبارسنجی می‌کند و یک مقدار JavaScript تولید می‌کند؛ jsyaml.dump(value, { indent, lineWidth: -1, sortKeys: false }) فرم YAML 1.2 را می‌نویسد. با Multi-document روشن، یک آرایه ورودی یک عنصر به ازای هر سند با جداکننده‌های --- dump می‌شود.
3. YAML → JSON: jsyaml.loadAll هر سند در ورودی را تجزیه می‌کند (جداکننده‌های --- را به صورت خودکار مدیریت می‌کند) به یک آرایه؛ ورودی‌های تک‌سند باز می‌شوند تا خروجی JSON خود سند باشد نه یک آرایه یک‌عنصری.
4. تورفتگی (۲ یا ۴ فاصله) و Pretty-print قابل‌تنظیم هستند. خاموش بودن Pretty-print JSON فشرده‌شده از طریق JSON.stringify(value) بدون فاصله خالی منتشر می‌کند.
5. خروجی به textarea فقط‌خواندنی نوشته می‌شود. در صورت شکست تجزیه YAML، پیام خطا شامل خط و ستون ۱-indexed گزارش‌شده توسط e.mark js-yaml می‌شود تا بتوانید مستقیماً به باگ بروید.

چرا JSON و YAML را با این ابزار تبدیل کنیم؟

• حریم خصوصی: هر پاس تجزیه، تبدیل و انتشار در مرورگر شما اتفاق می‌افتد. داده‌ها — شامل secrets Kubernetes، JWT های امضاشده و ponfig های اختصاصی — هرگز به سرورهای ما نمی‌رسند.
• YAML چند‌سندی: jsyaml.loadAll جداکننده‌های --- را تشخیص می‌دهد و یک آرایه از اسناد برمی‌گرداند که مبدل برای موارد تک‌سند آن را باز می‌کند یا برای موارد چند‌سند به عنوان یک آرایه JSON حفظ می‌کند.
• Anchor ها و alias ها حل می‌شوند: مکانیزم &anchor / *alias در YAML توسط schema پیش‌فرض js-yaml مدیریت می‌شود. یک مقدار که یک بار تعریف و دو بار ارجاع داده شده، به یک شیء JSON دور برگشت می‌کند که همه ارجاعات مقادیر برابر دارند.
• بدون CDN، بدون telemetry: کتابخانه js-yaml.min.js از همان مبدأ صفحه ارسال می‌شود، بنابراین ابزار به صورت آفلاین، پشت proxy های شرکتی و داخل محیط‌های air-gapped کار می‌کند.

کاربردهای رایج تبدیل JSON ↔ YAML چیست؟

جابجایی بین JSON و YAML در DevOps، مهندسی platform و ابزار API نمایان می‌شود:

• Manifest های Kubernetes: تبدیل یک Deployment، ConfigMap یا HelmRelease YAML به JSON تا یک اعتبارسنج policy داخلی (Joi، Ajv، OPA Rego) بتواند آن را به صورت برنامه‌نویسی lint کند، سپس برگشت به YAML برای اعمال به cluster.
• Workflow های CI/CD: دور برگشت یک workflow.yml GitHub Actions از طریق JSON تا یک code-generator بتواند matrix یا وابستگی‌های job را بازنویسی کند، سپس انتشار YAML پاک‌شده برای PR.
• مشخصات OpenAPI: پیست کردن یک openapi.json JSON از مستندات خودکارتولیدشده backend و تبدیل به openapi.yaml برای مرجع انسان‌ویرایش‌شده که در مخزن check-in شده است.

یک مثال دور برگشت JSON ↔ YAML چه شکلی است؟

پیست کردن {"apiVersion":"apps/v1","kind":"Deployment","metadata":{"name":"web"},"spec":{"replicas":3,"selector":{"matchLabels":{"app":"web"}}}} و فشار دادن CONVERT در حالت JSON → YAML هشت خط YAML با تورفتگی با apiVersion: apps/v1 در خط اول تولید می‌کند. ارسال آن YAML در حالت YAML → JSON با Pretty-print روشن شیء اصلی را بایت به بایت پس از یک JSON.stringify(value, null, 2) پایدار برمی‌گرداند، با حفظ ترتیب کلید چون schema پیش‌فرض js-yaml در هر دو جهت ترتیب درج را رعایت می‌کند.

آیا این مبدل JSON ↔ YAML کاملاً در مرورگر من اجرا می‌شود؟

بله. هر پاس تجزیه، تبدیل و انتشار به صورت محلی به عنوان JavaScript داخل تب مرورگر شما اجرا می‌شود. کتابخانه js-yaml همراه‌شده از همان مبدأ صفحه ارسال می‌شود — بدون CDN، بدون fetch، بدون XMLHttpRequest، بدون navigator.sendBeacon روی ورودی. ابزار همچنین وقتی صفحه بارگذاری شد به صورت آفلاین کار می‌کند، چون یک بسته HTML/CSS/JS استاتیک با کتابخانه vendor کپی‌شده کنارش است. secrets Kubernetes، payload های JWT، YAML های CloudFormation امضاشده و config های اختصاصی روی دستگاه شما باقی می‌مانند.

مبدل چگونه YAML چند‌سندی را مدیریت می‌کند؟

YAML از چندین سند در یک جریان جداشده با خطوط حاوی فقط --- پشتیبانی می‌کند. در YAML → JSON مبدل jsyaml.loadAll را صدا می‌زند که هر سند را به عنوان یک مقدار JavaScript برمی‌گرداند. اگر دقیقاً یک سند پیدا شد خروجی JSON همان سند است؛ اگر دو یا بیشتر پیدا شدند خروجی JSON یک آرایه است. در JSON → YAML، وقتی ورودی یک آرایه JSON است و تاگل Multi-document روشن است، هر عنصر آرایه به عنوان سند مستقل خودش با جداکننده‌های --- بین آن‌ها منتشر می‌شود — مفید برای تولید یک بسته سازگار با kubectl apply از یک آرایه JSON از منابع.

آیا anchor ها و alias های YAML پشتیبانی می‌شوند؟

بله — تعاریف &anchor و ارجاعات *alias توسط schema پیش‌فرض js-yaml در طول مرحله بارگذاری حل می‌شوند. یک ورودی YAML مانند defaults: &d\n retries: 3\n timeout: 30\njob_a:\n <<: *d\njob_b:\n <<: *d به یک شیء JSON تجزیه می‌شود که job_a و job_b هر دو دارای retries: 3, timeout: 30 هستند. کلید merge << (یک پسوند YAML 1.1 که js-yaml هنوز رعایت می‌کند) نیز روی schema پیش‌فرض پشتیبانی می‌شود.

آیا کامنت‌های YAML هنگام تبدیل به JSON و برگشت حفظ می‌شوند؟

خیر — js-yaml کامنت‌ها را در طول مرحله تجزیه حذف می‌کند، بنابراین یک دور برگشت YAML → JSON → YAML همه خطوط با پیشوند # را از دست می‌دهد. این یک محدودیت شناخته‌شده مدل load/dump است؛ اگر حفظ کامنت حیاتی است، به جای js-yaml از یک کتابخانه آگاه از کامنت مانند پکیج npm yaml (که یک API CST + AST طراحی‌شده برای حفظ trivia ارسال می‌کند) استفاده کنید. برای اکثر workflow های تبدیل پیکربندی این مبادله قابل‌قبول است: YAML دور برگشت‌شده هر کلید، مقدار، anchor و alias را حفظ می‌کند، فقط بدون کامنت‌های انسان‌نوشته.

با تگ‌های سفارشی YAML چه اتفاقی می‌افتد؟

مبدل از DEFAULT_SCHEMA js-yaml استفاده می‌کند که !!str، !!int، !!float، !!bool، !!null، !!seq، !!map، !!binary و !!timestamp را درک می‌کند — هر تگ در schema های core و JSON YAML 1.2. تگ‌های سفارشی یا خاص اپلیکیشن (مانند !Ref در CloudFormation، !vault در Ansible) شناخته نمی‌شوند و با یک خطای واضح که تگ ناپشتیبانی را ذکر می‌کند نمایان می‌شوند. برای CloudFormation به طور خاص، از جریان aws cloudformation package + --output-template-file برای گسترش تگ‌های سفارشی قبل از پیست کردن در این مبدل استفاده کنید.

این مبدل JSON ↔ YAML با js-yaml@4.1.0 بسته‌شده در همان مبدأ ارسال می‌شود، از جریان‌های چند‌سند و anchor/alias ها از پیش‌درصورت پشتیبانی می‌کند، و خطاهای تجزیه YAML را با خط و ستون گزارش می‌دهد تا بتوانید منبع را اصلاح کنید. بدون آپلود، بدون CDN، بدون telemetry — هر بایت در مرورگر شما باقی می‌ماند.