SOQVER Preparar uma fonte
Português

Blog · Guia ·

Como disponibilizar so4ag.json e JSON-LD com Next.js, Astro e Nuxt

Saiba onde colocar o arquivo so4ag.json em projetos com Next.js, Astro e Nuxt, como validá-lo na integração contínua e como incorporar as mesmas informações em JSON-LD.

Mantenha os fatos do cliente junto ao conteúdo

SO4AG (Source Objects for AGents) é um formato aberto para fatos sobre empresas. A versão 0.1 é um rascunho em desenvolvimento. É possível manter a fonte como JSON simples no seu repositório e disponibilizá-la em /so4ag.json. Os mesmos fatos podem aparecer como JSON-LD em uma página pública de “Fatos e condições”.

Manter o arquivo junto ao conteúdo do site permite revisar uma alteração de preço ou política ao lado da página em que ela é informada. Quem faz a revisão pode ver o que mudou, a quem o fato se aplica, onde o cliente o informa e quando ele expira. Também é possível tornar a validação obrigatória no build para que fatos malformados interrompam o processo antes da publicação. Um programa que lê os fatos publicados tem menos margem para erro porque pode consultar suas condições e datas.

Comece com uma afirmação

Um exemplo da Example Plumbing mostra um preço de 95.00 USD por hora para um chamado de serviço. O campo scope indica a que o preço se aplica. Toda afirmação precisa de valid_from e valid_until. Uma afirmação marcada como known também precisa de pelo menos uma evidência com url e um registro de data e hora observed_at. Neste caso, a evidência aponta para a página de preços e registra quando o preço foi observado nela.

{
  "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"
}

Este bloco contém uma afirmação. Consulte a especificação para ver como as afirmações se encaixam no arquivo-fonte completo. Especificação do SO4AG 0.1

Disponibilize a fonte em /so4ag.json

O caminho public/so4ag.json funciona nos três frameworks. Se usar uma rota ou um endpoint, execute a validação no arquivo-fonte que fornece os dados da resposta. Use um único caminho para disponibilizar o arquivo na URL.

Next.js

Coloque o arquivo em public/so4ag.json para disponibilizá-lo na raiz do site. Se preferir disponibilizá-lo pelo App Router, use app/so4ag.json/route.ts e retorne os dados da fonte do manipulador da rota com Response.json(...).

Astro

Coloque o arquivo em public/so4ag.json ou crie um endpoint estático em src/pages/so4ag.json.ts para gerar /so4ag.json. Se usar o endpoint, mantenha o JSON que ele lê no repositório para poder revisá-lo e validá-lo antes do build.

Nuxt

Coloque o arquivo em public/so4ag.json. O Nuxt disponibiliza os arquivos de public/ na raiz do site, portanto a URL é /so4ag.json.

Adicione este link ao head das páginas que as pessoas leem para que cada página aponte para o arquivo-fonte.

<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">

Valide o arquivo e gere o JSON-LD

Execute o validador antes do build do site ou como etapa obrigatória da CI. Estes comandos usam a estrutura public/. Se um endpoint ler o JSON de outro caminho, passe esse caminho ao validador.

npm install github:soqvercom/so4ag#v0.1.4
npx so4ag-validate public/so4ag.json

O comando exibe VALID ou INVALID. Se o arquivo for inválido, ele lista os erros e indica onde ocorrem. Configure o build ou a tarefa da CI para interromper a execução se a validação falhar. Use os locais indicados para corrigir a fonte antes de gerar a saída da página.

A partir de um clone do repositório do SO4AG, execute o conversor abaixo com so4ag.json no diretório atual. Também é possível passar o caminho do arquivo validado no repositório do seu site. Código-fonte do SO4AG

node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld

Insira o conteúdo de facts.jsonld dentro de uma tag <script type="application/ld+json"> na página “Fatos e condições”. Gere o conteúdo do script a partir do mesmo arquivo disponibilizado em /so4ag.json para que as duas saídas contenham os mesmos fatos após cada atualização. A conversão preserva os fatos, inclusive suas condições e datas.

Peça ao cliente que confirme os fatos

Você mantém o arquivo e as verificações do build. O cliente confirma os fatos e se responsabiliza por eles. Antes de um fato chegar a valid_until, peça ao cliente que confirme seu valor, seu escopo e a página que o comprova. Um preço, por exemplo, pode ser confirmado por até 60 dias de cada vez.

Atualize a afirmação e suas datas após a confirmação do cliente. Em seguida, execute a validação e gere novamente o JSON-LD. Depois do último dia de validade, um programa passa a tratar o fato como um dado histórico. Se o cliente não informar um fato, publique a afirmação com knowledge_state definido como unknown e sem valor. Nas páginas, ele aparece como “não informado”.

Próximo passo

Adicione public/so4ag.json ao repositório do seu cliente seguindo o guia para desenvolvedores. Verifique o arquivo com o validador público antes de adicionar a verificação à CI.

Mais artigos

Guia ·

Como publicar as informações da sua empresa em um site WordPress

Instale o SO4AG Facts no WordPress, adicione informações da sua empresa com condições e datas e publique uma página de Informações e condições que pode ser conferida no painel de administração.

Guia ·

Transforme os dados de frete, pagamentos e devoluções do WooCommerce em informações estruturadas

Use o SO4AG Facts para revisar as sugestões de frete e pagamento do WooCommerce e depois adicione manualmente os prazos de devolução, os prazos de entrega e outras condições.

Guia ·

Shopify: como publicar informações e condições sem um aplicativo

Saiba como publicar uma página de Informações e condições na Shopify, adicionar JSON-LD e criar um link para um arquivo SO4AG hospedado quando não for possível colocar o arquivo na raiz do domínio da loja.

Auditoria gratuita do site Todos os artigos