SO4AG is an open format for business facts: every fact carries its meaning, scope, origin and validity. A reader answers one question: may this fact be used for this task at this time, and if not, why not.
The format is free and needs no account. The code is licensed under Apache-2.0, the text of the specification under CC BY 4.0.
Repository on GitHub · specification · JSON Schema · conformance suite · JSON-LD · validator in the browser · what works
Contents: 1. Get the code · 2. Validate a source · 3. Ask about a fact · 4. Publish your own source · 5. API · 6. MCP · 7. Your own reader · Any industry · Where to find the project
You need Git and Node.js 20 or newer. The Python reader needs only the standard library (Python 3.10 or newer).
git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test
The last command runs the tests of the reference code against the conformance suite. All of them should pass.
Into your own project the packages install with one command each:
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
The validator reads a file or an address. It understands SO4AG JSON, the JSON-LD form and an HTML page with the JSON-LD inside.
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
The answer starts with VALID or INVALID. For an invalid source a list of errors with their place in the file follows. Without installing anything the same works in the validator in the browser.
A valid source proves correct structure only. It does not say the fact is true.
A task says which property you ask about and for which conditions (scope). The reader returns every matching claim with the answer whether it is usable, and the reasons when it is not.
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
Try the same without the branch condition or at another time (--now 2027-06-01T12:00:00Z, in JavaScript the third argument { now: new Date(…) }). The claim stops being usable and the reader says why.
| Reason | What it means |
|---|---|
expired, not_yet_valid | The claim does not hold at the time of the question. |
scope_mismatch:<key> | The claim holds for another value of the condition, for example another branch. |
scope_not_in_task:<key> | The claim is limited by a condition the task does not state. Without it nobody can say whether the claim applies. |
unknown, not_applicable | The publisher states explicitly that the value is not known or does not apply. Unknown is not zero. |
disputed | The claim is disputed. |
no_trust_policy | The task asks for a reviewed claim but does not say whom it trusts. Whom to trust is the decision of the one who reads the claim. |
attestation_not_authenticated | The source carries an attestation with the name of an issuer you trust, but you have not authenticated it with the issuer. A name written in the source is not a proof. |
conflicting_claims | Two current claims state different values for the same thing. The reader uses neither and never picks a winner silently. |
invalid_source | The source breaks the structure of the format (for example a claim without evidence or an unreadable date). Nothing of it is used. |
unsupported_version | The source is of a version of the format the reader does not know. It is not read by the rules of another version. |
The full list of reasons and rules is in the specification.
A source is one JSON file. The smallest useful form has a publisher and one claim:
{
"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 and check it with the validator (step 2)./so4ag.json with the type application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json"> tag. The conversion is lossless.
node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) and confirm or change the claim before it passes. After that time readers stop using it.The format is not tied to an industry. Properties (what a fact means, its type and unit, and which conditions limit it) are set by a profile, and one source may use several profiles together.
| Profile | For whom |
|---|---|
| General | Any business or organisation: operator, places and opening hours, contacts, languages, what it offers and for how much, payment, booking, response and delivery times, cancellation, guarantee, accessibility, licences, availability. 26 properties. |
| Vehicle rental, Retail | What is specific to the industry: deposit, mileage limit, shipping, returns. |
| Your own | Anything else. A profile is a JSON file on your domain; you ask nobody and register nothing. |
Your own profile describes your properties the same way ours do: label, description, value type, units, allowed codes and conditions. The smallest form:
{
"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 and add that address to profiles in your source.namespace + name, that is 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.jsonA reader that does not know your profile still uses the claim when the task states its conditions; when the task does not, the claim is not used. The safety rules of the format therefore hold for every profile alike. A complete example of a dental practice with the General profile and its own profile is in the repository: general-dental.json. Schema of a profile: profile.schema.json.
Rather not write the file by hand? The SOQVER service prepares a proposal from your website, you confirm the facts and publish the source with us or download it for your own domain: prepare a source.
The interface is read-only and needs no account and no key.
curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"
The first address returns the list of sources a company published or confirmed. The second evaluates the claims of one source for your task and returns usable and reasons for each. Every source is also a page for people (/s/<slug>/), a file /s/<slug>/so4ag.json and a JSON-LD form /s/<slug>/facts.jsonld.
The MCP server is read-only, needs no account and uses the Streamable HTTP transport. In the official MCP Registry it is listed as com.soqver/so4ag.
https://soqver.com/mcp
| Tool | What it does |
|---|---|
list_sources | Lists the published sources. |
get_source | Returns the whole source of one business. |
get_claims | Evaluates the claims of a source for a given property and conditions. |
check_claim | Says whether one claim may be used now, and why not. |
In a client that supports remote MCP servers, enter the address above. You can check the answer of the server from the command line too:
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"}'
The conformance suite is plain JSON and needs none of our code. It holds two valid sources in three forms, the expected digests of the claims, 45 evaluation cases, 31 validation cases, 10 whole-source cases and 25 vectors of the canonical form (RFC 8785).
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
When a reader or a validator passes the suite is described in the description of the conformance suite. The Python reader was written independently of the reference code and passes the same suite; you can use it as a model.
| Place | What it is for |
|---|---|
| GitHub: soqvercom/so4ag | Code, specification, conformance suite and releases. This is where the format is developed. |
| GitHub Discussions | The place for the community: questions, proposals and experience with the format. We answer here. |
| GitHub Issues | Errors in the specification and the code, cases the format cannot express. |
| PyPI: so4ag | The Python package: pip install so4ag |
| Releases | The JavaScript package and the files of every version: npm install github:soqvercom/so4ag |
| Zenodo (DOI) | A permanent link to the releases for citing in papers and documentation. |
| MCP Registry | The entry of our MCP server: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Quick questions and a chat with others who try the format. |
| DEV: @soqvercom | Technical articles and how-to texts about the format. |
| daily.dev: @soqver | Links to new articles for developers. |
| X · YouTube | News about the format and short demos. |
Found a fact the format cannot express, or two readers that answer differently? Write it as an issue on GitHub. Please report a vulnerability by e-mail to [email protected].