SOQVER Preparar una fuente
Español

Guía para desarrolladores

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.

Todo en un solo lugar

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

1. Obtener el código

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

2. Validar una fuente

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.

3. Preguntar si un dato puede usarse

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.

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

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é.

MotivoQué significa
expired, not_yet_validLa 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_applicableEl publicador declara de forma explícita que el valor no se conoce o no procede. Desconocido no es cero.
disputedLa afirmación está en disputa.
no_trust_policyLa 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_authenticatedLa 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_claimsDos afirmaciones vigentes indican valores distintos para lo mismo. El lector no usa ninguna y nunca elige un ganador en silencio.
invalid_sourceLa fuente incumple la estructura del formato (por ejemplo, una afirmación sin evidencia o una fecha ilegible). No se usa nada de ella.
unsupported_versionLa 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.

4. Publicar su propia fuente

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"
    }
  ]
}
  1. Guarde el archivo como so4ag.json y compruébelo con el validador (paso 2).
  2. Sírvala por HTTPS en su dominio en /so4ag.json con el tipo application/json.
  3. Añada un enlace a la fuente en las páginas para las personas:
    <link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">
  4. Para tener los mismos hechos dentro de la página, convierta la fuente a JSON-LD e inserte el resultado en una etiqueta <script type="application/ld+json">. La conversión no tiene pérdidas.
    node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld
  5. Asigne a cada afirmación un fin de validez (valid_until) y confirme o modifique la afirmación antes de que venza. A partir de ese momento, los lectores dejan de utilizarla.

Cualquier sector: el perfil General y su propio perfil

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.

PerfilPara quién
GeneralCualquier 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 minoristaLo específico del sector: depósito, límite de kilometraje, envío, devoluciones.
PropioCualquier 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."
    }
  }
}
  1. Sirva el archivo por HTTPS en la dirección indicada en id y añada esa dirección a profiles en su fuente.
  2. Escriba la propiedad de una afirmación como namespace + nombre, es decir, https://dental.example/so4ag-profile#emergencySlot.
  3. Compruebe el perfil y la fuente:
    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

Un 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.

5. Leer las fuentes publicadas a través de la API

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.

6. Conectar un agente a través de MCP

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
HerramientaQué hace
list_sourcesLista las fuentes publicadas.
get_sourceDevuelve la fuente completa de una empresa.
get_claimsEvalúa las afirmaciones de una fuente para una propiedad y unas condiciones dadas.
check_claimIndica 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"}'

7. Escribir su propio lector

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.

Dónde encontrar el proyecto

LugarPara qué sirve
GitHub: soqvercom/so4agCódigo, especificación, suite de conformidad y versiones. Aquí se desarrolla el formato.
GitHub DiscussionsEl lugar de la comunidad: preguntas, propuestas y experiencia con el formato. Aquí respondemos.
GitHub IssuesErrores en la especificación y en el código, y casos que el formato no puede expresar.
PyPI: so4agEl paquete de Python: pip install so4ag
VersionesEl 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 RegistryLa entrada de nuestro servidor MCP: com.soqver/so4ag
Discord: SOQVER · SO4AGPreguntas rápidas y una conversación con otras personas que prueban el formato.
DEV: @soqvercomArtículos técnicos y textos prácticos sobre el formato.
daily.dev: @soqverEnlaces a artículos nuevos para desarrolladores.
X · YouTubeNoticias sobre el formato y demostraciones breves.

Comentarios y errores

¿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].