مذكرات سعيد
اتقرأ🔖

🗺️ الخريطة

البدايةفصلين
فصل ١المشكلة — الـ JSON ملوش عقد#الـ JSON ملوش types #الـ TS بيختفي #حدود الثقة #fail fast
فصل ٢يعني إيه JSON Schema؟#schema وinstance #validator #assertions #annotations #أول مثال
الـ keywords٥ فصول
فصل ٣الأساسيات — الـ type والـ properties والـ required#الـ types السبعة #required #additionalProperties #enum #const #annotations
فصل ٤القيود — الـ strings والأرقام والـ arrays والـ objects#strings #format #أرقام #arrays #tuples #objects #dependencies
فصل ٥التركيب والشروط — الـ allOf والـ oneOf والـ if/then#allOf #anyOf #oneOf #not #if/then/else #discriminated unions #unevaluatedProperties
فصل ٦إعادة الاستخدام — الـ $defs والـ $ref والملفات#$defs #$ref #ملفات منفصلة #recursive #$anchor #$dynamicRef
فصل ٧الإصدارات — من draft-04 لحد 2020-12#الـ drafts #إيه اللي اتغير #الفروق اللي بتعض #مين بيدعم إيه
التطبيق٤ فصول
فصل ٨الـ validation بجد — Ajv من جوه#compile مرة واحدة #الـ options #شكل الـ errors #رسايل بالعربي #standalone #لغات تانية
فصل ٩🧪 Lab: API طلبات الكشري بالـ Express والـ Fastify#middleware #errors نضيفة #body limit #Fastify built-in #response serialization
فصل ١٠الـ TypeScript — مصدر واحد للحقيقة#type guard #schema ← types #types ← schema #TypeBox #Zod #إمتى مين
فصل ١١بتتستخدم فين؟ — OpenAPI والـ editors والـ LLMs#OpenAPI #autocomplete للـ config #LLM structured outputs #MongoDB #forms #contract tests #Kafka
بعدهافصلين
فصل ١٢إمتى لأ؟ — الحدود والتطوّر والأمان#مش بتعمل إيه #schema evolution #breaking changes #ReDoS #حجم الـ payload #schemas من بره
الآخرCheat Sheet: الـ JSON Schema#المشكلة والحل في سطر

المذكرة دي بتجاوب على أربع أسئلة عن الـ JSON Schema: هي إيه؟ بتحل مشكلة إيه؟ أستخدمها إمتى؟ وليه هي بالذات؟

المشكلة باختصار:

  • الـ JSON ملوش عقد: أي حد يقدر يبعتلك {"age": "30"} بدل {"age": 30}، والـ parser هيقبله عادي.
  • الـ TypeScript مش هيلحقك: الـ types بتختفي بعد الـ compile، فوقت التشغيل مفيش حد بيراجع.
  • الغلط بيتأخر: البيانات الغلط بتعدّي من الباب، وتنفجر بعدين في مكان بعيد خالص (undefined is not a function في الـ service الرابعة).
  • الحدود كتير: API bodies، وwebhooks، وملفات config، ورسايل queue، وردود الـ LLM. كل دول بيانات جاية من بره ومش مضمونة.
الحل: تكتب “العقد” مرة واحدة كـ JSON Schema، وvalidator يراجع كل JSON داخل على العقد ده عند الباب، قبل ما يلمس الكود بتاعك.
terminal
mkdir schema-lab && cd schema-lab && pnpm initpnpm pkg set type=modulepnpm add ajv ajv-formats# للفصول اللي بعد كدهpnpm add zod typebox fastify express