JSON Schema واقعاً چه چیزی را حل میکند
جمع‌بندی: Schema ساختار و نوع را حکومت میکند، نه معنای کسبوکار. فیلد گم‌شده، نوع اشتباه و enum بیرون از بازه را متوقف میکند، اما قواعدی مانند مبلغ بالای صفر در کد می‌مانند.
جمع‌بندی: بگذارید JSON Schema ساختار، نوع، بازه و قالب را اعمال کند، در حالی که قواعد بینفیلدی، ناورداهای کسبوکار و وضعیت بیرونی در کد می‌مانند؛ آن را برای APIهای عمومی و payloadهای مشترک بپذیرید، نه برای سرویس داخلی پنج‌فیلدی.
به «آیا این داده شکل درستی دارد» پاسخ می‌دهد، نه «آیا این داده معنا دارد».
چه کاری را خوب انجام می‌دهد
کامل بودن ساختاری. کدام فیلدها باید وجود داشته باشند، آیا اضافی‌ها مجازند (required، additionalProperties).
نوع‌ها. port عدد است یا رشته، tags آرایه است یا اسکالر. همین به‌تنهایی کد دفاعی زیادی را در سیستم‌های چندزبانه حذف میکند.
بازه‌ها. enum، minimum/maximum، طول رشته و آرایه.
قالب‌ها. format برای تاریخ، ایمیل، URI و UUID، با اعتبارسنج‌هایی که اعمالشان می‌کنند.
تودرتویی. هر سطح از اشیا و آرایه‌ها محدودیت خودش را دارد و خطاها مسیر دقیق حمل می‌کنند.
مستندسازی. Schema همان قرارداد است. فیلدی را تغییر دهید و diff شعاع اثر را نشان می‌دهد. همچنین نوع و فرم تولید میکند، پس یک تعریف چند مصرف‌کننده را تغذیه میکند.
چه کاری را نمی‌تواند انجام دهد
وابستگی‌های بینفیلدی. «پایان باید بعد از شروع باشد» با if/then/else قابل بیان است، اما نتیجه از سه خط کد بلندتر و ناخواناتر است.
ناورداهای کسبوکار. «موجودی نمی‌تواند منفی شود» به وضعیت بیرونی بستگی دارد. Schema یک سند می‌بیند.
معناشناسی. price: -100 کاملاً {"type": "number"} را برآورده میکند. اینکه قیمت قانونی است یا نه بیرون از دانش Schema است.
تقسیم کار عملی
| لایه | مالک |
|---|---|
| نحو: آیا JSON معتبر است | پارسر |
| ساختار: فیلدها، نوع‌ها، بازه‌ها، قالب‌ها | JSON Schema |
| معناشناسی: بینفیلدی، قواعد کسبوکار، وضعیت بیرونی | کد برنامه |
| ایمنی: اندازه، عمق، نرخ | دروازه / middleware |
اینها را در یک جا جمع کنید و Schema به صدها خط با پنج سطح if/then رشد میکند. آن‌گاه مردم دورش می‌زنند.
چه زمانی ارزشش را دارد
- APIهای عمومی با مصرف‌کننده‌های ناشناخته
- چند سرویس که همان payload را می‌خوانند
- سیستم‌های پیکربندی‌محور که تایپو باید فوراً شکست بخورد
- تولید نوع یا فرم از قرارداد
برای سرویس داخلی کوچک با پنج فیلد و یک فرانت‌اند، بررسی‌های دست‌نویس نگهداری‌شان سریع‌تر است. معرفی Schema آنجا کار منفی است.
پرسش‌های متداول
چگونه تصمیم بگیرم JSON Schema را بپذیرم؟
مصرف‌کننده‌های عمومی، چند سرویس که همان payload را می‌خوانند و نیاز به تولید نوع یا فرم را بسنجید. برای سرویس داخلی کوچک با پنج فیلد و یک فرانت‌اند، بررسی‌های دست‌نویس نگهداری‌شان سریع‌تر است.
چرا قواعد بینفیلدی باید در کد بمانند؟
«پایان باید بعد از شروع باشد» را می‌توان در if/then/else فشرد، اما نتیجه از چند خط کد بلندتر و ناخواناتر است. Schema وضعیت بیرونی را هم نمی‌بیند.
آیا Schema باید اندازه payload و عمق تودرتویی را اعتبارسنجی کند؟
نه. Schema ساختار را توصیف میکند، نه اندازه یا عمق؛ این محدودیت‌ها به لایه دروازه یا middleware تعلق دارند.