اعتبارسنج JSON Schema

اعتبارسنجی JSON Schema چیست؟

اعتبارسنجی JSON Schema فرآیندی است که بررسی می‌کند آیا یک سند JSON با مجموعه‌ای از محدودیت‌های ساختاری و مقداری که در یک JSON Schema تعریف شده‌اند مطابقت دارد یا نه. خود schema یک سند JSON است که شکل مورد انتظار داده‌های شما را توصیف می‌کند: کدام ویژگی‌ها اجباری هستند، چه نوع‌هایی باید داشته باشند، محدوده‌های مجاز اعداد، الگوهای رشته‌ای، طول آرایه‌ها و موارد دیگر. مشخصات JSON Schema در json-schema.org نگهداری می‌شود و به صورت مجموعه‌ای از پیش‌نویس‌های IETF منتشر شده است؛ Draft 7 و Draft 2020-12 پرکاربردترین نسخه‌ها هستند.

در حالی که اعتبارسنجی ساده JSON تنها نحو را بررسی می‌کند (آیا براکت‌ها درست بسته شده‌اند؟ آیا رشته‌ها داخل کوتیشن هستند؟)، اعتبارسنجی schema یک گام فراتر می‌رود. به سؤالاتی از این قبیل پاسخ می‌دهد: آیا پاسخ این API حاوی یک فیلد «id» است که همیشه یک عدد صحیح است؟ آیا فیلد «status» یکی از سه مقدار مجاز است؟ آیا اشیاء تودرتو ساختار صحیحی دارند؟ این نوع بررسی ساختاری اشکالاتی را کشف می‌کند که بررسی‌های نحوی کاملاً از آن‌ها می‌گذرند، زیرا JSON نحواً درست می‌تواند از نظر معنایی برای برنامه‌ی شما اشتباه باشد.

JSON Schema در تعریف‌های OpenAPI/Swagger، اعتبارسنجی فایل‌های پیکربندی، اعتبارسنجی فرم، محدودیت‌های اسناد پایگاه داده و آزمون خودکار استفاده می‌شود. ابزارهایی مانند Ajv (JavaScript)، jsonschema (Python) و check-jsonschema (CLI) مشخصات را پیاده‌سازی می‌کنند تا بتوانید داده‌ها را به صورت برنامه‌نویسانه اعتبارسنجی کنید. این اعتبارسنج آنلاین به شما امکان می‌دهد هر دو schema و سند داده را بچسبانید و انطباق را فوراً بررسی کنید، بدون نیاز به نصب هیچ کتابخانه‌ای.

چرا از اعتبارسنج آنلاین JSON Schema استفاده کنیم؟

نوشتن schema و رفع اشکال خطاهای اعتبارسنجی به صورت دستی کند است. یک اعتبارسنج آنلاین JSON Schema بازخورد فوری درباره انطباق داده‌ها با schema ارائه می‌دهد، با پیام‌های خطای واضحی که دقیقاً فیلد خطادار را نشان می‌دهند.

موارد استفاده از اعتبارسنجی JSON Schema

مرجع کلیدواژه‌های JSON Schema

یک JSON Schema از کلیدواژه‌هایی ساخته می‌شود که هر کدام یک محدودیت بر داده‌های اعتبارسنجی‌شده اعمال می‌کنند. جدول زیر پرکاربردترین کلیدواژه‌ها در Draft 7 و نسخه‌های بعدی را فهرست می‌کند. هر کلیدواژه می‌تواند با دیگران در همان شیء schema ترکیب شود.

مقایسه نسخه‌های JSON Schema: Draft 7 در مقابل 2019-09 در مقابل 2020-12

JSON Schema از چندین نسخه پیش‌نویس عبور کرده است. Draft 7 (منتشرشده در ۲۰۱۸) پرپشتیبانی‌ترین نسخه در ابزارها است. Draft 2019-09 کلیدواژه‌های $defs (جایگزین definitions)، unevaluatedProperties و $recursiveRef را معرفی کرد. Draft 2020-12 (آخرین نسخه پایدار) کلیدواژه‌ی $recursiveRef را با $dynamicRef جایگزین کرد و prefixItems برای اعتبارسنجی tuple را معرفی نمود. هنگام انتخاب نسخه، بررسی کنید که کتابخانه اعتبارسنجی شما از آن پشتیبانی می‌کند. Ajv هر سه نسخه را پشتیبانی می‌کند. کتابخانه jsonschema پایتون از نسخه 4.0 تا 2020-12 را پشتیبانی می‌کند.

نمونه‌های کد

این مثال‌ها نشان می‌دهند چگونه JSON را در برابر یک schema به صورت برنامه‌نویسانه اعتبارسنجی کنید. هر کدام از یک کتابخانه معتبر برای اکوسیستم زبان خود استفاده می‌کند.

import Ajv from 'ajv';

const ajv = new Ajv();

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 1 },
    age: { type: 'integer', minimum: 0 },
    email: { type: 'string', format: 'email' }
  },
  required: ['name', 'email'],
  additionalProperties: false
};

const data = { name: 'Alice', age: 30, email: 'alice@example.com' };

const validate = ajv.compile(schema);
const valid = validate(data);
console.log(valid);          // → true
console.log(validate.errors); // → null

// Invalid data — missing required "email"
validate({ name: 'Bob', age: 25 });
console.log(validate.errors);
// → [{ instancePath: '', keyword: 'required', params: { missingProperty: 'email' } }]

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "age": {"type": "integer", "minimum": 0},
        "tags": {
            "type": "array",
            "items": {"type": "string"},
            "uniqueItems": True
        }
    },
    "required": ["name"]
}

# Valid data
validate(instance={"name": "Alice", "age": 30, "tags": ["admin"]}, schema=schema)
# → No exception raised

# Invalid data — wrong type for "age"
try:
    validate(instance={"name": "Alice", "age": "thirty"}, schema=schema)
except ValidationError as e:
    print(e.message)
    # → 'thirty' is not of type 'integer'
    print(e.json_path)
    # → $.age

package main

import (
    "fmt"
    "strings"
    "github.com/santhosh-tekuri/jsonschema/v5"
)

func main() {
    schemaJSON := `{
        "type": "object",
        "properties": {
            "id": { "type": "integer" },
            "status": { "enum": ["active", "inactive"] }
        },
        "required": ["id", "status"]
    }`

    compiler := jsonschema.NewCompiler()
    compiler.AddResource("schema.json", strings.NewReader(schemaJSON))
    schema, _ := compiler.Compile("schema.json")

    // Valid data
    data := map[string]interface{}{"id": 1, "status": "active"}
    err := schema.Validate(data)
    fmt.Println(err) // → <nil>

    // Invalid — missing "status"
    bad := map[string]interface{}{"id": 2}
    err = schema.Validate(bad)
    fmt.Println(err) // → validation failed: missing properties: 'status'
}

# Install via pip
pip install check-jsonschema

# Validate a file against a schema
check-jsonschema --schemafile schema.json data.json
# → ok -- validation done

# Validate against a remote schema (e.g., GitHub Actions workflow)
check-jsonschema --builtin-schema vendor.github-workflows my-workflow.yml

# Validate multiple files at once
check-jsonschema --schemafile schema.json file1.json file2.json file3.json

سؤالات متداول