از چند نمونهٔJSONمی‌توان پیش‌نویسی از نوع‌های دیده‌شده ساخت،اما نمی‌توان الزامی‌بودنِ فیلد،مجوز یا قواعدِ کسب‌وکار را قطعی حدس زد. کدِ این صفحه سه شیءِ اصیل را می‌خواند و یک پیش‌نویسِ قابل‌ویرایش باtype،propertiesوitemsمی‌سازد. همراهِ آن،پوششِ مشاهده و چیزهای نامعلوم را ثبت می‌کند؛این ابزار اعتبارسنجِ کاملِJSON Schemaنیست.
مشاهده را از قانون جدا نگه داریم
سه نمونهٔ ساختگیidهای متنیِ001،002و003دارند. activeدر دو نمونه بولی است و در سومی وجود ندارد. amountبه‌ترتیبnull،۰و۳٫۵است. tagsیک بار خالی،یک بار رشته و بارِ دیگر عدد دارد؛metaهم objectِتودرتوست. هیچ‌یک دادهٔ مشتری یا قراردادِ واقعیِ APIنیستند.
اینکهidدر هر سه ردیف آمده،دلیلِ requiredبودنِ آن در سامانهٔ واقعی نیست. دیدنِ دو مقدارِtrue/falseهم مجوزِ تبدیلِ فیلدهای دیگر بهbooleanنمی‌دهد. خروجی عمداًrequired،enum،حدود،additionalProperties=falseو حکمِ دسترسی تولید نمی‌کند؛مالکِ قرارداد باید دربارهٔ آن‌ها تصمیم بگیرد.
نوع‌ها را بدونِ تبدیلِ خاموش ثبت کنیم
کد booleanرا پیش ازintegerتشخیص می‌دهد؛درPythonنبایدTrueرا صرفاً به‌دلیلِ رابطهٔ نوع‌ها یک عددِ۱حساب کنیم. برایamount،nullوnumberدر پیش‌نویس می‌آیند؛وقتیnumberوجود دارد،integerِمشاهده‌شده زیرمجموعهٔ همان دامنه است و نوعِ اضافهٔ تکراری درج نمی‌شود. مقدارهای ورودی تبدیل یا پُر نمی‌شوند.
| مسیرِ نمونه | مشاهده | پیش‌نویسِ محدود |
|---|---|---|
| id | سه رشته | type:string،بدونِrequiredیاenum |
| active | دوboolean،یکmissing | type:boolean؛نبودِ فیلد جدا ثبت |
| amount | null،integer،number | type:[null,number] |
| tags | آرایهٔخالی/رشته/عدد | arrayباitemsِintegerیاstring |
missing با null یکی نیست
برای هر ویژگی،تعدادِ objectهای والد،حضور،غیبت وnullثبت می‌شود. activeدو حضور،یک غیبت و صفرnullدارد. meta.sourceدر یکobjectغایب،در یکیstringو در دیگریnullاست. شمارشِ مسیرِ داخلی نسبت بهobjectهای همان سطح است؛آن را بی‌توضیح فراوانیِ کلِ جهانِ داده نمی‌نامیم.
برای unknown_itemsهر سه آرایه خالی‌اند. از این مشاهده دربارهٔ نوعِ عضو چیزی نمی‌دانیم؛پسitemsتولید نمی‌شود و unknownصریح داریم. کدِ محدود نشان می‌دهد یک عضوِ مشاهده‌نشده بعداً از همین پیش‌نویسِ باز عبور می‌کند. خالی‌بودنِ نمونه،اثباتِ «هیچ عضوی مجاز نیست» نیست.
چه چیزی واقعاً آزموده شده است؟
ساختارِ مورد انتظارِ propertiesونوع‌های ترکیبی با assertهای مستقل کنترل می‌شود. یک checkerدست‌نویس فقط همینtype/properties/itemsرا می‌فهمد؛هر سه نمونه با آن سازگارند،objectخالی هم چونrequiredحدس نزده‌ایم می‌گذرد. idعددی یاactiveعددی در این قراردادِ محدود نمی‌گذرد؛idمتنیِ تازه وکلیدِ اضافی می‌توانند بگذرند چون بسته‌بودنِ دامنه تعیین نشده است.
dialectِنام‌برده در خروجی۲۰۲۰-۱۲است،اماcheckerراvalidatorِکاملِهمان نسخه یا آزمونِmeta-schemaمعرفی نمی‌کنیم. در runtimeکتابخانهٔjsonschemaوجود نداشت و نصب نکردیم؛full_json_schema_validator_executedدر گزارش نادرست است. تولیدِ یک فایلِschemaبا اجرایِ اعتبارسنجِ کامل و تأییدِ قرارداد سه کارِ متفاوت‌اند.
محدودیتِ ورودی،قاعدهٔ استنباطی نیست
کد یک تا ده نمونهٔobject،عمقِحداکثر۴،بودجهٔ۲۰۰گره در هر نمونه و ظرفِحداکثر۲۰عضو را می‌پذیرد؛رشته‌ها وکلیدها هم سقفِ محلی دارند. عددِ صحیح در زیرمجموعهٔsigned64ِورودی محدود شده است. این سقف‌ها قاعدهٔ خودِتمرین‌اند وبه‌عنوانِmaximumیاmaxItemsاز داده «کشف» و درschemaدرج نمی‌شوند.
بدونِ نمونه،تعدادِ بیش‌ازحد،NaNو ریشهٔ غیرobjectواقعاً رد می‌شوند. ورودیِ اصلی هم پس از کار برابر می‌ماند. این کد فایلِ خصوصی یاAPIرا نمی‌خواند،نمونهٔ نمایندهٔ آماری نمی‌سازد و از سه ردیف،قواعدِ امنیت ومالکیتِ کاربر استخراج نمی‌کند.
از پیش‌نویس به قراردادِ واقعی
متنِ اعتبارسنجیِJSONباschema از قراردادِ ازپیش‌تعریف‌شده شروع می‌کند؛این صفحه مسیرِ برعکسِ مشاهدهٔ نمونه تا پیش‌نویس را دارد. پس از آن،مسئولِ داده باید نیازها را صریح کند،نسخهٔ قرارداد را ثبت و باvalidatorمناسب وکنترل‌های معناییِ جدا بیازماید.
برای بررسیِ اتصال در راهکارهای اپرا،نمونهٔ مجاز و فهرستِ قواعدِ معلوم/نامعلوم را همراه بیاورید. وجودِ این ابزار،قابلیتِ تولیدِ خودکارِschemaیا اجرایِ عملیات در محصول را وعده نمی‌دهد. خروجیِ مفیدش،پیش‌نویسِ قابلِبازبینی است که حدودِ استنتاجش را پنهان نمی‌کند.
فایل تمرین و منبع
کدِ کاملِ محلیِ تمرین و کنترل‌هایش · دادهٔ اصیل و نتیجهٔ اجرای واقعی؛ نویسه‌های کنترلی escape شده‌اند
- راهنمای رسمیِJSON Schema،properties/required/additionalPropertiesومقدارِnull؛بخش‌های مرتبط خوانده شدند
- JSON Schema Validation۲۰۲۰-۱۲،بخش۶٫۱٫۱؛نوعِتکی/ترکیبی وintegerبا بخشِکسریِصفر؛فقط بخشِمرتبط خوانده شد
منابع در 2026-11-04 خوانده شدند؛ این تاریخ، تاریخ انتشار منبع نیست. مثال‌ها و فایل‌های این راهنما آموزشی و ساختهٔ تحریریه‌اند.