JSON Schema जनरेटर

JSON Schema किस लिए है

JSON Schema एक JSON दस्तावेज़ कैसा दिखना चाहिए, इसका वर्णन करने का एक घोषणात्मक तरीक़ा है: इसकी कौन-सी प्रॉपर्टीज़ हैं, वे प्रॉपर्टीज़ कौन-से प्रकार रखती हैं, क्या आवश्यक है बनाम वैकल्पिक, और कौन-से मान वैध हैं। यह JSON-जगत का XML के लिए XSD या डेटाबेस तालिका परिभाषा का समकक्ष है। आधिकारिक प्रोजेक्ट json-schema.org पर है।

जहाँ आप इसे जंगल में मिलेंगे:

• API अनुबंध। OpenAPI 3.1 (फ़रवरी 2021 की रिलीज़) JSON Schema को सीधे एम्बेड करता है: एक आधुनिक API spec में हर अनुरोध-निकाय और प्रतिक्रिया-निकाय एक JSON Schema टुकड़े से वर्णित होता है।
• IDE ऑटोकंप्लीट और सत्यापन। VS Code का settings.json, आपकी प्रोजेक्ट का package.json और tsconfig.json, GitHub Actions workflow.yml फ़ाइलें सब प्रकाशित JSON Schemas के विरुद्ध ऑटोकंप्लीट और लिंट होते हैं।
• सर्वर-साइड सत्यापन। Express / Fastify / Spring / Flask / FastAPI / Echo सभी JSON Schema सत्यापकों (AJV, jsonschema, fastjsonschema) के साथ एकीकृत होते हैं ताकि व्यापार तर्क तक पहुँचने से पहले मालफॉर्म्ड अनुरोध निकायों को अस्वीकार किया जा सके।
• कोड जनरेशन। quicktype, json-schema-to-typescript, और datamodel-code-generator जैसे टूल एक schema को Go structs, TypeScript types, Python dataclasses, Java POJOs आदि में बदल देते हैं, एक स्रोत से भाषा-अज्ञेय types प्रदान करते हुए।
• दस्तावेज़ीकरण। एक schema आपके द्वारा प्रकाशित किसी भी JSON-आकार के डेटा के लिए मशीन-पठनीय दस्तावेज़ के रूप में भी काम करता है।

वे drafts जो आप जंगल में देखेंगे

JSON Schema की विशिष्टता drafts की एक श्रृंखला के रूप में प्रकाशित हुई है। वर्तमान स्थिर draft 2020-12 है (आधिकारिक spec पृष्ठ के अनुसार: «The current version is 2020-12»)। वे drafts जो आप मिल सकते हैं:

• Draft 4, पुराना पर अब भी उपयोग में; OpenAPI 3.0 ने JSON Schema Specification Wright Draft 00 (कभी-कभी अनौपचारिक रूप से Draft 5 कहा जाता है) के एक विस्तारित उपसमुच्चय का उपयोग किया, जो Draft 4 के क़रीब है पर समान नहीं।
• Draft 6, Draft 7, Draft 7 (2018) वर्षों तक प्रबल उत्पादन draft था और लीगेसी टूलिंग में अब भी बहुत आम है।
• Draft 2019-09, year-month identifier convention का उपयोग करने वाला पहला draft; लीगेसी definitions कीवर्ड के साथ $defs को पेश किया।
• Draft 2020-12, वर्तमान स्थिर draft और यह जो जनरेटर निकालता है। OpenAPI 3.1 के साथ संरेखित।

संदेह में, वह draft चुनें जो आपके सत्यापक से मेल खाए। AJV (सबसे लोकप्रिय JavaScript सत्यापक) स्पष्ट opt-in के साथ Drafts 04, 06, 07, 2019-09, और 2020-12 का समर्थन करता है। Python में jsonschema भी ऐसा ही करता है। यदि आप नहीं जानते कि आपका डाउनस्ट्रीम उपभोक्ता क्या चाहता है, तो 2020-12 नए कार्य के लिए एक सुरक्षित डिफ़ॉल्ट है।

बिल्ट-इन प्रकार

JSON Schema JSON के मान-प्रकारों के अनुरूप सात आधार प्रकार वर्णित करता है:

रचना कीवर्ड आपको मिक्स-एंड-मैच की अनुमति देते हैं: oneOf (ठीक एक), anyOf (कम से कम एक), allOf (हर एक), not (विपरीत)। साथ ही enum अनुमत मानों की एक सीमित सूची के लिए और const एकल निश्चित मान के लिए।

एक स्वतः-उत्पन्न schema आपको क्या बता सकता है और क्या नहीं

एकल JSON उदाहरण से schema का अनुमान शक्तिशाली पर सीमित है। जनरेटर पता लगा सकता है:

• हर पत्ती मान का प्रकार (string vs number vs boolean vs array vs object)।
• नेस्टेड ऑब्जेक्ट और एरे की संरचना।
• उदाहरण में आने वाली कुंजियाँ (और यदि आप opt in करें तो उन्हें required चिह्नित करें)।

यह नहीं पता लगा सकता:

• वैकल्पिक फ़ील्ड। आपके उदाहरण की एक कुंजी असल spec में वैकल्पिक हो सकती है, पर एक ही उदाहरण आपको नहीं बता सकता कौन-सी। डिफ़ॉल्ट रूप से सब कुछ आवश्यक दिखता है।
• प्रारूप संकेत। स्ट्रिंग "2024-04-12" एक तारीख़ जैसी दिखती है, पर वह एक मुक्त-पाठ लेबल भी हो सकती है जो संयोग से तारीख़-आकार लगती है। अगर फ़ील्ड वाक़ई तारीख़ है तो हाथ से format: date जोड़ें।
• सत्यापन बाधाएँ। अधिकतम लंबाई, अनुमत enum मान, regex पैटर्न: सभी को मानवीय इनपुट चाहिए।
• दस्तावेज़ीकरण स्ट्रिंग्स। हर फ़ील्ड पर title, description, और examples डेवलपर अनुभव बेहतर बनाते हैं पर curation की ज़रूरत है।
• वैरिएंट। यदि कोई फ़ील्ड संदर्भ के आधार पर या तो string या number हो सकती है, तो एकल उदाहरण एक चुनेगा और दूसरा छूट जाएगा। कई उदाहरण मिलाएँ या मैन्युअल रूप से oneOf का उपयोग करें।

आउटपुट को 70%-पूर्ण शुरुआती बिंदु के रूप में मानें। मूल्यवान जोड़ (कौन-से फ़ील्ड वास्तव में आवश्यक हैं, कौन-से स्ट्रिंग प्रारूप लागू होते हैं, कौन-सी मान सीमाएँ अनुमत हैं, हर फ़ील्ड का क्या मतलब है) मानवीय-curation का चरण है।

जानने योग्य दो सूक्ष्म जाल

• 2020-12 में format डिफ़ॉल्ट रूप से सलाहकार है। format-annotation शब्दावली format: email को एक संकेत के रूप में चिह्नित करती है, सख़्त सत्यापन नियम के रूप में नहीं, जब तक आपका सत्यापक स्पष्ट रूप से format-assertion में opt-in न करे। तो email regex से न मेल खाने वाली स्ट्रिंग भी डिफ़ॉल्ट रूप से पास हो जाती है। AJV का strict मोड और ajv-formats पैकेज पूर्ण प्रारूप सत्यापन जोड़ते हैं; सुरक्षा-संवेदनशील इनपुट के लिए प्रारूप जाँच पर निर्भर होने से पहले अपने सत्यापक के डिफ़ॉल्ट जाँचें।
• additionalProperties: false allOf के साथ अच्छा सहयोग नहीं करता। यदि आप विरासत-शैली सत्यापन के लिए allOf के साथ schemas रचते हैं, एक शाखा पर additionalProperties: false भाई शाखाओं में परिभाषित प्रॉपर्टीज़ नहीं देखता, इसलिए वैध फ़ील्ड सत्यापन में विफल हो जाते हैं। Draft 2019-09+ में फ़िक्स है unevaluatedProperties: false, जो रचना-जागरूक है।

JSON Schema vs Zod / Joi / Yup vs TypeScript टाइप्स

कई तकनीकें JSON Schema की भूमिका से ओवरलैप करती हैं; प्रत्येक का अलग स्वीट स्पॉट है:

• JSON Schema। घोषणात्मक JSON, रनटाइम सत्यापन, भाषा-अज्ञेय। तब जीतता है जब API अनुबंध भाषाई सीमाओं को पार करते हैं (उदाहरण के लिए एक Go सर्वर, एक Python डेटा पाइपलाइन और एक TypeScript फ्रंटेंड एक ही API का उपभोग करते हुए)।
• TypeScript टाइप्स। केवल कंपाइल-समय। एक TS कोडबेस के अंदर इन-प्रोसेस टाइप सुरक्षा के लिए सुंदर पर वे रनटाइम पर ग़ायब हो जाते हैं, आने वाले JSON का कोई सत्यापन प्रदान नहीं करते। json-schema-to-typescript जैसे टूल एक schema से types उत्पन्न करते हैं दोनों दुनिया का सबसे अच्छा प्राप्त करने के लिए।
• Zod / Joi / Yup। JavaScript / TypeScript में कोड-फ़र्स्ट रनटाइम सत्यापन, बेक-इन TypeScript inference के साथ। एकल भाषा, पर उस भाषा के अंदर उत्कृष्ट डेवलपर अनुभव। Schema JS ऑब्जेक्ट हैं, पोर्टेबल JSON नहीं।
• Pydantic / Marshmallow। Python के समकक्ष: Python type hints के साथ class-आधारित रनटाइम सत्यापन।

यदि आपके schema को कई भाषाओं द्वारा या टूलों (IDE, OpenAPI टूलिंग, कोड जेनरेटर) द्वारा उपभोग करना है, तो JSON Schema सही घर है। यदि आप एक भाषा के अंदर रहते हैं, तो भाषा-नेटिव विकल्प आम तौर पर लिखने में अच्छा होता है।

सामान्य उपयोग मामले

• एक OpenAPI spec को बूटस्ट्रैप करना। एक वास्तविक API प्रतिक्रिया चिपकाएँ, schema उत्पन्न करें, इसे अपने components.schemas में डालें।
• TypeScript / Go / Python types उत्पन्न करना quicktype या समान के माध्यम से, एक स्रोत से भाषा-अज्ञेय types प्रदान करते हुए।
• अविश्वसनीय इनपुट सत्यापित करना AJV / jsonschema / Pydantic के साथ सर्वर एंडपॉइंट पर।
• एक कस्टम कॉन्फ़िग प्रारूप के लिए IDE ऑटोकंप्लीट लिखना। VS Code, JetBrains IDE और अन्य JSON-फ़ाइल ऑटोकंप्लीट को पावर देने के लिए JSON Schemas पढ़ते हैं।
• एक कॉन्फ़िगरेशन फ़ाइल के आकार का दस्तावेज़ीकरण डाउनस्ट्रीम उपभोक्ताओं के लिए।
• डेटा प्रारूपों के बीच माइग्रेट करना। एक स्रोत से उत्पन्न JSON Schema डाउनस्ट्रीम सत्यापन, परिवर्तन या दस्तावेज़ीकरण को संचालित कर सकता है।

सामान्य ग़लतियाँ

1. स्वतः-उत्पन्न schema को अंतिम spec मानना। यह एक शुरुआती बिंदु है। प्रारूप संकेत जोड़ें, सच में-वैकल्पिक फ़ील्ड चिह्नित करें, दस्तावेज़ीकरण जोड़ें, मान सीमाएँ निर्धारित करें।
2. $schema घोषणा गुम। सत्यापक इसका उपयोग जानने के लिए करते हैं कि कौन-सा draft लागू करें। इसे हमेशा schema के शीर्ष पर शामिल करें।
3. required को प्रति-प्रॉपर्टी विशेषता के रूप में मानना। XSD या Mongoose schemas के विपरीत, JSON Schema का required मूल ऑब्जेक्ट स्तर पर एक array है जो आवश्यक प्रॉपर्टीज़ के नाम सूचीबद्ध करता है।
4. जब आप सख़्त सत्यापन चाहते हैं तो additionalProperties: false भूलना। डिफ़ॉल्ट true है, यानी अज्ञात कुंजियाँ चुपचाप अनुमत होती हैं।
5. enum को examples के साथ भ्रमित करना। enum = अनुमत मानों की सूची (सत्यापन)। examples = केवल दस्तावेज़ीकरण के लिए नमूना मान (कोई सत्यापन प्रभाव नहीं)।
6. यह मानना कि format लागू किया जाता है। Draft 2020-12 में डिफ़ॉल्ट रूप से यह एक एनोटेशन है, अभिकथन नहीं; आपका email regex तब तक नहीं चलेगा जब तक आप opt in न करें।
7. एकल उदाहरण से वैकल्पिकता का अनुमान लगाना। आपके उदाहरण की हर कुंजी डिफ़ॉल्ट रूप से required बन जाती है। वास्तविक specs में लगभग हमेशा वैकल्पिक फ़ील्ड होते हैं; उन्हें curation के हिस्से के रूप में required array से हटाएँ।

अधिक अक्सर पूछे जाने वाले प्रश्न

क्या schema OpenAPI 3.1 के साथ काम करेगा?

हाँ। OpenAPI 3.1 (फ़रवरी 2021 में जारी) ने अपनी schema भाषा को JSON Schema Draft 2020-12 के साथ पूरी तरह संरेखित किया, जो यह जनरेटर निकालता है। schema को अपने OpenAPI दस्तावेज़ में components.schemas में डालें और $ref के माध्यम से इसे संदर्भित करें। पुराना OpenAPI 3.0 पहले के उपसमुच्चय का उपयोग करता था; यदि आप 3.0 लक्षित कर रहे हैं तो आपको समायोजित करने की आवश्यकता हो सकती है।

क्या मैं इस schema से अपनी भाषा में types उत्पन्न कर सकता हूँ?

हाँ। quicktype एक JSON Schema से TypeScript, Go, Python, Java, C#, Swift, Kotlin, Rust, Elm, और अन्य उत्पन्न करता है। json-schema-to-typescript एक JS-विशिष्ट विकल्प है। अधिकांश आधुनिक भाषाओं में कम से कम एक schema-to-types टूल है; उत्पन्न schema उन सभी के लिए इनपुट के रूप में काम करता है।

$defs और definitions में क्या अंतर है?

दोनों पुनः उपयोग करने योग्य उप-schemas रखने के स्थान हैं जिन्हें आप दस्तावेज़ में अन्यत्र $ref कर सकते हैं। definitions लीगेसी नाम है, जो Drafts 04, 06, और 07 में उपयोग किया गया। $defs वर्तमान नाम है, Draft 2019-09 में पेश किया गया और 2020-12 में जारी रहा। कार्यात्मक रूप से समतुल्य, पर नए कार्य के लिए $defs का उपयोग करें।

क्या मेरा JSON कहीं भेजा जाता है?

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

मेरे array के schema ने केवल पहला तत्व क्यों वर्णित किया?

एकल उदाहरण से अनुमान arrays को सजातीय मानता है: यह पहला तत्व देखता है और मानता है कि बाकी मेल खाता है। यदि आपका वास्तविक array विभिन्न आकार रख सकता है, तो आपको items को हाथ से { "oneOf": [...] } के रूप में लिखना होगा। या प्रत्येक वैरिएंट पर अलग-अलग जनरेटर चलाएँ और schemas को संयोजित करें।

क्या मुझे जनरेटर का उपयोग करना चाहिए, या schema हाथ से लिखना चाहिए?

एक छोटे schema के लिए जिसे आप अंत-से-अंत तक नियंत्रित करते हैं, हाथ से लिखना आपको spec तेज़ी से सिखाता है। दर्जनों नेस्टेड ऑब्जेक्ट वाली बड़ी API प्रतिक्रिया के लिए, उत्पन्न करना आपको सेकंडों में एक मसौदा देता है और आप बचाया गया समय बाधाओं, विवरणों और required arrays को curate करने में बिताते हैं। अधिकांश सक्रिय डेवलपर दोनों करते हैं: उत्पन्न करें, फिर curate करें।