ما هو التحقق من مخطط JSON Schema؟
التحقق من مخطط JSON Schema هو عملية فحص ما إذا كان مستند JSON يتوافق مع مجموعة من القيود الهيكلية وقيود القيم المحددة في مخطط JSON Schema. المخطط نفسه مستند JSON يصف الشكل المتوقع لبياناتك: أي الخصائص مطلوبة، وما الأنواع التي يجب أن تكون عليها، والنطاقات المسموح بها للأرقام، وأنماط النصوص، وأطوال المصفوفات، وغير ذلك. مواصفات JSON Schema تتولى صيانتها json-schema.org وتُنشر كسلسلة من مسودات IETF، والأكثر اعتمادًا هما Draft 7 وDraft 2020-12.
بينما يفحص التحقق من JSON العادي الصياغة فقط (هل الأقواس متطابقة؟ هل النصوص بين علامات اقتباس؟)، يذهب التحقق من المخطط أبعد من ذلك. فهو يجيب على أسئلة كـ: هل تحتوي استجابة API هذه على حقل "id" يكون دائمًا عددًا صحيحًا؟ هل حقل "status" واحد من ثلاث قيم مسموح بها؟ هل الكائنات المتداخلة ذات شكل صحيح؟ هذا النوع من التحقق الهيكلي يكتشف أخطاء تفوت فحوصات الصياغة تمامًا، لأن JSON الصحيح صياغيًا قد يكون خاطئًا دلاليًا في سياق تطبيقك.
يُستخدم JSON Schema في تعريفات OpenAPI/Swagger، والتحقق من ملفات الإعداد، والتحقق من النماذج، وقيود مستندات قاعدة البيانات، والاختبار الآلي. أدوات كـ Ajv (JavaScript) وjsonschema (Python) وcheck-jsonschema (CLI) تُنفذ المواصفة لتمكينك من التحقق من البيانات برمجيًا. يتيح لك هذا المدقق الإلكتروني لصق المخطط ومستند البيانات معًا للتحقق من التوافق فورًا، دون تثبيت أي مكتبة.
لماذا تستخدم مدققًا إلكترونيًا لمخطط JSON Schema؟
كتابة المخططات وتصحيح أخطاء التحقق يدويًا أمر بطيء. يمنحك مدقق مخطط JSON Schema الإلكتروني ردود فعل فورية على مدى تطابق بياناتك مع مخططك، مع رسائل خطأ واضحة تشير إلى الخاصية التي فشلت بالضبط.
حالات استخدام التحقق من مخطط JSON Schema
مرجع كلمات مفتاح JSON Schema
يتكوّن مخطط JSON Schema من كلمات مفتاح تفرض كل منها قيدًا على البيانات المُتحقَّق منها. يسرد الجدول أدناه كلمات المفتاح الأكثر استخدامًا في Draft 7 وما بعده. يمكن دمج كل كلمة مفتاح مع غيرها في كائن المخطط نفسه.
| كلمة المفتاح | الغرض | مثال |
|---|---|---|
| type | Restricts the data type | "type": "string" |
| properties | Defines expected object keys and their schemas | "properties": { "name": { "type": "string" } } |
| required | Lists mandatory properties | "required": ["id", "name"] |
| items | Schema for array elements | "items": { "type": "number" } |
| enum | Restricts value to a fixed set | "enum": ["active", "inactive"] |
| pattern | Regex constraint on strings | "pattern": "^[A-Z]{2}\\d{4}$" |
| minimum / maximum | Numeric range bounds | "minimum": 0, "maximum": 100 |
| minLength / maxLength | String length bounds | "minLength": 1, "maxLength": 255 |
| $ref | Reuses another schema by URI | "$ref": "#/$defs/address" |
| additionalProperties | Controls extra keys in objects | "additionalProperties": false |
| anyOf / oneOf / allOf | Combines multiple schemas logically | "anyOf": [{ "type": "string" }, { "type": "null" }] |
| if / then / else | Conditional schema application | "if": { "properties": { "type": { "const": "email" } } } |
مقارنة إصدارات JSON Schema: Draft 7 مقابل 2019-09 مقابل 2020-12
مرّ JSON Schema بعدة إصدارات من المسودات. Draft 7 (المنشور عام 2018) هو الأوسع دعمًا في أدوات التطوير. أدخل Draft 2019-09 كلمة $defs (بديلًا عن definitions) وunevaluatedProperties و$recursiveRef. أما Draft 2020-12 (الإصدار المستقر الأحدث) فقد استبدل $recursiveRef بـ $dynamicRef وأضاف prefixItems للتحقق من الصفوف. عند اختيار مسودة، تحقق من أن مكتبة التحقق الخاصة بك تدعمها. Ajv يدعم المسودات الثلاث. مكتبة jsonschema في Python تدعم حتى 2020-12 منذ الإصدار 4.0.
| الميزة | Draft 7 | Draft 2019-09 | Draft 2020-12 |
|---|---|---|---|
| $schema URI | draft-07/schema# | 2019-09/schema | 2020-12/schema |
| if / then / else | Yes | Yes | Yes |
| $defs (definitions) | definitions | $defs | $defs |
| $ref alongside keys | No (sibling ignored) | Yes | Yes |
| $dynamicRef | No | No ($recursiveRef) | Yes |
| prefixItems | No (use items array) | No (use items array) | Yes |
| unevaluatedProperties | No | Yes | Yes |
| $vocabulary | No | Yes | Yes |
أمثلة على الكود
تُظهر هذه الأمثلة كيفية التحقق من JSON مقابل مخطط برمجيًا. كل مثال يستخدم مكتبة موثوقة ومُصانة في نظامها البيئي.
import Ajv from 'ajv';
const ajv = new Ajv();
const schema = {
type: 'object',
properties: {
name: { type: 'string', minLength: 1 },
age: { type: 'integer', minimum: 0 },
email: { type: 'string', format: 'email' }
},
required: ['name', 'email'],
additionalProperties: false
};
const data = { name: 'Alice', age: 30, email: 'alice@example.com' };
const validate = ajv.compile(schema);
const valid = validate(data);
console.log(valid); // → true
console.log(validate.errors); // → null
// Invalid data — missing required "email"
validate({ name: 'Bob', age: 25 });
console.log(validate.errors);
// → [{ instancePath: '', keyword: 'required', params: { missingProperty: 'email' } }]from jsonschema import validate, ValidationError
schema = {
"type": "object",
"properties": {
"name": {"type": "string", "minLength": 1},
"age": {"type": "integer", "minimum": 0},
"tags": {
"type": "array",
"items": {"type": "string"},
"uniqueItems": True
}
},
"required": ["name"]
}
# Valid data
validate(instance={"name": "Alice", "age": 30, "tags": ["admin"]}, schema=schema)
# → No exception raised
# Invalid data — wrong type for "age"
try:
validate(instance={"name": "Alice", "age": "thirty"}, schema=schema)
except ValidationError as e:
print(e.message)
# → 'thirty' is not of type 'integer'
print(e.json_path)
# → $.agepackage main
import (
"fmt"
"strings"
"github.com/santhosh-tekuri/jsonschema/v5"
)
func main() {
schemaJSON := `{
"type": "object",
"properties": {
"id": { "type": "integer" },
"status": { "enum": ["active", "inactive"] }
},
"required": ["id", "status"]
}`
compiler := jsonschema.NewCompiler()
compiler.AddResource("schema.json", strings.NewReader(schemaJSON))
schema, _ := compiler.Compile("schema.json")
// Valid data
data := map[string]interface{}{"id": 1, "status": "active"}
err := schema.Validate(data)
fmt.Println(err) // → <nil>
// Invalid — missing "status"
bad := map[string]interface{}{"id": 2}
err = schema.Validate(bad)
fmt.Println(err) // → validation failed: missing properties: 'status'
}# Install via pip pip install check-jsonschema # Validate a file against a schema check-jsonschema --schemafile schema.json data.json # → ok -- validation done # Validate against a remote schema (e.g., GitHub Actions workflow) check-jsonschema --builtin-schema vendor.github-workflows my-workflow.yml # Validate multiple files at once check-jsonschema --schemafile schema.json file1.json file2.json file3.json