دليل التحقق من JSON Schema: التحقق من هياكل البيانات

كل تطبيق يتلقى بيانات من مصادر خارجية يواجه نفس المشكلة الأساسية: هل يمكنني الوثوق بهذه البيانات؟ سواء كانت أجسام طلبات API أو ملفات التكوين أو رسائل الطوابير أو استيراد البيانات، يجب التحقق من البيانات غير الموثوقة قبل دخولها إلى نظامك. يوفر JSON Schema طريقة معيارية ومستقلة عن اللغة لتعريف شكل البيانات الصالحة والتحقق من تطابق البيانات الواردة مع هذا التعريف. يغطي هذا الدليل كل شيء من كتابة أول Schema إلى أنماط متقدمة للتحقق المعقد، مع أمثلة عملية يمكنك تطبيقها فورًا.

ما هو JSON Schema؟

JSON Schema هو مستند JSON يصف هيكل وقيود مستندات JSON الأخرى. إنه مفردات تتيح لك توثيق والتحقق من بيانات JSON، موحدة من قبل IETF. يعرف JSON Schema قواعد حول الحقول التي يجب أن تكون موجودة، وأنواعها، والقيم المقبولة، وكيفية هيكلة الكائنات والمصفوفات.

فكر في JSON Schema كعقد بياناتك. مثلما يعرف Schema قاعدة البيانات الأعمدة والأنواع والقيود، يعرف JSON Schema خصائص وأنواع وقيود مستندات JSON. أي بيانات JSON تستوفي جميع القيود في Schema تسمى مثيلاً صالحًا، بينما البيانات التي تنتهك أي قيد تكون غير صالحة.

ما ليس JSON Schema

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

إصدارات JSON Schema

تطور JSON Schema عبر عدة مسودات، كل منها أضافت ميزات وحسنت المفردات. معرفة هذه الإصدارات تساعدك في اختيار الإصدار المناسب لمشروعك وتجنب مشكلات التوافق.

كتابة أول Schema

لنبدأ بمثال بسيط: Schema لكائن مستخدم يحتوي على الاسم والبريد الإلكتروني والعمر.

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://example.com/schemas/user.json",
    "title": "User",
    "description": "A user account in the system",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "The user's full name"
        },
        "email": {
            "type": "string",
            "format": "email",
            "description": "The user's email address"
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 150,
            "description": "The user's age in years"
        }
    },
    "required": ["name", "email"],
    "additionalProperties": false
}

يعلن هذا الـ Schema أن المستخدم الصالح يجب أن يكون كائنًا، حيث name و email هما خاصيتان نصيتان مطلوبتان. خاصية age اختيارية، لكن إذا كانت موجودة يجب أن تكون عددًا صحيحًا بين 0 و 150. القيد additionalProperties: false يمنع أي خصائص غير معرفة في الـ Schema، مما يلتقط الأخطاء الإملائية والحقول غير المتوقعة.

مرجع الكلمات المفتاحية الأساسية

يوفر JSON Schema مفردات غنية من الكلمات المفتاحية لتعريف القيود. إليك أهم الكلمات المفتاحية منظمة حسب الفئة.

كلمات مفتاحية النوع

قيود الأرقام

قيود السلاسل

قيود الكائنات

قيود المصفوفات

أنماط Schema الشائعة

غالبًا ما تتطلب Schemas الواقعية أنماطًا تتجاوز التحقق البسيط من النوع. إليك أكثر الأنماط استخدامًا.

التحقق الشرطي باستخدام if/then/else

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

{
    "type": "object",
    "properties": {
        "method": { "enum": ["credit_card", "bank_transfer"] },
        "card_number": { "type": "string" },
        "routing_number": { "type": "string" }
    },
    "required": ["method"],
    "if": {
        "properties": { "method": { "const": "credit_card" } }
    },
    "then": {
        "required": ["card_number"]
    },
    "else": {
        "required": ["routing_number"]
    }
}

التركيب باستخدام allOf و anyOf و oneOf

تتيح لك كلمات التركيب دمج Schemas بطرق قوية:

• allOf: يجب أن تستوفي البيانات جميع الـ Schemas الفرعية. تستخدم لدمج قيود متعددة أو خلط أجزاء Schema قابلة لإعادة الاستخدام.
• anyOf: يجب أن تستوفي البيانات Schema فرعيًا واحدًا على الأقل. تستخدم لأنواع الاتحاد حيث تكون عدة أشكال مقبولة.
• oneOf: يجب أن تستوفي البيانات Schema فرعيًا واحدًا بالضبط. تستخدم للبدائل المتنافية.

{
    "oneOf": [
        {
            "type": "object",
            "properties": {
                "type": { "const": "email" },
                "address": { "type": "string", "format": "email" }
            },
            "required": ["type", "address"]
        },
        {
            "type": "object",
            "properties": {
                "type": { "const": "phone" },
                "number": { "type": "string", "pattern": "^\\+?[1-9]\\d{1,14}$" }
            },
            "required": ["type", "number"]
        }
    ]
}

إعادة استخدام Schema باستخدام $ref

تتيح لك كلمة $ref المرجعية استيراد وإعادة استخدام Schemas، مما يلغي التكرار ويحافظ على قابلية صيانة Schemas. يمكنك الإشارة إلى Schemas داخل نفس المستند أو في ملفات خارجية.

{
    "$id": "https://example.com/schemas/order.json",
    "type": "object",
    "properties": {
        "customer": { "$ref": "#/$defs/address" },
        "shipping": { "$ref": "#/$defs/address" },
        "billing": { "$ref": "#/$defs/address" },
        "items": {
            "type": "array",
            "items": { "$ref": "#/$defs/lineItem" },
            "minItems": 1
        }
    },
    "required": ["customer", "items"],
    "$defs": {
        "address": {
            "type": "object",
            "properties": {
                "street": { "type": "string" },
                "city": { "type": "string" },
                "zip": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" },
                "country": { "type": "string", "minLength": 2, "maxLength": 2 }
            },
            "required": ["street", "city", "zip", "country"]
        },
        "lineItem": {
            "type": "object",
            "properties": {
                "product": { "type": "string" },
                "quantity": { "type": "integer", "minimum": 1 },
                "price": { "type": "number", "exclusiveMinimum": 0 }
            },
            "required": ["product", "quantity", "price"]
        }
    }
}

الأنواع القابلة للـ null

في JSON Schema Draft 2020-12، يتم تمثيل الأنواع القابلة للـ null باستخدام مصفوفة نوع تحتوي على "null":

{
    "type": ["string", "null"],
    "description": "An optional display name, or null if not set"
}

في المسودات الأقدم، استخدمت مواصفات OpenAPI الكلمة المفتاحية nullable: true. بالنسبة لـ JSON Schema القياسي، استخدم دائمًا نهج مصفوفة النوع.

التحقق من التنسيق

توفر كلمة format المفتاحية تحققًا دلاليًا يتجاوز فحص الهيكل. تحدد أن السلسلة يجب أن تتوافق مع تنسيق معروف. تشمل التنسيقات المدعومة الشائعة:

التحقق البرمجي من بيانات JSON

يكون التحقق من Schema أكثر فائدة عند دمجه في كود التطبيق. إليك أمثلة باستخدام مكتبات شائعة في لغات مختلفة.

JavaScript باستخدام Ajv

Ajv هو أكثر مدقق JSON Schema استخدامًا في JavaScript. يدعم جميع إصدارات المسودات ويوفر أداءً ممتازًا من خلال ترجمة JIT للـ Schema.

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

const ajv = new Ajv();
addFormats(ajv);

const schema = {
    type: 'object',
    properties: {
        name: { type: 'string', minLength: 1 },
        email: { type: 'string', format: 'email' },
        age: { type: 'integer', minimum: 0 }
    },
    required: ['name', 'email'],
    additionalProperties: false
};

const validate = ajv.compile(schema);
const valid = validate({ name: 'Alice', email: 'alice@example.com', age: 30 });

if (!valid) {
    console.log(validate.errors);
    // [{ keyword: 'required', params: { missingProperty: 'email' }, ... }]
}

Python باستخدام jsonschema

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"},
        "age": {"type": "integer", "minimum": 0}
    },
    "required": ["name", "email"],
    "additionalProperties": False
}

try:
    validate(instance={"name": "Alice", "email": "alice@example.com"}, schema=schema)
except ValidationError as e:
    print(f"Validation failed: {e.message}")

التحقق من بيانات API باستخدام JSON Schema

أحد أكثر تطبيقات JSON Schema قيمة هو التحقق من بيانات طلبات واستجابات API. هذا يضمن أن API الخاص بك يتلقى مدخلات منسقة جيدًا ويعيد البيانات بالتنسيق المتوقع، مما يلتقط الأخطاء مبكرًا ويوفر رسائل خطأ واضحة للعملاء.

وسيط Express.js

import Ajv from 'ajv';

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

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

app.post('/api/users',
    validateBody({
        type: 'object',
        properties: {
            name: { type: 'string', minLength: 1, maxLength: 100 },
            email: { type: 'string', format: 'email' },
            role: { enum: ['admin', 'editor', 'viewer'] }
        },
        required: ['name', 'email'],
        additionalProperties: false
    }),
    (req, res) => {
        // req.body is guaranteed valid here
        createUser(req.body);
    }
);

OpenAPI و JSON Schema

يستخدم OpenAPI (المعروف سابقًا بـ Swagger) مجموعة فرعية من JSON Schema لتعريف Schemas طلبات واستجابات API. إذا كنت تستخدم OpenAPI بالفعل، يمكنك استخراج الـ Schemas من مواصفات API واستخدامها للتحقق في وقت التشغيل. أدوات مثل openapi-schema-validator و express-openapi-validator تؤتمت هذه العملية، مما يضمن بقاء توثيق API ومنطق التحقق متزامنين دائمًا.

أفضل الممارسات

• عيّن دائمًا $schema: ضمن كلمة $schema المفتاحية للإعلان عن إصدار المسودة الذي يستخدمه Schema الخاص بك. هذا يمنع الغموض ويضمن أن المدقق يفسر Schema بشكل صحيح.
• استخدم $id كمعرف Schema: توفر كلمة $id المفتاحية معرفًا فريدًا لـ Schema الخاص بك وتعمل كـ URI أساسي لحل مراجع $ref. عيّنها دائمًا حتى للـ Schemas المحلية.
• عيّن additionalProperties: false: افتراضيًا، يسمح JSON Schema بأي خصائص إضافية في الكائنات. تعيين additionalProperties: false يلتقط الأخطاء الإملائية والحقول غير المتوقعة، مما يجعل Schema أكثر صرامة و API أكثر قابلية للتنبؤ.
• استخدم $defs للمكونات القابلة لإعادة الاستخدام: عرّف Schemas الشائعة في $defs وارجع إليها باستخدام $ref. هذا يقلل التكرار ويجعل Schemas أسهل في الصيانة.
• أضف الوصف (description): يجب أن يكون لكل خاصية و Schema حقل description. هذا يعمل كتوثيق ويساعد المطورين الآخرين في فهم غرض وقيود كل حقل.
• تحقق عند حدود النظام: طبق التحقق من Schema عند حواف نظامك: نقاط نهاية API، مستهلكي الرسائل، أنابيب استيراد البيانات، ومحمّلات التكوين. لا تتحقق من البيانات التي أنتجها كودك الخاص وتثق بها بالفعل.
• مكّن الوضع الصارم في المدقق: كوّن المدقق لرفض الكلمات المفتاحية غير المعروفة، وفرض التحقق من التنسيق، والإبلاغ عن جميع الأخطاء بدلاً من التوقف عند أول خطأ. هذا يلتقط المزيد من المشكلات في تحقق واحد.
• تحكم في إصدارات Schemas: ضمن إصدار الـ Schema في URI الخاص بـ $id (مثل https://example.com/schemas/user/v2.json). هذا يسمح لك بتطوير Schemas دون كسر المستهلكين الحاليين.
• اختبر Schemas الخاصة بك: اكتب اختبارات وحدة لـ Schemas تتضمن أمثلة صالحة وغير صالحة. هذا يضمن أن Schema ينفذ القيود التي تقصدها ويلتقط التراجعات عند تعديل الـ Schema.
• استخدم format للتحقق الدلالي: فضل format: "email" على أنماط regex المعقدة. التنسيقات أكثر قابلية للقراءة والصيانة، وتستفيد من منطق التحقق المختبر جيدًا في مكتبات المدققين.