SOQVER Preparar una fuente
Español

Blog · Guía ·

Cómo servir so4ag.json y JSON-LD desde Next.js, Astro y Nuxt

Aprenda dónde colocar so4ag.json en Next.js, Astro y Nuxt, cómo validarlo en el proceso de integración continua y cómo incrustar los mismos datos como JSON-LD.

Mantenga los datos del cliente junto al contenido

SO4AG (Source Objects for AGents) es un formato abierto para datos empresariales. La versión 0.1 es un borrador de trabajo. Puede guardar la fuente como JSON sin procesar en su repositorio y servirla en /so4ag.json. Los mismos datos pueden aparecer como JSON-LD en una página pública de «Datos y condiciones».

Guardar el archivo junto al contenido del sitio le permite revisar un cambio de precio o de política junto con la página que lo indica. Quienes revisen el cambio pueden ver qué cambió, a quién se aplica el dato, dónde lo declara el cliente y cuándo vence. También puede hacer que la validación sea obligatoria durante la compilación, de modo que los datos con errores de formato detengan el proceso antes de la publicación. Los programas que leen los datos publicados tienen menos margen de error porque pueden consultar sus condiciones y fechas.

Empiece con una afirmación

Un ejemplo de Example Plumbing muestra un precio de 95.00 USD por hora por una visita de servicio. El campo scope indica a qué se aplica el precio. Cada afirmación requiere valid_from y valid_until. Una afirmación marcada como known también requiere al menos un elemento de evidencia con url y una marca de tiempo observed_at. En este caso, la evidencia remite a la página de precios y registra cuándo se observó allí el precio.

{
  "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 bloque contiene una sola afirmación. Consulte la especificación para ver cómo se integran las afirmaciones en el archivo fuente completo. Especificación de SO4AG 0.1

Sirva la fuente en /so4ag.json

La ruta public/so4ag.json funciona en los tres frameworks. Si usa una ruta o un endpoint, valide el archivo fuente que proporciona los datos de la respuesta. Use una sola ruta para servir el archivo en esa URL.

Next.js

Coloque el archivo en public/so4ag.json para servirlo desde la raíz del sitio. Si prefiere servirlo mediante App Router, use app/so4ag.json/route.ts y devuelva los datos de la fuente desde el controlador de la ruta con Response.json(...).

Astro

Coloque el archivo en public/so4ag.json o cree un endpoint estático en src/pages/so4ag.json.ts para generar /so4ag.json. Si usa el endpoint, guarde en el repositorio el JSON que lee para poder revisarlo y validarlo antes de compilar el sitio.

Nuxt

Coloque el archivo en public/so4ag.json. Nuxt sirve los archivos de public/ desde la raíz del sitio, por lo que la URL es /so4ag.json.

Agregue este enlace en la sección head de las páginas que consultan los lectores para que cada una apunte al archivo fuente.

<link rel="describedby" type="application/json" href="/so4ag.json" title="SO4AG source manifest">

Valide el archivo y genere JSON-LD

Ejecute el validador antes de compilar el sitio o como paso obligatorio de la integración continua. Estos comandos usan la estructura de public/. Si un endpoint lee el JSON desde otra ruta, pase esa ruta al validador.

npm install github:soqvercom/so4ag#v0.1.4
npx so4ag-validate public/so4ag.json

El comando muestra VALID o INVALID. Si el archivo no es válido, enumera los errores e indica dónde se producen. Configure la compilación o la tarea de integración continua para que se detenga si falla la validación. Use las ubicaciones indicadas para corregir el archivo fuente antes de generar la página.

Desde un clon del repositorio de SO4AG, ejecute el conversor que aparece a continuación con so4ag.json en el directorio actual. También puede pasarle la ruta del archivo validado en el repositorio de su sitio. Código fuente de SO4AG

node validator/cli.mjs so4ag.json --to-jsonld > facts.jsonld

Coloque el contenido de facts.jsonld dentro de una etiqueta <script type="application/ld+json"> en la página «Datos y condiciones». Genere el contenido del script a partir del mismo archivo que sirve en /so4ag.json para que ambos formatos contengan los mismos datos después de cada actualización. La conversión conserva los datos, incluidas sus condiciones y fechas.

Pida al cliente que confirme los datos

Usted mantiene el archivo y las comprobaciones de compilación. El cliente confirma y respalda los datos. Antes de que un dato llegue a valid_until, pida al cliente que confirme su valor, su alcance y la página que lo respalda. Por ejemplo, un precio se puede confirmar por un máximo de 60 días cada vez.

Actualice la afirmación y sus fechas después de que el cliente la confirme. Luego, ejecute la validación y vuelva a generar el JSON-LD. Una vez transcurrido el último día, los programas tratan el dato como histórico. Si el cliente no declara un dato, publique la afirmación con knowledge_state establecido en unknown y sin valor. Las páginas lo muestran como «sin declarar».

Siguiente paso

Agregue public/so4ag.json al repositorio de su cliente siguiendo la guía para desarrolladores. Pase el archivo por el validador público antes de incorporar la comprobación a la integración continua.

Más artículos

Guía ·

Cómo publicar los datos de su negocio en un sitio de WordPress

Instale SO4AG Facts en WordPress, añada los datos de su negocio con sus condiciones y fechas, y publique una página de Datos y condiciones que pueda revisar desde el panel de administración.

Guía ·

Convierta la información de envíos, pagos y devoluciones de WooCommerce en datos estructurados

Use SO4AG Facts para revisar las sugerencias de envío y pago de WooCommerce y añada manualmente los plazos de devolución, los tiempos de entrega y otras condiciones.

Guía ·

Cómo publicar datos y condiciones en Shopify sin una aplicación

Aprenda a publicar una página de Datos y condiciones en Shopify, añadir JSON-LD y enlazar a un archivo SO4AG alojado cuando no pueda colocarlo en la raíz del dominio de su tienda.

Auditoría web gratuita Todos los artículos