ForHosting KIT · البيانات والملفات: تحويل وتنظيف

التحقق من JSON وفق مخطط

اعرف إن كان السجل يلتزم بالقواعد التي يجب أن يتبعها: في المثال تستوفي Ada بعمر 37 والوسمين math وcode كل القواعد، فتعود قائمة المشكلات فارغة. وعند الإخفاق تحصل على كل المشكلات في مرة واحدة. مجاني في متصفحك.

مجاني
يعمل في متصفحك
دون تسجيل
بياناتك لا تغادر جهازك

شغّل الأداة مجانًا اطّلع على الـAPI

استخدمها من الويبAPIالبريدTelegramالتطبيق قريبًا

فقد يؤدي غياب معرّف، أو وجود خاصية غير متوقعة، أو قِصر سلسلة نصية، أو خروج رقم عن النطاق المسموح إلى تعطيل الاستيراد بعد التحليل بوقت طويل. وتتضمن كل مشكلة مسار المستند ومسار المخطط والكلمة المفتاحية وشرحًا واضحًا، كي تتمكنوا من الانتقال مباشرة إلى الحقل الذي يحتاج إلى تصحيح.

الكتابة السليمة لا تعني الصحة

قد تُقرأ البيانات تمامًا ومع ذلك تكون خاطئة بالنسبة للنظام الذي يستقبلها. فغياب معرّف، أو مدخل غير متوقع، أو نص قصير جدًا، أو رقم خارج نطاقه، كلها قد تعطل الاستيراد بعد قراءة البيانات بلا مشكلة بوقت طويل. القراءة تفحص علامات الترقيم فقط، أما المخطط فهو مكان التوقعات الحقيقية: المدخلات المطلوبة، ونوع قيمة كل منها، والحدود المطبقة. وتقارن هذه الأداة البيانات بالمخطط وتسرد كل المخالفات.

كيف تقرأ النتيجة وتستفيد منها

القائمة الفارغة تعني أن كل قاعدة تحققت، كما في المثال: Ada بعمر 37 والوسمين math وcode تستوفي مخططًا يطلب اسمًا من حرفين على الأقل، وعمرًا بعدد صحيح لا يقل عن الصفر، ووسومًا بلا تكرار، ولا مدخلات أخرى. وتذكر كل مشكلة موضعها والقاعدة المخالفة ورسالة مقروءة. استخدم الرسالة للناس، والموضع والقاعدة للأتمتة. فالنموذج يستطيع إبراز الخانة المقابلة، والاستيراد يستطيع تجميع الأخطاء المتكررة قبل وصول سجلات الشريك إلى قاعدة بياناتك.

تحقق من القواعد المتفق عليها لا من الصياغة وحدها

تحتوي النتيجة على الحكم المنطقي <code>valid</code> ومصفوفة <code>violations</code>. وتعني المصفوفة الفارغة أن المستند استوفى جميع القيود التي جرى تقييمها. وعند الإخفاق تُحفظ كل المشكلات بدل التوقف عند أول مشكلة.

يدعم المدقق الأنواع والخصائص المطلوبة والتابعة والخصائص الإضافية وعناصر المصفوفات وأطوال النصوص والأنماط والحدود العددية والثوابت والتعدادات والمراجع المحلية وتركيب المخططات.

اقرؤوا مسارات المخالفات من دون تخمين

تشير السلسلة الفارغة إلى جذر المستند، ويشير <code>/customer/email</code> إلى email داخل customer، بينما يشير <code>/lines/2/quantity</code> إلى quantity في العنصر الثالث. ويحافظ ترميز Pointer على وضوح أسماء الخصائص حتى عند احتوائها على شرطة مائلة أو علامة التلدة. استخدموا الرسالة في الواجهات والسجلات، واستخدموا المسار والكلمة المفتاحية في منطق البرامج.

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

حالات الاستخدام

حماية عمليات استيراد البيانات

تحققوا من سجلات الشركاء قبل التحميل لمنع الحقول المفقودة والبنى غير المتوقعة من الوصول إلى المعالجة اللاحقة.

الأسئلة الشائعة

هل يتوقف التحقق عند المشكلة الأولى؟

لا. فهو يبلغ عن كل مخالفة مع مسار المستند ومسار المخطط والكلمة المفتاحية والرسالة.

كيف أقرأ الموضع المذكور مع كل مشكلة؟

الموضع الفارغ يعني المستند كله. والموضع /customer/email يشير إلى البريد داخل customer، والموضع /lines/2/quantity يشير إلى الكمية في العنصر الثالث من lines، لأن المواضع تُعدّ بدءًا من الصفر.

ما أنواع القواعد التي يمكن للمخطط التعبير عنها؟

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

لماذا قد تفشل بيانات تُقرأ دون خطأ في هذا الفحص؟

لأن القراءة تؤكد فقط أن الأقواس وعلامات الاقتباس والفواصل في مكانها. ولا تعرف أن الطلب يحتاج إلى رقم، أو أن الكمية يجب أن تكون موجبة، أو أن المدخلات المجهولة يجب رفضها؛ هذه التوقعات مكانها المخطط.

كيف أرفض المدخلات التي لم أتوقعها؟

حدّد في المخطط أن المدخلات الإضافية غير مسموحة. في المثال لا يقبل المخطط إلا name وage وtags، فأي مدخل آخر بجانبها كان سيظهر مخالفة مستقلة بموضعها.

أدوات ذات صلة

للمطوّرين — الوصول عبر API

كل ما في هذه الصفحة متاح برمجيًا. هذا القسم موجّه للفرق التقنية التي تريد ربط الأداة بأنظمتها الخاصة؛ بقية المستخدمين يمكنهم استخدام الأداة أعلاه مباشرة دون الحاجة لقراءة ما يلي.

الـEndpoint

POSThttps://api.kit.forhosting.com/data/json-schema-validate

صادِق على طلبك بترويسة Bearer، وأرسل طلب POST واحدًا لتدخل مهمتك قائمة التنفيذ فورًا؛ ثم تستلم النتيجة عبر webhook أو رابط موقّع.

استدعِ الخدمة من بيئتك

curl -X POST https://api.kit.forhosting.com/data/json-schema-validate \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document":{"name":"Ada","age":37},"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}'

const res = await fetch("https://api.kit.forhosting.com/data/json-schema-validate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "document": {
      "name": "Ada",
      "age": 37
    },
    "schema": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/data/json-schema-validate",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "document": {
        "name": "Ada",
        "age": 37
    },
    "schema": {
        "type": "object",
        "required": [
            "name"
        ],
        "properties": {
            "name": {
                "type": "string"
            }
        }
    }
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/data/json-schema-validate", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"document":{"name":"Ada","age":37},"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"document":{"name":"Ada","age":37},"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/data/json-schema-validate", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

مثال على الطلب

{
  "document": {
    "name": "Ada",
    "age": 37
  },
  "schema": {
    "type": "object",
    "required": [
      "name"
    ],
    "properties": {
      "name": {
        "type": "string"
      }
    }
  }
}

مثال على الاستجابة

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "data.json_schema_validate",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

الواجهة غير متزامنة: تستلم task_id فور الإرسال، ويمكنك الاستعلام عن الحالة بمعدل طلب واحد في الثانية.

الأسعار

لكل طلب$0.002

السعر معلن كما تراه: لا tokens ولا نظام نقاط؛ وإن فشلت المهمة فلن تُحاسَب عليها.

الحدود

max_mb 25

الأخطاء

HTTP	الرمز	المعنى
`401`	`unauthorized`	مفتاح الوصول مفقود أو غير صالح؛ تحقق من ترويسة Bearer في طلبك.
`402`	`insufficient_balance`	رصيدك لا يكفي لتنفيذ هذه المهمة؛ أعد شحن الرصيد ثم أعد المحاولة.
`404`	`unknown_type`	نوع المهمة المطلوب غير موجود في الكتالوج — راجع الاسم المرسل في الطلب.
`429`	`rate_limited`	تجاوزت الحد المسموح من الطلبات؛ انتظر قليلًا ثم أعد المحاولة.

ملاحظات تقنية

قد يكون JSON سليم البنية تمامًا، ومع ذلك لا يطابق متطلبات النظام الذي يستقبله. يقارن هذا المدقق مستند JSON مع JSON Schema ويعيد جميع المخالفات المكتشفة في استجابة واحدة.

تحققوا من العقد، لا من صياغة JSON وحدها

لا يجيب محلل JSON إلا عما إذا كانت الأقواس وعلامات الاقتباس والفواصل والقيم تكوّن JSON سليمًا. فهو لا يعرف أن الطلب يجب أن يتضمن رقمًا، أو أن الكمية يجب أن تكون موجبة، أو أن الكائن ينبغي أن يرفض الحقول المجهولة. يعبّر JSON Schema عن هذه التوقعات في صورة عقد قابل للقراءة آليًا. ضعوا المستند المحلل في <code>document</code> والعقد في <code>schema</code>.

اقرؤوا مسارات المخالفات من دون تخمين

تتضمن كل مخالفة حقل <code>path</code> مكتوبًا بصيغة JSON Pointer. يشير <code>schema_path</code> إلى القاعدة التي سببت المشكلة، بينما يوفر <code>keyword</code> فئة ثابتة مثل <code>required</code> أو <code>type</code> أو <code>minimum</code>.

ميّزوا المخطط التالف من البيانات غير الصالحة

المستند غير الصالح نتيجة تحقق عادية: ينجح الطلب مع ضبط <code>valid</code> على false وشرح جميع المخالفات. أما المخطط المشوه فحالة مختلفة، إذ لا يمكن إجراء تحقق موثوق. يمنع ذلك الخلط بين عقد تالف وبيانات سيئة. إذا كانت صيغة كلمة مفتاحية خاطئة، أو كان النوع مجهولًا، أو تعذر تجميع تعبير نمطي، أو كان حد عددي غير منطقي، أو تعذر حل مرجع محلي، فتعيد القدرة خطأ <code>invalid_input</code>. لا يتصل التنفيذ الحتمي بالشبكة، ولذلك لا يجلب المراجع البعيدة؛ استخدموا مراجع JSON Pointer المحلية التي تبدأ بالرمز <code>#/</code>. يناسب التحقق حدود API، وما قبل استيراد البيانات، والمخرجات المنظمة، ومسارات البناء. تبدأ طلبات API من $0.002، ويمكن تشغيل المنطق نفسه في المتصفح.

حالات التكامل

رفض حمولات API المعيبة

افحصوا أجسام الطلبات وفق عقد مشترك وأعيدوا المسار الدقيق لكل حقل يحتاج العملاء إلى تصحيحه.

اختبار JSON المولّد

تحققوا من أنواع المخرجات المنظمة ونطاقاتها وخصائصها المطلوبة قبل أن يتصرف نظام آخر بناءً عليها.

أسئلة تقنية

ماذا يعيد التحقق الناجح؟

يعيد valid بالقيمة true ومصفوفة violations فارغة.

ماذا يحدث إذا كان المخطط نفسه مشوهًا؟

يفشل الطلب بخطأ invalid_input، لأن العقد غير الصالح لا يتيح نتيجة تحقق موثوقة.

هل مراجع المخططات البعيدة مدعومة؟

لا. لا يستخدم المدقق الشبكة، ويدعم مراجع JSON Pointer المحلية داخل المخطط المقدم.

ما تكلفة التحقق عبر API؟

يبدأ كل طلب من $0.002. ويستخدم مشغّل المتصفح المنطق الحتمي نفسه للفحوص التفاعلية.

اطّلع على توثيق KIT الكامل ←

شغّل الأداة مجانًا

الكتابة السليمة لا تعني الصحة

كيف تقرأ النتيجة وتستفيد منها

تحقق من القواعد المتفق عليها لا من الصياغة وحدها

اقرؤوا مسارات المخالفات من دون تخمين

حالات الاستخدام

حماية عمليات استيراد البيانات

الأسئلة الشائعة

أدوات ذات صلة

للمطوّرين — الوصول عبر API

الـEndpoint

استدعِ الخدمة من بيئتك

مثال على الطلب

مثال على الاستجابة

الأسعار

الحدود

الأخطاء

ملاحظات تقنية

تحققوا من العقد، لا من صياغة JSON وحدها

اقرؤوا مسارات المخالفات من دون تخمين

ميّزوا المخطط التالف من البيانات غير الصالحة

حالات التكامل

رفض حمولات API المعيبة

اختبار JSON المولّد

أسئلة تقنية

شكرًا