SO4AG व्यावसायिक तथ्यों का एक खुला प्रारूप है: प्रत्येक तथ्य अपना अर्थ, दायरा, उत्पत्ति और वैधता साथ रखता है। रीडर एक प्रश्न का उत्तर देता है: क्या इस तथ्य का उपयोग इस समय इस कार्य के लिए किया जा सकता है, और यदि नहीं, तो क्यों नहीं।
यह प्रारूप निःशुल्क है और इसके लिए खाते की आवश्यकता नहीं है। कोड Apache-2.0 के अंतर्गत तथा विनिर्देश का पाठ CC BY 4.0 के अंतर्गत लाइसेंस प्राप्त है।
GitHub पर रिपॉज़िटरी · विनिर्देश · JSON Schema · अनुरूपता सूट · JSON-LD · ब्राउज़र में वैलिडेटर · क्या काम करता है
विषय-सूची: 1. कोड प्राप्त करें · 2. स्रोत का सत्यापन करें · 3. किसी तथ्य के बारे में पूछें · 4. अपना स्रोत प्रकाशित करें · 5. API · 6. MCP · 7. अपना रीडर · कोई भी उद्योग · परियोजना कहाँ मिलेगी
आपको 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
वैलिडेटर एक फ़ाइल या एक पता पढ़ता है। यह 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 से शुरू होता है। अमान्य स्रोत के लिए फ़ाइल में उनके स्थान सहित त्रुटियों की सूची आती है। कुछ भी इंस्टॉल किए बिना यही ब्राउज़र में वैलिडेटर में काम करता है।
एक वैध स्रोत केवल सही संरचना सिद्ध करता है। यह नहीं कहता कि तथ्य सत्य है।
एक कार्य बताता है कि आप किस गुण के बारे में और किन शर्तों (दायरे) के लिए पूछ रहे हैं। रीडर प्रत्येक मेल खाते दावे के साथ यह उत्तर देता है कि वह उपयोग योग्य है या नहीं, और जब नहीं है तो उसके कारण भी।
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 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 | स्रोत प्रारूप के उस संस्करण का है जिसे रीडर नहीं जानता। इसे किसी अन्य संस्करण के नियमों से नहीं पढ़ा जाता। |
कारणों और नियमों की पूरी सूची विनिर्देश में है।
एक स्रोत एक 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"
}
]
}
so4ag.json के रूप में सहेजें और वैलिडेटर से जाँचें (चरण 2)।/so4ag.json पर प्रकार application/json के साथ उपलब्ध कराएँ।<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json"> टैग में रखें। रूपांतरण दोषरहित है। node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_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."
}
}
}
id में दिए पते पर HTTPS के माध्यम से उपलब्ध कराएँ और उस पते को अपने स्रोत में profiles में जोड़ें।namespace + नाम के रूप में लिखें, अर्थात https://dental.example/so4ag-profile#emergencySlot।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 सेवा आपकी वेबसाइट से एक प्रस्ताव तैयार करती है, आप तथ्यों की पुष्टि करते हैं और स्रोत हमारे साथ प्रकाशित करते हैं या उसे अपने डोमेन के लिए डाउनलोड करते हैं: स्रोत तैयार करें।
यह इंटरफ़ेस केवल पढ़ने योग्य है और इसके लिए खाते या कुंजी की आवश्यकता नहीं है।
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 भी होता है।
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"}'
अनुरूपता सूट सादा 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: so4ag | Python पैकेज: 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] पर दें।