YAML چیست؟ راهنمای کامل Syntax، ساختار، کاربردها و بهترین روش‌ها

YAML یکی از رایج‌ترین فرمت‌های متنی برای فایل‌های پیکربندی، تعریف Pipeline، تنظیمات زیرساخت، تبادل داده و نگهداری ساختارهای قابل‌خواندن برای انسان است. بسیاری از توسعه‌دهندگان نخستین‌بار YAML را در فایل‌هایی مانند تنظیمات CI/CD، Docker Compose، Kubernetes Manifest، GitHub Actions یا پیکربندی ابزارهای برنامه‌نویسی می‌بینند. ظاهر ساده و کم‌علامت آن باعث می‌شود فایل‌ها نسبت به JSON خواناتر به نظر برسند؛ اما همین انعطاف و وابستگی به تورفتگی می‌تواند خطاهای ظریفی ایجاد کند.

پاسخ سریع: YAML یک فرمت سریال‌سازی داده متنی و انسان‌خوان است که ساختارهایی مانند mapping، sequence و scalar را با استفاده از تورفتگی و نشانه‌های ساده نمایش می‌دهد. YAML برای فایل‌های پیکربندی بسیار مناسب است، اما فاصله‌گذاری، نوع‌دهی ضمنی، کوتیشن، کاراکترهای ویژه و تفاوت نسخه‌ها باید با دقت مدیریت شوند. معتبر بودن Syntax YAML نیز لزوماً به معنی معتبر بودن تنظیمات برای نرم‌افزار مقصد نیست.

YAML چیست؟

YAML یک زبان برنامه‌نویسی نیست؛ یک فرمت سریال‌سازی داده است. هدف آن نمایش داده‌های ساخت‌یافته به شکلی است که هم ماشین بتواند آن را Parse کند و هم انسان بتواند بدون نویز زیاد آن را بخواند و ویرایش کند. ساختار اصلی YAML بر سه مفهوم استوار است:

• Mapping: مجموعه‌ای از کلید و مقدار، مشابه object در JSON.
• Sequence: فهرستی مرتب از مقدارها، مشابه array در JSON.
• Scalar: مقدار ساده مانند متن، عدد، Boolean یا null.

نمونه ساده:

app:
  name: xdflow
  debug: false
  port: 3000
  features:
    - json-tools
    - yaml-tools
    - xml-tools

در این مثال، app یک mapping است، features یک sequence است و مقدارهایی مانند xdflow، false و 3000 scalar هستند.

YAML مخفف چیست؟

YAML در ابتدا با عبارت «Yet Another Markup Language» شناخته می‌شد، اما بعدها برای تأکید بر اینکه YAML یک زبان markup نیست، نام بازگشتی «YAML Ain't Markup Language» برای آن استفاده شد. YAML برخلاف HTML یا XML برای نشانه‌گذاری محتوای سند طراحی نشده است؛ هدف اصلی آن نمایش داده است.

چرا YAML محبوب شد؟

محبوبیت YAML نتیجه ترکیب چند ویژگی است:

• خوانایی بالا برای فایل‌های پیکربندی.
• حذف بسیاری از براکت‌ها و ویرگول‌های JSON.
• پشتیبانی از comment.
• نمایش طبیعی objectها و arrayها.
• امکان نوشتن متن چندخطی.
• پشتیبانی از anchor و alias برای استفاده مجدد از ساختارها.
• سازگاری با طیف وسیعی از زبان‌ها و ابزارها.

بااین‌حال، YAML همیشه بهترین انتخاب نیست. برای APIهای عمومی، داده‌های ماشینی حساس به ابهام یا پردازش با کارایی بالا، JSON اغلب ساده‌تر و قابل‌پیش‌بینی‌تر است.

ساختار پایه YAML چگونه است؟

Mapping یا نگاشت کلید و مقدار

Mapping با علامت colon میان کلید و مقدار نوشته می‌شود:

name: xdflow
version: 1.0
published: false

در حالت block style، هر جفت کلید و مقدار معمولاً روی خط جدا قرار می‌گیرد. فاصله بعد از colon اهمیت دارد.

Sequence یا فهرست

هر عضو sequence در block style با dash آغاز می‌شود:

languages:
  - JavaScript
  - Python
  - Go

ساختار ترکیبی

Mapping و sequence می‌توانند داخل یکدیگر قرار بگیرند:

users:
  - id: 1
    name: Sara
    roles:
      - admin
      - editor
  - id: 2
    name: Amir
    roles:
      - viewer

هر عضو users یک mapping است و roles درون آن یک sequence.

تورفتگی در YAML

YAML برای تعیین سطح ساختار به indentation وابسته است. برخلاف بعضی زبان‌ها، تورفتگی فقط برای زیبایی نیست و معنای نحوی دارد.

نمونه صحیح:

database:
  host: localhost
  port: 5432
  credentials:
    username: app
    password: secret

نمونه غلط:

database:
  host: localhost
   port: 5432

تعداد فاصله‌ها باید در یک سطح ثابت باشد. معمولاً دو فاصله انتخاب رایجی است. استفاده از tab برای indentation توصیه نمی‌شود و بسیاری از Parserها آن را رد می‌کنند.

انواع داده در YAML

YAML می‌تواند scalarهای مختلف را نمایش دهد:

name: xdflow
port: 3000
ratio: 0.75
enabled: true
disabled: false
empty_value: null
another_null: ~

نوع‌دهی ضمنی یکی از منابع خطاست. بعضی Parserها و نسخه‌ها ممکن است رشته‌هایی مانند yes، no، on یا off را Boolean در نظر بگیرند، در حالی که Parser دیگری آن‌ها را String بخواند. برای داده حساس بهتر است مقدارهای مبهم را داخل کوتیشن قرار دهید.

String در YAML

متن بدون کوتیشن

title: YAML Guide

این حالت ساده است، اما اگر متن شامل colon، hash، bracket یا عبارت شبیه نوع داده باشد، ممکن است نیاز به کوتیشن داشته باشد.

Single Quote

message: 'value: still text'

در single-quoted string بیشتر کاراکترها به‌صورت literal باقی می‌مانند. برای قرار دادن single quote داخل آن، معمولاً باید آن را دو بار نوشت.

Double Quote

message: "line one\nline two"

Double quote از escape sequenceها پشتیبانی می‌کند. این حالت برای newline، tab، Unicode escape و کاراکترهای کنترل مناسب است.

Comment در YAML

Comment با hash آغاز می‌شود:

port: 3000 # application port
debug: false

اگر hash بخشی از مقدار باشد، بهتر است مقدار داخل کوتیشن قرار گیرد:

color: "#1a73e8"

Commentها معمولاً در مدل داده Parse‌شده نگهداری نمی‌شوند. اگر YAML خوانده و دوباره Serialize شود، ممکن است commentها یا قالب‌بندی اصلی از بین بروند.

Flow Style و Block Style

YAML علاوه بر سبک بلوکی، سبک فشرده شبیه JSON دارد.

Block Style

user:
  name: Sara
  roles:
    - admin
    - editor

Flow Style

user: {name: Sara, roles: [admin, editor]}

Block style برای فایل‌های پیکربندی بزرگ خواناتر است. Flow style برای ساختارهای کوچک یا مقدارهای کوتاه مناسب است. ترکیب بیش‌ازحد دو سبک می‌تواند خوانایی را کاهش دهد.

متن چندخطی در YAML

Literal Block با |

شکست خط‌ها حفظ می‌شوند:

description: |
  خط اول
  خط دوم
  خط سوم

Folded Block با >

بیشتر شکست خط‌ها به فاصله تبدیل می‌شوند:

description: >
  این متن در چند خط
  نوشته شده است اما معمولاً
  به یک پاراگراف تبدیل می‌شود.

Chomping indicatorهایی مانند |-، |+، >- و >+ رفتار newline انتهایی را کنترل می‌کنند. این بخش در فایل‌های certificate، script و template اهمیت دارد.

Anchor و Alias در YAML

Anchor و alias امکان استفاده مجدد از یک node را فراهم می‌کنند:

defaults: &defaults
  timeout: 30
  retries: 3

development:
  <<: *defaults
  debug: true

production:
  <<: *defaults
  debug: false

&defaults anchor را تعریف می‌کند و *defaults به آن ارجاع می‌دهد. کلید merge با << در بسیاری از ابزارها استفاده می‌شود، اما رفتار دقیق آن می‌تواند به Parser وابسته باشد. برای فایل‌های بین‌سیستمی، پشتیبانی Parser مقصد را بررسی کنید.

Document Separator در YAML

یک فایل YAML می‌تواند چند سند داشته باشد. سه dash آغاز سند جدید را مشخص می‌کند:

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

سه نقطه می‌تواند پایان صریح سند را نشان دهد:

---
name: first
...

همه ابزارها multi-document YAML را نمی‌پذیرند. بسیاری از فایل‌های پیکربندی فقط یک document انتظار دارند.

YAML و JSON چه ارتباطی دارند؟

JSON و YAML هر دو برای نمایش داده ساخت‌یافته استفاده می‌شوند. JSON از brace، bracket، comma و quote استفاده می‌کند، در حالی که YAML بیشتر به indentation متکی است. YAML قابلیت‌هایی مانند comment، anchor و متن چندخطی خواناتر دارد، اما پیچیدگی Parser و احتمال ابهام در آن بیشتر است.

معیار	YAML	JSON
خوانایی تنظیمات	معمولاً بالاتر	خوب اما پرعلامت‌تر
Comment	دارد	ندارد
Parser	پیچیده‌تر	ساده‌تر
Type ambiguity	بیشتر	کمتر
API عمومی	کمتر رایج	بسیار رایج
فایل پیکربندی	بسیار رایج	رایج

کاربردهای اصلی YAML

فایل‌های پیکربندی

YAML برای تنظیمات برنامه، محیط، سرویس، logging، feature flag و dependencyها استفاده می‌شود.

CI/CD

Pipelineها، jobها، stepها و environment variableها در بسیاری از سامانه‌ها با YAML تعریف می‌شوند.

زیرساخت و Container

تعریف service، volume، network، deployment و resource در ابزارهای زیرساختی اغلب با YAML انجام می‌شود.

مستندسازی API

بعضی قراردادهای API و Schemaها با YAML نوشته می‌شوند، چون ساختار بزرگ آن‌ها نسبت به JSON خواناتر است.

Static Site و CMS

Front matter و metadata محتوا می‌تواند به شکل YAML در ابتدای فایل قرار گیرد.

YAML در Docker Compose

نمونه ساده:

services:
  web:
    image: example/web:latest
    ports:
      - "8080:80"
    environment:
      APP_ENV: production
      DEBUG: "false"

در این نمونه، quoting برای "8080:80" و "false" از تفسیر ناخواسته جلوگیری می‌کند. نوع دقیق مقدارهای environment معمولاً باید String باشد.

YAML در Kubernetes

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  APP_ENV: production
  LOG_LEVEL: info

در Kubernetes معتبر بودن YAML فقط اولین مرحله است. فیلدها باید با Schema منبع موردنظر هماهنگ باشند. یک فایل می‌تواند از نظر YAML صحیح باشد اما به‌دلیل نام فیلد یا نوع نامعتبر توسط API رد شود.

YAML در CI/CD

jobs:
  test:
    steps:
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test

هر پلتفرم Schema و keywordهای مخصوص خود را دارد. Validator عمومی YAML فقط Syntax را بررسی می‌کند و نمی‌تواند وجود step ناشناخته یا تنظیم اشتباه پلتفرم را تشخیص دهد.

Parsing YAML در JavaScript

JavaScript به‌صورت داخلی Parser YAML ندارد و باید از کتابخانه استفاده شود. الگوی عمومی:

import fs from "node:fs";
import YAML from "yaml";

const source = fs.readFileSync("config.yaml", "utf8");
const config = YAML.parse(source);

console.log(config.app?.name);

در ورودی غیرقابل‌اعتماد باید محدودیت اندازه، alias، depth و featureهای Parser بررسی شوند. API و رفتار کتابخانه به نسخه وابسته است.

Parsing YAML در Python

from pathlib import Path
import yaml

source = Path("config.yaml").read_text(encoding="utf-8")
config = yaml.safe_load(source)

print(config["app"]["name"])

استفاده از loader امن اهمیت زیادی دارد. Loaderهایی که اجازه ساخت objectهای دلخواه می‌دهند ممکن است برای ورودی غیرقابل‌اعتماد خطرناک باشند. نام و رفتار API به کتابخانه بستگی دارد.

تفاوت Syntax Validation و Schema Validation

این YAML از نظر Syntax ممکن است معتبر باشد:

server:
  port: "not-a-number"
  enabled: maybe

اما برنامه مقصد ممکن است انتظار Number و Boolean داشته باشد. بنابراین:

• Syntax Validation: آیا متن طبق قواعد YAML Parse می‌شود؟
• Schema Validation: آیا ساختار، فیلدها و نوع‌ها مطابق قرارداد هستند؟
• Semantic Validation: آیا مقدارها در منطق برنامه قابل‌قبول‌اند؟

Formatter نیز فقط ظاهر را مرتب می‌کند و جایگزین Validator یا Schema نیست.

خطاهای رایج YAML

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

app:
  name: xdflow
   port: 3000

یک فاصله اضافه می‌تواند ساختار را خراب کند.

استفاده از Tab

Tab در indentation می‌تواند باعث خطا یا رفتار غیرقابل‌پیش‌بینی شود. Editor را روی space تنظیم کنید.

فراموش‌کردن فاصله بعد از Colon

name:xdflow

این متن ممکن است آن چیزی که انتظار دارید Parse نشود. شکل روشن‌تر:

name: xdflow

مقدار دارای Colon بدون کوتیشن

url: host: 3000

مقدارهای پیچیده را quote کنید:

url: "host: 3000"

Hash در متن

color: #ffffff

در این حالت مقدار ممکن است comment تلقی شود. شکل صحیح:

color: "#ffffff"

کلید تکراری

port: 3000
port: 4000

بعضی Parserها آخرین مقدار را نگه می‌دارند و بعضی خطا می‌دهند. کلید تکراری باید در Validation رد شود.

مشکلات Type Coercion

مقدارهایی مثل تاریخ، عدد دارای صفر ابتدایی، Booleanهای قدیمی یا عبارت علمی می‌توانند به نوعی غیر از انتظار تبدیل شوند:

postal_code: "00123"
version: "1.0"
answer: "yes"
date_text: "2026-08-06"

کوتیشن‌گذاری برای فیلدهایی که باید String بمانند، بهترین روش ساده است. همچنین رفتار Parser مقصد را در نسخه مورد استفاده تست کنید.

امنیت YAML

YAML می‌تواند ویژگی‌های قدرتمندی داشته باشد و Parse کردن ورودی غیرقابل‌اعتماد بدون تنظیمات امن خطرناک است.

• از loader امن استفاده کنید.
• از ساخت خودکار object یا اجرای constructorهای سفارشی جلوگیری کنید.
• تعداد alias و عمق nesting را محدود کنید.
• اندازه فایل را محدود کنید.
• Schema و کلیدهای مجاز را بررسی کنید.
• مقدارهای حساس را در فایل عمومی یا repository ذخیره نکنید.
• YAML را به‌عنوان فرمان shell یا template خام اجرا نکنید.
• پس از Parse، داده را متناسب با مقصد validate کنید.

Alias Expansion

استفاده گسترده و بازگشتی از aliasها می‌تواند مصرف حافظه و CPU را افزایش دهد. Parser امن باید محدودیت expansion داشته باشد.

Deserialization ناامن

برخی کتابخانه‌ها قابلیت نگاشت tagهای خاص به objectهای زبان برنامه‌نویسی را دارند. برای داده خارجی، این قابلیت باید غیرفعال باشد و فقط نوع‌های ساده مجاز باشند.

کارایی YAML

YAML معمولاً از JSON پیچیده‌تر Parse می‌شود. برای فایل‌های پیکربندی کوچک این تفاوت اهمیت زیادی ندارد، اما در پردازش حجم بالا باید به هزینه Parser توجه کرد.

• YAML را برای تبادل پرتعداد API فقط با دلیل روشن انتخاب کنید.
• فایل‌های بسیار بزرگ را به چند فایل منطقی تقسیم کنید.
• Schema و caching را برای تنظیمات ثابت استفاده کنید.
• از anchorهای پیچیده و nesting بسیار عمیق پرهیز کنید.
• در Pipelineهای حساس به کارایی، JSON یا فرمت‌های باینری را بررسی کنید.

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

1. از دو فاصله برای indentation استفاده کنید.
2. Tab را ممنوع کنید.
3. Stringهای مبهم را quote کنید.
4. کلیدهای تکراری را در lint و validation رد کنید.
5. ساختار را کم‌عمق و واضح نگه دارید.
6. برای فایل مقصد، Schema Validation داشته باشید.
7. Commentها را برای دلیل تصمیم‌ها بنویسید، نه توضیح بدیهیات.
8. Anchor را فقط وقتی خوانایی را بهتر می‌کند استفاده کنید.
9. نسخه Parser و رفتار type resolution را ثابت کنید.
10. Secretها را در فایل YAML عمومی ذخیره نکنید.

چک‌لیست بررسی فایل YAML

• آیا indentation در هر سطح ثابت است؟
• آیا هیچ tabی در فایل وجود ندارد؟
• آیا کلیدهای تکراری وجود ندارند؟
• آیا Stringهای مبهم quote شده‌اند؟
• آیا hash و colon داخل متن درست مدیریت شده‌اند؟
• آیا multiline string رفتار newline مورد انتظار را دارد؟
• آیا anchor و alias توسط Parser مقصد پشتیبانی می‌شوند؟
• آیا فایل یک سند است یا چند سند؟
• آیا Syntax YAML معتبر است؟
• آیا Schema ابزار مقصد نیز معتبر است؟
• آیا داده حساس در فایل وجود ندارد؟
• آیا Parse با loader امن انجام می‌شود؟

چه زمانی YAML انتخاب مناسبی نیست؟

YAML برای تنظیمات انسان‌محور عالی است، اما در این شرایط ممکن است انتخاب ضعیف‌تری باشد:

• API عمومی با پردازش پرتعداد.
• داده‌ای که باید بدون ابهام نوعی میان سیستم‌ها منتقل شود.
• محیطی که Parserهای مختلف و ناسازگار دارد.
• ورودی غیرقابل‌اعتماد بدون امکان sandbox و loader امن.
• داده بسیار بزرگ یا حساس به سرعت Parse.
• نیاز به round-trip دقیق comment و formatting.

YAML، Parser، Formatter و Validator

این ابزارها نقش‌های متفاوت دارند:

ابزار	وظیفه	چه چیزی را تضمین نمی‌کند؟
Parser	تبدیل متن YAML به ساختار داده	درستی منطق و Schema
Formatter	مرتب‌سازی ظاهر و indentation	سازگاری با نرم‌افزار مقصد
Syntax Validator	بررسی قابل Parse بودن	نوع و معنای فیلدها
Schema Validator	بررسی ساختار و نوع موردانتظار	صحت کامل منطق کسب‌وکار

قواعد نام‌گذاری کلیدها در YAML

کلیدهای YAML می‌توانند ساده یا پیچیده باشند، اما در فایل‌های پیکربندی بهتر است از نام‌های کوتاه، پایدار و قابل‌پیش‌بینی استفاده شود. استفاده از فاصله، علامت سؤال، colon یا ساختارهای پیچیده در کلیدها ممکن است از نظر Syntax مجاز باشد، اما سازگاری ابزارها و خوانایی را کاهش می‌دهد.

server_name: api
server-port: 8080
log_level: info

برای پروژه‌های تیمی، یک convention ثابت مانند snake_case یا kebab-case انتخاب کنید. تغییر نام کلید در فایل پیکربندی می‌تواند یک breaking change باشد، زیرا برنامه مقصد معمولاً دقیقاً همان نام را جست‌وجو می‌کند.

کلیدهای پیچیده در YAML

YAML از complex key پشتیبانی می‌کند، اما این قابلیت در پیکربندی‌های معمول کمتر استفاده می‌شود. نمونه زیر از sequence به‌عنوان کلید استفاده می‌کند:

? - north
  - east
: direction-a

هرچند این Syntax بخشی از قابلیت‌های YAML است، بسیاری از زبان‌ها و ساختارهای object معمولی نمی‌توانند چنین کلیدی را بدون تبدیل اضافی نمایش دهند. برای تبادل میان سیستم‌ها، کلیدهای scalar ساده انتخاب امن‌تری هستند.

Tag در YAML چیست؟

Tag نوع یا معنای یک node را مشخص می‌کند. بیشتر فایل‌ها به tag صریح نیاز ندارند، زیرا Parser نوع scalar را تشخیص می‌دهد. بااین‌حال می‌توان نوع را صریح کرد:

port: !!int "3000"
enabled: !!bool "true"
version: !!str 1.0

Tagهای سفارشی ممکن است توسط بعضی کتابخانه‌ها به object یا constructor زبان برنامه‌نویسی نگاشت شوند. این قابلیت برای ورودی غیرقابل‌اعتماد باید غیرفعال باشد. استفاده از tagهای استاندارد و loader امن خطر deserialization ناامن را کاهش می‌دهد.

Null، مقدار خالی و کلید بدون مقدار

حالت‌های زیر ممکن است شبیه به هم دیده شوند، اما باید رفتار Parser مقصد بررسی شود:

first: null
second: ~
third:
fourth: ""
fifth: ''

first، second و در بسیاری از Parserها third null هستند، در حالی که fourth و fifth String خالی‌اند. اگر تفاوت null و رشته خالی برای برنامه مهم است، آن را در Schema تست و مستند کنید.

عددها در YAML

YAML از integer و floating-point پشتیبانی می‌کند، اما نمایش‌های مختلف و تفاوت نسخه‌ها می‌توانند ابهام ایجاد کنند:

decimal: 42
negative: -15
float_value: 3.14
scientific: 1.5e3
hex_value: 0x2A
binary_value: 0b101010
string_id: "00123"

برای identifier، شماره تلفن، کد پستی، version و هر مقداری که محاسبه عددی روی آن انجام نمی‌شود، String مناسب‌تر است. صفر ابتدایی یکی از نشانه‌های مهم نیاز به quoting است.

Boolean در نسخه‌های مختلف YAML

در بعضی پیاده‌سازی‌های قدیمی‌تر، مقدارهایی مانند yes، no، on و off ممکن است Boolean تفسیر شوند. در رفتارهای جدیدتر معمولاً true و false شکل‌های واضح‌ترند. چون پروژه‌ها ممکن است از Parserهای متفاوت استفاده کنند، برای متن‌هایی مانند نام کشور، وضعیت یا پاسخ انسانی quoting را فراموش نکنید.

answer: "yes"
switch_label: "off"
enabled: true

تاریخ و Timestamp در YAML

بعضی Parserها مقدارهایی شبیه تاریخ را به object تاریخ زبان میزبان تبدیل می‌کنند و برخی آن‌ها را String نگه می‌دارند:

release_date: "2026-08-06"
created_at: "2026-08-06T09:30:00Z"

برای جلوگیری از اختلاف timezone، serialization و نوع خروجی، تاریخ‌ها را quote کنید و قالب مورد انتظار را در Schema مشخص کنید. YAML به‌تنهایی تضمین نمی‌کند تمام مصرف‌کننده‌ها یک timestamp را یکسان تفسیر کنند.

Merge Key و اولویت مقدارها

هنگام استفاده از merge key، باید مشخص باشد مقدار محلی نسبت به مقدار merge‌شده چه اولویتی دارد:

defaults: &base
  timeout: 30
  retries: 2
  debug: false

development:
  <<: *base
  debug: true

در این مثال مقدار محلی debug: true باید مقدار پیش‌فرض را override کند. اگر چند mapping merge شوند، ترتیب و رفتار کتابخانه را آزمایش کنید. برای تنظیمات امنیتی، overrideهای پنهان می‌توانند باعث خطای بررسی شوند.

Round-trip و حفظ Commentها

Parserهای معمولی YAML متن را به object تبدیل می‌کنند. هنگام Serialize دوباره، ممکن است commentها، سبک quote، ترتیب بعضی کلیدها، anchorها و قالب‌بندی اولیه تغییر کند. اگر ابزار شما ویرایشگر YAML است، به کتابخانه‌ای نیاز دارید که Concrete Syntax Tree یا metadata قالب‌بندی را حفظ کند.

تفاوت مهمی میان این دو سناریو وجود دارد:

• Data parsing: فقط مقدار نهایی اهمیت دارد.
• Document editing: comment، ترتیب، quote و style نیز باید حفظ شوند.

Environment Variable و YAML

خود YAML به‌صورت استاندارد متغیر محیطی را جایگزین نمی‌کند. Syntaxهایی مانند ${PORT} معمولاً قابلیت ابزار میزبان هستند، نه YAML عمومی:

server:
  port: "${PORT}"
  host: "${HOST}"

بنابراین معتبر بودن این فایل به معنی انجام substitution نیست. باید مستندات و رفتار نرم‌افزار مقصد بررسی شود. همچنین مقدارهای جایگزین‌شده باید از نظر نوع و امنیت validate شوند.

Secret Management در فایل YAML

قرار دادن رمز عبور، token، private key یا credential در YAML ساده است، اما فایل‌های YAML اغلب وارد repository، backup و log می‌شوند. بهترین روش‌ها:

• Secret را در repository commit نکنید.
• از secret manager یا variable امن محیط استفاده کنید.
• فایل‌های محلی حساس را در ignore قرار دهید.
• در نمونه فایل از مقدار نمونه غیرواقعی استفاده کنید.
• دسترسی فایل و retention backup را محدود کنید.
• Secretهای افشاشده را فقط حذف نکنید؛ آن‌ها را rotate کنید.

Lint کردن YAML چه کمکی می‌کند؟

Linter می‌تواند علاوه بر Syntax، قواعد سبک و مشکلات رایج را بررسی کند:

• فاصله‌گذاری و indentation ناسازگار.
• خط طولانی.
• کلید تکراری.
• trailing space.
• نبودن newline انتهایی.
• truthy value مبهم.
• استفاده ناسازگار از quote.

Lint جای Schema Validation را نمی‌گیرد، اما خطاهای انسانی را پیش از اجرا کاهش می‌دهد.

طراحی Schema برای YAML

Schema باید فیلدهای الزامی، نوع‌ها، مقدارهای مجاز، حداقل و حداکثر، الگوی String و امکان وجود کلیدهای اضافی را مشخص کند. نمونه مفهومی:

server:
  host: localhost
  port: 3000
  mode: production

قواعد مقصد می‌تواند بگوید server اجباری است، port باید integer میان 1 و 65535 باشد و mode فقط یکی از development یا production باشد. این بررسی‌ها از Syntax YAML فراتر می‌روند.

YAML در Git و Code Review

YAML برای review انسانی مناسب است، اما تغییر indentation ممکن است ساختار بزرگی را جابه‌جا کند. برای review بهتر:

• تغییر formatting و تغییر منطقی را در commit جدا نگه دارید.
• Formatter واحد در پروژه تعریف کنید.
• Validation را در CI اجرا کنید.
• فایل‌های تولیدشده را از فایل‌های دست‌نویس جدا کنید.
• تغییر anchor و merge را با خروجی نهایی مقایسه کنید.

تبدیل YAML به JSON چه محدودیت‌هایی دارد؟

ساختارهای ساده mapping و sequence معمولاً به JSON تبدیل می‌شوند، اما commentها، anchorها، aliasها، tagها و بعضی نوع‌های ویژه ممکن است در خروجی JSON از بین بروند یا resolve شوند. همچنین کلیدهای غیررشته‌ای YAML با object JSON سازگار نیستند و باید به String تبدیل یا ساختار دیگری برای آن‌ها انتخاب شود.

تبدیل JSON به YAML چه نکاتی دارد؟

JSON فاقد comment، anchor و tag است؛ بنابراین تبدیل JSON به YAML معمولاً داده را حفظ می‌کند، اما قابلیت‌های اضافی YAML را ایجاد نمی‌کند. Serializer ممکن است درباره quoting، flow style، ترتیب کلید و line width تصمیم بگیرد. خروجی تولیدشده باید با Formatter پروژه هماهنگ شود.

راهنمای Troubleshooting خطاهای YAML

1. شماره خط و ستون گزارش‌شده را پیدا کنید.
2. چند خط قبل از محل خطا را نیز بررسی کنید؛ مشکل ممکن است بالاتر باشد.
3. tab را به space تبدیل کنید.
4. سطح indentation والد و فرزند را مقایسه کنید.
5. colon، dash و quote بازمانده را بررسی کنید.
6. مقدارهای دارای hash یا colon را quote کنید.
7. کلیدهای تکراری را جست‌وجو کنید.
8. فایل را با Parser واقعی مقصد تست کنید.
9. پس از رفع Syntax، Schema Validation را اجرا کنید.

نمونه یک فایل YAML ساخت‌یافته و خوانا

app:
  name: xdflow
  environment: production
  server:
    host: 0.0.0.0
    port: 3000
  logging:
    level: info
    format: json
  features:
    - name: yaml-tools
      enabled: true
    - name: xml-tools
      enabled: true
  limits:
    max_file_size_mb: 10
    request_timeout_seconds: 30

این فایل از naming ثابت، دو فاصله indentation، نوع‌های روشن و ساختار کم‌عمق استفاده می‌کند. هیچ مقدار مبهمی بدون quote وجود ندارد و گروه‌بندی تنظیمات قابل‌فهم است.

جمع‌بندی YAML چیست

YAML یک فرمت سریال‌سازی داده انسان‌خوان است که mapping، sequence و scalar را با Syntax کم‌علامت و مبتنی بر indentation نمایش می‌دهد. نقطه قوت آن خوانایی، comment، multiline string و قابلیت استفاده در فایل‌های پیکربندی است. در مقابل، حساسیت به تورفتگی، type coercion، کلید تکراری، تفاوت Parserها و خطر loader ناامن نیازمند توجه جدی است.

برای استفاده درست، Syntax را ساده نگه دارید، Stringهای مبهم را quote کنید، از loader امن استفاده کنید و Validation را در دو سطح Syntax و Schema انجام دهید. برای مشاهده و مرتب‌سازی داده می‌توانید از ابزار داخلی فرمت‌کننده YAML استفاده کنید و برای بررسی خطاهای ساختاری، اعتبارسنج YAML مناسب است.