Para conectar varios bloques JSON-LD, coloque sus entidades en un solo arreglo @graph bajo un único @context, asigne a cada entidad un @id estable, como https://example.com/#organization, y reemplace cada copia anidada y repetida de una entidad por una referencia que contenga solo ese @id. Después, confirme que la página muestra los mismos datos y pruebe el JSON.
Cuando un tema, un plugin, una aplicación o código escrito a mano imprimen cada uno su propio bloque, la misma organización, autor o página termina descrita en más de un lugar sin nada que relacione esas descripciones. Al unirlos, obtiene un solo conjunto de entidades que apuntan unas a otras.
@graph organiza los datos y hace explícitas las relaciones. No produce una mejora de posicionamiento, y por sí solo no genera un resultado enriquecido. Seis nodos ficticios en example.com muestran el patrón: Organization, WebSite, WebPage, Article, Person y BreadcrumbList.
Conozca primero las cuatro palabras clave de JSON-LD
JSON-LD es JSON que describe datos enlazados, y cuatro claves que empiezan con arroba hacen el trabajo de conexión. Cada una está definida en la especificación JSON-LD 1.1 del W3C. Las claves y los valores distinguen mayúsculas y minúsculas, así que @id y @ID son cosas distintas, y Article no es lo mismo que article.
@contextindica a un analizador cómo se asignan palabras cortas, comoname,authoryArticle, a direcciones web completas."https://schema.org"aporta el vocabulario de Schema.org.@graphcontiene un grupo de nodos relacionados. Al inicio de un documento, permite que varias entidades compartan un solo@context.@idle da a un nodo un identificador único escrito como dirección web. Cualquier otro nodo puede reutilizar esa dirección para apuntar a él.@typeindica qué es el nodo, por ejemploOrganization,WebPage,ArticleoPerson.
Un nodo es una cosa descrita, y una entidad es la cosa real que describe el nodo. Una referencia es un objeto que contiene solo un @id, así que apunta a un nodo definido en otra parte del grafo. Todo grafo unido depende de esa diferencia entre una definición y una referencia.
Elija un @id estable para cada entidad
Un @id es un nombre, y un buen nombre no cambia. Fórmelo con una URL canónica más un fragmento corto: https://example.com/#organization para la empresa, https://example.com/#website para el sitio y https://example.com/blog/graph/#webpage para una página. La dirección no tiene que cargar nada. Solo tiene que ser única y permanente.
Las entidades a nivel de sitio mantienen el mismo @id en todas las páginas. La organización es https://example.com/#organization en la página de inicio, en cada artículo y en la página de contacto, y así un analizador puede reconocer que todas esas menciones son una sola organización. Las entidades a nivel de página toman la URL de la página como base, de modo que el Article y el BreadcrumbList de una página son nodos distintos de los de la página siguiente.
Use la misma URL canónica para el nodo de página que la página declara como enlace canónico. Si la página se puede abrir con y sin barra final, elija una forma y úsela en el @id, en url y en la ruta de navegación. Evite todo lo que cambie, como una fecha, un valor de sesión o un número de fila de la base de datos que una migración posterior podría renumerar.
La guía de schema de organización en cada página explica cómo mantener coherente la organización compartida en todo un sitio. La guía de SEO de entidades con sameAs explica cómo apuntar un nodo a los perfiles que identifican la misma entidad en otros lugares.
Vea cómo se conectan los seis nodos
El ejemplo describe una página de artículo y une sus entidades mediante @id. Las relaciones siguen un patrón fijo, y cada flecha de abajo es una propiedad cuyo valor es una referencia a otro nodo.
WebSite.publisherapunta aOrganization.WebPage.isPartOfapunta aWebSite.WebPage.mainEntityapunta aArticle, yWebPage.breadcrumbapunta aBreadcrumbList.Article.authorapunta aPerson, yArticle.publisherapunta aOrganization.Article.mainEntityOfPageapunta aWebPage, yArticle.isPartOfapunta aWebSite.- Cada
ListItem.itemde la ruta de navegación contiene una URL de página.
Schema.org define author como una propiedad que acepta un Person o un Organization, isPartOf como la que vincula una obra con una obra más grande, como un sitio web, y mainEntityOfPage como la que indica la página para la que una cosa es el tema principal. Su propio sitio puede usar menos vínculos. Un sitio sin autores individuales puede apuntar Article.author a Organization.
En un negocio local, el nodo de organización puede usar un tipo más específico. La guía de schema de negocio local muestra qué campos corresponden allí, y se aplica el mismo enfoque de @id.
Copie el ejemplo de seis nodos y reemplace los valores
El ejemplo siguiente es código didáctico. Cada nombre, URL, dirección de imagen, fecha y perfil es ficticio y usa el dominio reservado example.com, así que reemplace cada uno por un dato que aparezca en su página real. Está dividido en dos documentos JSON válidos para que cada uno sea fácil de leer: primero los nodos de nivel de sitio y después los nodos de nivel de página. En una página real, coloque los seis nodos en un solo arreglo @graph.
El primer bloque define Organization, WebSite y Person. WebSite apunta a la organización mediante una referencia, y Person la señala a través de worksFor.
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "Organization",
"@id": "https://example.com/#organization",
"name": "Northstar Example Media",
"url": "https://example.com/",
"logo": "https://example.com/images/logo.png",
"sameAs": ["https://social.example.com/northstar-example"]
},
{
"@type": "WebSite",
"@id": "https://example.com/#website",
"url": "https://example.com/",
"name": "Northstar Example Media",
"alternateName": "Northstar Media",
"publisher": { "@id": "https://example.com/#organization" }
},
{
"@type": "Person",
"@id": "https://example.com/authors/river-lee/#person",
"name": "River Lee",
"url": "https://example.com/authors/river-lee/",
"worksFor": { "@id": "https://example.com/#organization" }
}
]
}Primero cambie name y url de la organización y del sitio web. Conserve alternateName solo si su sitio tiene un nombre corto real. Reemplace logo por la dirección de un archivo de logotipo de su sitio, y incluya en sameAs solo perfiles que pertenezcan a la organización. Person necesita el nombre real del autor y, cuando exista una página de autor, la URL de esa página.
El segundo bloque contiene los nodos de nivel de página. Cada referencia de este bloque apunta a un @id del primer bloque o a otro nodo de este mismo bloque.
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "WebPage",
"@id": "https://example.com/blog/graph/#webpage",
"url": "https://example.com/blog/graph/",
"name": "Cómo usar @graph para unir su schema en un mapa de entidades",
"isPartOf": { "@id": "https://example.com/#website" },
"breadcrumb": { "@id": "https://example.com/blog/graph/#breadcrumb" },
"mainEntity": { "@id": "https://example.com/blog/graph/#article" }
},
{
"@type": "Article",
"@id": "https://example.com/blog/graph/#article",
"url": "https://example.com/blog/graph/",
"headline": "Cómo usar @graph para unir su schema en un mapa de entidades",
"image": "https://example.com/images/graph-16x9.png",
"datePublished": "2026-08-01T09:00:00-06:00",
"dateModified": "2026-08-20T14:30:00-06:00",
"author": { "@id": "https://example.com/authors/river-lee/#person" },
"publisher": { "@id": "https://example.com/#organization" },
"mainEntityOfPage": { "@id": "https://example.com/blog/graph/#webpage" },
"isPartOf": { "@id": "https://example.com/#website" }
},
{
"@type": "BreadcrumbList",
"@id": "https://example.com/blog/graph/#breadcrumb",
"itemListElement": [
{ "@type": "ListItem", "position": 1, "name": "Inicio", "item": "https://example.com/" },
{ "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://example.com/blog/" },
{ "@type": "ListItem", "position": 3, "name": "Cómo usar @graph para unir su schema en un mapa de entidades", "item": "https://example.com/blog/graph/" }
]
}
]
}Aquí, headline, image, datePublished y dateModified deben coincidir con lo que muestra la página real del artículo. Los nombres y URL de la ruta de navegación deben seguir la ruta que el visitante ve en la página. Al unir los dos documentos, conserve un solo @context, coloque los seis objetos en un arreglo @graph y conserve cada @id exactamente como está escrito.
Una los bloques que su sitio ya imprime
Empiece por lo que ya aparece en la página, porque un tema, un plugin de SEO o una aplicación puede imprimir varios bloques sin avisarle. Vea el código fuente de la página, o use la vista de página renderizada de una herramienta de prueba, y haga una lista de cada elemento <script type="application/ld+json"> junto con las entidades que describe cada uno. La guía de schema de organización explica por qué una segunda descripción de la misma organización es un problema.

Para cada entidad, elija un bloque como definición y anote su @id. Después, cambie cada otro bloque que mencione la entidad para que contenga solo una referencia a ese @id. Si un plugin ya genera un grafo, la solución más limpia suele ser ajustar su configuración, o agregar los nodos que faltan al grafo que genera, en lugar de agregar un segundo bloque que vuelva a describir la organización.
Cuando dos bloques no coincidan, por ejemplo dos archivos de logotipo distintos o dos formas de escribir el nombre de la empresa, decida cuál valor es el correcto y el que aparece en la página, y conserve solo ese. Un grafo unido que repite una contradicción no es mejor que dos bloques separados que se contradicen.
Reemplace las entidades anidadas repetidas por referencias @id
La causa más común de duplicados es el anidamiento. Un plugin escribe la organización completa dentro de WebSite.publisher, la escribe otra vez dentro de Article.publisher, y un tercer bloque la agrega por tercera vez. Para un lector, los nodos parecen idénticos, pero un analizador ve tres descripciones que pueden desviarse entre sí.

El bloque siguiente es JSON válido y muestra el patrón que hay que eliminar. El objeto publisher es una definición completa en dos lugares, con una dirección de logotipo distinta en cada uno.
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "WebSite",
"@id": "https://example.com/#website",
"url": "https://example.com/",
"publisher": {
"@type": "Organization",
"name": "Northstar Example Media",
"logo": "https://example.com/images/logo.png"
}
},
{
"@type": "Article",
"@id": "https://example.com/blog/graph/#article",
"headline": "Cómo usar @graph para unir su schema en un mapa de entidades",
"publisher": {
"@type": "Organization",
"name": "Northstar Example Media",
"logo": "https://example.com/images/logo-old.png"
}
}
]
}Defina la organización una sola vez como un nodo con su propio @id, como en el primer bloque del ejemplo de seis nodos. Después, reemplace cada copia anidada por "publisher": { "@id": "https://example.com/#organization" }. La referencia no lleva name ni logo propios, y ese es el punto: los datos viven en un solo lugar, así que no pueden contradecirse.
Una definición y una referencia son ambas objetos, así que pueden parecerse. La diferencia está en el contenido. Una definición tiene un @type y propiedades que describen la cosa. Una referencia tiene solo un @id, y significa «el nodo con este identificador, definido en otra parte del grafo».
Conozca qué propiedades pide cada motor
Un grafo puede ser JSON válido y vocabulario válido de Schema.org y aun así no cumplir lo que necesita una función de búsqueda. Son cuatro niveles separados: la sintaxis JSON, el vocabulario de Schema.org, los requisitos de una función específica de Google, y si el resultado se indexa y se muestra. Superar uno no implica el siguiente, y «obligatorio» siempre debe indicar el motor y la función a los que corresponde.
Google indica que sus datos estructurados de Article no tienen propiedades obligatorias, y recomienda propiedades como headline, image, datePublished, dateModified y author. La documentación de datos estructurados de Organization de Google tampoco enumera propiedades obligatorias, y recomienda name, url, logo y sameAs cuando corresponden.
La documentación de nombres de sitio de Google pide name y url en WebSite, y trata alternateName como opcional para los sitios con un nombre corto. La documentación de la ruta de navegación de Google establece los requisitos de la ruta de navegación: itemListElement, y para cada ListItem, un position, un name y un item, salvo que el último elemento puede apoyarse en la URL de la página que lo contiene.
El nodo WebPage es un tipo válido de Schema.org, y Google no documenta una función de resultado enriquecido aparte para un WebPage genérico. Aun así, conviene tenerlo en el grafo, porque es el centro al que se conectan el sitio web, el artículo y la ruta de navegación. Las propiedades publisher son relaciones válidas de Schema.org que son opcionales para las funciones de Google mencionadas arriba.
Google anunció en octubre de 2024 que retiraba el cuadro de búsqueda de enlaces de sitio, y la misma publicación indica que los nombres de sitio siguen funcionando con el marcado WebSite. Por eso, un nodo WebSite sigue sirviendo para los nombres de sitio, y mantiene conectado el grafo.
Haga que el grafo sea legible para Bing y la búsqueda con IA
Los nodos del grafo son los mismos para todos los motores. Bing admite Schema.org en JSON-LD, Microdata y RDFa, así que un solo grafo le sirve, y la búsqueda web de Copilot usa contenido indexado por Bing. Yandex no admite todos los tipos de Schema.org, según su página de preguntas sobre marcado.
Para aparecer en ChatGPT Search, permita OAI-SearchBot (página de ayuda de ChatGPT Search); para Perplexity, permita PerplexityBot (documentación de rastreadores). Mantenga la página rastreable, muestre los datos importantes en HTML visible, y consulte si los sistemas de IA usan el marcado schema.
Agregue el grafo a su página
Coloque el documento terminado en un elemento script de tipo application/ld+json en el HTML de la página. La mayoría de los sitios lo colocan en el head de la página. El elemento contiene solo el JSON, sin texto adicional alrededor.
<script type="application/ld+json">
<!-- pegue aquí el documento JSON-LD completo -->
</script>La vía que use depende de la plataforma. Una opción del tema, un plugin de SEO, un administrador de etiquetas, un campo de código personalizado o un archivo de plantilla pueden agregar el elemento, y las instrucciones oficiales vigentes de su plataforma indican dónde va. Revise primero lo que la plataforma ya imprime, para ampliar esa salida en lugar de agregar una segunda descripción de las mismas entidades.
Si un script agrega el marcado después de cargar la página, la guía de datos estructurados con JavaScript de Google indica que pruebe la página renderizada con la Prueba de resultados enriquecidos (Rich Results Test) o con URL Inspection (Inspección de URL). El marcado renderizado es distinto del HTML que devuelve una descarga simple, así que asegúrese de que la prueba que usa lea la versión que verán los rastreadores.
El grafo describe la página que lo contiene. Los nodos de nivel de sitio se repiten en cada página con el mismo @id, y los nodos de nivel de página cambian de una página a otra. Mantenga visible para los lectores de esa página cada dato del grafo, porque las directrices generales de datos estructurados de Google piden un marcado que refleje el contenido visible.
Puede crear el grafo en el navegador con el constructor de @graph de Schema Nova, que une los nodos bajo un solo @context y muestra las referencias.
Pruebe el grafo con la herramienta adecuada
Elija la prueba que corresponda a la pregunta que tiene. El Schema Markup Validator revisa el vocabulario de Schema.org y la sintaxis de JSON-LD. La Prueba de resultados enriquecidos de Google revisa las funciones que Google admite, y URL Inspection de Search Console muestra cómo Google leyó la página renderizada.
Para Bing, use el Markup Validator o la tarjeta Markup (de marcado) de Bing URL Inspection. Para Yandex, use su validador de datos estructurados, y para Apple, use la herramienta de validación de la guía de marcado de Apple. Cada motor informa según sus propias reglas, así que un resultado limpio en uno no equivale a un resultado limpio en otro.
El JSON-LD Playground es un visor útil para el grafo en sí. Expande el contexto y muestra cada nodo con su identificador, así que puede ver si una referencia se resuelve en un nodo definido.
Para una revisión rápida de sintaxis del código que pegue, el validador de schema de Schema Nova señala los problemas del JSON, y el comprobador de schema de Schema Nova revisa el marcado de una página. Una prueba correcta significa que el marcado se leyó como se pretendía. No promete una aparición en la búsqueda, un mejor posicionamiento ni una cita.
Corrija los problemas comunes de un grafo unido
La mayoría de los problemas de un grafo provienen de cinco causas, y cada una tiene una corrección directa.
La primera es una referencia sin una definición correspondiente. Si author apunta a https://example.com/authors/river-lee/#person y ningún nodo tiene ese @id, el vínculo no lleva a ninguna parte. Busque en el grafo la cadena exacta y asegúrese de que un nodo la defina, carácter por carácter.
La segunda son valores de @id que difieren un poco. Una barra final, http en lugar de https, o una letra mayúscula distinta crea un segundo identificador. Copie cada @id desde un solo lugar en lugar de escribirlo de nuevo.
La tercera es un JSON no válido: una coma final, unas comillas que faltan, o un comentario, que JSON no permite. Pase el código por una herramienta que entienda JSON antes de publicarlo. La cuarta es una falta de coincidencia con la página, por ejemplo un autor nombrado en el grafo que no aparece en ninguna parte de la página. Corríjalo agregando el dato visible o eliminando el nodo.
La quinta es que queden dos grafos después de una unión, uno de un plugin y otro de su propio código. Busque cada elemento script en el código fuente y elimine o reconfigure el que ya no necesita. Después, ejecute las pruebas de nuevo desde el principio.
Preguntas frecuentes
¿Qué es @graph en JSON-LD?
@graph es una clave que contiene un grupo de nodos relacionados en un mismo documento JSON-LD. Permite que varias entidades, como una organización, una página y un artículo, compartan un solo @context mientras cada una conserva su propio @id. Organiza los datos y no es una señal de posicionamiento.
¿Necesito @graph si solo tengo una entidad de schema?
No. Una sola entidad funciona como un objeto JSON-LD simple. @graph resulta útil cuando describe dos o más entidades que se relacionan entre sí, o cuando quiere unir bloques en un solo documento.
¿Puedo usar varios bloques JSON-LD en lugar de un solo @graph?
Sí. Google indica que puede entender varios elementos de datos estructurados en una misma página. Los bloques separados todavía pueden conectarse mediante los mismos valores de @id, pero un solo @graph es más fácil de leer, mantener y probar.
¿@graph garantiza un resultado enriquecido?
No. Google indica que los datos estructurados pueden hacer que una página sea elegible para apariencias más ricas, pero no garantizan que una de ellas se muestre, y Bing indica que sus anotaciones no garantizan un fragmento visualmente enriquecido. Un grafo organiza las relaciones, y cada proveedor decide cómo usar el marcado elegible.
¿Debe aparecer el mismo nodo Organization en todas las páginas?
Sí, cuando la página pertenece a esa organización. Use el mismo @id y los mismos datos en cada caso para que todas las páginas apunten a una sola organización. Los nodos de nivel de página cambian con cada página.
