معرفی کتابخانه jsonschema در پایتون

کتابخانه jsonschema برای اعتبارسنجی داده‌های JSON بر اساس استاندارد JSON Schema طراحی شده است. این کتابخانه به توسعه‌دهندگان پایتون امکان می‌دهد قراردادهای داده (schema) را تعریف و از اعتبار داده‌های ورودی در APIها، فایل‌های پیکربندی، و پردازش‌های داده‌ای اطمینان حاصل کنند. پشتیبانی از نسخه‌های مختلف JSON Schema، قابلیت افزودن فرمت‌های سفارشی و امکان گرفتن خطاهای دقیق از مزایای عمده این ابزار است.

نصب و شروع سریع

pip install jsonschema

این دستور کتابخانه را نصب می‌کند. بعد از نصب، می‌توانید از متدهای ساده یا ساختار کلاسیک Validator استفاده کنید.

مثال پایه‌ای: تعریف schema و اعتبارسنجی

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer", "minimum": 0},
    },
    "required": ["name"]
}

instance = {"name": "Ali", "age": 30}

try:
    validate(instance=instance, schema=schema)
    print("Valid!")
except ValidationError as e:
    print("Invalid:", e)

کد بالا یک schema ساده تعریف می‌کند و با تابع validate داده را بررسی می‌کند. در صورت مغایرت، ValidationError پرتاب می‌شود. این روش برای اعتبارسنجی سریع و ساده مناسب است.

استفاده از Validator پیش‌کامپایل‌شده برای کارایی و خطاهای دقیق

from jsonschema import Draft7Validator

validator = Draft7Validator(schema)
errors = sorted(validator.iter_errors({"age": -5}), key=lambda e: e.path)
for error in errors:
    print(error.message, list(error.path))

در این مثال، یک Validator پیش‌کامپایل‌شده از نوع Draft7 ساخته‌ایم و از iter_errors برای گرفتن تمام خطاها استفاده کرده‌ایم. این روش به‌ویژه وقتی داده‌های زیادی را می‌خواهید در یک حلقه بررسی کنید یا نیاز به گزارش جامع از خطاها دارید کاربردی است.

نمونه‌هایی از ویژگی‌های پرکاربرد schema

مثال: schema پیشرفته با آرایه و enum

schema = {
    "type": "object",
    "properties": {
        "tags": {
            "type": "array",
            "items": {"type": "string"},
            "minItems": 1,
            "uniqueItems": True
        },
        "status": {"enum": ["draft", "published", "archived"]}
    },
    "required": ["tags", "status"]
}

در این schema، فیلد tags باید آرایه‌ای از رشته‌ها باشد، حداقل یک عضو داشته و تکراری نباشد. فیلد status نیز باید یکی از مقادیر مشخص‌شده باشد.

اطلاعات بیش‌تر درباره خطاها و مسیر آن‌ها

خطاهایی که از Validator برمی‌گردند دارای ویژگی‌هایی مثل message، path، schema_path و context هستند. با استفاده از این مشخصه‌ها می‌توان پیغام‌های کاربرپسند ساخت یا محل دقیق خطا در داده را گزارش داد.

پشتیبانی از format و افزودن custom format

from jsonschema import Draft7Validator, FormatChecker

schema = {
    "type": "object",
    "properties": {
        "email": {"type": "string", "format": "email"}
    }
}

validator = Draft7Validator(schema, format_checker=FormatChecker())
errors = list(validator.iter_errors({"email": "not-an-email"}))
print(len(errors))

در این مثال format_checker فعال است و مقدار email براساس قاعدهٔ استاندارد ایمیل بررسی می‌شود. می‌توان format دلخواه نیز اضافه کرد (مثلاً شناسه‌های داخلی).

تعریف فرمت سفارشی

from jsonschema import FormatChecker
import re

format_checker = FormatChecker()

@format_checker.checks("my-id")
def is_my_id(value):
    return bool(re.match(r"^ID-d{4}$", value))

schema = {"type": "string", "format": "my-id"}
validator = Draft7Validator(schema, format_checker=format_checker)
print(list(validator.iter_errors("ID-1234")))

مثال بالا نحوهٔ ثبت یک فرمت سفارشی به نام “my-id” را نشان می‌دهد. تابع is_my_id مقادیر را بر اساس الگوی regex بررسی می‌کند. این امکان برای بررسی قواعد خاص سازمانی مفید است.

رفرنس‌ها ($ref) و حل ارجاعات

from jsonschema import Draft7Validator, RefResolver

root_schema = {
    "$id": "http://example.com/schemas/root.json",
    "definitions": {
        "person": {
            "type": "object",
            "properties": {
                "name": {"type": "string"}
            },
            "required": ["name"]
        }
    }
}
schema = {"$ref": "http://example.com/schemas/root.json#/definitions/person"}

resolver = RefResolver.from_schema(root_schema)
validator = Draft7Validator(schema, resolver=resolver)
print(list(validator.iter_errors({"name": 5})))

در این کد با استفاده از RefResolver ارجاع به تعریف داخلی حل می‌شود. این الگو در پروژه‌های بزرگ که schemaها تقسیم‌بندی شده‌اند کاربرد دارد.

موارد کاربرد و نکات عملی

• اعتبارسنجی ورودی API قبل از پردازش برای جلوگیری از خطاهای منطقی.
• کنترل فایل‌های پیکربندی یا داده‌های ورودی در خط لوله‌های ETL.
• مستندسازی قراردادهای JSON بین سرویس‌ها و تطبیق با تست‌های اتوماتیک.

نکات مهم: برای بهینه‌سازی، Validator را یک‌بار بسازید و دوباره استفاده کنید. از iter_errors برای جمع‌آوری همهٔ خطاها استفاده کنید تا کاربر گزارش جامع دریافت کند. همچنین توجه داشته باشید که نسخهٔ Draft انتخابی (Draft7، Draft2020-12 و…) باید با نیازهای پروژه مطابقت داشته باشد.

نمونه‌هایی از مدیریت بهتر خطاها

from jsonschema import Draft7Validator
from jsonschema.exceptions import best_match

validator = Draft7Validator(schema)
errors = list(validator.iter_errors({"age": -1}))
best = best_match(errors)
if best:
    print("Most relevant error:", best.message)

در برخی مواقع لازم است «مهم‌ترین» یا مرتبط‌ترین خطا را مشخص کنید؛ تابع best_match این کمک را انجام می‌دهد تا پیام قابل فهم‌تری به کاربر نشان دهید.

جمع‌بندی و منابع بیشتر

کتابخانه jsonschema در پایتون ابزاری قدرتمند برای اعتبارسنجی داده‌هاست. از تعریف سادهٔ قوانین تا پیاده‌سازی schemaهای پیچیده با ارجاعات و فرمت‌های سفارشی پشتیبانی می‌کند. برای پروژه‌های API، پردازش داده و قراردادهای بین سرویس‌ها، این ابزار می‌تواند بخش مهمی از لایهٔ اعتبارسنجی باشد. برای جزئیات بیشتر مستندات رسمی jsonschema و نسخه‌های مختلف استاندارد JSON Schema را مطالعه کنید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال