SOQVER Préparer une source
Français

Guide pour les développeurs

SO4AG est un format ouvert pour les faits d'entreprise : chaque fait porte son sens, son périmètre, son origine et sa validité. Un lecteur répond à une seule question : ce fait peut-il être utilisé pour cette tâche à cet instant et, sinon, pourquoi.

Le format est gratuit et ne nécessite aucun compte. Le code est sous licence Apache-2.0, le texte de la spécification sous CC BY 4.0.

Tout au même endroit

Dépôt sur GitHub · spécification · JSON Schema · suite de conformité · JSON-LD · validateur dans le navigateur · ce qui fonctionne

Sommaire : 1. Obtenir le code · 2. Valider une source · 3. Interroger un fait · 4. Publier votre propre source · 5. API · 6. MCP · 7. Votre propre lecteur · Tout secteur · Où trouver le projet

1. Obtenir le code

Vous avez besoin de Git et de Node.js 20 ou plus récent. Le lecteur Python n'a besoin que de la bibliothèque standard (Python 3.10 ou plus récent).

git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test

La dernière commande exécute les tests du code de référence sur la suite de conformité. Tous devraient réussir.

Dans votre propre projet, les paquets s'installent chacun avec une seule commande :

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. Valider une source

Le validateur lit un fichier ou une adresse. Il comprend le JSON SO4AG, la forme JSON-LD et une page HTML contenant le JSON-LD.

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

La réponse commence par VALID ou INVALID. Pour une source non valide, une liste d'erreurs avec leur emplacement dans le fichier suit. Sans rien installer, la même vérification fonctionne dans le validateur dans le navigateur.

Une source valide prouve uniquement une structure correcte. Elle n'indique pas que le fait est vrai.

3. Demander si un fait peut être utilisé

Une tâche indique quelle propriété vous interrogez et pour quelles conditions (périmètre). Le lecteur renvoie chaque affirmation correspondante avec la réponse sur son caractère utilisable, et les motifs lorsqu'elle ne l'est pas.

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

Essayez la même chose sans la condition de succursale ou à un autre moment (--now 2027-06-01T12:00:00Z, en JavaScript le troisième argument { now: new Date(…) }). L'affirmation cesse d'être utilisable et le lecteur indique pourquoi.

MotifSignification
expired, not_yet_validL'affirmation ne s'applique pas au moment de la question.
scope_mismatch:<key>L'affirmation s'applique pour une autre valeur de la condition, par exemple une autre succursale.
scope_not_in_task:<key>L'affirmation est limitée par une condition que la tâche n'énonce pas. Sans elle, personne ne peut dire si l'affirmation s'applique.
unknown, not_applicableL'éditeur indique explicitement que la valeur n'est pas connue ou ne s'applique pas. Inconnu n'est pas zéro.
disputedL'affirmation est contestée.
no_trust_policyLa tâche demande une affirmation revue, mais n'indique pas en qui elle a confiance. À qui faire confiance est la décision de celui qui lit l'affirmation.
attestation_not_authenticatedLa source comporte une attestation au nom d'un émetteur auquel vous faites confiance, mais vous ne l'avez pas authentifiée auprès de l'émetteur. Un nom inscrit dans la source ne constitue pas une preuve.
conflicting_claimsDeux déclarations en vigueur indiquent des valeurs différentes pour la même chose. Le lecteur n'utilise ni l'une ni l'autre et ne désigne jamais un vainqueur en silence.
invalid_sourceLa source rompt la structure du format (par exemple une déclaration sans preuve ou une date illisible). Rien n'en est utilisé.
unsupported_versionLa source est d'une version du format que le lecteur ne connaît pas. Elle n'est pas lue selon les règles d'une autre version.

La liste complète des motifs et des règles figure dans la spécification.

4. Publier votre propre source

Une source est un fichier JSON. La plus petite forme utile comporte un éditeur et une affirmation :

{
  "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. Enregistrez le fichier sous so4ag.json et vérifiez-le avec le validateur (étape 2).
  2. Servez-le en HTTPS sur votre domaine à /so4ag.json avec le type application/json.
  3. Ajoutez un lien vers la source aux pages destinées aux personnes :
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Pour avoir les mêmes faits dans la page, convertissez la source en JSON-LD et placez le résultat dans une balise <script type="application/ld+json">. La conversion est sans perte.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Donnez à chaque affirmation une fin de validité (valid_until) et confirmez ou modifiez l'affirmation avant qu'elle ne soit dépassée. Après ce moment, les lecteurs cessent de l'utiliser.

Tout secteur : le profil General et votre propre profil

Le format n'est lié à aucun secteur. Les propriétés (ce qu'un fait signifie, son type et son unité, et les conditions qui le limitent) sont définies par un profil, et une source peut utiliser plusieurs profils ensemble.

ProfilPour qui
GeneralToute entreprise ou organisation : exploitant, lieux et horaires d'ouverture, contacts, langues, ce qu'elle propose et à quel prix, paiement, réservation, délais de réponse et de livraison, annulation, garantie, accessibilité, licences, disponibilité. 26 propriétés.
Location de véhicules, Commerce de détailCe qui est propre au secteur : dépôt de garantie, limite de kilométrage, expédition, retours.
Le vôtreTout le reste. Un profil est un fichier JSON sur votre domaine ; vous ne demandez à personne et n'enregistrez rien.

Votre propre profil décrit vos propriétés de la même façon que les nôtres : libellé, description, type de valeur, unités, codes autorisés et conditions. La forme minimale :

{
  "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. Servez le fichier en HTTPS à l'adresse indiquée dans id et ajoutez cette adresse à profiles dans votre source.
  2. Écrivez la propriété d'une assertion sous la forme namespace + nom, c'est-à-dire https://dental.example/so4ag-profile#emergencySlot.
  3. Vérifiez le profil et la 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

Un lecteur qui ne connaît pas votre profil utilise tout de même l'assertion lorsque la tâche en énonce les conditions ; lorsque la tâche ne les énonce pas, l'assertion n'est pas utilisée. Les règles de sécurité du format valent donc pareillement pour chaque profil. Un exemple complet de cabinet dentaire avec le profil General et son propre profil se trouve dans le dépôt : general-dental.json. Schéma d'un profil : profile.schema.json.

Vous préférez ne pas écrire le fichier à la main ? Le service SOQVER prépare une proposition à partir de votre site web, vous confirmez les faits et publiez la source avec nous ou la téléchargez pour votre propre domaine : préparer une source.

5. Lire les sources publiées via l'API

L'interface est en lecture seule et ne nécessite ni compte ni clé.

curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"

La première adresse renvoie la liste des sources qu'une entreprise a publiées ou confirmées. La seconde évalue les affirmations d'une source pour votre tâche et renvoie usable et reasons pour chacune. Chaque source est aussi une page pour les personnes (/s/<slug>/), un fichier /s/<slug>/so4ag.json et une forme JSON-LD /s/<slug>/facts.jsonld.

6. Connecter un agent via MCP

Le serveur MCP est en lecture seule, ne nécessite aucun compte et utilise le transport Streamable HTTP. Dans le MCP Registry officiel, il est répertorié comme com.soqver/so4ag.

https://soqver.com/mcp
OutilCe qu'il fait
list_sourcesListe les sources publiées.
get_sourceRenvoie la source complète d'une entreprise.
get_claimsÉvalue les affirmations d'une source pour une propriété et des conditions données.
check_claimIndique si une affirmation peut être utilisée maintenant, et pourquoi elle ne le peut pas.

Dans un client qui prend en charge les serveurs MCP distants, saisissez l'adresse ci-dessus. Vous pouvez aussi vérifier la réponse du serveur depuis la ligne de commande :

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. Écrire votre propre lecteur

La suite de conformité est du JSON simple et n'a besoin d'aucun de notre code. Elle contient deux sources valides sous trois formes, les condensés attendus des déclarations, 45 cas d'évaluation, 31 cas de validation, 10 cas portant sur la source entière et 25 vecteurs de la forme canonique (RFC 8785).

python readers/python/so4ag_reader.py conformance spec/conformance/0.1

Les conditions dans lesquelles un lecteur ou un validateur réussit la suite sont décrites dans la description de la suite de conformité. Le lecteur Python a été écrit indépendamment du code de référence et réussit la même suite ; vous pouvez vous en servir comme modèle.

Où trouver le projet

LieuÀ quoi cela sert
GitHub : soqvercom/so4agCode, spécification, suite de conformité et versions. C'est ici que le format est développé.
GitHub DiscussionsLe lieu de la communauté : questions, propositions et retours d'expérience sur le format. Nous répondons ici.
GitHub IssuesErreurs dans la spécification et le code, cas que le format ne peut pas exprimer.
PyPI : so4agLe paquet Python : pip install so4ag
VersionsLe paquet JavaScript et les fichiers de chaque version : npm install github:soqvercom/so4ag
Zenodo (DOI)Un lien permanent vers les versions pour les citer dans les articles et la documentation.
MCP RegistryL'entrée de notre serveur MCP : com.soqver/so4ag
Discord : SOQVER · SO4AGQuestions rapides et discussion avec d'autres personnes qui essaient le format.
DEV : @soqvercomArticles techniques et guides pratiques sur le format.
daily.dev : @soqverLiens vers les nouveaux articles pour les développeurs.
X · YouTubeActualités sur le format et courtes démonstrations.

Retours et erreurs

Vous avez trouvé un fait que le format ne peut pas exprimer, ou deux lecteurs qui répondent différemment ? Rédigez-le comme un ticket sur GitHub. Veuillez signaler une vulnérabilité par e-mail à [email protected].