SOQVER Chuẩn bị nguồn
Tiếng Việt

Blog · Guide ·

Cung cấp so4ag.json và JSON-LD từ Next.js, Astro và Nuxt

Tìm hiểu vị trí đặt so4ag.json trong Next.js, Astro và Nuxt, cách xác thực tệp trong CI và cách nhúng cùng dữ liệu dưới dạng 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

Hướng dẫn ·

Cách công bố dữ liệu doanh nghiệp của quý vị trên trang web WordPress

Cài đặt SO4AG Facts trên WordPress, bổ sung thông tin doanh nghiệp kèm điều kiện và ngày áp dụng, rồi xuất bản trang Dữ liệu và điều khoản để kiểm tra từ giao diện quản trị.

Hướng dẫn ·

Chuyển thông tin vận chuyển, thanh toán và trả hàng trên WooCommerce thành dữ liệu có cấu trúc

Dùng SO4AG Facts để xem các đề xuất về vận chuyển và thanh toán trên WooCommerce, sau đó tự nhập thời hạn trả hàng, thời gian giao hàng và các điều khoản khác.

Hướng dẫn ·

Shopify: Cách công bố dữ liệu và điều khoản mà không cần ứng dụng

Tìm hiểu cách xuất bản trang Dữ liệu và điều khoản trên Shopify, thêm JSON-LD và liên kết đến tệp SO4AG được lưu trữ khi không thể đặt tệp ở thư mục gốc của tên miền cửa hàng.

Kiểm tra trang web miễn phí Tất cả bài viết