SO4AG es un formato abierto para hechos empresariales: cada hecho incluye su significado, ámbito, origen y validez. Un lector responde a una pregunta: si este hecho puede utilizarse para esta tarea en este momento y, si no, por qué.
El formato es gratuito y no requiere cuenta. El código se licencia bajo Apache-2.0 y el texto de la especificación, bajo CC BY 4.0.
Repositorio en GitHub · especificación · JSON Schema · conjunto de conformidad · JSON-LD · validador en el navegador · qué funciona
Contenidos: 1. Obtener el código · 2. Validar una fuente · 3. Preguntar por un dato · 4. Publicar su propia fuente · 5. API · 6. MCP · 7. Su propio lector · Cualquier sector · Dónde encontrar el proyecto
Necesita Git y Node.js 20 o posterior. El lector en Python solo necesita la biblioteca estándar (Python 3.10 o posterior).
git clone https://github.com/soqvercom/so4ag.git
cd so4ag
npm install
npm test
El último comando ejecuta las pruebas del código de referencia contra el conjunto de conformidad. Todas deben superarse.
Los paquetes se instalan en su propio proyecto con un comando cada uno:
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
El validador lee un archivo o una dirección. Entiende el JSON de SO4AG, la forma JSON-LD y una página HTML con el 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
La respuesta empieza por VALID o INVALID. Si la fuente no es válida, sigue una lista de errores con su lugar en el archivo. Sin instalar nada, lo mismo funciona en el validador en el navegador.
Una fuente válida solo demuestra que la estructura es correcta. No indica que el hecho sea verdadero.
Una tarea indica qué propiedad se consulta y en qué condiciones (ámbito). El lector devuelve cada afirmación coincidente con la respuesta de si es utilizable y los motivos cuando no lo es.
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
Pruebe lo mismo sin la condición de sucursal o en otro momento (--now 2027-06-01T12:00:00Z; en JavaScript, el tercer argumento { now: new Date(…) }). La afirmación deja de ser utilizable y el lector indica por qué.
| Motivo | Qué significa |
|---|---|
expired, not_yet_valid | La afirmación no se cumple en el momento de la consulta. |
scope_mismatch:<key> | La afirmación se cumple para otro valor de la condición, por ejemplo otra sucursal. |
scope_not_in_task:<key> | La afirmación está limitada por una condición que la tarea no indica. Sin ella, nadie puede decir si la afirmación es aplicable. |
unknown, not_applicable | El publicador declara de forma explícita que el valor no se conoce o no procede. Desconocido no es cero. |
disputed | La afirmación está en disputa. |
no_trust_policy | La tarea pide una afirmación revisada, pero no indica en quién confía. En quién confiar es decisión de quien lee la afirmación. |
attestation_not_authenticated | La fuente lleva una atestación con el nombre de un emisor en el que usted confía, pero usted no la ha autenticado con el emisor. Un nombre escrito en la fuente no es una prueba. |
conflicting_claims | Dos afirmaciones vigentes indican valores distintos para lo mismo. El lector no usa ninguna y nunca elige un ganador en silencio. |
invalid_source | La fuente incumple la estructura del formato (por ejemplo, una afirmación sin evidencia o una fecha ilegible). No se usa nada de ella. |
unsupported_version | La fuente corresponde a una versión del formato que el lector no conoce. No se lee según las reglas de otra versión. |
La lista completa de motivos y reglas está en la especificación.
Una fuente es un archivo JSON. La forma útil más pequeña tiene un publicador y una afirmación:
{
"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 y compruébelo con el validador (paso 2)./so4ag.json con el tipo application/json.<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest"><script type="application/ld+json">. La conversión no tiene pérdidas. node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonldvalid_until) y confirme o modifique la afirmación antes de que venza. A partir de ese momento, los lectores dejan de utilizarla.El formato no está ligado a un sector. Las propiedades (qué significa un dato, su tipo y su unidad, y qué condiciones lo limitan) las establece un perfil, y una fuente puede usar varios perfiles a la vez.
| Perfil | Para quién |
|---|---|
| General | Cualquier empresa u organización: operador, lugares y horarios de apertura, contactos, idiomas, qué ofrece y por cuánto, pago, reserva, tiempos de respuesta y de entrega, cancelación, garantía, accesibilidad, licencias, disponibilidad. 26 propiedades. |
| Alquiler de vehículos, Comercio minorista | Lo específico del sector: depósito, límite de kilometraje, envío, devoluciones. |
| Propio | Cualquier otra cosa. Un perfil es un archivo JSON en su dominio; no consulta a nadie ni registra nada. |
Su propio perfil describe sus propiedades del mismo modo que los nuestros: etiqueta, descripción, tipo de valor, unidades, códigos permitidos y condiciones. La 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 y añada esa dirección a profiles en su fuente.namespace + nombre, es decir, 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.jsonUn lector que no conoce su perfil usa de todos modos la afirmación cuando la tarea indica sus condiciones; cuando la tarea no las indica, la afirmación no se usa. Las reglas de seguridad del formato rigen, por tanto, por igual para todos los perfiles. Un ejemplo completo de una clínica dental con el perfil General y su propio perfil está en el repositorio: general-dental.json. Esquema de un perfil: profile.schema.json.
¿Prefiere no escribir el archivo a mano? El servicio SOQVER prepara una propuesta a partir de su sitio web; usted confirma los hechos y publica la fuente con nosotros o la descarga para su propio dominio: preparar una fuente.
La interfaz es de solo lectura y no requiere cuenta ni clave.
curl https://soqver.com/api/v1/sources
curl "https://soqver.com/api/v1/sources/<slug>/claims?property=<name>&scope.<key>=<value>"
La primera dirección devuelve la lista de fuentes que una empresa publicó o confirmó. La segunda evalúa las afirmaciones de una fuente para su tarea y devuelve usable y reasons para cada una. Cada fuente es también una página para personas (/s/<slug>/), un archivo /s/<slug>/so4ag.json y una forma JSON-LD /s/<slug>/facts.jsonld.
El servidor MCP es de solo lectura, no requiere cuenta y utiliza el transporte Streamable HTTP. En el MCP Registry oficial figura como com.soqver/so4ag.
https://soqver.com/mcp
| Herramienta | Qué hace |
|---|---|
list_sources | Lista las fuentes publicadas. |
get_source | Devuelve la fuente completa de una empresa. |
get_claims | Evalúa las afirmaciones de una fuente para una propiedad y unas condiciones dadas. |
check_claim | Indica si una afirmación puede usarse ahora y por qué no. |
En un cliente que admita servidores MCP remotos, introduzca la dirección anterior. También puede comprobar la respuesta del servidor desde la línea de comandos:
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"}'
La suite de conformidad es JSON simple y no necesita nada de nuestro código. Contiene dos fuentes válidas en tres formas, los resúmenes esperados de las afirmaciones, 45 casos de evaluación, 31 casos de validación, 10 casos de fuente completa y 25 vectores de la forma canónica (RFC 8785).
python readers/python/so4ag_reader.py conformance spec/conformance/0.1
Cuándo un lector o un validador supera la suite se describe en la descripción de la suite de conformidad. El lector en Python se escribió de forma independiente del código de referencia y supera la misma suite; puede usarlo como modelo.
| Lugar | Para qué sirve |
|---|---|
| GitHub: soqvercom/so4ag | Código, especificación, suite de conformidad y versiones. Aquí se desarrolla el formato. |
| GitHub Discussions | El lugar de la comunidad: preguntas, propuestas y experiencia con el formato. Aquí respondemos. |
| GitHub Issues | Errores en la especificación y en el código, y casos que el formato no puede expresar. |
| PyPI: so4ag | El paquete de Python: pip install so4ag |
| Versiones | El paquete de JavaScript y los archivos de cada versión: npm install github:soqvercom/so4ag |
| Zenodo (DOI) | Un enlace permanente a las versiones para citarlas en artículos y documentación. |
| MCP Registry | La entrada de nuestro servidor MCP: com.soqver/so4ag |
| Discord: SOQVER · SO4AG | Preguntas rápidas y una conversación con otras personas que prueban el formato. |
| DEV: @soqvercom | Artículos técnicos y textos prácticos sobre el formato. |
| daily.dev: @soqver | Enlaces a artículos nuevos para desarrolladores. |
| X · YouTube | Noticias sobre el formato y demostraciones breves. |
¿Ha encontrado un dato que el formato no puede expresar, o dos lectores que responden de forma distinta? Escríbalo como una incidencia en GitHub. Informe de una vulnerabilidad por correo electrónico a [email protected].