# JSON-LD: qué es y cómo funciona

> JSON-LD (JavaScript Object Notation for Linked Data) es un formato del W3C para escribir datos estructurados en JSON dentro de un script; Google lo recomienda.

URL: https://yes-seo.com/es/glosario/json-ld

**JSON-LD** —JavaScript Object Notation for Linked Data— es una forma de escribir datos estructurados como JSON plano. Es una [Recomendación del W3C](https://www.w3.org/TR/json-ld11/) y el formato que Google recomienda para el [marcado Schema](https://yes-seo.com/es/glosario/marcado-schema), porque vive en su propio bloque en lugar de estar entretejido con tu HTML.

## Dónde se coloca

JSON-LD va dentro de un elemento script con un tipo especial. Los navegadores no lo ejecutan; lo leen los rastreadores. Puede ir en el `<head>` o en cualquier parte del `<body>`.

```

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#org",
      "name": "Green Sill",
      "url": "https://example.com/",
      "sameAs": ["https://www.linkedin.com/company/green-sill"]
    },
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "url": "https://example.com/",
      "name": "Green Sill",
      "publisher": { "@id": "https://example.com/#org" }
    }
  ]
}

```

## Las palabras clave que importan

- `@context` declara el vocabulario; para SEO, `https://schema.org`.

- `@type` nombra el tipo de cosa: Organization, Product, Event, etc.

- `@id` da a un nodo un identificador estable, normalmente una URL más un fragmento, para que otros nodos puedan referenciarlo en lugar de repetirlo.

- `@graph` agrupa varios nodos conectados en un solo bloque, como arriba, donde el WebSite apunta a su publisher mediante el ID.

## Por qué importa

JSON-LD hace que una página sea apta para [resultados enriquecidos](https://yes-seo.com/es/glosario/resultados-enriquecidos) y ofrece a los buscadores y a los sistemas de IA un resumen inequívoco de las entidades y los hechos que contiene. Al estar separado del diseño, un cambio de plantilla no lo rompe, y es sencillo de generar desde un CMS o una base de datos de productos. La [introducción a los datos estructurados](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data?hl=es) de Google enumera los formatos admitidos y las políticas que se aplican.

## Errores frecuentes

- **JSON no válido.** Una coma sobrante, unas comillas que faltan o comillas tipográficas pegadas desde un procesador de textos invalidan todo el bloque, y cada elemento que contiene.

- **Caracteres sin escapar.** Unas comillas dobles dentro del nombre de un producto necesitan una barra invertida, y una etiqueta de cierre de script literal dentro de un valor de texto termina el bloque antes de tiempo.

- **Entidades duplicadas** en varios bloques con valores distintos, a menudo por varios plugins.

- **Inyección solo con JavaScript.** Google puede leer el JSON-LD añadido por scripts después del renderizado, pero los rastreadores que no ejecutan JavaScript, incluidos muchos bots de IA, nunca lo ven. Genéralo en el HTML del servidor.

- **HTML dentro de los valores**, como etiquetas de párrafo en un campo de descripción.

Genera el JSON-LD con el codificador JSON de tu lenguaje —`json_encode()` en PHP, `JSON.stringify()` en JavaScript— en lugar de pegar cadenas de texto. Los codificadores se ocupan de las comillas y los caracteres especiales por ti.

## Valídalo

Pasa la página por el [validador de Schema](https://yes-seo.com/es/validador-schema): extrae cada bloque JSON-LD junto con cualquier Microdata o RDFa, informa de los errores de sintaxis JSON y comprueba las propiedades obligatorias y recomendadas por Google para los tipos habituales. Para los conceptos que hay detrás, consulta [datos estructurados](https://yes-seo.com/es/glosario/datos-estructurados).

## Preguntas frecuentes

### ¿Es JSON-LD mejor que Microdata?

Para la mayoría de los sitios, sí. Google admite JSON-LD, Microdata y RDFa, pero recomienda JSON-LD porque está separado del HTML visible y es más fácil de generar y mantener.

### ¿Puede una página tener más de un bloque JSON-LD?

Sí. Los buscadores leen todos. Solo asegúrate de que los bloques no describan la misma entidad con valores contradictorios; enlazar los nodos con @id dentro de un único @graph lo mantiene ordenado.

### ¿Ralentiza JSON-LD una página?

Apenas. Es un pequeño bloque de texto que los navegadores no ejecutan. Incluso un grafo de producto detallado suele ocupar solo unos pocos kilobytes.