لا تحب الإعلانات؟ يذهب خالية من الإعلانات اليوم 

التحقق من صحة مخطط JSON الاستجابة للانتهاكات في عقد API قبل الإطلاق

نُشرت في 11 مايو 2026

تحقق من معايير JSON عند انتهاك عقد API في المصدر. اكتشف الكلمات الأساسية، ووسائط AJV للـ Express، وتكامل FastAPI، ورصد تغييرات المعايير، وعلاقة OpenAPI.

التحقق من مخطط JSON: اكتشاف انتهايات عقد API قبل التسليم 1

إعلان · حذف؟

إذا أعادت واجهة برمجة تطبيقات (API) حقلًا لم يُعرف في مخططك، أو تقبل جسم طلب يفتقر إلى خاصية مطلوبة، فهذا يُعد انتهاكًا للعقد. هذه الأخطاء دقيقة، غالبًا صامتة، وعُرفت بأنها مكلفة جدًا للإيجاد في بيئة الإنتاج. يُعد التحقق من صحة مخطط JSON الطبقة التي تُكتشف هذه الأخطاء مبكرًا — أقرب إلى مكان تدخلها.

يغطي هذا الدليل كيفية عمل مخطط JSON، وما هي المُحققين المناسبين لاستخدامهم في Node.js، Python، وAWS، وكيفية الحفاظ على توازي مخططك مع الواقع.

ما هو مخطط JSON

مخطط JSON هو مصطلح يُستخدم لوصف بنية مستند JSON. ليس برمجياً — بل هو بيانات معلومات. تكتب مخططًا يُعلن ما يشبه مستند JSON الصالح، ثم تمر بجهاز مُحقق لفحصه.

المخطط نفسه مستند JSON. مثال بسيط:

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0 }
  },
  "required": ["email"]
}

هذا كل ما تحتاجه. اعرضه على مُحقق JSON مع أي محتوى JSON، وستحصل على نتيجة "مرر" أو قائمة مبنية على الأخطاء.

الكلمات الأساسية

تغطي عدد قليل من الكلمات معظم احتياجات التحقق من الواقع في الحياة اليومية:

الكلمة	ما يتحقق منه	مثال
`type`	نوع القيمة	`"type": "string"`
`properties`	شكل حقول كائن	`"properties": { "name": { "type": "string" } }`
`required`	أي الخصائص يجب أن تكون موجودة	`"required": ["email", "password"]`
`additionalProperties`	إذا كانت الخصائص غير المعروفة مسموحة	`"additionalProperties": false`
`enum`	يجب أن تكون القيمة من مجموعة محددة	`"enum": ["admin", "editor", "viewer"]`
`format`	فحص صيغة منطقي	`"format": "email"` أو `"format": "date-time"`
`pattern`	يجب أن تكون السلسلة تطابق نمط منطقي	`"pattern": "^[a-z0-9-]+$"`
`$ref`	الإشارة إلى مخطط آخر	`"$ref": "#/$defs/Address"`

additionalProperties: false تستحق الانتباه. هي الكلمة التي تجعل مخططك صارمًا — أي خاصية غير معلنة في properties تُثير خطأ تحقق. تُستخدم بشكل افتراضي، مما يعني أن معظم المخططات تقبل حقولاً غير صحيحة ما لم تُفعَّل.

مخطط كامل: طلب تسجيل المستخدم

إليك مخطط JSON كامل لطلب طلب تسجيل. هذا النوع من المخططات هو الذي تكتبُه مرة واحدة، ثم تتحقق منه في كل طبقة تتفاعل مع النقطة.

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "title": "UserRegistration",
  "type": "object",
  "required": ["email", "password", "username"],
  "additionalProperties": false,
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string",
      "minLength": 8
    },
    "username": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_]{3,32}$"
    },
    "role": {
      "type": "string",
      "enum": ["user", "admin"],
      "default": "user"
    },
    "birthDate": {
      "type": "string",
      "format": "date"
    }
  }
}

يمكنك اختباره بشكل تفاعلي ضد أي محتوى باستخدام مُحقق JSON Schema IO Tools قبل توصيله إلى بيئة الكود.

التحقق من جسم طلب API

Express + AJV

AJV أسرع مُحقق لصيغة JSON Schema لـ Node.js. إليك متوسط Express يتحقق من جسم الطلب قبل وصوله إلى مُعالجك:

import Ajv from "ajv";
import addFormats from "ajv-formats";

const ajv = new Ajv({ allErrors: true });
addFormats(ajv);

function validateBody(schema) {
  const validate = ajv.compile(schema);
  return (req, res, next) => {
    if (validate(req.body)) {
      return next();
    }
    res.status(400).json({
      error: "Validation failed",
      details: validate.errors,
    });
  };
}

// Usage
app.post("/register", validateBody(registrationSchema), registerHandler);

allErrors: true يُخبر AJV بجمع كل الأخطاء في المستند بدل التوقف عند أول خطأ — مفيد عندما ترغب في عرض جميع أخطاء التحقق للعميل في نفس الوقت.

لاحظ نمط Nginx: تحتاج إلى

في Python، يستخدم FastAPI مكتبة Pydantic من الداخل ويُولد مخطط JSON Schema تلقائيًا من تسمياتك. إذا كنت تعمل مع مخططات JSON Schema من مصدر خارجي بدل استخدام نماذج Pydantic، jsonschema هو المكتبة القياسية:

from jsonschema import validate, ValidationError

schema = { ... }  # your schema dict

try:
    validate(instance=request_body, schema=schema)
except ValidationError as e:
    return {"error": e.message}, 400

AWS API Gateway

يدعم التحقق من جسم طلب بدرجة أولية. تُعرّف نموذج (أي مستند JSON Schema) وتحدد له كمُتحقق على طريقة معينة. يتم رفض الطلبات التي تفشل في التحقق عند مستوى البوابة — قبل أن تبدأ عملية تنفيذ الدالة Lambda. هذا يزيل فئة كاملة من أخطاء المعالجات ويقلل من عدد الزيارات التي تحدث عند تحميل البيانات غير الصالحة. REQUEST_BODY مخططات قابلة للإعادة باستخدام

عندما تشارك عدة مخططات بنية مشتركة — مثل عنوان، مبلغ مالي، أو كائن تصفية — اجعلها مُعرّفة مرة واحدة في `$ref` و `$defs`

وأعد استخدامها باستخدام $defs لأعمال أكبر، تُخزن المخططات في ملفات منفصلة و $ref:

{
  "$defs": {
    "Address": {
      "type": "object",
      "required": ["street", "city", "country"],
      "properties": {
        "street": { "type": "string" },
        "city":   { "type": "string" },
        "country": { "type": "string", "pattern": "^[A-Z]{2}$" }
      }
    }
  },
  "type": "object",
  "properties": {
    "billingAddress":  { "$ref": "#/$defs/Address" },
    "shippingAddress": { "$ref": "#/$defs/Address" }
  }
}

تُشير إلى عنوان URL. يمكن لمُحققين يدعمون الكلمة $ref وإعادة التحميل من مخزن — يمكن لـ AJV التعامل مع ذلك من خلال $id انحراف المخطط addSchema().

يحدث انحراف المخطط عندما يختلف المخطط عن الواقع. يُعتبر أكثر شيوعًا مما يعتقد: يُكتب المخطط مرة واحدة، تتطور واجهة برمجة التطبيقات، ولا يُحدث أي تغيير في المخطط.

العلامات ملحوظة. يُغير اسم حقل في الكود ولكن ليس في المخطط — يمر التحقق لأنه

مُعطى كخاطئ. يصبح حقل مطلوب غير مطلوب في الممارسة لأن الكود لم يعد يتحقق منه — يظل المخطط يطلب وجوده ولكن لا يلاحظ أحد حتى يرسل طلبًا بدونه. additionalProperties التعامل مع الانحراف يتطلب اعتبار التحقق من المخطط كاختبار، وليس تحقق في وقت التشغيل. بعض الفرق تستخدم اختبارات "س냅 شات" لاختبارات الواقع ضد نماذج استجابة حقيقية. آخرون ينفذون مُحقق المخطط في بيئة CI على مجموعة من طلبات API المُحفوظة. المقصود أن المخطط يجب أن يُختبر بانتظام، وليس فقط أن يُنشر مرة واحدة.

مخطط JSON و OpenAPI

يستخدم OpenAPI (الذي كان سابقًا Swagger) مخططات JSON لوصف جسم الطلب والرد، ولكن بتعديلات. في الإصدارات السابقة (OpenAPI 2.0، 3.0) استخدمت جزءًا من مخططات JSON Schema مع توسعة. OpenAPI 3.1 تتوافق أكثر مع مخططات JSON Schema (draft 2020-12)، لذا تُعتبر المخططات متوافقة بشكل كبير.

الفرق العملي: يُستخدم OpenAPI للفصل بين المخططات في مستند أكبر يحتوي على معلومات عن المسارات، العمليات، التحقق من الهوية، والخوادم. أما مخطط JSON بذاته فهو مجرد عقد تحقق. إذا كنت تبني واجهة برمجة تطبيقات من البداية، يمكنك كتابة مخطط JSON لكل نقطة، وتحقيق التحقق منه، ثم نقل هذه المخططات مباشرة إلى مستند OpenAPI.

إعادة إنشاء المخططات من البيانات الحالية

يُعتبر كتابة المخططات يدويًا مناسبًا للاستفادة من واجهات برمجة التطبيقات الجديدة. في حالات الواجهات القائمة التي لا تمتلك وصفًا دقيقًا، يكون من السهل جدًا إنشاء مخطط من محتوى واقعي، ثم تحسينه.

(Python) و

أداة مثل genson (Node.js) يأخذان أشكال JSON وينتجان مخططًا أوليًا. يكون المخطط المُنشأ عادةً مُعَدًا بشكل مفرط — كل شيء يصبح اختياريًا، لا يوجد generate-schema — لكنه يوفر نقطة بداية. ثم تضيف additionalProperties: false ، تحسين requiredالتعريفات، وتحدد type القيود عند وجود قيم محدودة. enum يُساعد هذا النهج أيضًا عند دخول واجهة برمجة تابعة من خارج، دون وثيقة مخطط. امرر عدة ردود إلى مُولد المخطط، ودمج النتائج، وستحصل على عقد عمل يمكن التحقق منه.

يجب أن يكون التحقق من صحة مخطط JSON موجودًا في كل طبقة تقبل بيانات مبنية — متوسطات HTTP، مستهلكي طوابع الرسائل، مسارات الكتابة في قاعدة البيانات. كلما ظهر انتهاك للعقد مبكرًا، كان تكلفته أقل. يمكن استخدام

مُحقق مخطط JSON على الإنترنت لإطلاق مخططات على أساس واقع محتوى قبل الاعتماد على تكامل مكتبة، مما يجعله الخطوة الأولى المناسبة لأي عمل تحقق. التحقق من صحة مخطط JSON: اكتشاف انتهاكات عقود الواجهة قبل إرسالها 2