الأساسيات — الـ type والـ properties والـ required

الـ type: سبع أنواع بس

الـ JSON فيه ٦ أنواع، والـ JSON Schema زوّدت integer:

• الـ integer بالقيمة مش بالشكل: 5.0 بيعدّي كـ integer لأنه رياضيًا رقم صحيح. اتجرّبت في Ajv وطلعت true.
• الـ null نوع لوحده: "type": "string" مش بيقبل null. لو عايز تسمح بيه لازم تقول كده صراحة.
• الـ array مش object: مع إن typeof [] === "object" في JavaScript، الـ JSON Schema بتفرق بينهم.

أكتر من type

اكتب type كـ array:

{ "type": ["string", "null"] }

• بيقبل: "Saeed" وnull.
• بيرفض: 5 برسالة must be string,null.
• ده بديل nullable: true: اللي كان في OpenAPI 3.0. في JSON Schema الحقيقية مفيش keyword اسمه nullable (فصل ١١).

الـ properties والـ required

{  "type": "object",  "properties": {    "name": { "type": "string" },    "price": { "type": "number" },    "inStock": { "type": "boolean" }  },  "required": ["name", "price"]}

• الـ properties: بتوصف كل حقل لو موجود. حقل مش موجود؟ مفيش مشكلة.
• الـ required: array بأسماء الحقول اللي لازم تبقى موجودة. Ajv بيرد بـ must have required property 'price'.
• موجود يعني موجود: "price": null يعتبر موجود، وبعدين بيفشل في الـ type. والـ required مش بيمنع "" ولا 0.
• الـ required بره الـ properties: غلطة مشهورة إنك تكتب "required": true جوه الحقل. ده كان draft-03 وخلاص مبقاش موجود.

الـ additionalProperties: الحقول الزيادة

الـ default إن أي حقل زيادة مسموح. ده خطر لما الـ body بيتحفظ زي ما هو:

// اليوزر بعت { "name": "Saeed", "isAdmin": true }await db.users.update(id, req.body); // 😱 بقى admin

عندك ٣ اختيارات:

• للـ input اللي بيتحفظ: false غالبًا هو الصح.
• للـ responses اللي بتستقبلها من حد تاني: سيبها مفتوحة، عشان لما يضيف حقل ميكسرش عندك.
• فيه فخ كبير مع allOf: هتشوفه في فصل ٥.

الـ enum والـ const

{  "type": "object",  "properties": {    "status": { "enum": ["new", "paid", "shipped", "cancelled"] },    "apiVersion": { "const": "v2" },    "priority": { "enum": [1, 2, 3, null] }  }}

• الـ enum: القيمة لازم تساوي واحدة من القايمة بالظبط. الرسالة must be equal to one of the allowed values والقايمة في params.allowedValues.
• ينفع أنواع مختلفة: [1, 2, 3, null] مسموح.
• المقارنة deep equality: ينفع تحط objects وarrays جوه الـ enum.
• الـ const: قيمة واحدة بس. مفيد جدًا كـ “discriminator” في الـ unions (فصل ٥). الرسالة must be equal to constant.
• الـ case بيفرق: "Paid" مش زي "paid".

الـ annotations: الوصف والتوثيق

{  "$schema": "https://json-schema.org/draft/2020-12/schema",  "$id": "https://example.com/schemas/signup.json",  "title": "Signup",  "description": "البيانات المطلوبة لإنشاء حساب جديد",  "$comment": "الـ comment ده للمطورين بس ومش بيظهر لليوزر",  "type": "object",  "properties": {    "id": { "type": "string", "readOnly": true },    "password": { "type": "string", "minLength": 8, "writeOnly": true },    "plan": {      "description": "خطة الاشتراك",      "enum": ["free", "pro"],      "default": "free",      "examples": ["pro"]    },    "referrer": { "type": "string", "deprecated": true }  },  "required": ["password"]}

• الـ title والـ description: للـ docs والـ editors (بتظهر في الـ hover في VS Code) وللـ LLMs كمان.
• الـ default: القيمة اللي المفروض تتفهم لو الحقل مش موجود. Ajv مش بيحطها إلا بـ useDefaults.
• الـ examples: array من أمثلة. في OpenAPI 3.0 كان example مفرد.
• الـ readOnly / writeOnly: الـ server بيرجّعه بس / الـ client بيبعته بس. معلومة للأدوات، ومش بيمنعوا حاجة في Ajv لوحده.
• الـ deprecated: بيعلّم الحقل إنه هيتشال. الـ editors بتشطب عليه.
• الـ $comment: ملاحظة للمطورين جوه الـ schema.

الـ $schema والـ $id

• الـ $schema: أول سطر، بيحدد الـ draft. الـ validator بيعرف منه يفسّر الـ keywords إزاي. اكتبه دايمًا في الـ root.
• الـ $id: URI فريد للـ schema. مش لازم يبقى URL حقيقي بيفتح، هو مجرد اسم. بيستخدمه الـ $ref وكمان ajv.getSchema(id).
• الـ $id بيحدد الـ base: أي $ref relative جوه الـ schema بيتحسب بالنسبة له، زي "$ref": "money.json".

خلّصت الفصل لما

• تعرف الـ 7 types وإن 5.0 integer
• تسمح بـ null بـ type array
• تفرق بين properties وrequired
• تختار additionalProperties false أو schema أو مفتوح
• تستخدم enum وconst
• تكتب annotations: title وdescription وdefault وexamples وreadOnly وdeprecated
• تعرف إن $id اسم مش لازم يفتح