پرش به محتوای اصلی

راهنمای اعتبارسنج JSON Schema

زمان مطالعه: ۲ دقیقه

این ابزار چیست؟

JSON Schema قراردادی است که می‌گوید یک داده‌ی JSON باید چه شکلی داشته باشد: کدام فیلدها الزامی‌اند، هر کدام چه نوعی دارد، عددها در چه بازه‌ای‌اند و رشته‌ها از چه الگویی پیروی می‌کنند. APIها، فایل‌های پیکربندی و فرم‌ها با همین قرارداد ورودی را بررسی می‌کنند. این ابزار داده را با اسکیما می‌سنجد و هر خطا را با مسیر دقیق و توضیح فارسی نشان می‌دهد.

دو نسخه‌ی رایج draft-07 و 2020-12 پشتیبانی می‌شوند و اگر اسکیما ندارید، می‌توانید از روی خود داده یک اسکیمای اولیه بسازید. همه‌چیز در مرورگر شما انجام می‌شود.

گام‌به‌گام

  1. نسخه را انتخاب کنید

    از «نسخه‌ی JSON Schema» همان نسخه‌ای را بردارید که اسکیما برایش نوشته شده؛ اگر مطمئن نیستید، مقدار $schema در ابتدای اسکیما را ببینید.

  2. اسکیما و داده را بچسبانید

    اسکیما را در کادر اسکیما و داده را در «داده‌ی JSON» بگذارید. اگر یکی JSON معتبر نباشد، همان‌جا پیام خطا می‌گیرید.

  3. خطاها را بخوانید

    اگر داده مطابق نباشد، جدولی با مسیر هر خطا، قانونی که نقض شده و توضیح فارسی آن می‌بینید؛ مسیر /age یعنی فیلد age در ریشه.

  4. در صورت نیاز اسکیما بسازید

    اگر فقط داده دارید، از روی آن یک اسکیمای اولیه بسازید و سپس قانون‌های دقیق‌تر مثل حداقل و حداکثر را خودتان اضافه کنید.

نمونه‌های کاربردی

  • سن کمتر از حد

    اسکیما سن را عدد صحیح و دست‌کم ۱۸ می‌خواهد و داده ۱۵ دارد.

    {"name":"علی","age":15}

    نتیجه: /age · minimum · مقدار باید حداقل ۱۸ باشد.

  • فیلد الزامی جاافتاده

    فیلد age در required آمده اما در داده نیست.

    {"name":"علی"}

    نتیجه: /age · required · ویژگی الزامی «age» وجود ندارد.

اشتباه‌های رایج

  • انتخاب نسخه‌ی اشتباه: کلیدواژه‌هایی مثل prefixItems و dependentRequired فقط در 2020-12 تعریف شده‌اند و items در دو نسخه معنای متفاوتی دارد؛ نسخه را مطابق اسکیما انتخاب کنید.
  • فراموش کردن required: نوشتن یک فیلد در properties آن را الزامی نمی‌کند. فیلدهای اجباری را در فهرست required هم بیاورید.
  • انتظار رد شدن فیلدهای اضافه: به‌طور پیش‌فرض هر فیلد اضافه‌ای پذیرفته می‌شود. اگر نمی‌خواهید، additionalProperties را false بگذارید.
  • تکیه‌ی کامل بر اسکیمای ساخته‌شده از داده: این اسکیما فقط شکل همان نمونه را توصیف می‌کند و بازه‌ها و الگوها را نمی‌داند. آن را نقطه‌ی شروع بدانید.

مسیر خطا چطور خوانده می‌شود؟

مسیرها با قاعده‌ی JSON Pointer نوشته می‌شوند: هر بخش پس از / نام یک کلید یا شماره‌ی عنصر آرایه است که از صفر شروع می‌شود. پس /items/2/price یعنی قیمت سومین عنصر آرایه‌ی items. خطای ریشه با «/ (ریشه)» نشان داده می‌شود.

ستون قانون، کلیدواژه‌ای از اسکیما است که نقض شده؛ مثلاً type، required، minimum یا pattern. با جست‌وجوی همین کلیدواژه در اسکیما زود می‌فهمید کدام بخش را باید اصلاح کنید.

پرسش‌های متداول

تفاوت draft-07 و 2020-12 چیست؟
در 2020-12 کلیدهایی مثل prefixItems و $defs جایگزین items آرایه‌ای و definitions شده‌اند. اگر اسکیمای شما قدیمی است draft-07 را انتخاب کنید.
طول متن فارسی چطور شمرده می‌شود؟
minLength و maxLength بر اساس نقطه‌کد یونیکد شمرده می‌شوند، نه واحد UTF-16؛ پس هر حرف فارسی یک نویسه است و ایموجی هم یکی حساب می‌شود.
مسیر خطا یعنی چه؟
مسیر به صورت JSON Pointer نمایش داده می‌شود؛ مثلاً /users/0/email یعنی فیلد email از اولین عنصر آرایه‌ی users. مسیر خالی یعنی خود ریشه.

ابزارهای مرتبط