API-Data formats (JSON, XML, YAML)

مفاهیم

Data Format چیست؟

Data Format یعنی قالب یا ساختاری که داده در آن بین Client و Server ردوبدل می‌شود.
در تست API، دانستن فرمت داده مهم است چون روی Request Body، Response Body، Schema Validation، Serialization / Deserialization، Parsing و حتی Headerهایی مثل Content-Type اثر مستقیم دارد.

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

• JSON

• XML

• YAML

JSON چیست؟

JSON مخفف JavaScript Object Notation است و رایج‌ترین فرمت تبادل داده در REST APIهاست.
JSON سبک، خوانا و ساختاریافته است و داده را به شکل key-value نمایش می‌دهد.

مثال:

{
  "customerId": 123,
  "firstName": "Ali",
  "active": true
}

ویژگی‌های مهم JSON

• ساختار داده به‌صورت Object و Array است

• از key-value استفاده می‌کند

• برای APIهای REST بسیار رایج است

• معمولاً با Content-Type: application/json ارسال می‌شود

• خواندن و Parse کردن آن برای انسان و ابزارها راحت است

انواع داده در JSON

در JSON معمولاً این نوع داده‌ها را می‌بینیم:

• string

• number

• boolean

• null

• object

• array

مثال:

{
  "name": "Sara",
  "age": 30,
  "vip": true,
  "nationalCode": null,
  "accounts": ["111", "222"]
}

XML چیست؟

XML مخفف eXtensible Markup Language است و یک فرمت متنی ساختاریافته برای تبادل داده است.
در XML داده‌ها به‌صورت Tag-based نمایش داده می‌شوند.
در بعضی سیستم‌های قدیمی‌تر، سازمانی، بانکی یا SOAP-based هنوز XML رایج است.

مثال:

<customer>
  <customerId>123</customerId>
  <firstName>Ali</firstName>
  <active>true</active>
</customer>

ویژگی‌های مهم XML

• داده با Tagها نمایش داده می‌شود

• ساختار آن معمولاً از JSON سنگین‌تر و پرحجم‌تر است

• می‌تواند Attribute هم داشته باشد

• در سیستم‌های قدیمی، Enterprise و بعضی سرویس‌های بین‌سیستمی زیاد دیده می‌شود

• معمولاً با Content-Type: application/xml یا text/xml ارسال می‌شود

Attribute در XML

در XML علاوه بر Tag، می‌توان از Attribute هم استفاده کرد.

مثال:

<customer id="123" active="true">
  <firstName>Ali</firstName>
</customer>

اینجا:

• id و active → Attribute

• firstName → Element

YAML چیست؟

YAML مخفف YAML Ain’t Markup Language است و یک فرمت متنی خوانا برای انسان است که بیشتر برای Configuration، OpenAPI Specification، CI/CD، Docker و Kubernetes استفاده می‌شود.
در تست API، YAML را بیشتر در Swagger/OpenAPI، فایل‌های تنظیمات یا تست‌دیتا می‌بینی؛ نه لزوماً در بدنه‌ی APIهای بانکی روزمره.

مثال:

customerId: 123
firstName: Ali
active: true
accounts:
  - "111"
  - "222"

ویژگی‌های مهم YAML

• بسیار خوانا و مناسب برای انسان است

• به‌جای brace و tag بیشتر از indentation استفاده می‌کند

• در OpenAPI / Swagger، GitLab CI، GitHub Actions، Docker Compose و ابزارهای DevOps رایج است

• برای تنظیمات و تعریف ساختارها مناسب‌تر از تبادل روزمره API است

تفاوت کلی JSON، XML و YAML

JSON

• رایج‌ترین فرمت در REST API

• سبک‌تر و ساده‌تر

• مناسب برای Request/Response Body

• خواندن و Parse کردن راحت

XML

• ساختار Tag-based

• معمولاً حجیم‌تر از JSON

• در سیستم‌های قدیمی‌تر، SOAP و بعضی سرویس‌های سازمانی رایج

• می‌تواند Attribute و Namespace داشته باشد

YAML

• بیشتر برای Configuration و Specification

• خوانایی بالا برای انسان

• در OpenAPI و فایل‌های تنظیمات بسیار رایج

• کمتر از JSON به‌عنوان فرمت اصلی API payload روزمره استفاده می‌شود

نگاه تستری به JSON / XML / YAML

1) تستر باید فرمت داده را با Contract تطبیق دهد

اگر Swagger/OpenAPI گفته Request Body باید JSON باشد، ارسال XML یا فرمت اشتباه باید رفتار مشخصی داشته باشد.

2) فقط داده مهم نیست؛ ساختار هم مهم است

در تست API باید این موارد بررسی شود:

• فیلد اجباری وجود دارد یا نه

• نوع داده درست است یا نه

• ساختار Object / Array درست است یا نه

• نام فیلدها درست است یا نه

• مقدار null مجاز است یا نه

• Enumها و مقادیر مجاز درست‌اند یا نه

3) خطاهای رایج در فرمت JSON

نمونه‌های پرتکرار:

• بسته نشدن brace یا bracket

• گذاشتن comma اضافه

• ارسال string به‌جای number

• ارسال boolean به‌صورت string

• اشتباه بودن نام فیلد

• ارسال array به‌جای object یا برعکس

• فرستادن فیلدی که schema آن را قبول نمی‌کند

مثال غلط:

{
  "age": "30"
}

اگر طبق Contract، age باید number باشد، این می‌تواند Validation Error ایجاد کند.

4) خطاهای رایج در XML

• بسته نشدن Tag

• اشتباه در ساختار Tagها

• ارسال Element به‌جای Attribute یا برعکس

• ناسازگاری با XSD یا Schema

• مشکل در Namespace

5) خطاهای رایج در YAML

• Indentation اشتباه

• اشتباه در ساختار لیست‌ها

• ناسازگاری با OpenAPI/YAML schema

• استفاده نادرست از فاصله و تورفتگی

Serialization و Deserialization

این دو اصطلاح خیلی مهم‌اند:

Serialization

تبدیل Object یا داده‌ی داخلی برنامه به یک فرمت قابل ارسال مثل JSON یا XML.

مثال:
شیء Customer در برنامه تبدیل می‌شود به JSON و در Response برمی‌گردد.

Deserialization

تبدیل داده‌ی دریافتی مثل JSON یا XML به ساختار داخلی برنامه.

مثال:
Server یک JSON Request Body را می‌گیرد و آن را به مدل داخلی CustomerRequest تبدیل می‌کند.

نقش Content-Type در Data Format

فرمت داده باید با Content-Type هم‌راستا باشد.

مثال‌ها:

• application/json → برای JSON

• application/xml → برای XML

• application/x-yaml یا فرمت‌های مشابه → برای YAML در بعضی ابزارها

اگر Body، JSON باشد ولی Content-Type چیز دیگری باشد، ممکن است API خطا بدهد یا داده را اشتباه پردازش کند.

Schema Validation در Data Format

در تست API فقط کافی نیست که JSON یا XML «ظاهراً» درست باشد.
باید ببینی آیا با Schema یا Contract هم سازگار هست یا نه.

برای JSON:

• نوع فیلد درست است؟

• فیلد اجباری وجود دارد؟

• طول رشته یا الگو رعایت شده؟

• فیلد اضافی مجاز است یا نه؟

برای XML:

• ساختار با XSD سازگار است؟

• Tagها و ترتیب آن‌ها درست است؟

• مقادیر معتبر هستند؟

برای YAML:

• ساختار OpenAPI یا فایل تنظیمات درست است؟

• indentation و mappingها درست‌اند؟

مثال تستی برای JSON

فرض کن Contract گفته:

{
  "username": "string",
  "age": "number"
}

تست‌های مهم:

• username خالی

• age به‌صورت string

• نبودن username

• فرستادن فیلد اضافه

• فرستادن null برای فیلدی که nullable نیست

• فرستادن array به‌جای object

مثال تستی برای XML

اگر سرویس XML بگیرد:

• Tag اجباری را حذف کن

• ترتیب Tagها را اگر سیستم حساس است تغییر بده

• مقدار نامعتبر برای Tag بفرست

• XML خراب یا ناقص بفرست

• اگر XSD دارد، تست schema validation انجام بده

YAML از دید تستر بیشتر کجا مهم می‌شود؟

• وقتی Swagger/OpenAPI را در قالب YAML می‌خوانی

• وقتی فایل تنظیمات تست یا CI/CD را بررسی می‌کنی

• وقتی mock server یا تست‌دیتا با YAML تعریف شده

• وقتی می‌خواهی OpenAPI spec را تحلیل کنی

نکات امتحانی مهم Data Formats

• JSON رایج‌ترین فرمت در REST API است

• XML بیشتر در سیستم‌های قدیمی‌تر، SOAP و بعضی سرویس‌های سازمانی دیده می‌شود

• YAML بیشتر برای Configuration و OpenAPI Specification استفاده می‌شود

• تستر باید فرق syntax error و schema validation error را بفهمد

• Content-Type باید با فرمت واقعی داده هماهنگ باشد

• Serialization / Deserialization را بلد باش چون به فهم خطاهای API کمک می‌کند

• در تست API فقط «درست بودن ظاهری» کافی نیست؛ باید type، required field، array/object structure و contract compatibility را هم بررسی کنی

نمونه پاسخ کوتاه

Data Format قالبی است که داده در آن بین Client و Server تبادل می‌شود. سه فرمت مهم در این سرفصل JSON، XML و YAML هستند. JSON رایج‌ترین فرمت در REST APIهاست و ساختار key-value دارد. XML فرمت tag-based است و در بعضی سیستم‌های قدیمی‌تر یا سازمانی استفاده می‌شود. YAML بیشتر برای Configuration و OpenAPI Specification کاربرد دارد. در تست API، شناخت این فرمت‌ها برای تحلیل Request/Response Body، Content-Type، Schema Validation و شناسایی خطاهای ساختاری و معنایی ضروری است.

کلیدواژه‌ها

Data Format | JSON | XML | YAML | Request Body | Response Body | Content-Type | application/json | application/xml | key-value | Object | Array | Tag | Element | Attribute | Schema Validation | JSON Schema | XSD | Serialization | Deserialization | Parsing | Syntax Error | Validation Error | OpenAPI | Configuration

توضیح و کاربرد کلیدواژه‌ها

Data Format (قالب نمایش و تبادل داده بین Client و Server): برای تحلیل Request Body، Response Body و انتخاب روش درست تست API استفاده می‌شود.

JSON (فرمت متنی سبک مبتنی بر key-value): رایج‌ترین فرمت تبادل داده در REST APIها برای Request/Response است.

XML (فرمت متنی tag-based برای تبادل داده): در بعضی سرویس‌های قدیمی، SOAP و سیستم‌های سازمانی استفاده می‌شود.

YAML (فرمت متنی خوانا برای انسان، مناسب تنظیمات و Specification): در OpenAPI، CI/CD، Docker و فایل‌های تنظیمات کاربرد دارد.

Request Body (داده ارسالی در بدنه Request): برای ارسال JSON، XML یا سایر فرمت‌ها به Server استفاده می‌شود.

Response Body (داده برگشتی در بدنه Response): برای بررسی خروجی بیزینسی، ساختار داده و Schema Validation استفاده می‌شود.

Content-Type (نوع محتوای Body): برای مشخص کردن این‌که داده‌ی داخل Body با چه فرمتی ارسال یا دریافت می‌شود استفاده می‌شود.

application/json (نوع محتوای JSON): رایج‌ترین Content-Type در APIهای REST برای ارسال و دریافت داده ساختاریافته است.

application/xml (نوع محتوای XML): برای APIها یا سرویس‌هایی که XML تبادل می‌کنند استفاده می‌شود.

key-value (ساختار کلید-مقدار): مبنای اصلی نمایش داده در JSON است.

Object (ساختار داده شامل مجموعه‌ای از key-valueها): در JSON برای نمایش موجودیت‌هایی مثل Customer یا Account استفاده می‌شود.

Array (لیست مرتب از مقادیر یا Objectها): برای ارسال یا دریافت مجموعه‌ای از داده‌ها در JSON و YAML استفاده می‌شود.

Tag (برچسب ساختاری در XML): برای تعریف عناصر داده در XML استفاده می‌شود.

Element (گره یا بخش داده‌ای در XML): واحد اصلی نگه‌داری داده در XML است.

Attribute (ویژگی متصل به Tag در XML): برای نگه‌داری بعضی مقادیر یا متادیتا در ساختار XML استفاده می‌شود.

Schema Validation (اعتبارسنجی ساختار و نوع داده نسبت به قرارداد تعریف‌شده): برای بررسی درست بودن JSON/XML نسبت به Schema یا OpenAPI استفاده می‌شود.

JSON Schema (تعریف رسمی ساختار و قواعد JSON): برای بررسی نوع فیلد، فیلد اجباری، طول، الگو و ساختار JSON استفاده می‌شود.

XSD (XML Schema Definition): برای اعتبارسنجی ساختار و قواعد فایل یا پیام XML استفاده می‌شود.

Serialization (تبدیل Object داخلی برنامه به فرمت قابل ارسال مثل JSON/XML): برای تولید Request/Response Body و تحلیل رفتار Backend مهم است.

Deserialization (تبدیل JSON/XML دریافتی به مدل داخلی برنامه): برای فهم خطاهای Parsing، Mapping و Validation سمت Server مهم است.

Parsing (خواندن و تبدیل داده متنی به ساختار قابل فهم برای برنامه): در تحلیل خطاهای فرمت، JSON خراب یا XML خراب کاربرد دارد.

Syntax Error (خرابی در ساختار ظاهری فرمت داده): مثل JSON ناقص، XML خراب یا YAML با indentation اشتباه.

Validation Error (خطا در معتبر نبودن داده نسبت به Rule یا Schema): وقتی ساختار کلی درست است ولی نوع فیلد، مقدار یا قواعد قرارداد نقض شده‌اند استفاده می‌شود.

OpenAPI (استاندارد توصیف API و قرارداد Request/Response): برای مشخص کردن فرمت Body، نوع داده‌ها، فیلدهای اجباری و ساختار API استفاده می‌شود.

Configuration (تنظیمات سیستم یا ابزارها): YAML معمولاً در فایل‌های تنظیمات، CI/CD، Docker و تعریف Specها استفاده می‌شود.

#DataFormats
#JSON_XML_YAML
#APITesting
#SchemaValidation
#BackendTesting