Blog · Guide ·
Servir so4ag.json et du JSON-LD avec Next.js, Astro et Nuxt
Découvrez où placer so4ag.json dans Next.js, Astro et Nuxt, comment le valider en intégration continue et comment intégrer les mêmes informations au format JSON-LD.
Conservez les faits du client avec le contenu du site
SO4AG (Source Objects for AGents) est un format ouvert pour les faits d’entreprise. La version 0.1 est un document de travail. Vous pouvez conserver la source au format JSON dans votre dépôt et la servir à l’adresse /so4ag.json. Les mêmes faits peuvent figurer au format JSON-LD sur une page publique « Faits et conditions ».
En conservant le fichier avec le contenu du site, vous pouvez examiner une modification de prix ou de politique en même temps que la page qui l’annonce. Les personnes chargées de la révision peuvent voir ce qui a changé, à qui le fait s’applique, où le client l’énonce et quand il expire. Vous pouvez aussi rendre la validation obligatoire lors de la compilation, afin que les faits mal formatés bloquent la compilation avant la publication. Un logiciel qui lit les faits publiés risque moins de se tromper, car il a accès à leurs conditions et à leurs dates.
Commencez par une seule assertion
Un exemple d’Example Plumbing indique un tarif de 95.00 USD par heure pour une intervention. Le champ scope précise à quoi le tarif s’applique. Chaque assertion requiert valid_from et valid_until. Une assertion portant la mention known nécessite aussi au moins un élément de preuve avec un champ url et un horodatage observed_at. Ici, la preuve renvoie à la page des tarifs et indique quand le prix y a été relevé.
{
"id": "https://plumbing.example/so4ag.json#price-hour",
"subject": "https://plumbing.example/#org",
"property": "https://soqver.com/spec/so4ag/0.1/general#price",
"knowledge_state": "known",
"value": {
"type": "money",
"amount": "95.00",
"currency": "USD"
},
"scope": {
"item": "service call",
"per": "hour"
},
"assertion_basis": "publisher_asserted",
"evidence": [
{
"url": "https://plumbing.example/prices",
"observed_at": "2026-11-20T15:00:00Z",
"kind": "webpage"
}
],
"valid_from": "2026-11-20T00:00:00Z",
"valid_until": "2027-01-15T00:00:00Z"
}
Ce bloc correspond à une assertion. Consultez la spécification pour voir comment les assertions s’intègrent au fichier source complet. Spécification SO4AG 0.1
Servez la source à l’adresse /so4ag.json
Le chemin public/so4ag.json fonctionne avec les trois frameworks. Si vous utilisez une route ou un point de terminaison, validez le fichier source qui fournit les données de la réponse. Utilisez un seul mode de diffusion pour cette URL.
Next.js
Placez le fichier dans public/so4ag.json pour le servir depuis la racine du site. Si vous préférez le servir via App Router, utilisez app/so4ag.json/route.ts et renvoyez les données source depuis le gestionnaire de route avec Response.json(...).
Astro
Placez le fichier dans public/so4ag.json ou créez un point de terminaison statique à l’emplacement src/pages/so4ag.json.ts pour générer /so4ag.json. Si vous utilisez ce point de terminaison, conservez le JSON qu’il lit dans le dépôt pour pouvoir le vérifier et le valider avant la compilation.
Nuxt
Placez le fichier dans public/so4ag.json. Nuxt sert les fichiers de public/ depuis la racine du site. L’URL est donc /so4ag.json.
Ajoutez ce lien dans la section head des pages consultées par les visiteurs pour que chacune renvoie au fichier source.
<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
Validez le fichier et générez le JSON-LD
Exécutez le validateur avant la compilation du site ou imposez cette étape dans la CI. Ces commandes utilisent la structure public/. Si un point de terminaison lit le JSON depuis un autre emplacement, transmettez ce chemin au validateur.
npm install github:soqvercom/so4ag#v0.1.4
npx so4ag-validate public/so4ag.json
La commande affiche VALID ou INVALID. Si le fichier est invalide, elle indique les erreurs et leur emplacement. Configurez la compilation ou la tâche de CI pour qu’elle s’arrête si la validation échoue. Utilisez les emplacements indiqués pour corriger la source avant de générer le contenu de la page.
Depuis un clone du dépôt SO4AG, exécutez le convertisseur ci-dessous avec so4ag.json dans le répertoire courant. Vous pouvez aussi lui transmettre le chemin du fichier validé dans le dépôt de votre site. Code source de SO4AG
node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
Insérez le contenu de facts.jsonld dans une balise <script type="application/ld+json"> sur la page « Faits et conditions ». Générez le contenu du script à partir du fichier que vous servez à l’adresse /so4ag.json pour que les deux versions contiennent les mêmes faits après chaque mise à jour. La conversion préserve les faits, y compris leurs conditions et leurs dates.
Demandez au client de confirmer les faits
Vous assurez la maintenance du fichier et des contrôles de compilation. Le client confirme les faits et s’en porte garant. Avant de publier un fait à l’adresse valid_until, demandez au client d’en confirmer la valeur, le champ d’application et la page qui l’atteste. Par exemple, un prix peut être confirmé pour 60 jours au maximum à la fois.
Une fois que le client a confirmé l’assertion, mettez-la à jour avec ses dates, puis lancez la validation et régénérez le JSON-LD. Passé le dernier jour de validité, un logiciel considère le fait comme une donnée historique. Si le client ne précise pas un fait, publiez l’assertion sans valeur et définissez knowledge_state sur unknown. Les pages l’affichent avec la mention « non précisé ».
Étape suivante
Ajoutez public/so4ag.json au dépôt de votre client en suivant le guide de développement. Vérifiez le fichier à l’aide du validateur public avant d’ajouter le contrôle à la CI.