Guía práctica de datos estructurados

Guía de marcado JSON-LD para SEO práctico

JSON-LD ayuda a los motores a entender qué es una página, quién la publicó, cómo encaja en tu sitio y qué datos usar en funciones de búsqueda.

El objetivo útil no es añadir todos los tipos de esquema que encuentres. Es tener datos estructurados precisos que coincidan con la página visible, validen correctamente y se mantengan sincronizados con los cambios.

La útil versión corta

Usa JSON-LD cuando puedas describir la página con hechos visibles y honestos: título, descripción, autor, fecha, migas, detalles de producto, datos de vídeo o preguntas y respuestas claras. No añadas esquema para prometer funciones que Google ya no muestra o para marcar contenido invisible.

Mejor esquema inicial Article, WebPage y BreadcrumbList para la mayoría de páginas guía.
Mejor flujo de trabajo Genera esquema desde los mismos metadatos que alimentan título, descripción, canónica y Open Graph.
Mejor comprobación real El marcado FAQPage y WebSite puede describir contenido, pero no bases tu estrategia en funciones de Google obsoletas.

Qué hace realmente JSON-LD

JSON-LD es un bloque legible por máquinas de datos estructurados. Normalmente va en un script en el head o body y describe entidades con vocabulario schema.org. Los motores lo usan como capa de claridad sobre el contenido visible.

Claridad del parser

Significado

Convierte hechos de la página en entidades y propiedades nombradas, como Article, author, datePublished, BreadcrumbList o SoftwareApplication.

Función de búsqueda

Elegibilidad

Puede hacer que una página sea elegible para resultados enriquecidos, pero Google decide qué mostrar según calidad, política, consulta y disponibilidad.

Grafo del sitio

Consistencia

Ofrece a tu CMS o app Blazor un lugar estructurado para reutilizar la misma URL canónica, idioma, título, fechas, imágenes y datos del editor.

No es un atajo

Límite

No repara contenido débil, reseñas falsas, respuestas FAQ ocultas, fechas desactualizadas ni páginas que no coinciden con los datos estructurados.

Importante: Los datos estructurados deben apoyar la página, no reemplazar contenido útil. Si la página visible es pobre, confusa, obsoleta o engañosa, el esquema no la hará un buen resultado.

Elige el esquema según la función de la página

La forma más fácil de evitar datos estructurados spam o duplicados es preguntarse qué intenta hacer la página. Añade el conjunto mínimo de esquema que describa esa función con precisión.

Contenido

Article / BlogPosting

Úsalo para
Guías, tutoriales, reseñas, posts tipo noticias y explicaciones extensas.
Añadir cuando
La página tiene un titular claro, autor o editor, fecha de publicación, fecha de modificación, URL canónica e imagen.
Evitar cuando
La página es mayormente una interfaz de herramienta, listado de productos, página de categoría o landing page ligera.

Navegación

BreadcrumbList

Úsalo para
Casi todas las páginas debajo de la página principal.
Añadir cuando
Los usuarios pueden entender dónde está la página en la jerarquía del sitio.
Evitar cuando
La ruta de migas no coincide con enlaces internos, URLs canónicas o navegación visible.

Identidad del sitio

WebPage / WebSite / Organization

Úsalo para
Página principal, hubs, páginas sobre nosotros y donde importa la identidad del editor.
Añadir cuando
Quieres un grafo de entidades estable que conecte la página, sitio, editor e idioma.
Evitar cuando
Estás añadiendo marcado WebSite solo para buscar el antiguo cuadro de búsqueda de enlaces de sitio.

Producto o app

Product / SoftwareApplication

Úsalo para
Herramientas, apps, páginas SaaS, extensiones, software descargable o páginas de productos reales.
Añadir cuando
El contenido visible incluye nombre, descripción, sistema operativo o categoría, precio, ofertas y valoraciones cuando los marcas.
Evitar cuando
Valoraciones, precio, disponibilidad o reseñas no son visibles para usuarios en la página.

Preguntas

FAQPage

Úsalo para
Secciones visibles de preguntas y respuestas que realmente ayudan a los usuarios a entender el tema.
Añadir cuando
El contenido de preguntas y respuestas es útil en la página aunque Google no muestre resultados enriquecidos FAQ.
Evitar cuando
Añades preguntas y respuestas genéricas solo para ocupar espacio en búsqueda o repetir la misma respuesta en muchas páginas.

Medios

VideoObject / ImageObject

Úsalo para
Páginas con vídeo incrustado importante, tutorial o imagen rastreable.
Añadir cuando
El medio es central en la página y tiene título, descripción, miniatura, fecha de subida y URL estable.
Evitar cuando
El medio es decorativo, oculto, bloqueado o no relevante para el propósito principal de la página.

Lista de verificación para evitar la mayoría de errores

Un buen JSON-LD es aburrido en el mejor sentido: consistente, generado desde campos fiables, fácil de validar y difícil de olvidar al cambiar la página.

01

Elige una entidad principal de página

Decide si la página es principalmente un artículo, producto, app, vídeo, FAQ, colección o página web genérica. El esquema secundario debe apoyar esa entidad principal.

02

Coincidir con contenido visible

Cada dato marcado debe ser visible o claramente deducible en la página: título, autor, fechas, precio, valoración, preguntas y respuestas, migas de pan e imágenes.

03

Usa valores @id estables

Asigna IDs estables a entidades importantes como la URL canónica más #article, #webpage, #organization o #faq. Esto ayuda a los parsers a conectar piezas del grafo.

04

Generar desde metadatos compartidos

Reutiliza los mismos campos fuente que crean títulos, meta descripciones, URLs canónicas, imágenes Open Graph, etiquetas de idioma y fechas de última modificación.

05

Mantén las fechas honestas

Cambia dateModified solo cuando el contenido relevante cambie. No actualices fechas automáticamente solo para parecer más nuevo en resultados.

06

Haz las imágenes rastreables

Usa URLs absolutas para imágenes, dimensiones adecuadas y archivos no bloqueados por robots, autenticación o renderizado solo con lazy-loading.

07

Renderizar temprano

En Blazor y otras apps JavaScript, prefiere JSON-LD prerenderizado o renderizado en servidor para que los crawlers lo vean en el HTML inicial.

08

Validar y monitorizar

Ejecuta el Test de Resultados Enriquecidos antes de publicar, revisa sintaxis con el Validador de Esquemas y monitoriza Search Console tras indexar.

Un patrón limpio de JSON-LD para páginas Blazor

En Blazor, el patrón más seguro es crear el esquema desde los metadatos de la página durante la inicialización o prerenderizado, serializarlo una vez y renderizar el script application/ld+json donde los crawlers lo vean en el HTML inicial.

HTMLEjemplo de JSON-LD para artículo
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "@id": "https://example.com/en/json-ld-schema-guide/#article",
  "headline": "JSON-LD Schema Markup Guide for Practical SEO",
  "description": "A practical guide to choosing, generating, and validating structured data.",
  "image": "https://example.com/images/json-ld-guide.png",
  "datePublished": "2026-03-28T10:00:00+00:00",
  "dateModified": "2026-05-31T10:00:00+00:00",
  "author": {
    "@type": "Organization",
    "name": "Example Publisher"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Example Publisher",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.png"
    }
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://example.com/en/json-ld-schema-guide/"
  }
}
</script>
C#Patrón helper en C#
private MarkupString BuildJsonLd(PageMetaData meta)
{
    var pageUrl = BuildPageUrl(meta);

    var schema = new Dictionary<string, object?>
    {
        ["@context"] = "https://schema.org",
        ["@type"] = "Article",
        ["@id"] = $"{pageUrl}#article",
        ["headline"] = meta.Title,
        ["description"] = meta.Description,
        ["url"] = pageUrl,
        ["datePublished"] = meta.Published?.ToString("O"),
        ["dateModified"] = meta.Modified?.ToString("O"),
        ["inLanguage"] = CS.Culture
    };

    var json = JsonSerializer.Serialize(schema, new JsonSerializerOptions
    {
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
    });

    return new MarkupString($"<script type=\"application/ld+json\">{json}</script>");
}
Regla práctica: Usa URLs estables para url y @id. Usa la misma URL canónica en todas partes. Si la misma página aparece en varias URLs por idioma, genera metadatos específicos para cada idioma y mantén coherente la configuración hreflang/canónica.

Valida JSON-LD antes de usarlo

La validación tiene dos funciones: el Validador de Esquemas verifica vocabulario y sintaxis JSON-LD; el Test de Resultados Enriquecidos de Google comprueba si la página es elegible para tipos de resultados enriquecidos.

Elegibilidad Google

Test de Resultados Enriquecidos

Comprueba si Google puede leer la página y si los datos estructurados detectados son elegibles para resultados enriquecidos compatibles.

Abrir Test de Resultados Enriquecidos

Vocabulario

Validador de marcado Schema

Verifica la estructura general de schema.org y la sintaxis JSON-LD, incluyendo tipos, propiedades, entidades anidadas y JSON mal formado.

Abrir Validador de Esquemas

Errores comunes en JSON-LD que dañan la confianza

La mayoría de problemas con esquemas no son bugs técnicos complejos, sino discrepancias entre el marcado y lo que el usuario o crawler puede verificar en la página.

Marcar contenido oculto o ausente

Si los usuarios no pueden ver la respuesta, reseña, oferta, imagen o autor, no lo incluyas en datos estructurados. Es la forma más rápida de perder confianza.

Añadiendo FAQPage a todo

El esquema FAQ puede describir preguntas y respuestas visibles, pero no debe copiarse en todos los artículos. Úsalo solo si mejora la página.

Scripts duplicados en conflicto

Varios bloques Article con titulares, fechas o URLs diferentes dificultan la interpretación. Un grafo claro es mejor que tres parciales.

Canónica o @id incorrectos

Las URLs del esquema deben coincidir con la página canónica, URL cultural y configuración hreflang. URLs en idiomas mezclados generan contenido duplicado y confusión de entidades.

Falsa actualidad

No actualices dateModified por cambios en plantillas, seguimiento o solo esquema. Usa la fecha para cambios reales de contenido.

Renderizado tardío solo en cliente

Si JSON-LD aparece solo tras un renderizado tardío en cliente, los crawlers pueden no verlo. Prefiere renderizado en servidor o prerenderizado para páginas importantes.

Recetas prácticas de esquema por tipo de página

Rara vez necesitas un grafo gigante. Estas combinaciones cubren las páginas que la mayoría de sitios pequeños, blogs, herramientas y proyectos de reseñas publican.

Artículo guía

Article + BreadcrumbList + WebPage

  • Usa Article para titular, autor, editor, imagen, fechas y nombres de sección.
  • Usa BreadcrumbList para la ruta visible del sitio.
  • Usa referencias WebPage o @id para conectar la página y la entidad artículo.

Página de herramienta

SoftwareApplication + WebPage + BreadcrumbList

  • Usa SoftwareApplication solo si la página trata sobre una app o herramienta real.
  • Incluye sistema operativo, categoría, precio u oferta solo si son visibles.
  • Evita marcar reseñas o valoraciones si la página no muestra datos reales.

Página de reseña

Reseña / Producto solo si la página lo soporta

  • Marca el ítem revisado, autor, fecha y valoración solo si la página los muestra claramente.
  • Mantén transparentes los enlaces de afiliados y el contexto comercial.
  • Usa la misma puntuación en esquema y contenido visible.

Página de preguntas

FAQPage solo para preguntas y respuestas visibles útiles

  • Haz que cada respuesta sea útil por sí misma, no solo una variante de palabra clave.
  • No ocultes respuestas tras interfaces bloqueadas inaccesibles para crawlers.
  • No esperes que los resultados enriquecidos de FAQ sean el principal beneficio SEO.

Fuentes consultadas

La guía anterior se basa en documentación oficial de Google Search Central y schema.org, convertida en una checklist práctica de JSON-LD.

01 Introducción a datos estructurados de Google developers.google.com 02 Políticas de datos estructurados de Google developers.google.com 03 Datos estructurados Google Article developers.google.com 04 Datos estructurados Google Breadcrumb developers.google.com 05 Datos estructurados Google FAQ developers.google.com 06 Actualización del cuadro de búsqueda de enlaces de sitio de Google developers.google.com 07 Introducción a Schema.org schema.org 08 Test de Resultados Enriquecidos de Google search.google.com 09 Validador de marcado Schema validator.schema.org

Preguntas frecuentes

¿Es el marcado JSON-LD un factor de posicionamiento?

JSON-LD no es un interruptor mágico de posicionamiento. Ayuda a entender contenido elegible y puede apoyar resultados enriquecidos, pero el ranking depende de calidad, relevancia, rastreo, enlaces y más.

¿Dónde debe ir JSON-LD en una página?

Un script en el head suele ser más fácil de gestionar, pero Google también puede leer JSON-LD en el body. Lo importante es que el marcado esté en la página renderizada y coincida con el contenido visible.

¿Debería seguir usando el esquema FAQPage?

Usa FAQPage solo cuando la página tenga preguntas y respuestas visibles realmente útiles. No confíes en ello para más espacio en resultados Google, pues su uso está muy reducido y obsoleto para sitios comunes.

¿Puede una página tener varios bloques JSON-LD?

Sí. Una página normal de artículo puede tener datos Article, BreadcrumbList y WebPage. Mantén los bloques consistentes, evita entidades duplicadas en conflicto y usa valores @id estables para conectar piezas relacionadas.

¿Es JSON-LD mejor que Microdata?

Para la mayoría de sitios modernos, sí. Google soporta JSON-LD, Microdata y RDFa, pero JSON-LD es más fácil de mantener porque no requiere atributos schema en plantillas HTML visuales.

¿Con qué frecuencia debo validar los datos estructurados?

Valida cada vez que cambies plantillas, campos de metadatos, helpers de esquema, URLs, rutas de idioma, generación de imágenes, datos de reseñas o secciones FAQ. También revisa Search Console tras indexar páginas importantes.