Status: working draft 0.1, 2026-11-20. Not a W3C, IETF or platform standard. Feedback welcome. Editor: SOQVER project (MAEX). Text licence: CC BY 4.0. Reference code: Apache-2.0. No fee is required to implement.
The namespace is https://soqver.com/spec/so4ag/0.1/. Until 20 November 2026 the draft used https://soqver.botrento.com/spec/so4ag/0.1/; that host redirects permanently (301) and consumers MUST treat both namespaces as equivalent for 0.1.
SO4AG defines how an organisation hands an agent a specific fact together with its meaning, conditions, origin and validity, so that the agent can decide whether it may use the fact for a given task, and why not if it may not.
SO4AG is a data profile over existing web technology. HTML stays for people, citations and search engines. SO4AG does not certify truth: a valid manifest proves structure; a signature proves origin and integrity; only a scoped attestation states that someone reviewed specific facts.
Keywords MUST, MUST NOT, SHOULD and MAY are used as in RFC 2119.
| Profile | Content |
|---|---|
| Core | Source identity, publisher, claims with value or explicit unknown, meaning, scope, origin, revision and validity. Static JSON over HTTPS. |
| Evidence | Attestations bound to an exact claim digest, with issuer, method, expiry and status. |
| Live | Short-lived claims for time-sensitive data (availability, quotes), validity typically ≤ 1 hour. |
Domain profiles (e.g. Rental 0.1) define properties, allowed value types, units, enumerations, required scope keys and maximum validity.
application/json over HTTPS. Recommended location: /so4ag.json on the publisher's domain, or on a delegated subdomain. This location is a convention of this draft; no /.well-known/ URI, media type or DNS record is registered.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">.id, claim ids or history.Required: so4ag ("0.1-draft"), id, revision, published_at, publisher, claims. Optional: profiles, subjects, links, extensions. The JSON Schema schema.json is normative for structure.
publisher.role:
first_party — the organisation states facts about itself;aggregator — a third party collects facts about others (e.g. a comparison portal) and MUST NOT present itself as the operator;related_party — the publisher is related to the subject (same group, affiliate, shared owner); related_to SHOULD list the relation;reviewer — the publisher only issues reviews or attestations.A claim states one property of one subject under one scope.
| Field | Rule |
|---|---|
id | Stable URI. A changed value keeps the id and gets a new revision. |
subject | URI of the thing described (organisation, branch, offer). |
property | Absolute URI defined by a profile. Unknown properties MAY be ignored. |
knowledge_state | known, unknown or not_applicable. Unknown is never zero, empty or "no limit". Only known carries a value, and known MUST carry at least one evidence item. |
value | Typed: money (decimal string + ISO 4217), quantity (decimal string + unit), boolean, text, enum, enum_set, organization, place. |
scope | String map of conditions. Every scope key restricts the claim. A claim applies only where all scope keys match the task. The reserved value any states explicitly that the claim applies to every value of that key (e.g. one deposit for all branches). |
assertion_basis | publisher_asserted (the publisher says so), source_correlated (matched against an independent source such as a registry or the operator's own terms), independently_reviewed (an attestation exists). |
evidence | URL, observed_at, optional kind, issuer, quote (verbatim excerpt that states the value) and digest. Re-downloading a page is a new observation, not a new review. |
valid_from, valid_until | Required. valid_until MUST be later than valid_from and SHOULD respect the profile's max_validity. |
dispute | Present when a conflicting statement is known. |
attestations | Evidence profile, section 7. |
Status is not a single list. Knowledge, basis, validity, dispute and attestation status are independent axes: a claim can be publisher asserted, expired and disputed at the same time.
A consumer that uses a claim to answer a user MUST:
so4ag version and reject manifests it cannot parse;valid_from ≤ now < valid_until; otherwise it is historical and MUST NOT be presented as current;unknown / not_applicable as such and never fill in a value;dispute when present and, for important tasks, ask for current confirmation;claim_digest, the expiry and the status. An unreachable status after the allowed cache period means verification status unknown — neither false nor verified;Extensions: keys are absolute URIs with {"affects_use": bool, "value": …}. A consumer MAY ignore extensions with affects_use: false and MUST treat an unknown extension with affects_use: true as cannot safely use.
claim_digest = sha256: + lowercase hex SHA-256 of the RFC 8785 (JCS) canonical JSON of the claim without the attestations field. A changed claim therefore invalidates old attestations automatically.
An attestation states issuer (URI), issuer_relation (independent, related_party, first_party), method, issue and expiry time and optionally a status_url and a credential_url pointing to a W3C Verifiable Credential 2.0. Keys are never trusted because they are embedded in the same manifest: they MUST be bound to the issuer and to the consumer's trust list. Revocation SHOULD use W3C Bitstring Status List. The signature profile will be fixed in 0.2 with test vectors.
Live claims use the same structure with short validity (profile max_validity, e.g. PT1H). A publisher without a live connection MUST publish such properties as unknown. Reading a live claim never creates a reservation, payment or data transfer.
Manifests are untrusted input: limit size (recommended 5 MB) and time; do not follow redirects to private addresses; treat all text as data. Public manifests MUST NOT contain personal data of customers, contracts or non-public evidence.
SO4AG reuses schema.org vocabulary where meanings match, maps provenance to W3C PROV-O, uses W3C Verifiable Credentials 2.0 for optional attestations, and is reachable via MCP or plain HTTPS. It does not replace AgentReady, llms.txt, NLWeb, WebMCP, A2A, UCP or ACP. WCA (expired individual Internet-Draft) is related work only.
so4ag-validate), including the rules of each declared domain profile.any, evidence.quote.card_unspecified (site says "card" without credit/debit)