API स्कीमा वैलिडेशन

Q: क्या schema fields के बीच के rules जाँच सकता है?

कुछ हद तक। dependentRequired कह सकता है "अगर refundId मौजूद है तो refundedAt भी होना चाहिए", और if/then/else कह सकते हैं "जब status cancelled हो, तो cancelledAt required है"। Schema दो values की तुलना या calculation नहीं कर सकता, इसलिए "total items के जोड़ के बराबर है" या "end date start date के बाद है" जैसे rules value assertions ही रहते हैं।

Mutqan Soft QA टीम द्वारा · अपडेट 6 अक्टूबर 2026 · 18 मिनट · मध्यम

API schema validation किसी response को एक schema के विरुद्ध जाँचता है: यह उस structure का machine-readable विवरण है जो response में होना चाहिए — कौन-से fields मौजूद और required हैं, हर value का type क्या है, कौन-सी values और formats allowed हैं, और क्या दूसरे fields आ सकते हैं। JSON APIs में schema JSON Schema में लिखा जाता है और आम तौर पर API के OpenAPI document के अंदर रहता है।

उदाहरण के लिए, order schema कहता है कि total एक number है। अगर API "total": "149.50" यानी एक string लौटाता है, तो validator $.total पर keyword type से violation रिपोर्ट करता है, जबकि किसी ने उस field के लिए assertion नहीं लिखा। Response validation में fields एक-एक assertion से जाँचे गए थे; schema हर response का पूरा structure एक ही step में जाँचता है।

यह क्यों ज़रूरी है

Clients documented structure के हिसाब से बनाए जाते हैं। जो field अपना type बदल दे, ग़ायब हो जाए, null बन जाए या जिसका नाम बदल जाए, वह mobile app को crash कर सकता है या किसी report को चुपचाप बिगाड़ सकता है, जबकि status अब भी 200 OK होता है। ऐसे defects आँख से आसानी से छूट जाते हैं और अक्सर कई endpoints पर एक साथ असर डालते हैं, जैसे server के data serialise करने, यानी objects को JSON में बदलने, का तरीका बदलने के बाद।

Tester के लिए schema एक partial test oracle है — expected results का एक source — जो API description के साथ ही मिलता है। एक check दर्जनों fields cover करता है, internal data expose करने वाले undocumented fields पकड़ता है, और हर regression run को structure की जाँच बना देता है। Schema review करना सही सवाल जल्दी पूछने पर भी मजबूर करता है: optional या nullable, कौन-सी values, क्या API नए fields जोड़ सकता है?

JSON Schema पढ़ना: वे keywords जो ज़्यादातर काम करते हैं

JSON Schema ख़ुद एक JSON document है। हर keyword एक rule है जिसे validator response के matching हिस्से पर लागू करता है। $schema बताता है कि schema किस draft को follow करता है — मौजूदा draft 2020-12 है — क्योंकि अलग-अलग drafts में validators का व्यवहार थोड़ा अलग होता है।

नीचे वाला schema GET /orders/{orderId} के body का वर्णन करता है और उन्हीं keywords से बना है जो ज़्यादातर schemas इस्तेमाल करते हैं:

type: object, array, string, number, integer, boolean या null। ["string", "null"] जैसी list दोनों में से कोई भी allow करती है।
required: वे fields जिनका मौजूद होना ज़रूरी है; जो field सिर्फ़ properties में लिखा है, वह optional है। यह value नहीं, मौजूदगी जाँचता है: "couponCode": null मौजूद माना जाता है।
properties: हर नाम वाले field का rule, जो तभी लागू होता है जब field मौजूद हो। items यही काम array के हर element के लिए करता है।
enum, pattern, minimum, maxLength जैसे keywords: allowed values, text patterns और limits। enum exact और case-sensitive match है। pattern एक regular expression है: ^ORD-[0-9]+$ का मतलब है "ORD- से शुरू, फिर एक या ज़्यादा digits, फिर अंत"। ^ और $ के बिना यह text में कहीं भी match कर सकता है, इसलिए x-ORD-1-y भी pass हो जाएगा।
format: date-time या email जैसा नाम वाला format। Validators इसे सिर्फ़ annotation मान सकते हैं, और draft 2020-12 में यही default है, इसलिए जाँच लें कि आपका validator ग़लत value को सच में reject करता है।
additionalProperties: क्या properties में न लिखे fields आ सकते हैं। यह न हो तो हर extra field accept होता है; false उन्हें reject करता है।

Order schema, एक-एक keyword: required सिर्फ़ मौजूदगी माँगता है, additionalProperties: false undocumented fields reject करता है, और format तभी गिना जाता है जब validator उसे assert करे।

GET /orders/{orderId} का JSON Schema

{
  भाग 1:1"$schema": "https://json-schema.org/draft/2020-12/schema",
  भाग 2:2"type": "object",
  भाग 3:3"required": ["id", "status", "total", "createdAt", "items"],
  भाग 4:4"properties": {
    "id": { "type": "string", भाग 5:5"pattern": "^ORD-[0-9]+$" },
    "status": { भाग 6:6"enum": ["pending", "paid", "shipped", "cancelled"] },
    "total": { "type": "number", "minimum": 0 },
    "createdAt": { "type": "string", भाग 7:7"format": "date-time" },
    "couponCode": { भाग 8:8"type": ["string", "null"] },
    "items": {
      "type": "array",
      भाग 9:9"minItems": 1,
      "items": {
        "type": "object",
        "required": ["sku", "qty", "price"],
        "properties": {
          "sku": { "type": "string" },
          "qty": { "type": "integer", "minimum": 1 },
          "price": { "type": "number", "minimum": 0 }
        }
      }
    }
  },
  भाग 10:10"additionalProperties": false
}

1$schema: draft, यहाँ 2020-12अलग-अलग drafts में validators थोड़ा अलग चलते हैं
2type: body एक JSON object होना चाहिएTop level पर array, string या null fail होता है
3required: ये पाँच fields मौजूद होने चाहिएसिर्फ़ मौजूदगी: null value वाला field मौजूद माना जाता है
4properties: हर नाम वाले field का एक ruleतभी लागू जब field मौजूद हो
5pattern: id को regular expression से match करना होगा^ और $ के बिना anchored नहीं होता
6enum: status की सिर्फ़ ये चार valuesExact और case-sensitive: "Shipped" fail होता है
7format: RFC 3339 date और time2020-12 में default रूप से annotation: जाँचें कि आपका validator इसे assert करता है
8Optional और nullable: couponCoderequired में नहीं, और null allowed type है
9minItems: कम से कम एक line itemइसके बिना खाली list हर items rule में pass होती है
10additionalProperties: कोई undocumented field नहींइसके बिना हर extra field accept होता है

पाठ संस्करण

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "status", "total", "createdAt", "items"],
  "properties": {
    "id": { "type": "string", "pattern": "^ORD-[0-9]+$" },
    "status": { "enum": ["pending", "paid", "shipped", "cancelled"] },
    "total": { "type": "number", "minimum": 0 },
    "createdAt": { "type": "string", "format": "date-time" },
    "couponCode": { "type": ["string", "null"] },
    "items": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["sku", "qty", "price"],
        "properties": {
          "sku": { "type": "string" },
          "qty": { "type": "integer", "minimum": 1 },
          "price": { "type": "number", "minimum": 0 }
        }
      }
    }
  },
  "additionalProperties": false
}

आज़माएँ: JSON Schema वैलिडेटर

Schema कहाँ रहता है: OpenAPI

OpenAPI document, जो YAML या JSON में लिखा जाता है, पूरे HTTP API का वर्णन करता है: paths, methods, parameters, request bodies और हर status code के लिए हर media type का response body। Bodies को schemas से describe किया जाता है, जो अक्सर components/schemas के नीचे एक बार define होकर $ref से दोबारा इस्तेमाल होते हैं। Validator path, method, status code और media type से schema चुनता है, इसलिए 404 को error schema से जाँचा जाता है, order schema से नहीं।

Version मायने रखता है। OpenAPI 3.1 और 3.2 JSON Schema 2020-12 इस्तेमाल करते हैं, साथ में कुछ OpenAPI-only keywords। OpenAPI 3.0 एक पुराने draft का extended subset इस्तेमाल करता है: उसमें type सिर्फ़ एक value लेता है, और nullable field type list की जगह nullable: true से लिखा जाता है। किसी validator के results पर भरोसा करने से पहले ऊपर वाली openapi line देख लें।

openapi: 3.1.0
info: { title: Orders API, version: 1.0.0 }
paths:
  /orders/{orderId}:
    get:
      parameters:
        - { name: orderId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: The order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: No order with this id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Order:
      type: object
      required: [id, status, total, createdAt, items]
      additionalProperties: false
      properties:
        id: { type: string, pattern: '^ORD-[0-9]+$' }
        status: { enum: [pending, paid, shipped, cancelled] }
        couponCode: { type: [string, 'null'] }
        # ...बाकी properties, बिल्कुल ऊपर वाले JSON Schema की तरह
    Error:
      type: object
      required: [code, message]
      properties:
        code: { type: string }
        message: { type: string }

आज़माएँ: OpenAPI व्यूअर आज़माएँ: OpenAPI वैलिडेटर

Worked example: 200 OK लौटाने वाला एक order

Tester GET /orders/ORD-1042 call करता है और उसे 200 OK मिलता है; body इस section के आख़िर में दिखाई गई है। Status check pass होता है और पहली नज़र में कुछ भी टूटा हुआ नहीं लगता।

Order schema के विरुद्ध validate करने पर body में पाँच violations मिलते हैं, हर एक response की एक location और उसे reject करने वाला keyword, और एक ध्यान देने लायक pass:

$.status, enum: "Shipped" allowed नहीं है। Documented value shipped है, और strings को exact compare करने वाला client इसे नहीं पहचानेगा।
$.total, type: जहाँ number चाहिए वहाँ string है। Totals जोड़ने वाला client text को आपस में चिपका सकता है या fail हो सकता है।
$.createdAt, format: यह RFC 3339 date-time नहीं है — न T separator, न seconds, न offset। यह तभी रिपोर्ट होता है जब validator formats assert करता हो।
$.items[0], required: line item में price नहीं है।
$.internalNote, additionalProperties: ऐसा field जिसकी contract अनुमति नहीं देता, यहाँ internal data। OWASP API Security Top 10 (2023) ऐसी properties के exposure को API3, Broken Object Property Level Authorization, में रखता है।
couponCode की value null है और यह pass होता है: यह optional है और इसका type null allow करता है।

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "ORD-1042",
  "status": "Shipped",
  "total": "149.50",
  "createdAt": "2026-09-14 10:32",
  "couponCode": null,
  "items": [
    { "sku": "BK-201", "qty": 2 }
  ],
  "internalNote": "VIP customer, call before delivery"
}

आज़माएँ: API स्कीमा वैलिडेटर

Schema validation आपको क्या नहीं बता सकता

Schema valid data का आकार बताता है, यह नहीं कि data सही है। ऊपर के सारे violations ठीक कर दें, फिर भी response ग़लत हो सकता है: "total": 159.50 और 74.75 वाले दो items की एक line के साथ schema pass हो जाता है, जबकि items का जोड़ 149.50 है। Pass होने वाले check का मतलब बस इतना है कि response document के उस version के हिसाब से structurally valid है।

इन चीज़ों के लिए दूसरे checks चाहिए:

Values और calculations: totals, counts, और क्या id वही order है जो आपने माँगा था। JSON Schema दो values की तुलना या calculation नहीं कर सकता।
Business rules और state: क्या इस order के लिए shipped सही अगला status है। if/then आसान conditions बता सकते हैं, लेकिन order का इतिहास नहीं देख सकते।
Authorization: क्या इस caller को यह order देखने का अधिकार है या नहीं।
Status codes, headers और timing: body validator इन्हें नहीं देखता; इन्हें अलग assertions से जाँचें।
Empty arrays: खाली items list हर items rule में pass होती है, इसलिए [] लौटाने वाला list endpoint item schema को कभी exercise नहीं करता। जहाँ contract content की गारंटी देता है वहाँ minItems लगाएँ, और ऐसा test data रखें जो non-empty lists दे।
ख़ुद schema: अगर document ग़लत या पुराना है, तो validator उसी से सहमत होगा। एक sample से generate किया गया schema आम तौर पर उसमें दिखे हर field को required बना देता है और sample के defects copy कर लेता है; पहले उसे requirements से मिलाकर review करें।

आज़माएँ: JSON Schema जनरेटर

आम गलतियाँ

Pass होने वाले schema check को "response सही है" मान लेना। यह सिर्फ़ structure साबित करता है; values के लिए assertions फिर भी चाहिए।
यह मान लेना कि properties में लिखा field mandatory है। सिर्फ़ required उसे mandatory बनाता है, और required null स्वीकार करता है; null रोकने के लिए type इस्तेमाल करें।
additionalProperties छोड़कर leaked fields miss कर देना — या team से तय किए बिना client के checks में इसे false कर देना, जिससे हर नया optional field build तोड़ दे।
Validator format assert करता है या नहीं, यह जाँचे बिना उस पर भरोसा करना: "email": "not-an-email" चुपचाप pass हो सकता है।
मौजूदा OpenAPI document की जगह एक sample से generate किए गए, या महीनों पहले test में copy किए गए schema के विरुद्ध validate करना।
सिर्फ़ success responses validate करना। Error responses (400, 404, 422) के भी schemas होते हैं, और clients उन्हें parse करते हैं।

QA का नज़रिया

Schema का काम किसी response के बनने से पहले शुरू होता है। Draft OpenAPI document को test basis के रूप में review करें और हर field के लिए पूछें: क्या यह required है, क्या यह null हो सकता है, कौन-सी values और formats allowed हैं, इसकी limits क्या हैं, क्या extra fields चलेंगे? यहाँ मिली ambiguities सस्ते में ठीक होती हैं और आगे के lessons के boundary और negative tests बनती हैं।

Execution के दौरान अपने API tests के हर response पर schema check चलाएँ और उन values के लिए assertions जोड़ें जिन्हें यह नहीं देख सकता। Check fail हो तो request, location, keyword, expected rule और इस्तेमाल किया गया OpenAPI version record करें। फिर developer या API owner से पूछें कि ग़लत कौन है — API या document — क्योंकि ग़लत वाले को ठीक करना defect को छिपा देता है।

अभ्यास

Product schema review करें और response validate करें

आपका काम

Requirement: GET /products/{sku} लौटाता है sku (text), name (1 से 120 characters), SAR में price (0 से बड़ा) और stock (whole number, 0 या उससे ज़्यादा), ये सब हमेशा मौजूद, साथ में text labels की एक optional tags list। कोई और field allowed नहीं है। एक colleague ने नीचे वाला schema लिखा; API ने उसके नीचे वाला response लौटाया।

पता करें कि schema requirement से कहाँ चूकता है, फिर निकालें कि schema का हर version क्या रिपोर्ट करता है।

सामग्री

Schema (colleague का draft):
{
  "type": "object",
  "required": ["sku", "name"],
  "properties": {
    "sku":   { "type": "string" },
    "name":  { "type": "string", "maxLength": 120 },
    "price": { "type": "number", "minimum": 0 },
    "stock": { "type": "number" },
    "tags":  { "type": "array", "items": { "type": "string" } }
  }
}

Response body:
{ "sku": "BK-201", "name": "", "stock": 2.5, "tags": ["new", 7], "costPrice": 41.2 }

चरण

Schema को requirement से keyword-दर-keyword मिलाएँ; हर gap और उसका fix लिखें।
Schema और response को JSON Schema Validator में paste करें और नोट करें कि वह क्या रिपोर्ट करता है।
Schema ठीक करें, फिर से validate करें और हर violation उसकी location और keyword के साथ लिखें।
दो ऐसी चीज़ें बताएँ जो requirement से निकलती हैं लेकिन जिन्हें कोई schema जाँच नहीं सकता।

मॉडल उत्तर दिखाएँ

मॉडल उत्तर

Gaps: required में price और stock भी हों; name को "minLength": 1 चाहिए; price को "exclusiveMinimum": 0 चाहिए, क्योंकि "minimum": 0 शून्य को accept करता है; stock के लिए "type": "integer" और "minimum": 0 हो; और "additionalProperties": false नहीं है।

Colleague का schema एक violation रिपोर्ट करता है: $.tags[1], type (7 string नहीं है)। खाली name, ग़ायब price, fractional stock और extra costPrice, सब pass हो जाते हैं।

ठीक किया गया schema पाँच रिपोर्ट करता है: $, required (price नहीं है); $.name, minLength; $.stock, type; $.tags[1], type; $.costPrice, additionalProperties। आख़िरी वाले के लिए अलग bug report बनता है: cost price internal commercial data है।

कोई schema यह नहीं जाँच सकता कि लौटाया गया sku वही है जो माँगा गया था, या price और stock catalogue और warehouse से मेल खाते हैं। इनके लिए किसी भरोसेमंद source of truth के विरुद्ध value assertions चाहिए।

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

JSON Schema और OpenAPI में क्या फ़र्क है?

JSON Schema एक JSON value का वर्णन करता है: उसके fields, types, formats और limits। OpenAPI पूरे HTTP API का वर्णन करता है — paths, methods, parameters, status codes, headers और security — और bodies के लिए schemas इस्तेमाल करता है। OpenAPI 3.1 और 3.2 के schemas JSON Schema 2020-12 हैं, साथ में कुछ OpenAPI keywords; OpenAPI 3.0 एक पुराने draft का extended subset इस्तेमाल करता है।

क्या schema validation और contract testing एक ही हैं?

Schema validation उसका एक हिस्सा है। Provider के OpenAPI document के विरुद्ध responses जाँचना specification-based contract testing है, और कुछ teams किसी भी schema check को contract test कहती हैं। Contract testing में consumer-driven contracts भी आते हैं, जिन्हें एक बाद वाला lesson समझाता है।

क्या response schemas में additionalProperties को false रखना चाहिए?

Provider के अपने tests में अक्सर यह फ़ायदेमंद है, क्योंकि यह undocumented और leaked fields पकड़ता है। दूसरी ओर, client को आम तौर पर नए fields सहने चाहिए, वरना हर additive change उसे तोड़ देगा। Developers के साथ rule तय करें और उसे अपने test approach में लिखें, ताकि failure का मतलब सबके लिए एक ही हो।

क्या schema fields के बीच के rules जाँच सकता है?

कुछ हद तक। dependentRequired कह सकता है "अगर refundId मौजूद है तो refundedAt भी होना चाहिए", और if/then/else कह सकते हैं "जब status cancelled हो, तो cancelledAt required है"। Schema दो values की तुलना या calculation नहीं कर सकता, इसलिए "total items के जोड़ के बराबर है" या "end date start date के बाद है" जैसे rules value assertions ही रहते हैं।

संदर्भ

JSON Schema SpecificationJSON SchemaJSON दस्तावेज़ की संरचना का वर्णन और वैलिडेशन करने की शब्दावली (टाइप, आवश्यक प्रॉपर्टी, फ़ॉर्मेट)।
OpenAPI SpecificationOpenAPI InitiativeREST API के वर्णन का मानक: पाथ, ऑपरेशन, पैरामीटर, स्कीमा, रिस्पॉन्स और सिक्योरिटी स्कीम।
ISTQB GlossaryISTQBटेस्टिंग शब्दों की मानक परिभाषाएँ — टेस्ट केस, रिग्रेशन टेस्टिंग, सेवेरिटी, प्रायोरिटी, बाउंड्री वैल्यू एनालिसिस आदि।
OWASP API Security Top 10 (2023)OWASP Foundation · 2023API की दस सबसे आम कमज़ोरियाँ: ऑब्जेक्ट-लेवल ऑथराइज़ेशन का टूटना, ऑथेंटिकेशन का टूटना, अनियंत्रित रिसोर्स खपत और अन्य।

API स्कीमा वैलिडेशन

यह क्यों ज़रूरी है

JSON Schema पढ़ना: वे keywords जो ज़्यादातर काम करते हैं

Schema कहाँ रहता है: OpenAPI

Worked example: 200 OK लौटाने वाला एक order

Schema validation आपको क्या नहीं बता सकता

आम गलतियाँ

QA का नज़रिया

अभ्यास

Product schema review करें और response validate करें

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

संदर्भ

Mutqan tools से अभ्यास करें

JSON Schema वैलिडेटर

API स्कीमा वैलिडेटर

OpenAPI व्यूअर

OpenAPI वैलिडेटर

JSON Schema जनरेटर

और गहराई से

इस topic में आपकी प्रगति

इस topic से पहले

अगले topics

इस मॉड्यूल के दूसरे topics

यह क्यों ज़रूरी है

JSON Schema पढ़ना: वे keywords जो ज़्यादातर काम करते हैं

Schema कहाँ रहता है: OpenAPI

Worked example: 200 OK लौटाने वाला एक order

Schema validation आपको क्या नहीं बता सकता

आम गलतियाँ

QA का नज़रिया

अभ्यास

Product schema review करें और response validate करें

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

संदर्भ

Mutqan tools से अभ्यास करें

और गहराई से

इस topic में आपकी प्रगति

QA रोडमैप का हिस्सा

इस topic से पहले

अगले topics

इस मॉड्यूल के दूसरे topics