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ファイルへのリンクを設置します。

ウェブサイト無料診断 すべての記事