API -Schema Validation of Request / Response Body (OpenAPI, JSON Schema)

Schema Validation چیست؟

Schema Validation یعنی بررسی اینکه Request Body یا Response Body دقیقاً مطابق ساختار (Schema) تعریف‌شده در Contract باشد.
Schema مشخص می‌کند چه فیلدهایی وجود دارند، نوع داده هر فیلد چیست، کدام فیلدها Required هستند، چه محدودیت‌هایی دارند و چه مقادیر مجازی قابل قبول است.

در تست API، فقط بررسی Status Code کافی نیست؛ بلکه باید اطمینان حاصل شود که Schema نیز کاملاً رعایت شده است.

Schema چیست؟

Schema یک قرارداد ساختاری (Structural Contract) بین Client و Server است که مشخص می‌کند:

• چه فیلدهایی باید وجود داشته باشند.

• نوع هر فیلد چیست.

• کدام فیلدها اجباری (Required) هستند.

• مقدار مجاز هر فیلد چیست.

• ساختار Objectها و Arrayها چگونه است.

مثال:

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

در Schema ممکن است تعریف شود:

• customerId → Integer

• firstName → String

• isActive → Boolean

اگر API مقدار زیر را برگرداند:

{
  "customerId": "123"
}

از نظر Schema Validation خطاست؛ چون Integer به String تبدیل شده است.

Request Schema Validation

در Request Validation بررسی می‌شود که داده ارسالی Client مطابق Schema باشد.

نمونه مواردی که باید بررسی شوند:

• وجود تمام Required Fields

• نوع صحیح داده (Type Validation)

• طول رشته (MinLength / MaxLength)

• بازه عدد (Minimum / Maximum)

• فرمت (Format) مانند email یا date

• مقدارهای مجاز (Enum)

• ساختار Object و Array

اگر Request با Schema مطابقت نداشته باشد، معمولاً API باید 400 Bad Request برگرداند.

Response Schema Validation

در Response Validation بررسی می‌شود که خروجی API دقیقاً مطابق Contract باشد.

نمونه موارد:

• همه فیلدهای مورد انتظار وجود داشته باشند.

• نوع داده‌ها صحیح باشد.

• فیلد اضافه یا حذف نشده باشد.

• ساختار Response تغییر نکرده باشد.

• Nested Objectها صحیح باشند.

OpenAPI Specification

OpenAPI Specification (OAS) استاندارد مستندسازی API است که Contract کامل API را تعریف می‌کند.

در OpenAPI مشخص می‌شود:

• Paths

• HTTP Methods

• Parameters

• Headers

• Request Body

• Response

• Schemas

• Status Codes

• Authentication

در تست API، OpenAPI یکی از مهم‌ترین Test Basisها محسوب می‌شود.

JSON Schema

JSON Schema استانداردی برای تعریف ساختار فایل‌های JSON است.

به کمک آن می‌توان مشخص کرد:

• نوع داده

• Required بودن

• حداقل و حداکثر

• Pattern

• Enum

• Object

• Array

نمونه:

{
  "type": "object",
  "required": ["customerId","firstName"],
  "properties": {
    "customerId": {
      "type": "integer"
    },
    "firstName": {
      "type": "string"
    }
  }
}

تفاوت Schema Validation و Business Validation

Schema Validation بررسی می‌کند داده از نظر ساختاری صحیح باشد.

مثلاً:

{
  "age": 25
}

از نظر Schema صحیح است چون Integer است.

اما اگر Business Rule بگوید:

سن مشتری باید حداقل 18 سال باشد.

آن‌وقت بررسی این شرط دیگر Business Validation است، نه Schema Validation.

چه چیزهایی در Schema Validation بررسی می‌شوند؟

Required Fields

مثلاً:

{
  "required": ["firstName","nationalCode"]
}

اگر nationalCode ارسال نشود:

400 Bad Request

Type Validation

درست:

{
  "amount": 500
}

اشتباه:

{
  "amount": "500"
}

Format Validation

مثلاً:

{
  "email":"[email protected]"
}

صحیح است.

ولی:

{
  "email":"alitest"
}

در صورت تعریف format=email نامعتبر است.

Enum Validation

مثلاً:

status:
ACTIVE
INACTIVE
BLOCKED

اگر ارسال شود:

{
  "status":"UNKNOWN"
}

باید خطا برگردد.

Array Validation

بررسی می‌شود:

• نوع اعضا

• تعداد اعضا

• Empty بودن

• Nested Objectها

Additional Properties

گاهی Schema مشخص می‌کند:

additionalProperties:false

در این صورت:

{
  "firstName":"Ali",
  "age":30
}

اگر age در Schema تعریف نشده باشد، Request باید رد شود.

Contract Validation

در تست حرفه‌ای فقط Body بررسی نمی‌شود؛ بلکه باید بررسی کنیم:

• Schema

• Headers

• Status Codes

• Content-Type

• Required Headers

• Authentication

• Response Structure

همگی مطابق Contract باشند.

Schema Evolution

در نسخه‌های جدید API ممکن است Schema تغییر کند.

مثلاً:

نسخه اول:

{
  "firstName":"Ali"
}

نسخه دوم:

{
  "firstName":"Ali",
  "mobile":"0912..."
}

اگر mobile اختیاری باشد، Breaking Change نیست.

اما اگر:

firstName

حذف شود، معمولاً Breaking Change است.

Failureهای رایج Schema

• Missing Required Field

• Wrong Data Type

• Invalid Enum

• Invalid Format

• Missing Property

• Unexpected Property

• Nested Schema Error

• Array Type Error

• Nullable Error

• Contract Mismatch

تست‌های مهم

Backend Tester باید بررسی کند:

• تمام Required Fieldها

• Type Validation

• Enum Validation

• Format Validation

• Additional Properties

• Nested Objects

• Arrays

• Nullable Fields

• Empty Object

• Empty Array

• Missing Response Field

• Unexpected Response Field

اهمیت این سرفصل برای Backend Tester

Backend Tester باید بتواند:

• OpenAPI / Swagger را به‌عنوان Test Basis تحلیل کند.

• Request Schema و Response Schema را اعتبارسنجی کند.

• تفاوت Schema Validation و Business Validation را بداند.

• تغییرات Schema را از نظر Backward Compatibility بررسی کند.

• Failureهای ناشی از Contract Mismatch را تشخیص دهد.

• مطمئن شود Response دقیقاً مطابق Contract تولید شده است.

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

در پاسخ امتحانی فقط نگویید:

Schema Validation یعنی بررسی ساختار JSON.

پاسخ کامل باید این کلیدواژه‌ها را داشته باشد:

Contract, OpenAPI Specification, JSON Schema, Request Validation, Response Validation, Required Fields, Type Validation, Format Validation, Enum, Additional Properties, Contract Mismatch, Schema Evolution, Backward Compatibility

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

Schema Validation فرآیند بررسی تطابق Request Body و Response Body با Contract تعریف‌شده در OpenAPI Specification یا JSON Schema است. در این فرآیند مواردی مانند Required Fields، Data Type، Format، Enum، Nested Object، Array Structure و Additional Properties بررسی می‌شوند. تفاوت مهم آن با Business Validation این است که Schema فقط ساختار و نوع داده را کنترل می‌کند، در حالی که Business Validation قوانین کسب‌وکار را بررسی می‌کند. Backend Tester باید علاوه بر Status Code، تطابق کامل Schema با Contract و عدم وجود Contract Mismatch را نیز اعتبارسنجی کند.

کلیدواژه‌ها

Schema Validation Request Schema Response Schema JSON Schema OpenAPI Specification Swagger Contract Contract Validation Required Fields Type Validation Format Validation Enum Validation Additional Properties Nested Object Array Validation Nullable Schema Evolution Contract Mismatch Business Validation Backward Compatibility

Schema Validation (اعتبارسنجی ساختار Request یا Response): برای بررسی تطابق داده با Contract و جلوگیری از ناسازگاری بین Client و Server استفاده می‌شود.

Request Schema (ساختار مورد انتظار Request Body): نوع داده، Required بودن، Format و سایر محدودیت‌های ورودی را مشخص می‌کند.

Response Schema (ساختار مورد انتظار Response Body): مشخص می‌کند Response باید چه فیلدها و چه نوع داده‌ای داشته باشد.

JSON Schema (استاندارد تعریف ساختار JSON): برای تعریف نوع داده، Required Fields، Enum، Pattern و سایر محدودیت‌های ساختاری استفاده می‌شود.

OpenAPI Specification (استاندارد مستندسازی API): شامل Contract کامل API شامل Paths، Methods، Schemas، Responses و Authentication است.

Swagger (ابزار نمایش و تست OpenAPI): برای مشاهده و اعتبارسنجی Contract و اجرای تست‌های API استفاده می‌شود.

Contract (توافق بین Client و Server): رفتار، ساختار و قوانین تبادل داده را مشخص می‌کند.

Contract Validation (بررسی تطابق API با Contract): برای اطمینان از رعایت Schema، Status Code، Headers و سایر اجزای API انجام می‌شود.

Required Fields (فیلدهای اجباری): فیلدهایی که نبودن آن‌ها باید باعث خطای اعتبارسنجی شود.

Type Validation (بررسی نوع داده): کنترل می‌کند مقدار ارسال‌شده از نوع صحیح مانند String، Integer یا Boolean باشد.

Format Validation (اعتبارسنجی قالب داده): برای بررسی قالب‌هایی مانند Email، Date، UUID و URI استفاده می‌شود.

Enum Validation (بررسی مقادیر مجاز): اطمینان می‌دهد مقدار فقط یکی از گزینه‌های تعریف‌شده باشد.

Additional Properties (فیلدهای اضافی خارج از Schema): در صورت ممنوع بودن، وجود آن‌ها باید باعث رد شدن Request شود.

Nested Object (شیء تو در تو): برای اعتبارسنجی ساختارهای چندسطحی در Request یا Response استفاده می‌شود.

Array Validation (اعتبارسنجی آرایه): نوع اعضا، تعداد و ساختار Array را بررسی می‌کند.

Nullable (قابل Null بودن فیلد): مشخص می‌کند یک فیلد مجاز است مقدار Null داشته باشد یا خیر.

Schema Evolution (تغییر تدریجی Schema بین نسخه‌های API): برای مدیریت تغییرات بدون ایجاد Breaking Change استفاده می‌شود.

Contract Mismatch (عدم تطابق رفتار واقعی API با Contract): یکی از رایج‌ترین علت‌های Failure در تست API است.

Business Validation (اعتبارسنجی قوانین کسب‌وکار): قوانین منطقی سیستم را بررسی می‌کند و با Schema Validation متفاوت است.

Backward Compatibility (سازگاری نسخه‌های جدید با Clientهای قدیمی): بررسی می‌کند تغییرات Schema باعث خرابی نسخه‌های قبلی API نشده باشد.

تگ‌ها

#APITesting
#SchemaValidation
#OpenAPI
#BackendTesting
#JSONSchema