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.

Puntos clave

  1. Ponga las entidades en un único @graphColoque las entidades en un solo @graph bajo un único @context, y dé a cada una un @id estable, como https://example.com/#organization.
  2. Fusione los bloques existentesEnumere cada bloque JSON-LD de la página, elija una definición para cada entidad y resuelva los conflictos conservando el valor que la página muestra de forma visible.
  3. Sustituya las repeticiones por referenciasDefina cada entidad una vez y reemplace cada copia anidada por un objeto que solo tenga su @id. Los datos viven en un solo lugar, así que no pueden contradecirse.
  4. Mantenga los valores de @id idénticosCopie cada @id carácter por carácter. Una barra final, http en lugar de https o una mayúscula distinta crea un segundo identificador.
  5. Pruebe en la herramienta correspondienteUse el Validador de marcado Schema para el vocabulario, la Prueba de resultados enriquecidos para Google y la Inspección de URL de Bing. Cada una informa según sus reglas.
  6. No espere un resultado enriquecido@graph organiza los datos y hace explícitas las relaciones. Google y Bing indican que el marcado no garantiza un resultado enriquecido.

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.

  • @context indica a un analizador cómo se asignan palabras cortas, como name, author y Article, a direcciones web completas. "https://schema.org" aporta el vocabulario de Schema.org.
  • @graph contiene un grupo de nodos relacionados. Al inicio de un documento, permite que varias entidades compartan un solo @context.
  • @id le da a un nodo un identificador único escrito como dirección web. Cualquier otro nodo puede reutilizar esa dirección para apuntar a él.
  • @type indica qué es el nodo, por ejemplo Organization, WebPage, Article o Person.

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.publisher apunta a Organization.
  • WebPage.isPartOf apunta a WebSite.
  • WebPage.mainEntity apunta a Article, y WebPage.breadcrumb apunta a BreadcrumbList.
  • Article.author apunta a Person, y Article.publisher apunta a Organization.
  • Article.mainEntityOfPage apunta a WebPage, y Article.isPartOf apunta a WebSite.
  • Cada ListItem.item de 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.

json
{
  "@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.

json
{
  "@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.

Un hombre con camisa de trabajo verde sostiene dos impresiones de cuadros unidos por flechas en una oficina de astillero, con un portátil y una taza junto a él
Figura 1. Comparar lo que describe cada bloque existente es el primer paso para unirlos en un solo @graph.

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

Una tarjeta azul grande con filas llenas, con tres etiquetas pequeñas que envían flechas de regreso hacia ella sobre un fondo oscuro
Figura 2. Una definición completa vive en un solo lugar, y las referencias pequeñas en otros lugares apuntan a ella.

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.

json
{
  "@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.

Qué propiedades pide cada motor o estándar

Pase el cursor o toque una fila para resaltarla. En pantallas pequeñas la tabla se desplaza de lado.

Nodo o propiedadEstadoSe aplica a
OrganizationSin propiedades obligatorias; se recomiendan name, url, logo y sameAs cuando correspondenFunción de Google para Organization
name y url de WebSiteObligatorio para esta función de Google; se recomienda alternateName cuando aplica un nombre cortoNombres de sitio de Google
WebPageTipo válido; Google no documenta una función de resultado enriquecido aparte para un WebPage genéricoSchema.org
ArticleSin propiedades obligatorias; se recomiendan headline, image, fechas y authorFunción de Google para Article
Elementos de BreadcrumbListitemListElement, position, name e item son obligatorios para esta función de Google; el último elemento puede usar la URL de la páginaMigas de pan de Google
Vínculos de publisherRelación válida; opcional para las funciones de nombre de sitio y Article de GoogleSchema.org

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.

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

Configure un grafo conectado en seis pasos

  1. Elija URL canónicasElija una forma de dirección para el sitio y para cada página, y úsela en todas partes.
  2. Asigne valores @id establesAgregue fragmentos permanentes como #organization, #website, #webpage, #article y #person.
  3. Cree un solo @context compartidoColoque los nodos en un solo arreglo @graph bajo un único contexto de Schema.org.
  4. Reemplace las repeticiones por referenciasCambie las copias anidadas de una entidad por un objeto que solo contenga su @id.
  5. Coincida con la página visibleConfirme que cada dato del grafo también aparezca en la página que ven los lectores.
  6. Valide y pruebeRevise la sintaxis del JSON y luego ejecute la prueba del motor que le interese.

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.

Prueba rápida: definiciones y referencias

Elija una respuesta para ver comentarios. Nada se califica ni se guarda.

Pregunta 1 de 3

¿Qué objeto define el nombre del autor en el grafo de ejemplo?

Pregunta 2 de 3

¿Qué objeto conecta el artículo con ese autor?

Pregunta 3 de 3

¿Usar @graph garantiza un resultado enriquecido?

Términos usados al conectar JSON-LD

Seleccione un término para ver su definición.

JSON-LD. JSON usado para expresar datos enlazados, de modo que las entidades puedan apuntar unas a otras.