SOQVER Prepare a source
English

Guide for developers

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.

Everything in one place

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

1. Get the code

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

2. Validate a source

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.

3. Ask whether a fact may be used

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.

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

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.

ReasonWhat it means
expired, not_yet_validThe 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_applicableThe publisher states explicitly that the value is not known or does not apply. Unknown is not zero.
disputedThe claim is disputed.
no_trust_policyThe 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_authenticatedThe 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_claimsTwo current claims state different values for the same thing. The reader uses neither and never picks a winner silently.
invalid_sourceThe source breaks the structure of the format (for example a claim without evidence or an unreadable date). Nothing of it is used.
unsupported_versionThe 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.

4. Publish your own source

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"
    }
  ]
}
  1. Save the file as so4ag.json and check it with the validator (step 2).
  2. Serve it over HTTPS on your domain at /so4ag.json with the type application/json.
  3. Add a link to the source to the pages for people:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. To have the same facts inside the page, convert the source to JSON-LD and put the result into a <script type="application/ld+json"> tag. The conversion is lossless.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Give every claim an end of validity (valid_until) and confirm or change the claim before it passes. After that time readers stop using it.

Any industry: the General profile and your own profile

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.

ProfileFor whom
GeneralAny 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, RetailWhat is specific to the industry: deposit, mileage limit, shipping, returns.
Your ownAnything 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."
    }
  }
}
  1. Serve the file over HTTPS at the address given in id and add that address to profiles in your source.
  2. Write the property of a claim as namespace + name, that is https://dental.example/so4ag-profile#emergencySlot.
  3. Check the profile and the source:
    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

A 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.

5. Read published sources through the API

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.

6. Connect an agent through MCP

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
ToolWhat it does
list_sourcesLists the published sources.
get_sourceReturns the whole source of one business.
get_claimsEvaluates the claims of a source for a given property and conditions.
check_claimSays 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"}'

7. Write your own reader

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.

Where to find the project

PlaceWhat it is for
GitHub: soqvercom/so4agCode, specification, conformance suite and releases. This is where the format is developed.
GitHub DiscussionsThe place for the community: questions, proposals and experience with the format. We answer here.
GitHub IssuesErrors in the specification and the code, cases the format cannot express.
PyPI: so4agThe Python package: pip install so4ag
ReleasesThe 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 RegistryThe entry of our MCP server: com.soqver/so4ag
Discord: SOQVER · SO4AGQuick questions and a chat with others who try the format.
DEV: @soqvercomTechnical articles and how-to texts about the format.
daily.dev: @soqverLinks to new articles for developers.
X · YouTubeNews about the format and short demos.

Feedback and errors

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].