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]-এ দিন।