Datos estructurados para mejor SEO: JSON-LD en páginas Astro
Has construido un sitio web Astro bien estructurado. El contenido es cuidado, las paginas cargan rapido, el diseno cumple con los estandares de accesibilidad. Pero cuando Google rastrea tus paginas, solo ve texto y elementos HTML. No entiende automaticamente que tu seccion de FAQ contiene preguntas y respuestas, que tu pagina de servicios describe ofertas, o que tu negocio opera en una ubicacion especifica. Aqui es exactamente donde entran los datos estructurados.
JSON-LD (JavaScript Object Notation for Linked Data) es el formato preferido de Google para decirle a las maquinas lo que el contenido de una pagina significa — no solo lo que muestra. Una etiqueta <script> invisible en el head del HTML entrega un conjunto de datos estructurados a los motores de busqueda que conduce directamente a Rich Results en los resultados de busqueda: respuestas FAQ desplegables, calificaciones con estrellas, rutas de navegacion y tarjetas de negocio con direccion y horarios.
Google utiliza datos estructurados para comprender el contenido de una pagina y mostrar ese contenido en un formato visualmente mas atractivo en los resultados de busqueda — conocido como Rich Results.
Por que los datos estructurados son decisivos
Los Rich Results hacen que tu pagina destaque visualmente entre la masa de resultados de busqueda. Mientras que los resultados normales solo muestran titulo, URL y meta descripcion, las paginas con datos estructurados pueden mostrar secciones FAQ desplegables, calificaciones con estrellas, navegacion breadcrumb, tablas de precios y detalles del negocio directamente en la SERP. Eso significa mas espacio en pantalla, mas atencion y tasas de clics significativamente mas altas.
Los datos estructurados no son un factor de ranking en el sentido estricto — pero ayudan a Google a comprender mejor el contexto de tu contenido. E indirectamente, las tasas de clics mas altas, las tasas de rebote mas bajas y una mejor interaccion del usuario si mejoran tu posicionamiento.
Que es JSON-LD?
JSON-LD significa JavaScript Object Notation for Linked Data. Es un formato estandarizado que incrusta informacion semantica dentro de una etiqueta <script> en el documento HTML. Los motores de busqueda leen esta etiqueta; los usuarios nunca la ven.
<!-- Invisible para usuarios, legible por maquinas para Google -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "WebPage",
"name": "Mi Pagina",
"description": "Una descripcion de la pagina"
}
</script>El punto crucial: JSON-LD no se renderiza. Se encuentra como un script invisible en el <head> o al final del <body>. No bloquea el renderizado ni ralentiza la carga de la pagina. Es puro marcado de metadatos — Google lo lee, el navegador lo ignora.
Los cuatro tipos de Schema en detalle
Este portfolio implementa cuatro tipos de Schema.org que juntos crean una imagen semantica completa del sitio web para los motores de busqueda.
Hace visible el contenido FAQ directamente en los resultados de busqueda de Google como preguntas desplegables. Cada par pregunta-respuesta se captura como un elemento independiente en el schema. Google los renderiza como desplegables expandibles debajo del resultado de busqueda normal -- esto puede triplicar el area visible de tu resultado y aumentar las tasas de clics hasta un 30%.
Le dice a Google que servicios ofreces, incluyendo nombre, descripcion e informacion del proveedor. Especialmente relevante para freelancers y agencias cuyas paginas de servicios pueden mostrarse con detalles adicionales en los resultados de busqueda. Combinado con LocalBusiness, crea una imagen completa de tu oferta.
Crea una ruta de navegacion en los resultados de busqueda (Inicio > Servicios > Desarrollo Web). Google reemplaza la URL cruda con una estructura de ruta legible. Esto mejora la orientacion del usuario directamente en la SERP y senala a Google una jerarquia clara del sitio web. Se genera en cada pagina a traves del componente Breadcrumbs.
Contiene nombre del negocio, direccion, coordenadas geograficas y datos de contacto. Esencial para SEO local -- Google usa estos datos para el Knowledge Graph, incrustaciones de Google Maps y busqueda local. Se genera a nivel de todo el sitio a traves del componente SEO, obteniendo datos directamente de la configuracion central SITE.
Implementacion del Schema FAQPage
El schema FAQPage es uno de los formatos de datos estructurados mas impactantes porque produce Rich Results directamente visibles en Google. La implementacion en Astro aprovecha la estructura de datos FAQ existente y genera JSON-LD automaticamente.
---
/* Generacion de JSON-LD FAQPage desde el array de datos FAQ */
interface FaqItem {
question: string;
answer: string;
}
interface Props {
items: FaqItem[];
}
const { items } = Astro.props;
/* Datos estructurados Schema.org FAQPage */
const faqSchema = {
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": items.map((item) => ({
"@type": "Question",
"name": item.question,
"acceptedAnswer": {
"@type": "Answer",
"text": item.answer,
},
})),
};
---
<!-- Accordion visible para usuarios -->
<section id="faq" class="faq">
{items.map((item) => (
<details class="faq__item">
<summary class="faq__question">{item.question}</summary>
<p class="faq__answer">{item.answer}</p>
</details>
))}
</section>
<!-- JSON-LD invisible para motores de busqueda -->
<script
type="application/ld+json"
set:html={JSON.stringify(faqSchema)}
/>{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "Que tecnologias utilizan?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Trabajamos con Astro, React, TypeScript y tecnicas CSS modernas. Todos los proyectos siguen la metodologia Atomic Design."
}
},
{
"@type": "Question",
"name": "Cuanto tiempo tarda un proyecto tipico?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Dependiendo del alcance, entre 2 y 8 semanas. Un relanzamiento de portfolio tipicamente toma 3-4 semanas."
}
},
{
"@type": "Question",
"name": "Ofrecen mantenimiento?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Si, ofrecemos mantenimiento continuo, actualizaciones de seguridad y monitoreo de rendimiento como servicio mensual."
}
}
]
}Resultados de Google con Rich Result FAQPage:
+---------------------------------------------------+
| Arnold Wender — Desarrollador Web & Creator |
| https://arnoldwender.com |
| Diseno web moderno con Astro, React y... |
| |
| > Que tecnologias utilizan? |
| > Cuanto tiempo tarda un proyecto tipico? |
| > Ofrecen mantenimiento? |
+---------------------------------------------------+
Cada pregunta es clicable y expande la respuesta
directamente en los resultados de busqueda — sin
necesidad de visitar la pagina. Esto triplica el
area visible de tu resultado de busqueda.Schema Service para la pagina de servicios
El schema Service comunica a Google que servicios ofreces. Cada servicio se captura individualmente con nombre, descripcion y referencia al proveedor.
---
/* Schema Service para la pagina de servicios */
import { SITE } from '../../lib/constants';
const services = [
{
name: 'Desarrollo Web',
description: 'Sitios web personalizados con Astro, React y CSS moderno.',
},
{
name: 'Diseno UI/UX',
description: 'Diseno centrado en el usuario con metodologia Atomic Design.',
},
{
name: 'Optimizacion SEO',
description: 'SEO tecnico, datos estructurados y rendimiento.',
},
];
/* Cada servicio se convierte en su propio objeto schema */
const serviceSchemas = services.map((service) => ({
"@context": "https://schema.org",
"@type": "Service",
"name": service.name,
"description": service.description,
"provider": {
"@type": "Person",
"name": SITE.author,
"url": SITE.url,
},
}));
---
{serviceSchemas.map((schema) => (
<script
type="application/ld+json"
set:html={JSON.stringify(schema)}
/>
))}[
{
"@context": "https://schema.org",
"@type": "Service",
"name": "Desarrollo Web",
"description": "Sitios web personalizados con Astro, React y CSS moderno. Performantes, accesibles y optimizados para SEO.",
"provider": {
"@type": "Person",
"name": "Arnold Wender",
"url": "https://arnoldwender.com"
}
},
{
"@context": "https://schema.org",
"@type": "Service",
"name": "Diseno UI/UX",
"description": "Diseno centrado en el usuario con metodologia Atomic Design. Wireframes, prototipos y sistemas de diseno.",
"provider": {
"@type": "Person",
"name": "Arnold Wender",
"url": "https://arnoldwender.com"
}
},
{
"@context": "https://schema.org",
"@type": "Service",
"name": "Optimizacion SEO",
"description": "SEO tecnico, datos estructurados y optimizacion de rendimiento Core Web Vitals.",
"provider": {
"@type": "Person",
"name": "Arnold Wender",
"url": "https://arnoldwender.com"
}
}
]BreadcrumbList en Astro
BreadcrumbList es el schema que se genera en cada pagina individual. Describe la ruta de navegacion desde la pagina de inicio hasta la pagina actual. En Astro, esta informacion fluye a traves de una elegante cadena de props desde la pagina, pasando por el layout, hasta el componente Breadcrumbs.
Flujo de datos de Breadcrumbs
- Definir Breadcrumbs en la pagina
Cada pagina Astro define sus breadcrumbs como un array de objetos con label y un href opcional. El ultimo elemento no tiene enlace -- representa la pagina actual.
- Pasar al BaseLayout
La pagina pasa el array de breadcrumbs como prop al BaseLayout. BlogLayout y PortfolioLayout reenvian automaticamente esta prop al BaseLayout.
- Componente Breadcrumbs renderiza HTML y JSON-LD
El componente molecula Breadcrumbs renderiza tanto la navegacion visible como lista HTML como el schema BreadcrumbList invisible como script JSON-LD.
- Google muestra la ruta en la SERP
En lugar de la URL cruda (arnoldwender.com/blog/json-ld), Google muestra la ruta legible: Inicio > Blog > Datos Estructurados JSON-LD. Esto mejora la tasa de clics y la orientacion del usuario.
---
/* src/pages/servicios.astro — Breadcrumbs para la pagina de servicios */
import BaseLayout from '../layouts/BaseLayout.astro';
const breadcrumbs = [
{ label: 'Inicio', href: '/' },
{ label: 'Servicios' }, /* Sin href = pagina actual */
];
---
<BaseLayout
seo={{ title: 'Servicios', description: '...' }}
breadcrumbs={breadcrumbs}
>
<section id="servicios">
<!-- Contenido de la pagina -->
</section>
</BaseLayout>---
/* src/components/molecules/Breadcrumbs.astro */
import type { BreadcrumbItem } from '../../types';
interface Props {
items: BreadcrumbItem[];
}
const { items } = Astro.props;
/* Generar schema BreadcrumbList */
const breadcrumbSchema = {
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": items.map((item, index) => ({
"@type": "ListItem",
"position": index + 1,
"name": item.label,
...(item.href && { "item": `${Astro.site}${item.href}` }),
})),
};
---
<!-- Navegacion breadcrumb visible -->
<nav aria-label="Breadcrumb" class="breadcrumbs">
<ol class="breadcrumbs__list">
{items.map((item, i) => (
<li class="breadcrumbs__item">
{item.href
? <a href={item.href}>{item.label}</a>
: <span aria-current="page">{item.label}</span>
}
</li>
))}
</ol>
</nav>
<!-- Datos estructurados para Google -->
<script
type="application/ld+json"
set:html={JSON.stringify(breadcrumbSchema)}
/>{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Inicio",
"item": "https://arnoldwender.com/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Blog",
"item": "https://arnoldwender.com/blog"
},
{
"@type": "ListItem",
"position": 3,
"name": "Datos Estructurados JSON-LD"
}
]
}LocalBusiness para segmentacion geografica
El schema LocalBusiness es esencial para cualquier negocio que atiende clientes en una region especifica. Contiene el nombre de la empresa, direccion, coordenadas geograficas y datos de contacto. Google utiliza esta informacion para el Knowledge Graph, resultados de busqueda local e incrustaciones de Google Maps.
En este portfolio, los datos geograficos se mantienen centralmente en la configuracion SITE y se transfieren automaticamente al schema LocalBusiness.
/* src/lib/constants.ts — Configuracion central */
export const SITE: SiteConfig = {
name: 'Arnold Wender',
description: 'Desarrollador Web & Creador Digital',
url: 'https://arnoldwender.com',
locale: 'es',
author: 'Arnold Wender',
geo: {
latitude: 51.4818,
longitude: 11.9689,
placeName: 'Halle (Saale), Germany',
region: 'ST',
},
};{
"@context": "https://schema.org",
"@type": "LocalBusiness",
"name": "Arnold Wender — Desarrollo Web",
"description": "Desarrollador Web & Creador Digital",
"url": "https://arnoldwender.com",
"telephone": "+49-XXX-XXXXXXX",
"address": {
"@type": "PostalAddress",
"addressLocality": "Halle (Saale)",
"addressRegion": "ST",
"addressCountry": "DE"
},
"geo": {
"@type": "GeoCoordinates",
"latitude": 51.4818,
"longitude": 11.9689
},
"areaServed": {
"@type": "GeoCircle",
"geoMidpoint": {
"@type": "GeoCoordinates",
"latitude": 51.4818,
"longitude": 11.9689
},
"geoRadius": "50000"
}
}---
/* src/components/seo/SEO.astro — Extracto */
import { SITE } from '../../lib/constants';
/* LocalBusiness solo en la pagina de inicio */
const isHomepage = Astro.url.pathname === '/';
const localBusinessSchema = isHomepage && SITE.geo ? {
"@context": "https://schema.org",
"@type": "LocalBusiness",
"name": SITE.name,
"description": SITE.description,
"url": SITE.url,
"address": {
"@type": "PostalAddress",
"addressLocality": SITE.geo.placeName,
"addressRegion": SITE.geo.region,
"addressCountry": "DE",
},
"geo": {
"@type": "GeoCoordinates",
"latitude": SITE.geo.latitude,
"longitude": SITE.geo.longitude,
},
} : null;
---
{localBusinessSchema && (
<script
type="application/ld+json"
set:html={JSON.stringify(localBusinessSchema)}
/>
)}Datos estructurados multilingues
En sitios web multilingues, cada version de idioma debe generar sus propios datos estructurados. Esto significa: la pagina en aleman entrega JSON-LD en aleman, la pagina en ingles entrega JSON-LD en ingles, la pagina en espanol entrega JSON-LD en espanol. Los motores de busqueda asocian los datos estructurados con la version de idioma respectiva. Si quieres saber como implementar un sitio multilingue con URLs traducidas y etiquetas hreflang, lee nuestra guia sobre i18n sin plugins con mapeo de slugs.
En Astro, las paginas multilingues se gestionan a traves de la estructura de carpetas (/de/, /en/, /es/) o mediante Content Collections con un campo locale. Cada version de idioma de la pagina renderiza su propio <script type="application/ld+json"> con el contenido traducido. La estructura del schema (@type, @context) permanece identica — solo los campos legibles por humanos (name, description, text) se traducen.
La implementacion utiliza la informacion de locale del frontmatter o la URL. Las preguntas FAQ, descripciones de servicios y etiquetas de breadcrumbs provienen de archivos de datos especificos por idioma. El schema se genera en tiempo de build para cada idioma por separado — no hay cambio dinamico de idioma en JSON-LD.
El error mas comun es mezclar idiomas dentro de un solo bloque JSON-LD. Si la pagina esta en espanol, todo el texto en el schema tambien debe estar en espanol. Un segundo error: olvidar establecer la propiedad inLanguage. Tercer error: datos estructurados identicos en todas las versiones de idioma — Google reconoce esto como contenido duplicado.
Pruebas y validacion
Implementar datos estructurados es solo la mitad del trabajo. Sin pruebas sistematicas, no puedes estar seguro de que Google interpreta correctamente tus schemas. Hay cuatro herramientas que deberias usar en tu flujo de trabajo.
Flujo de validacion
- Google Rich Results Test
La herramienta oficial de Google en search.google.com/test/rich-results. Ingresa tu URL o pega codigo HTML. Te muestra exactamente que Rich Results puede generar Google a partir de tus datos estructurados -- y reporta errores o advertencias.
- Validador Schema.org
En validator.schema.org puedes validar tu JSON-LD contra la especificacion de Schema.org. Esta herramienta es mas estricta que el test de Google y tambien verifica campos que Google mismo ignora. Ideal para conformidad completa.
- Inspeccion con Chrome DevTools
Abre DevTools (F12), ve a Elements y busca <script type="application/ld+json">. Aqui ves la salida JSON-LD real de tu pagina. Verifica que los datos son correctos, todos los campos estan presentes y ningun error de JavaScript interfiere con la generacion.
- Google Search Console
Despues del despliegue, monitorea el estado de los datos estructurados a lo largo del tiempo en la seccion "Mejoras" > "Rich Results". Google te muestra que paginas son elegibles para Rich Results, cuales tienen errores y como se desarrollan las impresiones.
Evitar errores comunes
La implementacion correcta de datos estructurados requiere precision. Pequenos errores pueden hacer que Google ignore completamente tu schema. Aqui estan las trampas mas comunes y como evitarlas.
| Aspecto | Correcto Recommended | Incorrecto |
|---|---|---|
| Schema por pagina | Un schema FAQPage con todas las preguntas | Multiples schemas FAQPage en la misma pagina |
| Campos obligatorios | Todos los campos requeridos segun Schema.org | Omitir campos y esperar que Google lo acepte |
| Escritura de @type | @type: "FAQPage" (exacto) | @type: "faqpage" o @type: "FAQ" |
| Coincidencia de contenido | Texto JSON-LD = contenido visible de la pagina | Texto diferente en el schema que en la pagina |
| Anidamiento | Estructura plana, asignaciones @type limpias | Anidamiento excesivo sin jerarquia clara |
| Multiples schemas | Etiquetas <script> separadas para cada tipo | Todos los schemas en una sola etiqueta <script> |
| Idioma | inLanguage coincide con el idioma de la pagina | Sin inLanguage o idioma incorrecto |
Integracion con Sitemap
Los datos estructurados y el sitemap trabajan de la mano. Las paginas con marcado schema rico merecen una mayor prioridad de rastreo porque potencialmente entregan mas informacion para el indice de Google. En la configuracion de Astro, esto se implementa a traves de un sistema de prioridades escalonado.
La pagina de inicio contiene schemas Organization y LocalBusiness. Maxima prioridad de rastreo con frecuencia diaria.
Servicios, Sobre mi, Contacto -- paginas con schemas Service y ContactPage. Frecuencia de rastreo semanal.
Cada articulo tiene un schema Article con autor, fecha y etiquetas. Frecuencia de rastreo mensual para posts antiguos.
Paginas de proyectos con schema CreativeWork. Se actualizan con menos frecuencia pero son importantes para la estructura general.
Paginas de etiquetas y categorias con schema CollectionPage. Ayudan a Google a entender la taxonomia.
Paginas de busqueda y paginacion. Baja prioridad pero necesarias para indexacion completa.
Preguntas frecuentes
Frequently Asked Questions
No, JSON-LD practicamente no tiene impacto en el rendimiento. Las etiquetas script tipicamente son solo unos pocos kilobytes y no son renderizadas ni ejecutadas por el navegador. No bloquean ni el analisis ni el renderizado de la pagina. A diferencia de Microdata, que se incrusta en HTML, JSON-LD esta completamente separado del DOM visual.
No hay limite tecnico. Google recomienda usar todos los tipos de schema relevantes siempre que describan el contenido real de la pagina. Una pagina tipica podria combinar WebPage, BreadcrumbList y un schema especifico del contenido (FAQPage, Service, Article). Lo importante es que cada tipo de schema vaya en su propia etiqueta <script>.
Tecnicamente si, pero Google recomienda explicitamente JSON-LD como formato preferido. Microdata se incrusta directamente en atributos HTML, lo que hace el codigo mas dificil de mantener y puede causar problemas en frameworks basados en componentes como Astro o React. JSON-LD separa completamente los datos estructurados del marcado -- mas limpio, mas facil de depurar y mas facil de actualizar.
Entre unos pocos dias y varias semanas. Despues de que Google rastree tu pagina con los nuevos datos estructurados, el schema necesita ser validado y los Rich Results generados. Puedes acelerar el proceso enviando la URL para re-indexacion via Google Search Console. Monitorea el progreso en el informe de Rich Results de Search Console.
Google ignora silenciosamente los schemas con errores -- no hay penalizacion. Sin embargo, no se generaran Rich Results. Usa el Google Rich Results Test para detectar errores antes del despliegue. Errores comunes: campos obligatorios faltantes, valores @type incorrectos y contenido en el schema que no coincide con el contenido visible de la pagina.
Si tu JSON-LD se genera dinamicamente a partir de los datos de la pagina (como en esta configuracion de Astro), se actualiza automaticamente con cada build. Cuando cambian las preguntas FAQ, servicios o breadcrumbs, los datos estructurados reflejan esto automaticamente. Con bloques JSON-LD estaticos, debes asegurar manualmente la consistencia.
Conclusion
Los datos estructurados con JSON-LD no son un bonus SEO opcional — son una parte fundamental del desarrollo web moderno. No cuestan rendimiento (como detallamos en nuestra guia de Core Web Vitals), no requieren cambio de framework y pueden integrarse elegantemente en la arquitectura de componentes existente de Astro. Cuatro tipos de schema — FAQPage, Service, BreadcrumbList y LocalBusiness — cubren los casos de uso mas importantes para un portfolio o sitio web empresarial.
La clave esta en la automatizacion: los datos estructurados no deben mantenerse manualmente sino alimentarse de las mismas fuentes de datos que el contenido visible. En Astro, esto significa: props y Content Collections fluyen hacia componentes que renderizan tanto el HTML visual como el JSON-LD invisible. Una unica fuente de verdad para humanos y maquinas por igual.