इस लेख में
JSON Schema क्या है?
JSON Schema, JSON दस्तावेज़ों को एनोटेट और वैलिडेट करने की एक शब्दावली है। यह उस संरचना, प्रकार और बाधाओं को परिभाषित करती है जिन्हें किसी JSON दस्तावेज़ को पूरा करना ज़रूरी है। इसे एक अनुबंध की तरह समझें — schema यह बताता है कि मान्य डेटा कैसा दिखता है, और वैलिडेटर जाँचते हैं कि कोई दस्तावेज़ उस अनुबंध के अनुरूप है या नहीं।
JSON Schema स्वयं JSON में लिखा जाता है, जिससे यह मशीन-पठनीय और भाषा-निरपेक्ष बन जाता है। इसे हर प्रमुख प्रोग्रामिंग भाषा (JavaScript/Ajv, Python/jsonschema, Java/everit, Go/gojsonschema) के वैलिडेटर समर्थन देते हैं और इसका उपयोग API वैलिडेशन, कॉन्फ़िगरेशन फ़ाइलों और फ़ॉर्म जेनरेशन के लिए किया जाता है।
JSON Schema की मूल बातें
मुख्य कीवर्ड मान्य JSON दस्तावेज़ों के आकार को परिभाषित करते हैं।
- type — अनुमत JSON प्रकार निर्दिष्ट करता है: string, number, integer, boolean, object, array, या null। यह सबसे बुनियादी बाधा है।
- properties और required — ऑब्जेक्ट के लिए, 'properties' हर फ़ील्ड का schema परिभाषित करता है और 'required' सूचीबद्ध करता है कि कौन-से फ़ील्ड मौजूद होने चाहिए। जो फ़ील्ड 'required' में नहीं हैं, वे डिफ़ॉल्ट रूप से वैकल्पिक होते हैं।
- enum और const — 'enum' किसी मान को विकल्पों के एक निश्चित समूह तक सीमित करता है, जबकि 'const' उसे एक ही सटीक मान तक सीमित करता है। यह status फ़ील्ड, श्रेणियों और कॉन्फ़िगरेशन विकल्पों के लिए उपयोगी है।
- pattern और format — 'pattern' किसी स्ट्रिंग को रेगुलर एक्सप्रेशन के विरुद्ध वैलिडेट करता है। 'format' रेगेक्स के बिना 'email', 'uri', 'date-time' और 'ipv4' जैसा अर्थपूर्ण वैलिडेशन प्रदान करता है।
ये बुनियादी कीवर्ड अधिकांश वैलिडेशन ज़रूरतों को कवर करते हैं। एक साधारण schema किसी ऑब्जेक्ट प्रकार को परिभाषित कर सकता है जिसमें आवश्यक 'name' (string) और वैकल्पिक 'age' (integer, न्यूनतम 0) प्रॉपर्टीज़ हों।
उन्नत Schema सुविधाएँ
जटिल वैलिडेशन आवश्यकताओं के लिए, JSON Schema कंपोज़िशन, संदर्भ और सशर्त लॉजिक प्रदान करता है।
- $ref संदर्भ — schema परिभाषाओं को $ref से संदर्भित करके पुनः उपयोग करें। उसी दस्तावेज़ के भीतर परिभाषाओं की ओर इंगित करें ($ref: #/$defs/Address) या बाहरी फ़ाइलों की ओर। यह बड़े schema में दोहराव को समाप्त करता है।
- allOf / anyOf / oneOf — कंपोज़िशन कीवर्ड जो कई schema को जोड़ते हैं। 'allOf' के लिए सभी उप-schema का मेल होना ज़रूरी है, 'anyOf' के लिए कम से कम एक का, और 'oneOf' के लिए ठीक एक का। यह बहुरूपी प्रकारों के लिए उपयोगी है।
- if / then / else — सशर्त schema जो डेटा मानों के आधार पर अलग-अलग वैलिडेशन नियम लागू करते हैं। उदाहरण के लिए, यदि country 'US' है तो zip code को 5-अंकीय पैटर्न से मेल खाना चाहिए, अन्यथा किसी भी फ़ॉर्मेट की अनुमति है।
- additionalProperties — यह नियंत्रित करता है कि कोई ऑब्जेक्ट 'properties' में सूचीबद्ध न किए गए प्रॉपर्टीज़ रख सकता है या नहीं। सख़्त वैलिडेशन के लिए इसे false पर सेट करें या अतिरिक्त प्रॉपर्टीज़ को सीमित करने के लिए किसी schema पर।
निःशुल्क आज़माएँ — कोई साइनअप आवश्यक नहीं
JSON Schema वैलिडेट करें →Schema ड्राफ़्ट संस्करण
JSON Schema कई ड्राफ़्ट संस्करणों से गुज़रकर विकसित हुआ है, जिनमें से हर एक ने नई सुविधाएँ जोड़ीं और मौजूदा व्यवहार को परिष्कृत किया।
- Draft-04 — पहला व्यापक रूप से अपनाया गया संस्करण। इसने $ref, ऐरे के रूप में required, और बुनियादी वैलिडेशन कीवर्ड पेश किए। यह अब भी कई पुराने सिस्टम और OpenAPI 3.0 में इस्तेमाल होता है।
- Draft-06 — const कीवर्ड, propertyNames, ऐरे के लिए contains, और बूलियन schema (मान्य schema के रूप में true/false) जोड़े। छोटे लेकिन उपयोगी संवर्धन।
- Draft-07 — if/then/else सशर्त लॉजिक, readOnly/writeOnly एनोटेशन, और कंटेंट एन्कोडिंग कीवर्ड जोड़े। आज सबसे लोकप्रिय ड्राफ़्ट संस्करण।
- 2019-09 (Draft 2019-09) — बड़ा पुनर्गठन। $defs (definitions की जगह), $anchor, unevaluatedProperties, और शब्दावली प्रणाली पेश की। बड़े पैमाने के schema डिज़ाइन के लिए बेहतर।
- 2020-12 (Draft 2020-12) — नवीनतम स्थिर ड्राफ़्ट। इसने डायनामिक संदर्भों को परिष्कृत किया, ट्यूपल वैलिडेशन के लिए prefixItems जोड़ा (ऐरे के रूप में items की जगह), और आउटपुट फ़ॉर्मेट में सुधार किया। नई परियोजनाओं के लिए अनुशंसित।
आम उपयोग के मामले
JSON Schema का उपयोग वहाँ किया जाता है जहाँ भी JSON डेटा को वैलिडेट या दस्तावेज़ीकृत करने की ज़रूरत हो।
- API वैलिडेशन — Express/Fastify मिडलवेयर में request बॉडी और query पैरामीटर को schema के विरुद्ध वैलिडेट करें। OpenAPI/Swagger विनिर्देश API अनुबंध परिभाषा के लिए JSON Schema को अपने भीतर समाहित करते हैं।
- कॉन्फ़िगरेशन वैलिडेशन — स्टार्टअप के समय एप्लिकेशन कॉन्फ़िग फ़ाइलों (JSON, JSON में परिवर्तित YAML) को वैलिडेट करें। रनटाइम त्रुटियाँ पैदा करने से पहले ही टाइपो और गुम फ़ील्ड पकड़ें।
- फ़ॉर्म जेनरेशन — react-jsonschema-form और vue-jsonschema-form जैसे टूल, JSON Schema परिभाषाओं से HTML फ़ॉर्म अपने-आप बनाते हैं, जिनमें वैलिडेशन नियम और UI विजेट शामिल होते हैं।
- कोड जेनरेशन — JSON Schema परिभाषाओं से TypeScript इंटरफ़ेस, Go struct या Python dataclass बनाएँ। यह प्रकारों को API अनुबंधों के साथ समकालिक रखता है।
आम वैलिडेशन त्रुटियाँ
किसी schema के विरुद्ध JSON वैलिडेट करते समय, ये सबसे बार-बार आने वाली त्रुटियाँ हैं जिनका आप सामना करेंगे।
- प्रकार बेमेल — मान का प्रकार schema की 'type' बाधा से मेल नहीं खाता। आम उदाहरण: जहाँ number अपेक्षित हो वहाँ string, किसी non-nullable फ़ील्ड के लिए null, या जहाँ array ज़रूरी हो वहाँ object।
- गुम आवश्यक फ़ील्ड — JSON ऑब्जेक्ट में 'required' ऐरे में सूचीबद्ध कोई प्रॉपर्टी नहीं है। वैलिडेटर बताते हैं कि कौन-सा विशिष्ट फ़ील्ड गुम है।
- पैटर्न विफलता — कोई स्ट्रिंग मान 'pattern' रेगेक्स से मेल नहीं खाता। यह अक्सर अमान्य email फ़ॉर्मेट, फ़ोन नंबर, या अपेक्षित पैटर्न का पालन न करने वाले कस्टम पहचानकर्ताओं को पकड़ता है।
- $ref समाधान विफलता — schema $ref के ज़रिए किसी अन्य schema को संदर्भित करता है जो नहीं मिलता। यह तब होता है जब कोई $defs प्रविष्टि गुम हो, पथ ग़लत हो, या बाहरी schema फ़ाइलें सुलभ न हों।
अक्सर पूछे जाने वाले सवाल
नई परियोजनाओं के लिए मुझे कौन-सा JSON Schema ड्राफ़्ट इस्तेमाल करना चाहिए?
जब तक कोई बाधा न हो, नई परियोजनाओं के लिए Draft 2020-12 का उपयोग करें। इसमें सबसे अधिक सुविधाएँ (ट्यूपल के लिए prefixItems, unevaluatedProperties, डायनामिक संदर्भ) और सर्वोत्तम विनिर्देश गुणवत्ता है। यदि आपको OpenAPI 3.0 संगतता चाहिए, तो Draft-04 का उपयोग करें। यदि आपको सबसे व्यापक लाइब्रेरी समर्थन चाहिए, तो Draft-07 सबसे सुरक्षित विकल्प है — लगभग हर वैलिडेटर इसका समर्थन करता है।
मैं कई फ़ाइलों में schema का पुनः उपयोग कैसे करूँ?
schema को URI से संदर्भित करने के लिए $ref का उपयोग करें। स्थानीय परिभाषाओं के लिए, पुनः उपयोग योग्य schema को उसी फ़ाइल में $defs के नीचे रखें और उन्हें $ref: '#/$defs/SchemaName' से संदर्भित करें। क्रॉस-फ़ाइल संदर्भों के लिए, सापेक्ष URI ($ref: './address.json') या पूर्ण URI का उपयोग करें। अधिकांश वैलिडेटर स्थानीय और दूरस्थ, दोनों तरह के $ref समाधान का समर्थन करते हैं।
क्या JSON Schema नेस्टेड ऑब्जेक्ट को वैलिडेट कर सकता है?
हाँ। नेस्टेड schema को पैरेंट ऑब्जेक्ट की 'properties' में परिभाषित करें। हर नेस्टेड प्रॉपर्टी का अपना प्रकार, आवश्यक फ़ील्ड और वैलिडेशन नियम हो सकते हैं। गहराई से नेस्टेड संरचनाओं के लिए, schema को पठनीय रखने हेतु $ref का उपयोग करें। नेस्टिंग गहराई की कोई सीमा नहीं है — वैलिडेटर हर स्तर को रिकर्सिव तरीके से वैलिडेट करता है।