Site Knowledge Graph en JSON‑LD: diseño, versionado y compliance con Google

Un site knowledge graph expuesto como graph.jsonld es un archivo JSON‑LD que modela las entidades y relaciones del dominio del sitio más allá de cualquier página individual y sirve como fuente estructurada para que LLMs resuelvan identidades y relaciones durante las fases de entity resolution y context assembly de una pipeline RAG. La tensión técnica central es clara: Google exige que el structured data describa contenido visible de la página y prohíbe páginas vacías creadas solo para markup, mientras que los LLMs se benefician de un grafo consolidado que ninguna página individual puede contener íntegramente.

Dos audiencias, dos propósitos

JSON‑LD actúa como on-ramp a RDF gracias a sus keywords reservados (@context, @id, @type, @graph), que permiten representar grafos de entidades tipadas globalmente identificadas sin abandonar la sintaxis JSON familiar. Para Google Search, ese grafo solo importa si describe contenido que el usuario puede ver en la misma página; para LLMs que operan vía RAG, el grafo importa en la fase de entity resolution, donde el modelo intenta emparejar conceptos de la consulta con fuentes autoritativas del índice.

Google penaliza el structured data que no refleja contenido visible; los LLMs, en cambio, consumen JSON‑LD parseando el HTML completo o endpoints JSON independientes, y no evalúan si existe contenido visible equivalente. Esto crea un espacio de diseño donde se puede servir a ambas audiencias, pero requiere decisiones arquitectónicas deliberadas.

Análisis de cumplimiento con guidelines de Google

La regla de Google es directa: «Don’t create blank or empty pages just to hold structured data, and don’t add structured data about information that is not visible to the user, even if the information is accurate». Un archivo estático graph.jsonld servido en una URL propia sin contenido visible visible es, técnicamente, una página vacía de structured data violación clara que puede derivar en una structured data manual action eliminando elegibilidad para rich results. 

Sin embargo, existen tres patrones que no violan las guidelines:

Patrón	Riesgo Google	Utilidad LLM	Condición de seguridad
A: Structured data por página solamente	Ninguno	Bajo (fragmentado)	Baseline seguro
B: @graph consolidado embebido en homepage	Bajo (si refleja contenido visible)	Alto	El contenido del grafo debe estar representado en la página
C: graph.jsonld como fichero estático independiente	Alto (página vacía)	Muy alto	Solo seguro si se sirve como developer resource, no como URL indexable

¿Cómo publicar graph.jsonld sin violar guidelines?

¿Puede un fichero estático ser compatible?

Sí, bajo condiciones específicas. Google explícitamente indica que no hace falta crear ficheros especiales para AI Search; sin embargo, un archivo graph.jsonld accesible públicamente puede ser descubierto por LLMs que consumen llms.txt o tools MCP sin que Google lo indexe como página web.

La estrategia de seguridad es: 

• Incluir la URL de graph.jsonld en llms.txt como recurso para desarrolladores, no como contenido editorial
• Servir el archivo con encabezado X-Robots-Tag: noindex para excluirlo del índice de Google mientras lo dejan accesible a bots LLM
• Documentarlo en la sección For Developers de llms.txt, siguiendo el patrón ya establecido por proyectos como LangChain y LangGraph

Esto explota el hecho de que noindex bloquea la elegibilidad para rich results (el ámbito de las guidelines), pero no impide que crawlers LLM consuman el fichero.

¿Dónde incrustar el grafo para Google?

La arquitectura recomendada tras experimentos en producción es inyectar el @graph completo con todas las entidades en cada página del sitio, no solo en la homepage. Cada página de artículo recibe, adicionalmente, propiedades about y mentions que enlazan a las entidades relevantes del grafo central.

Esto permite:

• Que Google vea structured data asociado a contenido visible en cada URL
• Que LLMs reciban el grafo completo desde cualquier página que indexen
• Mantener una única fuente de verdad (el registro de entidades) que se renderiza en múltiples destinos

Un experimento documentado en febrero de 2026 mostró que esta arquitectura resultó en +18.1% de usuarios activos y +21.8% de nuevos usuarios en los 7 días siguientes al despliegue, aunque los autores reconocen explícitamente que la correlación no implica causalidad dado que se realizaron otros cambios simultáneamente.

Diseño del grafo: estructura técnica

¿Qué tipos y relaciones incluir?

La capa de entidades debe construirse en dos niveles:

• Capa 1 – Entidades base: Organization (identidad completa con sameAs a perfiles sociales), Person (autores con knowsAbout y worksFor), DefinedTerm (metodologías o frameworks propietarios), Service, SoftwareApplication
• Capa 2 – Relaciones: propiedades about, mentions, relatedLink, isPartOf, hasPart, sameAs entre entidades de dominios cruzados

Cada entidad debe tener un @id URI estable y permanente (patrón: https://example.com/#entity-slug). Estos URIs funcionan como identificadores, no necesitan resolverse a una página HTML. Se observó en producción que la sobreconexión de entidades (más de 6 relaciones por entidad) diluyó la señal; 3‑6 relaciones por entidad demostró mayor precisión en la resolución por parte de LLMs.

¿Cómo versionar el grafo?

El versionado debe operar en tres capas, siguiendo el patrón de provenance metadata descrito como la capa que transforma un hecho de «algo que la IA leyó en algún sitio» a «algo que la IA puede verificar y citar con confianza»:

{
  "@context": "https://schema.org/",
  "@graph": [
    {
      "@type": "Dataset",
      "@id": "https://example.com/graph.jsonld",
      "name": "Site Knowledge Graph v2.1",
      "version": "2.1.0",
      "dateModified": "2026-06-11",
      "maintainer": { "@id": "https://example.com/#organization" },
      "isBasedOn": "https://example.com/graph.jsonld?v=2.0.0"
    }
  ]
}

• Semántico (@type: Dataset): version, dateModified, isBasedOn para trazabilidad de versiones anteriores
• Git/CI: el fichero fuente vive en control de versiones; cada commit actualiza dateModified automáticamente en build
• Changelog legible por LLM: una sección en llms.txt que lista los cambios semánticos del grafo (no solo técnicos) proporciona contexto de provenance que los sistemas RAG priorizan al resolver conflictos entre fuentes

Qué falló en producción

Hipótesis inicial: DefinedTerm en JSON‑LD sería validado por Google Rich Results Test y habilitaría rich results específicos.

Resultado observado: Google Rich Results Test no renderiza DefinedTerm como feature de búsqueda las entidades funcionan para LLMs que parsean JSON‑LD, pero el tooling de Google no las surfaces.

Desviación: La utilidad de DefinedTerm es exclusivamente para la capa LLM/RAG, no para la capa Google Search. Esto confirma la arquitectura de doble audiencia: no todo el grafo está destinado a producir rich results; parte de él es infraestructura pura de entity resolution.

Conclusión técnica: Las guidelines de Google aplican estrictamente a los tipos de schema que producen rich results. Los tipos que no producen rich results (como DefinedTerm, Dataset, DefinedTermSet) tienen menor riesgo de penalización cuando no están asociados a contenido visible, porque Google no evalúa su «representación en página» con el mismo criterio aunque la regla general sigue aplicando.

Configuraciones que empeoran el resultado

• aggregateRating sin reseñas reales: inventar datos para cumplimentar propiedades requeridas genera riesgo de manual action por structured data engañoso
• Grafo solo en homepage: los LLMs indexan páginas individuales; si el @graph completo solo existe en /, una pipeline RAG que indexa un artículo individual no tendrá acceso al contexto de entidades
• graph.jsonld indexable sin contenido visible: URL expuesta a Googlebot sin noindex y sin contenido HTML visible es una página vacía de structured data, violación directa de guidelines 
• Relaciones excesivas: primera versión en producción con cada entidad relacionada a todas las demás diluyó la señal semántica; el recorte a 5‑6 relaciones por entidad restauró la precisión
• Mantenimiento manual del mapeo post → entidad: se vuelve inconsistente en días; el auto-matching por solapamiento de tags (≥2 coincidencias = about, 1 = mentions) es el patrón escalable

Comandos de validación

Validar JSON‑LD syntax y schema.org compliance:

curl -s https://example.com/graph.jsonld | python3 -c "import json,sys; json.load(sys.stdin); print('JSON válido')"

Rich Results Test (API):

curl "https://searchconsole.googleapis.com/v1/urlTestingTools/mobileFriendlyTest:run" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"url":"https://example.com/graph.jsonld"}'

Verificar que graph.jsonld tiene noindex:

curl -I https://example.com/graph.jsonld | grep -i "x-robots-tag"

Validar con Schema.org Validator:

curl "https://validator.schema.org/validate?url=https://example.com/graph.jsonld"

El dataset de referencia para comparar es el propio schema.org/docs/developers.html, que expone las representaciones machine-readable del vocabulario Schema.org en JSON‑LD, Turtle y RDFa útil como baseline para estructurar el propio grafo. 

Cuándo justifica el overhead un site knowledge graph separado

La arquitectura de graph.jsonld separado (con noindex + referenciado desde llms.txt) tiene ROI positivo cuando se cumplen al menos dos de estas condiciones:

• El modelo conceptual tiene más de 10 entidades con relaciones no triviales entre sí
• El contenido del sitio referencia sistemáticamente esas entidades (frameworks, SDKs, estándares, taxonomías)
• El equipo ya tiene llms.txt operativo y busca añadir una capa de entity resolution explícita
• Las entidades son más estables que el contenido de las páginas (el grafo cambia mensualmente, los artículos diariamente)

Para blogs editoriales, tiendas e-commerce o sitios de contenido puro sin modelo conceptual propio, el overhead de mantener el grafo supera el beneficio: structured data por página con @graph bien conectado es suficiente.