Blog · Guide ·
Next.js, Astro ও Nuxt থেকে so4ag.json ও JSON-LD পরিবেশন করুন
Next.js, Astro ও Nuxt-এ so4ag.json কোথায় রাখবেন, CI-তে কীভাবে সেটি যাচাই করবেন এবং একই তথ্য কীভাবে JSON-LD হিসেবে এম্বেড করবেন, তা জানুন।
Keep client facts next to the content
SO4AG (Source Objects for AGents) is an open format for business facts. Version 0.1 is a working draft. You can keep the source as plain JSON in your repository and serve it at /so4ag.json. The same facts can appear as JSON-LD on a public “Facts and terms” page.
Keeping the file next to the site content lets you review a change to a price or policy alongside the page that states it. Reviewers can see what changed, who the fact applies to, where the client states it, and when it expires. You can also make validation a required build check so malformed facts stop the build before publication. A program reading the published facts has less room for error because it can see their conditions and dates.
Start with one claim
An example from Example Plumbing shows a price of 95.00 USD per hour for a service call. The scope says what the price applies to. Every claim needs valid_from and valid_until. A claim marked known also needs at least one evidence item with a url and an observed_at timestamp. Here, the evidence points to the pricing page and records when the price was observed there.
{
"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"
}
This block is one claim. Use the specification to see how claims fit into the full source file. SO4AG 0.1 specification
Serve the source at /so4ag.json
The public/so4ag.json path works in all three frameworks. If you use a route or endpoint, run validation against the source file that supplies its response. Use one serving path for the URL.
Next.js
Place the file at public/so4ag.json to serve it from the site root. If you prefer to serve it through the App Router, use app/so4ag.json/route.ts and return the source data from the route handler with Response.json(...).
Astro
Place the file at public/so4ag.json, or create a static endpoint at src/pages/so4ag.json.ts to build /so4ag.json. With the endpoint, keep the JSON it reads in the repository so you can review and validate it before the build.
Nuxt
Place the file at public/so4ag.json. Nuxt serves files in public/ from the site root, so the URL is /so4ag.json.
Add this link to the head of the pages people read so each page points to the source file.
<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
Validate the file and generate JSON-LD
Run the validator before your site build or as a required CI step. These commands use the public/ layout. If an endpoint reads the JSON from another path, pass that path to the validator.
npm install github:soqvercom/so4ag#v0.1.4
npx so4ag-validate public/so4ag.json
The command prints VALID or INVALID. For an invalid file, it lists errors and where they occur. Configure the build or CI job to stop when validation fails. Use the reported locations to fix the source before generating the page output.
From a clone of the SO4AG repository, run the converter below with so4ag.json in the current directory. You can also pass the path to the validated file in your site repository. SO4AG source code
node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
Put the contents of facts.jsonld inside a <script type="application/ld+json"> tag on the “Facts and terms” page. Generate the script contents from the same file you serve at /so4ag.json so the two outputs carry the same facts after each update. The conversion preserves the facts, including their conditions and dates.
Ask the client to confirm the facts
You maintain the file and the build checks. The client confirms the facts and stands behind them. Before a fact reaches valid_until, ask the client to confirm its value, scope, and supporting page. For example, a price can be confirmed for up to 60 days at a time.
Update the claim and its dates after the client confirms it, then run validation and regenerate the JSON-LD. Once the last day passes, a program treats the fact as history. If the client does not state a fact, publish the claim with knowledge_state set to unknown and no value. Pages show it as "not stated".
Next step
Add public/so4ag.json to your client’s repository using the developer guide. Run the file through the public validator before adding the check to CI.