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.
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
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
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.
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.
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
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.
| Motif | Signification |
|---|---|
expired, not_yet_valid | L'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_applicable | L'éditeur indique explicitement que la valeur n'est pas connue ou ne s'applique pas. Inconnu n'est pas zéro. |
disputed | L'affirmation est contestée. |
no_trust_policy | La 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_authenticated | La 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_claims | Deux 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_source | La source rompt la structure du format (par exemple une déclaration sans preuve ou une date illisible). Rien n'en est utilisé. |
unsupported_version | La 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.
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"
}
]
}
so4ag.json et vérifiez-le avec le validateur (étape 2)./so4ag.json avec le type application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">. La conversion est sans perte. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_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.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.
| Profil | Pour qui |
|---|---|
| General | Toute 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étail | Ce qui est propre au secteur : dépôt de garantie, limite de kilométrage, expédition, retours. |
| Le vôtre | Tout 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."
}
}
}
id et ajoutez cette adresse à profiles dans votre source.namespace + nom, c'est-à-dire 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.jsonUn 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.
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.
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
| Outil | Ce qu'il fait |
|---|---|
list_sources | Liste les sources publiées. |
get_source | Renvoie 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_claim | Indique 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"}'
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.
| Lieu | À quoi cela sert |
|---|---|
| GitHub : soqvercom/so4ag | Code, spécification, suite de conformité et versions. C'est ici que le format est développé. |
| GitHub Discussions | Le lieu de la communauté : questions, propositions et retours d'expérience sur le format. Nous répondons ici. |
| GitHub Issues | Erreurs dans la spécification et le code, cas que le format ne peut pas exprimer. |
| PyPI : so4ag | Le paquet Python : pip install so4ag |
| Versions | Le 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 Registry | L'entrée de notre serveur MCP : com.soqver/so4ag |
| Discord : SOQVER · SO4AG | Questions rapides et discussion avec d'autres personnes qui essaient le format. |
| DEV : @soqvercom | Articles techniques et guides pratiques sur le format. |
| daily.dev : @soqver | Liens vers les nouveaux articles pour les développeurs. |
| X · YouTube | Actualités sur le format et courtes démonstrations. |
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].