Blog · Handleiding ·
so4ag.json en JSON-LD aanbieden vanuit Next.js, Astro en Nuxt
Lees waar u so4ag.json plaatst in Next.js, Astro en Nuxt, hoe u het bestand in CI valideert en hoe u dezelfde feiten als JSON-LD insluit.
Bewaar de feiten van uw klant bij de website-inhoud
SO4AG (Source Objects for AGents) is een open formaat voor bedrijfsfeiten. Versie 0.1 is een werkconcept. U kunt de bron als gewoon JSON-bestand in uw repository bewaren en beschikbaar stellen op /so4ag.json. Dezelfde feiten kunnen als JSON-LD op een openbare pagina ‘Feiten en voorwaarden’ staan.
Als u het bestand bij de website-inhoud bewaart, kunt u een wijziging in een prijs of beleid beoordelen naast de pagina waarop die staat. Beoordelaars zien wat er is gewijzigd, voor wie het feit geldt, waar de klant het vermeldt en wanneer het vervalt. U kunt validatie ook verplicht maken bij het bouwen van de site, zodat onjuist gestructureerde feiten de build vóór publicatie stoppen. Software die de gepubliceerde feiten leest, kan ze nauwkeuriger interpreteren doordat de voorwaarden en datums erbij staan.
Begin met één bewering
Een voorbeeld van Example Plumbing vermeldt een tarief van 95.00 USD per uur voor een servicebezoek. Het veld scope geeft aan waarvoor de prijs geldt. Elke bewering heeft valid_from en valid_until nodig. Een bewering met de markering known vereist ook minstens één bewijsitem met een url en een tijdstempel observed_at. In dit voorbeeld verwijst het bewijs naar de tarievenpagina en legt het vast wanneer de prijs daar is waargenomen.
{
"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"
}
Dit blok bevat één bewering. In de specificatie ziet u hoe beweringen in het volledige bronbestand passen. Specificatie van SO4AG 0.1
Stel de bron beschikbaar op /so4ag.json
Het pad public/so4ag.json werkt in alle drie de frameworks. Gebruikt u een route of endpoint, valideer dan het bronbestand dat de gegevens voor de respons levert. Gebruik één pad om het bestand op die URL beschikbaar te stellen.
Next.js
Plaats het bestand op public/so4ag.json om het vanuit de hoofdmap van de site beschikbaar te stellen. Wilt u het via de App Router aanbieden, gebruik dan app/so4ag.json/route.ts en geef de brongegevens vanuit de routehandler terug met Response.json(...).
Astro
Plaats het bestand op public/so4ag.json of maak een statisch endpoint op src/pages/so4ag.json.ts om /so4ag.json te genereren. Gebruikt u het endpoint, bewaar dan de JSON die het uitleest in de repository, zodat u die vóór de build kunt beoordelen en valideren.
Nuxt
Plaats het bestand op public/so4ag.json. Nuxt stelt bestanden in public/ beschikbaar vanuit de hoofdmap van de site, dus de URL is /so4ag.json.
Voeg deze link toe aan de head van de pagina’s die bezoekers lezen, zodat elke pagina naar het bronbestand verwijst.
<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
Valideer het bestand en genereer JSON-LD
Voer de validator uit vóór de build van uw site of als verplichte CI-stap. Deze opdrachten gaan uit van de structuur van public/. Leest een endpoint de JSON vanaf een ander pad, geef dat pad dan door aan de validator.
npm install github:soqvercom/so4ag#v0.1.4
npx so4ag-validate public/so4ag.json
De opdracht geeft VALID of INVALID weer. Bij een ongeldig bestand vermeldt de opdracht de fouten en waar ze voorkomen. Stel de build of CI-taak zo in dat deze stopt als de validatie mislukt. Gebruik de gemelde locaties om de bron te corrigeren voordat u de uitvoer voor de pagina genereert.
Voer in een kloon van de SO4AG-repository de onderstaande converter uit met so4ag.json in de huidige map. U kunt ook het pad naar het gevalideerde bestand in de repository van uw site doorgeven. SO4AG-broncode
node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
Plaats de inhoud van facts.jsonld in een <script type="application/ld+json">-tag op de pagina ‘Feiten en voorwaarden’. Genereer de scriptinhoud uit hetzelfde bestand dat u op /so4ag.json aanbiedt, zodat beide versies na elke update dezelfde feiten bevatten. Bij de omzetting blijven de feiten, hun voorwaarden en hun datums behouden.
Vraag uw klant de feiten te bevestigen
U beheert het bestand en de buildcontroles. Uw klant bevestigt de feiten en staat ervoor in. Vraag uw klant voordat een feit op valid_until terechtkomt om de waarde, het toepassingsbereik en de onderbouwende pagina te bevestigen. Een prijs kan bijvoorbeeld voor maximaal 60 dagen per keer worden bevestigd.
Werk de bewering en de bijbehorende datums bij nadat uw klant die heeft bevestigd. Voer daarna de validatie uit en genereer de JSON-LD opnieuw. Na de laatste geldigheidsdag behandelt software het feit als historisch gegeven. Vermeldt uw klant een feit niet, publiceer de bewering dan zonder waarde en stel knowledge_state in op unknown. Op de pagina’s staat dan ‘niet vermeld’.
Volgende stap
Voeg public/so4ag.json toe aan de repository van uw klant met behulp van de handleiding voor ontwikkelaars. Controleer het bestand met de openbare validator voordat u de controle aan CI toevoegt.