SOQVER स्रोत तैयार करें
हिन्दी

डेवलपरों के लिए मार्गदर्शिका

SO4AG व्यावसायिक तथ्यों का एक खुला प्रारूप है: प्रत्येक तथ्य अपना अर्थ, दायरा, उत्पत्ति और वैधता साथ रखता है। रीडर एक प्रश्न का उत्तर देता है: क्या इस तथ्य का उपयोग इस समय इस कार्य के लिए किया जा सकता है, और यदि नहीं, तो क्यों नहीं।

यह प्रारूप निःशुल्क है और इसके लिए खाते की आवश्यकता नहीं है। कोड Apache-2.0 के अंतर्गत तथा विनिर्देश का पाठ CC BY 4.0 के अंतर्गत लाइसेंस प्राप्त है।

सब कुछ एक ही स्थान पर

GitHub पर रिपॉज़िटरी · विनिर्देश · JSON Schema · अनुरूपता सूट · JSON-LD · ब्राउज़र में वैलिडेटर · क्या काम करता है

विषय-सूची: 1. कोड प्राप्त करें · 2. स्रोत का सत्यापन करें · 3. किसी तथ्य के बारे में पूछें · 4. अपना स्रोत प्रकाशित करें · 5. API · 6. MCP · 7. अपना रीडर · कोई भी उद्योग · परियोजना कहाँ मिलेगी

1. कोड प्राप्त करें

आपको Git और Node.js 20 या उससे नया संस्करण चाहिए। Python रीडर को केवल मानक लाइब्रेरी चाहिए (Python 3.10 या उससे नया)।

git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test

अंतिम कमांड संदर्भ कोड के परीक्षण अनुरूपता सूट के विरुद्ध चलाती है। उन सभी को सफल होना चाहिए।

अपने प्रोजेक्ट में पैकेज एक-एक कमांड से इंस्टॉल होते हैं:

npm install github:soqvercom/so4ag#v0.1.3
npx so4ag-validate https://example.com/so4ag.json

pip install so4ag
so4ag ask so4ag.json --property refundableDeposit --scope vehicle_class=economy

2. स्रोत का सत्यापन करें

वैलिडेटर एक फ़ाइल या एक पता पढ़ता है। यह SO4AG JSON, JSON-LD रूप और JSON-LD युक्त HTML पृष्ठ समझता है।

node validator/cli.mjs examples/valid/rental-first-party.json
node validator/cli.mjs https://example.com/so4ag.json
node validator/cli.mjs examples/valid/rental-first-party.json --json

उत्तर VALID या INVALID से शुरू होता है। अमान्य स्रोत के लिए फ़ाइल में उनके स्थान सहित त्रुटियों की सूची आती है। कुछ भी इंस्टॉल किए बिना यही ब्राउज़र में वैलिडेटर में काम करता है।

एक वैध स्रोत केवल सही संरचना सिद्ध करता है। यह नहीं कहता कि तथ्य सत्य है।

3. पूछें कि कोई तथ्य उपयोग किया जा सकता है या नहीं

एक कार्य बताता है कि आप किस गुण के बारे में और किन शर्तों (दायरे) के लिए पूछ रहे हैं। रीडर प्रत्येक मेल खाते दावे के साथ यह उत्तर देता है कि वह उपयोग योग्य है या नहीं, और जब नहीं है तो उसके कारण भी।

JavaScript

import { readFileSync } from 'node:fs';
import { validateManifest, selectClaims } from './validator/index.mjs';

const source = JSON.parse(readFileSync('examples/valid/rental-first-party.json', 'utf8'));
const check = validateManifest(source);          // { valid, errors, warnings, stats }

const answers = selectClaims(source, {
  property: 'https://soqver.com/spec/so4ag/0.1/rental#refundableDeposit',
  scope: { branch: 'https://rental.example/branches/prague-airport', vehicle_class: 'economy' },
});
for (const { claim, result } of answers) console.log(claim.id, result.usable, result.reasons, result.value);

Python

python readers/python/so4ag_reader.py ask examples/valid/rental-first-party.json \
  --property refundableDeposit --scope vehicle_class=economy \
  --scope branch=https://rental.example/branches/prague-airport

शाखा की शर्त के बिना या किसी अन्य समय पर वही आज़माएँ (--now 2027-06-01T12:00:00Z, JavaScript में तीसरा तर्क { now: new Date(…) })। दावा उपयोग योग्य नहीं रहता और रीडर बताता है कि क्यों।

कारणइसका अर्थ
expired, not_yet_validप्रश्न के समय दावा लागू नहीं होता।
scope_mismatch:<key>दावा शर्त के किसी अन्य मान पर लागू होता है, उदाहरण के लिए किसी अन्य शाखा पर।
scope_not_in_task:<key>दावा एक ऐसी शर्त से सीमित है जिसे कार्य नहीं बताता। उसके बिना कोई नहीं कह सकता कि दावा लागू होता है या नहीं।
unknown, not_applicableप्रकाशक स्पष्ट रूप से बताता है कि मान ज्ञात नहीं है या लागू नहीं होता। अज्ञात शून्य नहीं है।
disputedदावा विवादित है।
no_trust_policyकार्य एक समीक्षित दावे की माँग करता है, पर यह नहीं बताता कि वह किस पर विश्वास करता है। किस पर विश्वास करना है, यह निर्णय दावा पढ़ने वाले का होता है।
attestation_not_authenticatedस्रोत में एक प्रमाणन है जिसमें उस जारीकर्ता का नाम है जिस पर आप भरोसा करते हैं, पर आपने उसे जारीकर्ता से प्रमाणित नहीं किया है। स्रोत में लिखा नाम प्रमाण नहीं है।
conflicting_claimsदो वर्तमान दावे एक ही बात के लिए अलग-अलग मान बताते हैं। रीडर किसी का भी उपयोग नहीं करता और चुपचाप किसी एक को नहीं चुनता।
invalid_sourceस्रोत प्रारूप की संरचना तोड़ता है (उदाहरण के लिए बिना साक्ष्य का दावा या अपठनीय तिथि)। उसमें से कुछ भी उपयोग नहीं होता।
unsupported_versionस्रोत प्रारूप के उस संस्करण का है जिसे रीडर नहीं जानता। इसे किसी अन्य संस्करण के नियमों से नहीं पढ़ा जाता।

कारणों और नियमों की पूरी सूची विनिर्देश में है।

4. अपना स्रोत प्रकाशित करें

एक स्रोत एक JSON फ़ाइल होता है। सबसे छोटे उपयोगी रूप में एक प्रकाशक और एक दावा होता है:

{
  "so4ag": "0.1-draft",
  "id": "https://rental.example/so4ag.json",
  "revision": "2026-11-20.1",
  "published_at": "2026-11-19T20:05:00Z",
  "publisher": {
    "id": "https://rental.example/#org",
    "name": "Example Rental",
    "role": "first_party",
    "domain": "rental.example"
  },
  "profiles": ["https://soqver.com/spec/so4ag/0.1/rental"],
  "subjects": [
    { "id": "https://rental.example/#org", "type": "AutoRental", "name": "Example Rental" },
    { "id": "https://rental.example/branches/prague-airport", "type": "Place", "name": "Prague Airport" }
  ],
  "claims": [
    {
      "id": "https://rental.example/claims/deposit-economy-airport",
      "revision": "3",
      "subject": "https://rental.example/#org",
      "property": "https://soqver.com/spec/so4ag/0.1/rental#refundableDeposit",
      "knowledge_state": "known",
      "value": { "type": "money", "amount": "10000.00", "currency": "CZK" },
      "scope": { "branch": "https://rental.example/branches/prague-airport", "vehicle_class": "economy" },
      "assertion_basis": "publisher_asserted",
      "evidence": [
        { "url": "https://rental.example/terms#deposit", "observed_at": "2026-11-19T20:00:00Z", "kind": "webpage" }
      ],
      "valid_from": "2026-11-20T00:00:00Z",
      "valid_until": "2026-12-20T00:00:00Z"
    }
  ]
}
  1. फ़ाइल को so4ag.json के रूप में सहेजें और वैलिडेटर से जाँचें (चरण 2)।
  2. इसे अपने डोमेन पर HTTPS के माध्यम से /so4ag.json पर प्रकार application/json के साथ उपलब्ध कराएँ।
  3. लोगों के लिए बने पृष्ठों पर स्रोत का लिंक जोड़ें:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. पृष्ठ के भीतर वही तथ्य रखने के लिए स्रोत को JSON-LD में बदलें और परिणाम को <script type="application/ld+json"> टैग में रखें। रूपांतरण दोषरहित है।
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. प्रत्येक दावे को वैधता की समाप्ति दें (valid_until) और उसके बीतने से पहले दावे की पुष्टि करें या उसे बदलें। उस समय के बाद रीडर उसका उपयोग बंद कर देते हैं।

कोई भी उद्योग: सामान्य प्रोफ़ाइल और आपकी अपनी प्रोफ़ाइल

यह प्रारूप किसी उद्योग से बंधा नहीं है। गुण (किसी तथ्य का अर्थ, उसका प्रकार और इकाई, तथा कौन-सी शर्तें उसे सीमित करती हैं) एक प्रोफ़ाइल निर्धारित करती है, और एक स्रोत कई प्रोफ़ाइल एक साथ उपयोग कर सकता है।

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

आपकी अपनी प्रोफ़ाइल आपके गुणों का वर्णन उसी तरह करती है जैसे हमारी करती हैं: लेबल, विवरण, मान का प्रकार, इकाइयाँ, अनुमत कोड और शर्तें। सबसे छोटा रूप:

{
  "id": "https://dental.example/so4ag-profile",
  "name": "Example Dental profile",
  "version": "1",
  "namespace": "https://dental.example/so4ag-profile#",
  "scope_keys": { "day_type": "weekday, weekend, public_holiday, any" },
  "properties": {
    "emergencySlot": {
      "label": { "en": "Same-day treatment of acute pain" },
      "value_types": ["boolean"],
      "required_scope": ["day_type"],
      "max_validity": "P90D",
      "description": "Whether a patient with acute pain is treated on the day of the call."
    }
  }
}
  1. फ़ाइल को id में दिए पते पर HTTPS के माध्यम से उपलब्ध कराएँ और उस पते को अपने स्रोत में profiles में जोड़ें।
  2. दावे का गुण namespace + नाम के रूप में लिखें, अर्थात https://dental.example/so4ag-profile#emergencySlot।
  3. प्रोफ़ाइल और स्रोत की जाँच करें:
    node validator/cli.mjs --check-profile examples/profiles/dental-example-profile.json
    node validator/cli.mjs examples/valid/general-dental.json --profile examples/profiles/dental-example-profile.json

जो रीडर आपकी प्रोफ़ाइल नहीं जानता, वह भी दावे का उपयोग तब करता है जब कार्य उसकी शर्तें बताता है; जब कार्य ऐसा नहीं करता, तो दावे का उपयोग नहीं होता। इसलिए प्रारूप के सुरक्षा नियम हर प्रोफ़ाइल पर समान रूप से लागू होते हैं। General प्रोफ़ाइल और अपनी प्रोफ़ाइल वाले दंत चिकित्सालय का पूरा उदाहरण रिपॉज़िटरी में है: general-dental.json। प्रोफ़ाइल की स्कीमा: profile.schema.json।

फ़ाइल हाथ से नहीं लिखना चाहते? SOQVER सेवा आपकी वेबसाइट से एक प्रस्ताव तैयार करती है, आप तथ्यों की पुष्टि करते हैं और स्रोत हमारे साथ प्रकाशित करते हैं या उसे अपने डोमेन के लिए डाउनलोड करते हैं: स्रोत तैयार करें।

5. API के माध्यम से प्रकाशित स्रोत पढ़ें

यह इंटरफ़ेस केवल पढ़ने योग्य है और इसके लिए खाते या कुंजी की आवश्यकता नहीं है।

curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"

पहला पता उन स्रोतों की सूची देता है जिन्हें किसी कंपनी ने प्रकाशित या पुष्टि किया है। दूसरा आपके कार्य के लिए एक स्रोत के दावों का मूल्यांकन करता है और प्रत्येक के लिए usable तथा reasons लौटाता है। प्रत्येक स्रोत लोगों के लिए एक पृष्ठ (/s/<slug>/), एक फ़ाइल /s/<slug>/so4ag.json और एक JSON-LD रूप /s/<slug>/facts.jsonld भी होता है।

6. MCP के माध्यम से एजेंट जोड़ें

MCP सर्वर केवल पढ़ने योग्य है, इसके लिए खाते की आवश्यकता नहीं है और यह Streamable HTTP ट्रांसपोर्ट का उपयोग करता है। आधिकारिक MCP Registry में यह com.soqver/so4ag के रूप में सूचीबद्ध है।

https://soqver.com/mcp
उपकरणयह क्या करता है
list_sourcesप्रकाशित स्रोतों की सूची देता है।
get_sourceएक व्यवसाय का संपूर्ण स्रोत लौटाता है।
get_claimsदिए गए गुण और शर्तों के लिए किसी स्रोत के दावों का मूल्यांकन करता है।
check_claimबताता है कि कोई दावा अभी उपयोग किया जा सकता है या नहीं, और क्यों नहीं।

दूरस्थ MCP सर्वर का समर्थन करने वाले क्लाइंट में ऊपर दिया गया पता दर्ज करें। सर्वर का उत्तर आप कमांड लाइन से भी जाँच सकते हैं:

curl -s https://soqver.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

7. अपना रीडर स्वयं लिखें

अनुरूपता सूट सादा JSON है और इसके लिए हमारे किसी कोड की आवश्यकता नहीं। इसमें तीन रूपों में दो वैध स्रोत, दावों के अपेक्षित डाइजेस्ट, मूल्यांकन के 45 केस, सत्यापन के 31 केस, पूरे स्रोत के 10 केस और विहित रूप के 25 वेक्टर (RFC 8785) हैं।

python readers/python/so4ag_reader.py conformance spec/conformance/0.1

कोई रीडर या वैलिडेटर सूट कब पास करता है, इसका वर्णन अनुरूपता सूट के विवरण में है। Python रीडर संदर्भ कोड से स्वतंत्र रूप से लिखा गया है और वही सूट पास करता है; आप इसे नमूने के रूप में उपयोग कर सकते हैं।

परियोजना कहाँ मिलेगी

स्थानयह किस लिए है
GitHub: soqvercom/so4agकोड, विनिर्देश, अनुरूपता सूट और रिलीज़। प्रारूप का विकास यहीं होता है।
GitHub Discussionsसमुदाय का स्थान: प्रारूप से जुड़े प्रश्न, प्रस्ताव और अनुभव। हम यहाँ उत्तर देते हैं।
GitHub Issuesविनिर्देश और कोड की त्रुटियाँ, तथा वे मामले जिन्हें प्रारूप व्यक्त नहीं कर सकता।
PyPI: so4agPython पैकेज: pip install so4ag
रिलीज़JavaScript पैकेज और प्रत्येक संस्करण की फ़ाइलें: npm install github:soqvercom/so4ag
Zenodo (DOI)शोधपत्रों और दस्तावेज़ों में उद्धरण के लिए रिलीज़ का स्थायी लिंक।
MCP Registryहमारे MCP सर्वर की प्रविष्टि: com.soqver/so4ag
Discord: SOQVER · SO4AGसंक्षिप्त प्रश्न और प्रारूप आज़माने वाले अन्य लोगों के साथ बातचीत।
DEV: @soqvercomप्रारूप पर तकनीकी लेख और कैसे-करें पाठ।
daily.dev: @soqverडेवलपरों के लिए नए लेखों के लिंक।
X · YouTubeप्रारूप के समाचार और संक्षिप्त डेमो।

प्रतिक्रिया और त्रुटियाँ

ऐसा तथ्य मिला जिसे यह प्रारूप व्यक्त नहीं कर सकता, या दो रीडर जो अलग-अलग उत्तर देते हैं? इसे GitHub पर इश्यू के रूप में लिखें। कृपया भेद्यता की सूचना ई-मेल द्वारा [email protected] पर दें।