مولد مخطط JSON: تحويل عينة JSON إلى مخطط يمكن التحقق من صحته

لقد قمت بشحن ما يكفي من واجهات برمجة التطبيقات لمعرفة اللحظة المحددة التي يحتاج فيها المشروع إلى مخطط JSON. لم يكن الأمر كذلك في البداية أبدًا. لقد مرت ثلاثة أسابيع، عندما يبدأ فريق ثانٍ في استهلاك نقطة النهاية الخاصة بك، يرسل شخص ما نص طلب مشوهًا، و null ينزلق إلى الحقل الذي افترض الجميع أنه كان دائمًا سلسلة. فجأة تحتاج إلى عقد - مستند يقول، في شكل يمكن للآلة فرضه، &quot؛ هذا هو شكل الحمولة الصالحة.&quot؛ هذه الوثيقة عبارة عن مخطط JSON، وكتابة واحدة يدويًا من نقطة نهاية تُرجع بالفعل بيانات حقيقية هي واحدة من أكثر المهام مملة في العمل الخلفي.

ليرة تركية؛DR: لصق عينة JSON في مولد مخطط JSON، اختر Draft-07 أو 2020-12، وهو يستنتج أنواعًا من المخططات required الحقول وعناصر المصفوفة المدمجة وتنسيقات السلسلة مثل date-time و uuid. يتم تشغيله بالكامل في متصفحك، لذلك لا تغادر الصفحة أبدًا الحمولات التي تحمل الرموز والبيانات الشخصية. تعامل مع الإخراج باعتباره مسودة أولى قوية، ثم قم بتشديده بالقيود التي تعرفها أنت فقط.

لقد قمت ببناء هذه الأداة لـ Toolz.dev لأنني واصلت فعل الشيء نفسه يدويًا: فتح جسم الاستجابة، والتحديق فيه، ونسخ شكله إلى جملة مخطط تلو الأخرى. إنه متكرر، والنسخ المتكرر هو المكان الذي تختبئ فيه الأخطاء. يشرح هذا الدليل ما يفعله المولد، وأين يمكن الاعتماد على الاستدلال، وأين يحتاج إلى حكمك، وكيف يتناسب المخطط الذي تم إنشاؤه مع سير عمل التحقق الحقيقي.

ما هو مخطط JSON، ولماذا يتم إنشاء واحد من البيانات؟

مخطط JSON عبارة عن مفردات لوصف بنية JSON، ويتم الحفاظ عليها كـ مواصفات في حد ذاتها وليس كتقليد. المخطط هو في حد ذاته مستند JSON يعلن عن النوع المتوقع لكل حقل، والحقول المطلوبة، والشكل الذي تتخذه الكائنات والمصفوفات المتداخلة، و- مع كلمات رئيسية مثل pattern، enum، minimum، و format - ما هي القيم المسموح بها فعلا. يقرأ المدققون في كل لغة تقريبًا مخططًا ويخبرونك ما إذا كان مستند معين يتوافق أم لا. إنه أقرب شيء يمتلكه عالم JSON إلى نظام الكتابة الذي ينتقل عبر حدود الخدمة.

السبب وراء إنشاء مخطط من عينة، بدلاً من كتابته من الصفر، هو أن معظم المخطط ميكانيكي. المشي على حمولة والتسجيل والاقتباس؛ هذه سلسلة، وهذا عدد صحيح، وهذا الكائن لديه هذه المفاتيح والاقتباس؛ هو بالضبط نوع العمل الذي يجب على الآلة القيام به. ما هو لا الميكانيكية هي الطبقة الدلالية: معرفة ذلك status قد تكون واحدة فقط من أربع سلاسل، ذلك age لا يمكن أن يكون سلبيا، ذلك email يجب أن يتطابق مع نمط العنوان الحقيقي. يتعامل الجيل مع السقالات الميكانيكية حتى تتمكن من صرف انتباهك على القيود المهمة. تبدأ من مستند يطابق الواقع بالفعل وتضيف قواعد، بدلاً من البدء من ملف فارغ وتأمل أن تتذكر كل حقل.

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

كيف يستنتج المولد المخطط

يقوم المحرك بتوزيع JSON الخاص بك ويمشي القيمة بشكل متكرر، وينبعث عقدة مخطط لكل جزء من البنية. القواعد متحفظة بشكل متعمد، لأن المخطط الفضفاض للغاية لا فائدة منه والمخطط الصارم للغاية يرفض البيانات الصحيحة.

بالنسبة للعددية، فهو يميز integer من number - 42 يصبح integer، 4.2 يصبح number - لأن هذا التمييز مفيد للمدققين ولأي شخص يقرأ المخطط. القيم المنطقية و null خريطة لأنواعهم الخاصة. تصبح السلاسل type: string، وإذا كان اكتشاف التنسيق قيد التشغيل، يقوم المحرك بفحص القيمة مقابل مجموعة من الأنماط والعلامات المعروفة date-time، date، time، email، uri، uuid، و ipv4.

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

بالنسبة لمصفوفات الكائنات، يقوم المولد بشيء أكثر فائدة من السير الساذج. بدلاً من إصدار مخطط منفصل لكل عنصر أو مترامي الأطراف anyOf من الأشكال شبه المتطابقة، فإنه يدمج جميع الكائنات الموجودة في المصفوفة في كائن واحد items المخطط الذي يصف عنصرا واحدا. مطلوب مفتاح موجود في كل عنصر؛ يتم ترك المفتاح الموجود في بعض العناصر فقط اختياريًا. وهذا يعكس كيفية تصرف مجموعات API الحقيقية: قائمة مرقمة حيث تحمل معظم السجلات avatarUrl لكن القليل لا يفعل ذلك. يلتقط المخطط المدمج &quot؛ تظهر هذه الحقول دائمًا، وتظهر أحيانًا وتقتبس؛ في تعريف واحد قابل للقراءة. يمكنك رؤية هذا في العينة المضمنة، حيث members يحتوي المصفوفة على كائنين - أحدهما به active الحقل وواحد بدون - وعلامات مخطط العنصر الذي تم إنشاؤه id و role مطلوب ولكن يترك active اختياري.

بالنسبة للمصفوفات ذات الكميات القياسية المختلطة، يقوم المحرك بدمج أنواع العناصر في عنصر واحد type مجموعة - ["integer", "string", "boolean"] - بدلا من الاتحاد المطول. عندما تمتزج أشكال الكائنات وغير الكائنات بشكل حقيقي في مصفوفة واحدة، فإنها تعود إلى anyOf، وهو البناء الصحيح لمخطط JSON لـ &quot؛ أحد هذه البدائل.&quot؛

كيفية استخدام مولد مخطط JSON

الخطوة 1: لصق عينة تمثيلية

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

الخطوة 2: اختر اللهجة

اختر Draft-07 للحصول على أوسع توافق عبر مكتبات التحقق من الصحة، أو 2020-12 للمواصفات الحالية. الأداة تكتب الصحيح $schema المعرف الموجود على الجذر حتى يطبق المدقق القواعد الصحيحة. بالنسبة لأشكال الكائنات والمصفوفة التي ينتجها هذا المولد، يكون الإخراج الهيكلي هو نفسه عبر كلتا اللهجتين؛ الفرق المرئي هو المعرف. إذا لم تكن متأكدًا من أدواتك التي تدعمها، فإن Draft-07 هو الإعداد الافتراضي الآمن - فهو يتمتع بأوسع دعم للمكتبة من أي إصدار.

الخطوة 3: اضبط خياراتك

أضف أ title إذا كنت تريد التوثيق الذاتي للمخطط. قرر ما إذا كان سيتم إصدار required - في معظم الأوقات تريد ذلك، ولكن أثناء الاستكشاف المبكر قد تفضل مخططًا أكثر مرونة. استمر في اكتشاف التنسيق إلا إذا كنت ترى نتائج إيجابية كاذبة. وتشغيل الوضع الصارم (additionalProperties: false) عندما يحرس المخطط شيئًا تتحكم فيه بشكل كامل، مثل ملف التكوين أو نص الطلب، وتريد رفض المفاتيح غير المتوقعة بدلاً من تجاهلها.

الخطوة 4: الإنشاء والمراجعة والتصدير

اضغط على إنشاء، ثم اقرأ الإخراج بشكل نقدي. تحقق من ذلك required يطابق هدفك، حيث أن هذا العدد الصحيح مقابل الرقم جاء بشكل صحيح، وأن أي تنسيقات تم اكتشافها صحيحة وليست من قبيل الصدفة. عندما يبدو صحيحًا، انسخ المخطط أو قم بتنزيله كـ .json ملف جاهز للإسقاط في أداة التحقق من الصحة أو المستودع الخاص بك.

مثال عملي

النظر في هذا الرد من افتراضية /projects نقطة النهاية:

{
  "id": "5b2a1f6e-8c3d-4a1b-9f7e-2c1d3e4f5a6b",
  "name": "Toolz",
  "createdAt": "2026-01-14T09:30:00Z",
  "score": 4.8,
  "members": [
    { "id": 1, "role": "owner", "active": true },
    { "id": 2, "role": "editor" }
  ]
}

ينتج المولد مخططًا حيث id عبارة عن سلسلة مع format: "uuid"، createdAt عبارة عن سلسلة مع format: "date-time"، score هو number (ليس عددًا صحيحًا، بسبب العلامة العشرية)، و members هو مصفوفة لها items يتطلب المخطط id و role لكن لا active. هذه التفاصيل الأخيرة هي المكافأة: من مثالين للأعضاء، استنتج ذلك بشكل صحيح active اختياري. إن القيام بهذا التفكير يدويًا عبر حمولة كبيرة هو بالضبط نوع العمل الدقيق والممل الذي يزيله المولد.

حيث ينتهي الاستدلال ويبدأ حكمك

أريد أن أكون مباشرًا بشأن الحدود، لأن المخطط الذي تم إنشاؤه والذي يتم تسليمه مباشرة إلى الإنتاج يعد خطأ. يرى الاستدلال الأنواع والبنية؛ لا يمكنه رؤية النية.

لا يمكن أن يعرف ذلك role هو تعداد owner، editor، و viewer - من العينة لا يعرف إلا role هي سلسلة. لا يمكن أن يعرف ذلك score يتراوح من 0 إلى 5، ذلك name له أقصى طول، أو أن الكود الذي يبدو وكأنه UUID هو في الواقع معرف غير شفاف يجب أن يظل سلسلة عادية. يستنتج required من الحضور، سيتم وضع علامة على الحقل الاختياري الذي يظهر في عينتك مطلوبًا حتى تقوم بتصحيحه. ويعمل من البيانات التي تقدمها له: إذا لم تتضمن عينتك أبدًا null بالنسبة للحقل القابل للإلغاء، لن يعرف المخطط أن هذا الحقل يمكن أن يكون فارغًا.

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

مسودة 07 مقابل 2020-12: ما الذي يجب عليك اختياره؟

اعتبار	مشروع-07	2020-12
دعم المكتبة	الأوسع؛ مدعومة في كل مكان تقريبًا	تزايد؛ تحقق من المدقق الخاص بك
حالة	منتشرة على نطاق واسع، مستقرة	المواصفات الحالية
$schema قيمة	http://json-schema.org/draft-07/schema#	https://json-schema.org/draft/2020-12/schema
الكلمات الرئيسية لعنصر المصفوفة	items للمخططات ذات العنصر الواحد	items / prefixItems تقسيم للصفوف
الأفضل عندما	الحد الأقصى من التوافق مهم	تريد أحدث ميزات المواصفات

بالنسبة للمخططات التي تنشئها هذه الأداة - الكائنات والقوائم المطلوبة والمصفوفات ذات شكل عنصر واحد - تعبر كلتا اللهجتين عن نفس البنية. يعود القرار العملي إلى ما تدعمه مكتبة التحقق الخاصة بك. إذا كنت تقوم بتوصيل المخطط في مكدس محدد، فقم بمطابقة الإصدار الذي يحتوي على مستندات التحقق الخاصة بك. إذا كنت تبدأ من جديد وليس لديك أي قيود، فسيظل Draft-07 هو الخيار العملي لدعم النظام البيئي الذي لا مثيل له.

حالات الاستخدام الشائعة

توثيق واجهة برمجة التطبيقات الموجودة. عندما ترث نقطة نهاية بدون مخطط، فإن إنشاء واحدة من استجابة حقيقية يمنحك مستند بداية دقيقًا في ثوانٍ. ثم تقوم بتحسينه إلى عقد منشور. يقترن هذا بشكل طبيعي مع إنشاء أنواع لرمز العميل الخاص بك - يمكن لنفس العينة تغذية json إلى TypeScript الأداة بحيث يأتي عقد الخادم الخاص بك وأنواع العملاء من نفس مصدر الحقيقة.

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

التحقق من صحة ملف التكوين. تستفيد التطبيقات التي تقرأ تكوين JSON بشكل كبير من المخطط. قم بإنشاء واحد من تكوين معروف جيد، وقم بتشديده، والتحقق من صحته عند بدء التشغيل، بحيث يفشل الخطأ المطبعي في مفتاح التكوين بصوت عالٍ بدلاً من تعطيل الميزة بصمت.

الاختبارات والتركيبات. يتضاعف المخطط كأصل اختباري. تحقق من صحة تركيباتك مقابلها في CI بحيث يتم اكتشاف التركيبات التي تنجرف خارج الشكل قبل أن تنتج اختبارًا أخضر مضللاً.

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

الخصوصية: لماذا يتم تشغيل هذا في متصفحك

تعد عينات واجهة برمجة التطبيقات من أكثر النصوص حساسية التي يتعامل معها المطور. وهي تحتوي بشكل روتيني على رموز الوصول، ومعرفات الجلسة، وعناوين البريد الإلكتروني، ومعرفات السجلات الداخلية، وأحيانًا البيانات الشخصية التي لا ينبغي أبدًا لصقها في نموذج ويب عشوائي. وهذا هو بالضبط سبب قيام JSON Schema Generator بكل أعماله من جانب العميل. لا يتم تحميل أي شيء أو تسجيله أو تخزينه على الخادم. يمكنك التحقق من ذلك عن طريق فتح علامة تبويب الشبكة أثناء الإنشاء، أو عن طريق قطع الاتصال بالإنترنت - لا تزال الأداة تعمل. أهتم بهذا لأنني لن أستخدم أداة لشحن حمولاتي إلى خادم آخر &#39؛، ولن أطلب منك ذلك أيضًا. يمر نفس المبدأ عبر Toolz.dev بأكمله، وهي الحجة التي أقوم بها مطولًا في خصوصية البيانات في الأدوات عبر الإنترنت يكتب.

كيف يناسب مجموعة أدوات JSON الأوسع

المخطط هو قطعة أثرية واحدة في سير عمل JSON أكبر. قبل إنشاء المخطط، من المفيد الحصول على مدخلات نظيفة وصالحة - تنسيق JSON سيتم تنسيق الحمولة والتحقق من صحتها حتى لا تقوم بإدخال نص مشوه في المولد. بعد أن يكون لديك مخطط، غالبًا ما تريد أنواعًا لرمز التطبيق الخاص بك، وهو المكان الذي json إلى TypeScript يأتي في. وإذا كان خط الأنابيب الخاص بك يتحرك بين التنسيقات، فإن JSON إلى YAML يتعامل المحول مع التحويل الذي تتوقعه العديد من أنظمة التكوين وCI. لقد كتبت عن كيفية اتصال هذه القطع في الدليل النهائي لأدوات JSON، وحول تجميع مجموعة أوسع في مجموعة أدوات مطور الويب نظرة عامة. الهدف من مجموعة الأدوات المتصلة هو أن عينة واحدة يمكن أن تتدفق عبر عدة أدوات - المخطط والأنواع وتحويل التنسيق - دون مغادرة متصفحك مطلقًا.

أسئلة وأجوبة

كيف أقوم بإنشاء مخطط JSON من JSON؟

الصق JSON الخاص بك في المحرر، واختر Draft-07 أو 2020-12، ثم اضغط على إنشاء. تستنتج الأداة نوع كل حقل، وتستخرج المفاتيح المطلوبة، وتخرج مخططًا يمكنك نسخه مباشرة إلى أداة التحقق من الصحة. لم يتم تحميل أي شيء - يتم تشغيل الاستدلال بالكامل في متصفحك.

ما هو الفرق بين مشروع 07 و 2020-12؟

إنهما نسختان من مواصفات مخطط JSON. يتمتع Draft-07 بأكبر دعم عبر المكتبات وهو افتراضي آمن. 2020-12 هو الإصدار الحالي ويغير كيفية التعبير عن المصفوفات والمخططات الفرعية، من بين أمور أخرى. بالنسبة لأشكال الكائنات والمصفوفات، تنتج هذه الأداة البنية نفسها؛ والفرق الرئيسي المرئي هو $schema معرف.

كيف تحدد الأداة الحقول المطلوبة؟

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

ماذا يحدث مع مجموعة من الكائنات؟

يتم دمج الكائنات في كائن واحد items مخطط يصف عنصرًا واحدًا، ويتم كتابة الخاصية كمصفوفة منه. تصبح المفاتيح الموجودة في كل عنصر مطلوبة؛ تظل المفاتيح الموجودة في بعضها فقط اختيارية. وهذا يبقي المخطط قابلاً للقراءة بدلاً من إنتاج مخطط كبير anyOf من الأشكال شبه المتطابقة.

ما هي تنسيقات السلسلة التي يكتشفها؟

يعترف date-time، date، time، email، uri، uuid، و ipv4 سلاسل ويضيف المطابقة format كلمة رئيسية. يعد الاكتشاف أفضل جهد من عينة واحدة، لذا قم بمراجعة النتائج - سيتم وضع علامة على الكود الذي يبدو وكأنه UUID كرمز واحد. يمكنك تعطيل اكتشاف التنسيق إذا كنت تفضل أنواع السلاسل العادية.

هل يمكنني إنشاء مخطط من عينة واحدة؟

نعم، لكن عينة واحدة تظهر شكلًا واحدًا ممكنًا فقط. قد يكون الحقل الذي يمثل رقمًا في عينتك فارغًا أو سلسلة في مكان آخر، وسيتم وضع علامة على الحقل الاختياري الموجود. كلما كانت العينة أكثر تمثيلاً - ومن الناحية المثالية عدة سجلات حقيقية - كلما كانت الأنواع المستنتجة والقائمة المطلوبة أكثر دقة.

هل المخطط الذي تم إنشاؤه جاهز للتحقق من صحة الإنتاج؟

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

هل تم تحميل json الخاص بي على خادم؟

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

---