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.