SOQVER Preparar uma fonte
Português

Guia para desenvolvedores

SO4AG é um formato aberto para fatos empresariais: cada fato traz seu significado, escopo, origem e validade. Um leitor responde a uma pergunta: este fato pode ser usado para esta tarefa neste momento e, se não, por quê.

O formato é gratuito e não exige conta. O código é licenciado sob Apache-2.0 e o texto da especificação sob CC BY 4.0.

Tudo em um só lugar

Repositório no GitHub · especificação · JSON Schema · suíte de conformidade · JSON-LD · validador no navegador · o que funciona

Conteúdo: 1. Obter o código · 2. Validar uma fonte · 3. Perguntar sobre um fato · 4. Publicar a sua própria fonte · 5. API · 6. MCP · 7. O seu próprio leitor · Qualquer setor · Onde encontrar o projeto

1. Obter o código

Você precisa do Git e do Node.js 20 ou mais recente. O leitor em Python precisa apenas da biblioteca padrão (Python 3.10 ou mais recente).

git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test

O último comando executa os testes do código de referência contra a suíte de conformidade. Todos devem passar.

Em seu próprio projeto, os pacotes são instalados com um comando cada:

npm install github:soqvercom/so4ag#v0.1.3
npx so4ag-validate https://example.com/so4ag.json

pip install so4ag
so4ag ask so4ag.json --property refundableDeposit --scope vehicle_class=economy

2. Validar uma fonte

O validador lê um arquivo ou um endereço. Ele compreende SO4AG JSON, a forma JSON-LD e uma página HTML com o JSON-LD dentro.

node validator/cli.mjs examples/valid/rental-first-party.json
node validator/cli.mjs https://example.com/so4ag.json
node validator/cli.mjs examples/valid/rental-first-party.json --json

A resposta começa com VALID ou INVALID. Para uma fonte inválida, segue uma lista de erros com o local no arquivo. Sem instalar nada, o mesmo funciona no validador no navegador.

Uma fonte válida comprova apenas a estrutura correta. Ela não afirma que o fato é verdadeiro.

3. Perguntar se um fato pode ser usado

Uma tarefa indica qual propriedade você consulta e sob quais condições (escopo). O leitor retorna cada afirmação correspondente com a resposta sobre se ela é utilizável e os motivos quando não é.

JavaScript

import { readFileSync } from 'node:fs';
import { validateManifest, selectClaims } from './validator/index.mjs';

const source = JSON.parse(readFileSync('examples/valid/rental-first-party.json', 'utf8'));
const check = validateManifest(source);          // { valid, errors, warnings, stats }

const answers = selectClaims(source, {
  property: 'https://soqver.com/spec/so4ag/0.1/rental#refundableDeposit',
  scope: { branch: 'https://rental.example/branches/prague-airport', vehicle_class: 'economy' },
});
for (const { claim, result } of answers) console.log(claim.id, result.usable, result.reasons, result.value);

Python

python readers/python/so4ag_reader.py ask examples/valid/rental-first-party.json \
  --property refundableDeposit --scope vehicle_class=economy \
  --scope branch=https://rental.example/branches/prague-airport

Experimente o mesmo sem a condição de filial ou em outro momento (--now 2027-06-01T12:00:00Z, em JavaScript o terceiro argumento { now: new Date(…) }). A afirmação deixa de ser utilizável e o leitor informa o motivo.

MotivoO que significa
expired, not_yet_validA afirmação não vale no momento da consulta.
scope_mismatch:<key>A afirmação vale para outro valor da condição, por exemplo outra filial.
scope_not_in_task:<key>A afirmação é limitada por uma condição que a tarefa não informa. Sem ela, ninguém pode dizer se a afirmação se aplica.
unknown, not_applicableO publicador declara explicitamente que o valor não é conhecido ou não se aplica. Desconhecido não é zero.
disputedA afirmação está em disputa.
no_trust_policyA tarefa pede uma afirmação revisada, mas não diz em quem confia. Em quem confiar é decisão de quem lê a afirmação.
attestation_not_authenticatedA fonte traz uma atestação com o nome de um emissor em que você confia, mas você não a autenticou junto ao emissor. Um nome escrito na fonte não é uma prova.
conflicting_claimsDuas declarações vigentes indicam valores diferentes para a mesma coisa. O leitor não usa nenhuma das duas e nunca escolhe um vencedor em silêncio.
invalid_sourceA fonte quebra a estrutura do formato (por exemplo, uma declaração sem evidência ou uma data ilegível). Nada dela é usado.
unsupported_versionA fonte é de uma versão do formato que o leitor não conhece. Ela não é lida pelas regras de outra versão.

A lista completa de motivos e regras está na especificação.

4. Publicar a sua própria fonte

Uma fonte é um arquivo JSON. A forma útil mais simples tem um publicador e uma afirmação:

{
  "so4ag": "0.1-draft",
  "id": "https://rental.example/so4ag.json",
  "revision": "2026-11-20.1",
  "published_at": "2026-11-19T20:05:00Z",
  "publisher": {
    "id": "https://rental.example/#org",
    "name": "Example Rental",
    "role": "first_party",
    "domain": "rental.example"
  },
  "profiles": ["https://soqver.com/spec/so4ag/0.1/rental"],
  "subjects": [
    { "id": "https://rental.example/#org", "type": "AutoRental", "name": "Example Rental" },
    { "id": "https://rental.example/branches/prague-airport", "type": "Place", "name": "Prague Airport" }
  ],
  "claims": [
    {
      "id": "https://rental.example/claims/deposit-economy-airport",
      "revision": "3",
      "subject": "https://rental.example/#org",
      "property": "https://soqver.com/spec/so4ag/0.1/rental#refundableDeposit",
      "knowledge_state": "known",
      "value": { "type": "money", "amount": "10000.00", "currency": "CZK" },
      "scope": { "branch": "https://rental.example/branches/prague-airport", "vehicle_class": "economy" },
      "assertion_basis": "publisher_asserted",
      "evidence": [
        { "url": "https://rental.example/terms#deposit", "observed_at": "2026-11-19T20:00:00Z", "kind": "webpage" }
      ],
      "valid_from": "2026-11-20T00:00:00Z",
      "valid_until": "2026-12-20T00:00:00Z"
    }
  ]
}
  1. Salve o arquivo como so4ag.json e confira-o com o validador (etapa 2).
  2. Disponibilize-o por HTTPS no seu domínio em /so4ag.json com o tipo application/json.
  3. Adicione um link para a fonte nas páginas para pessoas:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Para ter os mesmos fatos dentro da página, converta a fonte para JSON-LD e coloque o resultado em uma tag <script type="application/ld+json">. A conversão é sem perdas.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Defina um fim de validade para cada afirmação (valid_until) e confirme ou altere a afirmação antes que ele passe. Depois desse momento, os leitores deixam de usá-la.

Qualquer setor: o perfil General e o seu próprio perfil

O formato não está vinculado a um setor. As propriedades (o que um fato significa, seu tipo e sua unidade, e quais condições o limitam) são definidas por um perfil, e uma fonte pode usar vários perfis em conjunto.

PerfilPara quem
GeneralQualquer empresa ou organização: operador, locais e horários de funcionamento, contatos, idiomas, o que oferece e por quanto, pagamento, reserva, prazos de resposta e de entrega, cancelamento, garantia, acessibilidade, licenças, disponibilidade. 26 propriedades.
Locação de veículos, VarejoO que é específico do setor: depósito, limite de quilometragem, envio, devoluções.
O seuQualquer outra coisa. Um perfil é um arquivo JSON no seu domínio; não é preciso pedir nada a ninguém nem registrar nada.

O seu próprio perfil descreve as suas propriedades da mesma forma que os nossos: rótulo, descrição, tipo de valor, unidades, códigos permitidos e condições. A forma mínima:

{
  "id": "https://dental.example/so4ag-profile",
  "name": "Example Dental profile",
  "version": "1",
  "namespace": "https://dental.example/so4ag-profile#",
  "scope_keys": { "day_type": "weekday, weekend, public_holiday, any" },
  "properties": {
    "emergencySlot": {
      "label": { "en": "Same-day treatment of acute pain" },
      "value_types": ["boolean"],
      "required_scope": ["day_type"],
      "max_validity": "P90D",
      "description": "Whether a patient with acute pain is treated on the day of the call."
    }
  }
}
  1. Sirva o arquivo por HTTPS no endereço indicado em id e adicione esse endereço a profiles na sua fonte.
  2. Escreva a propriedade de uma declaração como namespace + nome, ou seja, https://dental.example/so4ag-profile#emergencySlot.
  3. Verifique o perfil e a fonte:
    node validator/cli.mjs --check-profile examples/profiles/dental-example-profile.json
    node validator/cli.mjs examples/valid/general-dental.json --profile examples/profiles/dental-example-profile.json

Um leitor que não conhece o seu perfil ainda usa a declaração quando a tarefa indica as suas condições; quando a tarefa não as indica, a declaração não é usada. As regras de segurança do formato valem, portanto, igualmente para todos os perfis. Um exemplo completo de um consultório odontológico com o perfil General e o seu próprio perfil está no repositório: general-dental.json. Esquema de um perfil: profile.schema.json.

Prefere não escrever o arquivo à mão? O serviço SOQVER prepara uma proposta a partir do seu site, você confirma os fatos e publica a fonte conosco ou faz o download para o próprio domínio: preparar uma fonte.

5. Ler fontes publicadas pela API

A interface é somente leitura e não exige conta nem chave.

curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"

O primeiro endereço retorna a lista de fontes que uma empresa publicou ou confirmou. O segundo avalia as afirmações de uma fonte para a sua tarefa e retorna usable e reasons para cada uma. Cada fonte também é uma página para pessoas (/s/<slug>/), um arquivo /s/<slug>/so4ag.json e uma forma JSON-LD /s/<slug>/facts.jsonld.

6. Conectar um agente pelo MCP

O servidor MCP é somente leitura, não exige conta e usa o transporte Streamable HTTP. No MCP Registry oficial, ele está listado como com.soqver/so4ag.

https://soqver.com/mcp
FerramentaO que faz
list_sourcesLista as fontes publicadas.
get_sourceRetorna a fonte completa de uma empresa.
get_claimsAvalia as afirmações de uma fonte para uma propriedade e condições determinadas.
check_claimInforma se uma afirmação pode ser usada agora e por que não.

Em um cliente que aceita servidores MCP remotos, informe o endereço acima. Você também pode conferir a resposta do servidor pela linha de comando:

curl -s https://soqver.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

7. Escrever o seu próprio leitor

A suíte de conformidade é JSON puro e não precisa de nenhum código nosso. Ela contém duas fontes válidas em três formas, os resumos esperados das declarações, 45 casos de avaliação, 31 casos de validação, 10 casos de fonte inteira e 25 vetores da forma canônica (RFC 8785).

python readers/python/so4ag_reader.py conformance spec/conformance/0.1

As condições em que um leitor ou um validador passa na suíte estão descritas na descrição da suíte de conformidade. O leitor em Python foi escrito de forma independente do código de referência e passa na mesma suíte; você pode usá-lo como modelo.

Onde encontrar o projeto

LocalPara que serve
GitHub: soqvercom/so4agCódigo, especificação, suíte de conformidade e versões. É aqui que o formato é desenvolvido.
GitHub DiscussionsO espaço da comunidade: perguntas, propostas e experiência com o formato. Respondemos aqui.
GitHub IssuesErros na especificação e no código, casos que o formato não consegue expressar.
PyPI: so4agO pacote Python: pip install so4ag
VersõesO pacote JavaScript e os arquivos de cada versão: npm install github:soqvercom/so4ag
Zenodo (DOI)Um link permanente para as versões, para citação em artigos e na documentação.
Registro MCPA entrada do nosso servidor MCP: com.soqver/so4ag
Discord: SOQVER · SO4AGPerguntas rápidas e uma conversa com outras pessoas que experimentam o formato.
DEV: @soqvercomArtigos técnicos e textos práticos sobre o formato.
daily.dev: @soqverLinks para novos artigos para desenvolvedores.
X · YouTubeNotícias sobre o formato e demonstrações curtas.

Comentários e erros

Encontrou um fato que o formato não consegue expressar, ou dois leitores que respondem de formas diferentes? Registre como uma issue no GitHub. Informe uma vulnerabilidade por e-mail para [email protected].