اینکه پاسخ مدل با آکولاد شروع شود، آن را داده معتبر نمی‌کند. ابتدا باید JSON قابل تجزیه باشد، سپس با schema سازگار و در پایان از نظر قواعد کسب‌وکار مجاز باشد. این سه لایه را جدا کنید تا خطای ساختار با خطای معنا یا مجوز اشتباه نشود.
روش اجرا و تصمیم‌گیری
برای خروجی موردنیاز، نوع فیلدها و فهرست الزامی را تعریف کنید. در JSON Schema، تعریف properties به تنهایی همه فیلدها را الزامی نمی‌کند؛ required باید جدا تعیین شود. اگر فیلد اضافی مجاز نیست، قاعده آن را صریح بنویسید و رفتار نسخه مورد استفاده را آزمایش کنید.
بعد از تجزیه، نوع داده، محدوده عدد، طول رشته و مقدارهای مجاز را کنترل کنید. عددی که به صورت رشته آمده یا مقدار تهی غیرمجاز دارد نباید بی‌صدا اصلاح و پذیرفته شود. خطا را با مسیر فیلد ثبت کنید تا اصلاح قابل فهم باشد.
سازگاری schema صحت واقعی را تضمین نمی‌کند. شناسه مشتری ممکن است رشته معتبر اما متعلق به کاربر دیگری باشد. مبلغ نیز می‌تواند عدد مثبت ولی خلاف قیمت تأییدشده باشد. پس کنترل مالکیت و قواعد منبع معتبر باید خارج از مدل و پیش از هر اقدام انجام شود.
نمونهٔ ساختگی و قابل تکرار
خروجی ساختگی برای ثبت درخواست شامل نام، موضوع و تعداد است. schema تعداد را عدد صحیح مثبت می‌خواهد. پاسخ «سه» در فیلد تعداد از نظر معنا قابل حدس است، اما با قرارداد داده ناسازگار است و باید مسیر اصلاح روشن داشته باشد. پاسخ دیگری تعداد۳ دارد و schema را می‌گذراند، ولی شناسه مشتری غیرمجاز است؛ این مورد در کنترل دسترسی رد می‌شود. عبارت «JSON معتبر» نباید برای توجیه اجرای مورد دوم استفاده شود.
محدودیت‌ها و خطاهای رایج
حالت ساختاریافته سرویس می‌تواند برخی خطاها را کاهش دهد، اما برنامه همچنان باید خروجی را در مرز اعتماد اعتبارسنجی کند. schema و رفتار کتابخانه را نسخه‌گذاری کنید. مثال آموزشی، قرارداد آماده برای ثبت داده واقعی یا قابلیت تضمین‌شده هیچ محصولی نیست.
کنترل پیش از استفاده
| کنترل | معیار پذیرش |
|---|---|
| تجزیه | متن دقیقاً JSON معتبر و بدون بخش اضافی غیرمجاز باشد. |
| ساختار | فیلد لازم، نوع و مقدار مجاز با schema نسخه‌دار کنترل شوند. |
| معنا | مالکیت شناسه و قواعد کسب‌وکار پس از schema بررسی شوند. |
کاربرگ همراه
کاربرگ سه لایه خطا را جدا نگه می‌دارد. برای هر مورد نام فیلد و علت رد را ثبت کنید. از تبدیل خودکار همه ورودی‌های نامعتبر به مقدار پیش‌فرض خودداری کنید؛ این کار ممکن است خطای مهم را پنهان کند.
دریافت کاربرگ CSV این راهنما — داده‌های داخل فایل نمونهٔ ساختگی‌اند. نسخهٔ اصلی را نگه دارید و برای آزمون خودتان یک کپی بسازید.
منبع و ادامهٔ کار
JSON Schema: شیء و فیلدها. تاریخ بررسی منابع: ۱ نوامبر ۲۰۲۶.
اگر کاربرد شما پاسخ‌گویی به مشتری است، مسیر مرتبط اپرا را ببینید و مسئله و محدودیت‌های همین کاربرگ را برای بررسی در دمو همراه داشته باشید.