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.
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
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
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.
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 é.
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 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.
| Motivo | O que significa |
|---|---|
expired, not_yet_valid | A 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_applicable | O publicador declara explicitamente que o valor não é conhecido ou não se aplica. Desconhecido não é zero. |
disputed | A afirmação está em disputa. |
no_trust_policy | A 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_authenticated | A 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_claims | Duas 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_source | A fonte quebra a estrutura do formato (por exemplo, uma declaração sem evidência ou uma data ilegível). Nada dela é usado. |
unsupported_version | A 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.
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"
}
]
}
so4ag.json e confira-o com o validador (etapa 2)./so4ag.json com o tipo application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">. A conversão é sem perdas. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) e confirme ou altere a afirmação antes que ele passe. Depois desse momento, os leitores deixam de usá-la.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.
| Perfil | Para quem |
|---|---|
| General | Qualquer 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, Varejo | O que é específico do setor: depósito, limite de quilometragem, envio, devoluções. |
| O seu | Qualquer 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."
}
}
}
id e adicione esse endereço a profiles na sua fonte.namespace + nome, ou seja, https://dental.example/so4ag-profile#emergencySlot.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.jsonUm 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.
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.
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
| Ferramenta | O que faz |
|---|---|
list_sources | Lista as fontes publicadas. |
get_source | Retorna a fonte completa de uma empresa. |
get_claims | Avalia as afirmações de uma fonte para uma propriedade e condições determinadas. |
check_claim | Informa 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"}'
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.
| Local | Para que serve |
|---|---|
| GitHub: soqvercom/so4ag | Código, especificação, suíte de conformidade e versões. É aqui que o formato é desenvolvido. |
| GitHub Discussions | O espaço da comunidade: perguntas, propostas e experiência com o formato. Respondemos aqui. |
| GitHub Issues | Erros na especificação e no código, casos que o formato não consegue expressar. |
| PyPI: so4ag | O pacote Python: pip install so4ag |
| Versões | O 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 MCP | A entrada do nosso servidor MCP: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Perguntas rápidas e uma conversa com outras pessoas que experimentam o formato. |
| DEV: @soqvercom | Artigos técnicos e textos práticos sobre o formato. |
| daily.dev: @soqver | Links para novos artigos para desenvolvedores. |
| X · YouTube | Notícias sobre o formato e demonstrações curtas. |
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].