SOQVER 准备来源
简体中文

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.

More articles

指南 ·

如何在 WordPress 网站上发布您的商家事实信息

在 WordPress 中安装 SO4AG Facts,添加商家信息及其适用条件和日期,然后发布可在管理后台查看的“事实与条款”页面。

指南 ·

将 WooCommerce 的配送、付款和退货规则整理为事实信息

使用 SO4AG Facts 审阅根据 WooCommerce 设置生成的配送和付款建议,然后手动添加退货期限、送达时间和其他条款。

指南 ·

Shopify:如何在不安装应用的情况下发布事实与条款

了解如何在 Shopify 上发布“事实与条款”页面并添加 JSON-LD,以及在无法将文件放在店铺域名根目录时,如何添加指向托管 SO4AG 文件的链接。

免费网站审核 全部文章