JSON Schema सत्यापन गाइड: अपने डेटा संरचनाओं को मान्य करें

बाहरी स्रोतों से डेटा प्राप्त करने वाला प्रत्येक एप्लिकेशन एक ही मूलभूत प्रश्न का सामना करता है: क्या मैं इस डेटा पर भरोसा कर सकता हूँ? चाहे API अनुरोध बॉडी हो, कॉन्फ़िगरेशन फ़ाइल, कतार संदेश या डेटा आयात, अविश्वसनीय डेटा को सिस्टम में प्रवेश करने से पहले मान्य किया जाना चाहिए। JSON Schema मान्य डेटा कैसा दिखता है इसे परिभाषित करने और आने वाले डेटा को उस परिभाषा के अनुरूप सत्यापित करने का एक मानकीकृत, भाषा-अज्ञेय तरीका प्रदान करता है। यह गाइड आपके पहले Schema लिखने से लेकर जटिल सत्यापन के उन्नत पैटर्न तक सब कुछ कवर करती है, व्यावहारिक उदाहरणों के साथ जिन्हें आप तुरंत लागू कर सकते हैं।

JSON Schema क्या है?

JSON Schema एक JSON दस्तावेज़ है जो अन्य JSON दस्तावेज़ों की संरचना और बाधाओं का वर्णन करता है। यह एक शब्दावली है जो आपको JSON डेटा को एनोटेट और मान्य करने की अनुमति देती है, जिसे इंटरनेट इंजीनियरिंग टास्क फोर्स (IETF) द्वारा मानकीकृत किया गया है। JSON Schema नियमों को परिभाषित करता है कि कौन से फ़ील्ड मौजूद होने चाहिए, वे किस प्रकार के होने चाहिए, कौन से मान स्वीकार्य हैं, और ऑब्जेक्ट और ऐरे कैसे संरचित होने चाहिए।

JSON Schema को अपने डेटा अनुबंध के रूप में सोचें। जैसे डेटाबेस Schema टेबल के कॉलम, प्रकार और बाधाओं को परिभाषित करता है, JSON Schema JSON दस्तावेज़ के गुणों, प्रकारों और बाधाओं को परिभाषित करता है। कोई भी JSON डेटा जो Schema में सभी बाधाओं को संतुष्ट करता है, मान्य इंस्टेंस कहलाता है, जबकि किसी भी बाधा का उल्लंघन करने वाला डेटा अमान्य है।

JSON Schema क्या नहीं है

• डेटा प्रारूप नहीं: JSON Schema यह परिभाषित नहीं करता कि डेटा कैसे क्रमबद्ध या प्रेषित किया जाता है। यह केवल वर्णन करता है कि मान्य डेटा कैसा दिखता है।
• व्यावसायिक लॉजिक का विकल्प नहीं: Schema सत्यापन संरचनात्मक शुद्धता (प्रकार, प्रारूप, श्रेणी) की जाँच करता है। जटिल व्यावसायिक नियम (जैसे "उपयोगकर्ता अपनी शेष राशि से अधिक स्थानांतरित नहीं कर सकता") एप्लिकेशन कोड में हैं।
• डेटाबेस Schema नहीं: हालाँकि अवधारणात्मक रूप से समान, JSON Schema JSON दस्तावेज़ों को मान्य करता है, डेटाबेस टेबल को नहीं। हालाँकि, आप गहराई से रक्षा के लिए JSON Schema को डेटाबेस बाधाओं के साथ संयोजित कर सकते हैं।

JSON Schema संस्करण

JSON Schema कई ड्राफ्ट के माध्यम से विकसित हुआ है, प्रत्येक ने सुविधाएँ जोड़ी और शब्दावली को परिष्कृत किया। इन संस्करणों को समझने से आपको अपने प्रोजेक्ट के लिए सही संस्करण चुनने और संगतता समस्याओं से बचने में मदद मिलती है।

अपना पहला Schema लिखना

आइए एक सरल उदाहरण से शुरू करें: नाम, ईमेल और आयु वाले उपयोगकर्ता ऑब्जेक्ट के लिए एक Schema।

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://example.com/schemas/user.json",
    "title": "User",
    "description": "A user account in the system",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "The user's full name"
        },
        "email": {
            "type": "string",
            "format": "email",
            "description": "The user's email address"
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 150,
            "description": "The user's age in years"
        }
    },
    "required": ["name", "email"],
    "additionalProperties": false
}

यह Schema घोषित करता है कि एक मान्य उपयोगकर्ता एक ऑब्जेक्ट होना चाहिए जहाँ name और email आवश्यक स्ट्रिंग प्रॉपर्टीज़ हैं। age प्रॉपर्टी वैकल्पिक है, लेकिन यदि मौजूद है तो 0 और 150 के बीच पूर्णांक होना चाहिए। additionalProperties: false बाधा Schema में परिभाषित नहीं की गई किसी भी प्रॉपर्टी को रोकती है, जो टाइपो और अप्रत्याशित फ़ील्ड को पकड़ सकती है।

मुख्य कीवर्ड संदर्भ

JSON Schema बाधाओं को परिभाषित करने के लिए कीवर्ड की एक समृद्ध शब्दावली प्रदान करता है। यहाँ श्रेणी के अनुसार सबसे महत्वपूर्ण कीवर्ड हैं।

प्रकार कीवर्ड

संख्यात्मक बाधाएँ

स्ट्रिंग बाधाएँ

ऑब्जेक्ट बाधाएँ

ऐरे बाधाएँ

सामान्य Schema पैटर्न

वास्तविक दुनिया के Schema को अक्सर सरल प्रकार जाँच से परे पैटर्न की आवश्यकता होती है। यहाँ सबसे अधिक उपयोग किए जाने वाले पैटर्न हैं।

if/then/else के साथ सशर्त सत्यापन

प्रॉपर्टी मानों के आधार पर विभिन्न बाधाएँ लागू करने के लिए सशर्त लॉजिक का उपयोग करें। उदाहरण के लिए, भुगतान ऑब्जेक्ट को भुगतान विधि के आधार पर विभिन्न फ़ील्ड की आवश्यकता होती है।

{
    "type": "object",
    "properties": {
        "method": { "enum": ["credit_card", "bank_transfer"] },
        "card_number": { "type": "string" },
        "routing_number": { "type": "string" }
    },
    "required": ["method"],
    "if": {
        "properties": { "method": { "const": "credit_card" } }
    },
    "then": {
        "required": ["card_number"]
    },
    "else": {
        "required": ["routing_number"]
    }
}

allOf, anyOf, oneOf के साथ संयोजन

संयोजन कीवर्ड आपको शक्तिशाली तरीकों से Schema को संयोजित करने की अनुमति देते हैं:

• allOf: डेटा को सभी उप-Schema को संतुष्ट करना चाहिए। कई बाधाओं को संयोजित करने या पुन: प्रयोज्य Schema अंशों को मिलाने के लिए उपयोग किया जाता है।
• anyOf: डेटा को कम से कम एक उप-Schema को संतुष्ट करना चाहिए। यूनियन प्रकारों के लिए उपयोग किया जाता है जहाँ कई आकार स्वीकार्य हैं।
• oneOf: डेटा को ठीक एक उप-Schema को संतुष्ट करना चाहिए। पारस्परिक रूप से अनन्य विकल्पों के लिए उपयोग किया जाता है।

{
    "oneOf": [
        {
            "type": "object",
            "properties": {
                "type": { "const": "email" },
                "address": { "type": "string", "format": "email" }
            },
            "required": ["type", "address"]
        },
        {
            "type": "object",
            "properties": {
                "type": { "const": "phone" },
                "number": { "type": "string", "pattern": "^\\+?[1-9]\\d{1,14}$" }
            },
            "required": ["type", "number"]
        }
    ]
}

$ref के साथ Schema पुन: उपयोग

$ref कीवर्ड आपको Schema को संदर्भित और पुन: उपयोग करने की अनुमति देता है, दोहराव को समाप्त करता है और Schema को रखरखाव योग्य रखता है। आप उसी दस्तावेज़ के भीतर या बाहरी फ़ाइलों में Schema को संदर्भित कर सकते हैं।

{
    "$id": "https://example.com/schemas/order.json",
    "type": "object",
    "properties": {
        "customer": { "$ref": "#/$defs/address" },
        "shipping": { "$ref": "#/$defs/address" },
        "billing": { "$ref": "#/$defs/address" },
        "items": {
            "type": "array",
            "items": { "$ref": "#/$defs/lineItem" },
            "minItems": 1
        }
    },
    "required": ["customer", "items"],
    "$defs": {
        "address": {
            "type": "object",
            "properties": {
                "street": { "type": "string" },
                "city": { "type": "string" },
                "zip": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" },
                "country": { "type": "string", "minLength": 2, "maxLength": 2 }
            },
            "required": ["street", "city", "zip", "country"]
        },
        "lineItem": {
            "type": "object",
            "properties": {
                "product": { "type": "string" },
                "quantity": { "type": "integer", "minimum": 1 },
                "price": { "type": "number", "exclusiveMinimum": 0 }
            },
            "required": ["product", "quantity", "price"]
        }
    }
}

नल करने योग्य प्रकार

JSON Schema Draft 2020-12 में, नल करने योग्य प्रकारों को "null" शामिल करने वाले प्रकार ऐरे का उपयोग करके दर्शाया जाता है:

{
    "type": ["string", "null"],
    "description": "An optional display name, or null if not set"
}

पुराने ड्राफ्ट में, OpenAPI विनिर्देश ने nullable: true कीवर्ड का उपयोग किया था। मानक JSON Schema के लिए, हमेशा प्रकार ऐरे दृष्टिकोण का उपयोग करें।

प्रारूप सत्यापन

format कीवर्ड संरचनात्मक जाँच से परे सिमैंटिक सत्यापन प्रदान करता है। यह निर्दिष्ट करता है कि स्ट्रिंग को एक सुप्रसिद्ध प्रारूप के अनुरूप होना चाहिए। सामान्यतः समर्थित प्रारूपों में शामिल हैं:

प्रोग्रामेटिक रूप से JSON डेटा मान्य करना

Schema सत्यापन सबसे उपयोगी तब होता है जब एप्लिकेशन कोड में एकीकृत किया जाता है। यहाँ विभिन्न भाषाओं में लोकप्रिय लाइब्रेरी का उपयोग करने के उदाहरण हैं।

Ajv के साथ JavaScript

Ajv JavaScript में सबसे व्यापक रूप से उपयोग किया जाने वाला JSON Schema सत्यापनकर्ता है। यह सभी ड्राफ्ट संस्करणों का समर्थन करता है और Schema के JIT संकलन के माध्यम से उत्कृष्ट प्रदर्शन प्रदान करता है।

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv();
addFormats(ajv);

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

const validate = ajv.compile(schema);
const valid = validate({ name: 'Alice', email: 'alice@example.com', age: 30 });

if (!valid) {
    console.log(validate.errors);
    // [{ keyword: 'required', params: { missingProperty: 'email' }, ... }]
}

jsonschema के साथ Python

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"},
        "age": {"type": "integer", "minimum": 0}
    },
    "required": ["name", "email"],
    "additionalProperties": False
}

try:
    validate(instance={"name": "Alice", "email": "alice@example.com"}, schema=schema)
except ValidationError as e:
    print(f"Validation failed: {e.message}")

JSON Schema के साथ API डेटा सत्यापन

JSON Schema का सबसे मूल्यवान अनुप्रयोग API अनुरोध और प्रतिक्रिया डेटा को मान्य करना है। यह सुनिश्चित करता है कि आपका API सुव्यवस्थित इनपुट प्राप्त करता है और अपेक्षित प्रारूप में डेटा लौटाता है, त्रुटियों को जल्दी पकड़ता है और क्लाइंट्स को स्पष्ट त्रुटि संदेश प्रदान करता है।

Express.js मिडलवेयर

import Ajv from 'ajv';

const ajv = new Ajv({ allErrors: true });

function validateBody(schema) {
    const validate = ajv.compile(schema);
    return (req, res, next) => {
        if (!validate(req.body)) {
            return res.status(400).json({
                error: 'Validation failed',
                details: validate.errors
            });
        }
        next();
    };
}

app.post('/api/users',
    validateBody({
        type: 'object',
        properties: {
            name: { type: 'string', minLength: 1, maxLength: 100 },
            email: { type: 'string', format: 'email' },
            role: { enum: ['admin', 'editor', 'viewer'] }
        },
        required: ['name', 'email'],
        additionalProperties: false
    }),
    (req, res) => {
        // req.body is guaranteed valid here
        createUser(req.body);
    }
);

OpenAPI और JSON Schema

OpenAPI (पूर्व में Swagger) API अनुरोध और प्रतिक्रिया Schema को परिभाषित करने के लिए JSON Schema के एक उपसमुच्चय का उपयोग करता है। यदि आप पहले से OpenAPI का उपयोग कर रहे हैं, तो आप अपने API विनिर्देश से Schema निकाल सकते हैं और उन्हें रनटाइम सत्यापन के लिए उपयोग कर सकते हैं। openapi-schema-validator और express-openapi-validator जैसे उपकरण इस प्रक्रिया को स्वचालित कर सकते हैं, यह सुनिश्चित करते हुए कि आपके API दस्तावेज़ और सत्यापन लॉजिक हमेशा सिंक में रहें।

सर्वोत्तम अभ्यास

• हमेशा $schema सेट करें: अपने Schema द्वारा उपयोग किए जाने वाले ड्राफ्ट संस्करण की घोषणा करने के लिए $schema कीवर्ड शामिल करें। यह अस्पष्टता को रोकता है और सुनिश्चित करता है कि सत्यापनकर्ता आपके Schema की सही व्याख्या करें।
• Schema पहचान के लिए $id का उपयोग करें: $id कीवर्ड आपके Schema के लिए एक अद्वितीय पहचानकर्ता प्रदान करता है और $ref संदर्भों को हल करने के लिए आधार URI के रूप में कार्य करता है। स्थानीय Schema के लिए भी इसे हमेशा सेट करें।
• additionalProperties: false सेट करें: डिफ़ॉल्ट रूप से, JSON Schema ऑब्जेक्ट में किसी भी अतिरिक्त प्रॉपर्टी की अनुमति देता है। additionalProperties: false सेट करने से टाइपो और अप्रत्याशित फ़ील्ड पकड़े जाते हैं, आपके Schema को सख्त और API को अधिक पूर्वानुमेय बनाते हैं।
• पुन: प्रयोज्य घटकों के लिए $defs का उपयोग करें: $defs में सामान्य Schema परिभाषित करें और $ref का उपयोग करके उन्हें संदर्भित करें। यह दोहराव को कम करता है और Schema को बनाए रखना आसान बनाता है।
• विवरण जोड़ें: प्रत्येक प्रॉपर्टी और Schema में description फ़ील्ड होनी चाहिए। यह दस्तावेज़ीकरण के रूप में कार्य करता है और अन्य डेवलपर्स को प्रत्येक फ़ील्ड के उद्देश्य और बाधाओं को समझने में मदद करता है।
• सिस्टम सीमाओं पर मान्य करें: सिस्टम के किनारों पर Schema सत्यापन लागू करें: API एंडपॉइंट, संदेश उपभोक्ता, डेटा आयात पाइपलाइन और कॉन्फ़िगरेशन लोडर। अपने स्वयं के कोड द्वारा उत्पन्न और विश्वसनीय डेटा को मान्य न करें।
• सत्यापनकर्ता में सख्त मोड सक्षम करें: अज्ञात कीवर्ड को अस्वीकार करने, प्रारूप सत्यापन लागू करने और पहली त्रुटि पर रुकने के बजाय सभी त्रुटियों की रिपोर्ट करने के लिए सत्यापनकर्ता को कॉन्फ़िगर करें। यह एकल सत्यापन पास में अधिक समस्याएँ पकड़ता है।
• Schema को संस्करणित करें: $id URI में Schema संस्करण शामिल करें (जैसे https://example.com/schemas/user/v2.json)। यह आपको मौजूदा उपभोक्ताओं को तोड़े बिना Schema विकसित करने की अनुमति देता है।
• अपने Schema का परीक्षण करें: मान्य और अमान्य दोनों उदाहरणों के साथ अपने Schema के लिए यूनिट परीक्षण लिखें। यह सुनिश्चित करता है कि आपका Schema आपकी इच्छित बाधाओं को लागू करता है और Schema संशोधनों पर रिग्रेशन पकड़ता है।
• सिमैंटिक सत्यापन के लिए format का उपयोग करें: जटिल रेगेक्स पैटर्न के बजाय format: "email" को प्राथमिकता दें। प्रारूप अधिक पठनीय, अधिक रखरखाव योग्य हैं, और सत्यापनकर्ता लाइब्रेरी में अच्छी तरह से परीक्षित सत्यापन लॉजिक से लाभान्वित होते हैं।