⏱️ Lectura: 12 min
Cada vez que Google muestra un resultado con estrellas de reseña, una foto del autor o el logo de un sitio en vez de una URL anónima, detrás hay datos estructurados. La forma más extendida de agregarlos hoy es JSON-LD, un pequeño bloque de JSON que describe tu página en un lenguaje que los buscadores entienden.
📑 En este artículo
- TL;DR
- Qué es JSON-LD y por qué le importa a tu sitio
- Cómo funciona JSON-LD: el modelo de grafo
- Los nodos JSON-LD que mueven la aguja en SEO
- Manos a la obra: agrega JSON-LD a tu blog
- Validá antes de publicar (Windows, macOS y Linux)
- El detalle fino: crawlers tradicionales vs. LLMs
- Preguntas frecuentes
- Referencias
Lo mejor: es invisible para el visitante, no toca tu diseño y se agrega en minutos. En esta guía vemos qué es JSON-LD, cómo funciona su modelo de grafo, qué nodos mueven la aguja en SEO y cómo sumarlo a tu blog con ejemplos propios y validación en Windows, macOS y Linux.
TL;DR
- JSON-LD es un bloque
<script type="application/ld+json">que va en el<head>y describe tu página como datos estructurados. - El navegador lo ignora; crawlers como Googlebot lo leen y lo usan para rich snippets y mejor comprensión semántica.
- Todo se apoya en el vocabulario de Schema.org, el estándar que define los tipos y propiedades válidos.
- Un documento JSON-LD es un grafo: nodos con
@type,@idy propiedades, conectados entre sí. - Los crawlers fusionan nodos con el mismo
@identre páginas; los LLMs que leen una sola página NO los fusionan. - Los nodos con más impacto SEO para un sitio personal:
WebSite,WebPage,PersonyBlogPosting. - Siempre validá con la Rich Results Test de Google y el Schema Markup Validator antes de publicar.
Qué es JSON-LD y por qué le importa a tu sitio
JSON-LD significa JSON for Linked Data (JSON para Datos Enlazados). Es un formato que permite agregar metadatos a una página web describiendo qué representa cada cosa: quién es el autor, de qué trata el artículo, cuándo se publicó, a qué sitio pertenece. Esa descripción ayuda a los rastreadores web a entender la estructura semántica de tu sitio, te habilita para previsualizaciones más ricas y, potencialmente, mejora tu posicionamiento.
La pieza central es un bloque como este, que se coloca en el <head>:
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "WebSite",
"@id": "https://tusitio.dev/#website",
"url": "https://tusitio.dev/",
"name": "Tu Nombre"
}
]
}
</script>
Desglosemos cada parte. El atributo type="application/ld+json" declara un script con un tipo MIME especial: como no es text/javascript, el motor de JavaScript del navegador no lo ejecuta. Crawlers especializados como Googlebot, en cambio, buscan exactamente estos elementos y parsean su contenido. Es decir, el bloque existe solo para las máquinas que indexan la web.
La propiedad @context apunta a https://schema.org. En JSON-LD, el contexto define el vocabulario: qué pares clave-valor son válidos y qué significan. Toda la web está estandarizada sobre Schema.org, un proyecto colaborativo de Google, Microsoft, Yahoo y Yandex que define miles de tipos (Person, Article, SoftwareApplication, Recipe, etc.) y sus atributos. Una vez declarado el contexto, ya podés describir tu página.
Cómo funciona JSON-LD: el modelo de grafo
La clave para entender JSON-LD es pensar en un grafo dirigido y etiquetado, almacenado bajo la propiedad @graph. El grafo contiene varios nodos conectados entre sí mediante aristas dirigidas. Cada nodo tiene tres ingredientes:
- @type — describe qué es el nodo. Por ejemplo
WebSite,PersonoBlogPosting. - @id — un identificador único, típicamente una URL seguida de un hash, como
https://tusitio.dev/#person. - Propiedades — los pares clave-valor que describen los atributos del nodo (
name,url,description, etc.).
Los nodos se referencian entre sí por su @id. Si tu artículo tiene un autor, no repetís todos los datos de la persona dentro del artículo: simplemente apuntás a {"@id": "https://tusitio.dev/#person"} y el crawler resuelve la relación. Así se arma una red de entidades conectadas en vez de bloques de texto sueltos.
graph TD
W["WebSite #website"] --> P["Person #person"]
WP["WebPage #webpage"] --> W
BP["BlogPosting #post"] --> WP
BP --> PEn el diagrama, el BlogPosting pertenece a una WebPage, que a su vez forma parte del WebSite, y tanto el sitio como el artículo apuntan a la misma Person como autora y editora. Toda esa estructura es lo que Google interpreta cuando arma tu ficha en los resultados.
💭 Clave: Los crawlers fusionan las propiedades de un nodo entre varias páginas siempre que compartan el mismo @id. Pero los scrapers que leen una sola página —como la mayoría de los LLMs— NO hacen esa fusión. Si querés que un dato esté disponible para quien lee una sola URL, ese dato tiene que estar presente en esa página.
Los nodos JSON-LD que mueven la aguja en SEO
Schema.org define cientos de tipos, pero para un sitio personal o un blog hay cuatro que concentran casi todo el valor de SEO. Veámoslos con ejemplos listos para copiar y adaptar.
WebSite
Describe los metadatos del sitio completo. Le da pistas al crawler sobre cómo mostrar tu dominio (por ejemplo, qué nombre usar como etiqueta del resultado). La página raíz debería llevar la versión completa:
{
"@type": "WebSite",
"@id": "https://tusitio.dev/#website",
"url": "https://tusitio.dev/",
"name": "Ana Pérez",
"alternateName": ["tusitio.dev", "Blog de Ana"],
"description": "Sitio personal y blog técnico de Ana Pérez, desarrolladora backend en Buenos Aires enfocada en sistemas distribuidos.",
"inLanguage": "es-AR",
"publisher": { "@id": "https://tusitio.dev/#person" }
}
No hace falta repetir la versión completa en cada página. La raíz va detallada; el resto puede llevar una versión recortada con solo @type, @id, url y name. Eso le basta a un crawler de una sola página para nombrar el sitio correctamente, sin cargar detalles innecesarios.
WebPage
Representa la página física —el HTML— y su contenido. Es importante distinguirla del BlogPosting: la WebPage es el contenedor; el BlogPosting es el artículo en sí.
{
"@type": "WebPage",
"@id": "https://tusitio.dev/blog/json-ld/#webpage",
"url": "https://tusitio.dev/blog/json-ld/",
"name": "JSON-LD explicado",
"isPartOf": { "@id": "https://tusitio.dev/#website" },
"inLanguage": "es-AR"
}
Person y BlogPosting
El nodo Person describe quién está detrás del sitio; el BlogPosting describe un artículo concreto y lo enlaza con su autora y su página. Juntos habilitan que tu nombre y tu foto aparezcan asociados al contenido:
{
"@type": "BlogPosting",
"@id": "https://tusitio.dev/blog/json-ld/#post",
"headline": "JSON-LD explicado para sitios personales",
"datePublished": "2026-06-21",
"author": { "@id": "https://tusitio.dev/#person" },
"isPartOf": { "@id": "https://tusitio.dev/blog/json-ld/#webpage" },
"inLanguage": "es-AR"
}
Manos a la obra: agrega JSON-LD a tu blog
El flujo es sencillo: armás el grafo, lo serializás a JSON y lo inyectás en el <head> de cada plantilla. Si usás un generador de sitios estáticos (Astro, Hugo, Eleventy) o un framework como Next.js, lo habitual es generar el bloque desde las variables de la página. Un ejemplo con Next.js (App Router):
export default function Head() {
const data = {
"@context": "https://schema.org",
"@graph": [
{ "@type": "WebSite", "@id": "https://tusitio.dev/#website", "url": "https://tusitio.dev/", "name": "Ana Pérez" },
{ "@type": "Person", "@id": "https://tusitio.dev/#person", "name": "Ana Pérez", "url": "https://tusitio.dev/" }
]
};
return (
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }}
/>
);
}
💡 Tip: Generá el JSON con JSON.stringify en vez de escribirlo a mano. Así te asegurás de que las comillas escapen bien y evitás romper el HTML si un campo (como la descripción) contiene caracteres especiales o tildes.
Sobre la estrategia de @id: usá siempre URLs con un hash final (#website, #person, #post) que identifiquen el nodo de forma única y estable. Si cambiás esos identificadores entre páginas, Google deja de fusionar las propiedades y termina viendo entidades distintas donde debería ver una sola.
Validá antes de publicar (Windows, macOS y Linux)
Nunca publiques JSON-LD a ciegas: un error de sintaxis o un tipo inválido hace que el crawler descarte todo el bloque en silencio. Hay dos validadores oficiales gratuitos que deberías usar siempre:
- Rich Results Test de Google — te dice si tu marcado califica para resultados enriquecidos.
- Schema Markup Validator (validator.schema.org) — valida la sintaxis contra el vocabulario de Schema.org.
Para validar de forma local en tu pipeline de CI, podés instalar Node.js y correr un validador de línea de comandos. La instalación de Node difiere según el sistema:
# Windows (PowerShell con winget)
winget install OpenJS.NodeJS.LTS
# macOS (Homebrew)
brew install node
# Linux (Debian/Ubuntu)
sudo apt update && sudo apt install -y nodejs npm
Una vez instalado Node, el comando para extraer y revisar el JSON-LD de una URL es idéntico en los tres sistemas, porque npx es multiplataforma:
# Igual en Windows, macOS y Linux
npx structured-data-testing-tool --url https://tusitio.dev/
⚠️ Ojo: Validar localmente NO garantiza que Google indexe los rich snippets. La elegibilidad para resultados enriquecidos también depende de políticas de calidad y del tipo de contenido. Usá Search Console para confirmar qué reconoció Google en producción.
El detalle fino: crawlers tradicionales vs. LLMs
Hay una diferencia práctica que conviene tener presente en 2026, con tantos agentes y modelos de lenguaje recorriendo la web. Los crawlers clásicos de los buscadores mantienen un índice global y fusionan los nodos por @id entre todas las páginas de tu dominio. Por eso podés repartir la descripción de tu Person en varias páginas y aun así Google la arma completa.
Los LLMs y scrapers que leen una sola URL no tienen ese índice acumulado: solo ven el JSON-LD de la página que descargaron en ese momento. Si tu nombre, tu rol o tu foto solo aparecen en la home pero no en el artículo, un modelo que lee únicamente el artículo no los conocerá. La recomendación es buscar un equilibrio: incluí en cada página los datos mínimos que querés que cualquier lector de una sola URL conozca, y dejá la versión exhaustiva en la raíz o en tu página about.
JSON-LD, en definitiva, es una de esas mejoras de alto retorno: poco esfuerzo, cero impacto visual y un beneficio concreto en cómo te ven las máquinas que deciden tu visibilidad. Para un desarrollador en LATAM que recién arma su sitio personal o su portfolio, agregar estos cuatro nodos y validarlos es de lo más rentable que podés hacer por tu SEO.
📖 Resumen en Telegram: Ver resumen
Preguntas frecuentes
¿JSON-LD afecta lo que ve el usuario en mi página?
No. El bloque vive en el <head> con el tipo MIME application/ld+json, así que el navegador no lo ejecuta ni lo muestra. Solo lo leen los crawlers y validadores. Tu diseño y tu contenido visible quedan exactamente igual.
¿Necesito JSON-LD si ya tengo etiquetas meta y Open Graph?
Son complementarios. Las meta tags y Open Graph controlan títulos, descripciones y previsualizaciones en redes. JSON-LD describe entidades y relaciones (autor, sitio, artículo) con un vocabulario semántico mucho más rico, y es lo que habilita los rich snippets en Google. Lo ideal es tener ambos.
¿Qué pasa si mi JSON-LD tiene un error de sintaxis?
El crawler descarta el bloque entero en silencio: no recibís un error visible, simplemente no se generan los resultados enriquecidos. Por eso es obligatorio validar con la Rich Results Test de Google y el Schema Markup Validator antes de publicar cada cambio.
¿Puedo poner el JSON-LD en el body en vez del head?
Google acepta JSON-LD tanto en el <head> como en el <body>, e incluso inyectado por JavaScript. Aun así, la práctica recomendada es colocarlo en el <head> y, de ser posible, renderizarlo del lado del servidor para que esté presente sin depender de la ejecución de scripts.
¿Para qué sirve el campo @id exactamente?
El @id es el identificador único de cada nodo. Permite que distintos nodos se referencien entre sí (un artículo apunta a su autor) y que los crawlers fusionen las propiedades del mismo nodo entre varias páginas. Usar un @id estable con hash, como #person, es la clave para que Google trate todo como una sola entidad.
Referencias
- JSON-LD Explained for Personal Websites — Ethan Hawksley — guía original que inspiró este artículo, con ejemplos reales de cada nodo.
- Schema.org — vocabulario oficial que define todos los tipos y propiedades válidos para datos estructurados.
- JSON-LD.org — sitio oficial del formato JSON for Linked Data, con la especificación y herramientas.
- Google Search Central — Datos estructurados — documentación oficial de cómo Google usa el marcado para resultados enriquecidos.
📱 ¿Te gusta este contenido? Únete a nuestro canal de Telegram @programacion donde publicamos a diario lo más relevante de tecnología, IA y desarrollo. Resúmenes rápidos, contenido fresco todos los días.
0 Comentarios