Guía completa de implementación SEO con JSON-LD Schema Markup

Última actualización 28/3/2026
Datos estructurados Resultados enriquecidos

Los datos estructurados JSON-LD indican a los motores de búsqueda el contenido exacto de tu página. El marcado adecuado desbloquea resultados enriquecidos en Google — desplegables FAQ, carruseles de artículos, migas de pan y más — directamente en la página de resultados.

Esta guía incluye los principales tipos de schema con código real en C# y el JSON exacto que generan. Todos los ejemplos provienen de un código Blazor en producción.

Ver esquema de artículo Patrones de implementación
Ilustración que muestra datos JSON-LD generando resultados enriquecidos en Google, incluyendo FAQ, carruseles y navegación con migas de pan
Los datos JSON-LD son la forma más fácil de mantener el marcado schema, ya que se incluyen en una etiqueta script, separada del HTML.
Índice

Qué es JSON-LD y por qué es importante para el SEO

JSON-LD (JavaScript Object Notation for Linked Data) es un método para codificar datos estructurados en formato JSON. Los motores de búsqueda como Google leen estos datos para entender el significado de tu contenido, no solo las palabras clave.

Cuando Google interpreta tus datos estructurados, tu página puede mostrar resultados enriquecidos — listados visuales con valoraciones, FAQ desplegables, imágenes, migas de pan y más, que aumentan el CTR respecto a enlaces simples.

Google recomienda JSON-LD frente a Microdata y RDFa porque puede ubicarse en cualquier parte de la página — incluso en el head — sin modificar el HTML existente. Los datos están totalmente separados del marcado visual.

Elegibilidad para resultados enriquecidos

Un marcado schema válido hace que tus páginas sean aptas para desplegables FAQ, carruseles, migas de pan y otras funciones enriquecidas en Google.

Más clics con el mismo posicionamiento

Claridad semántica

Los datos estructurados eliminan ambigüedades. Una página de preguntas y respuestas se declara como FAQPage para que Google la muestre como resultado enriquecido FAQ.

Indica a los motores de búsqueda exactamente lo que tienes

Sin cambios en el HTML

JSON-LD se incluye en una etiqueta script en el head. No afecta al HTML visual, por lo que añadir o actualizar schema no rompe el diseño ni la accesibilidad.

Separación clara de responsabilidades

JSON-LD vs. Microdata vs. RDFa

Existen tres formatos para incluir datos schema.org en páginas web. Google entiende los tres, pero difieren mucho en aplicación y mantenimiento.

Formato Ubicación de la sintaxis Mantenimiento Impacto SEO Recomendación de Google
JSON-LD Etiqueta script separada Fácil — sin cambios en HTML Soporte completo para resultados enriquecidos Recomendado
Microdata Atributos HTML en línea Alto — muy ligado al marcado Soporte completo para resultados enriquecidos Soportado
RDFa Atributos HTML en línea Alto — muy ligado al marcado Soporte completo para resultados enriquecidos Soportado

Por qué JSON-LD es más fácil de mantener

Con Microdata y RDFa, los atributos schema están dispersos en el HTML. Cambios en el diseño pueden romper los datos. JSON-LD es un bloque independiente: actualiza el script y el HTML no se ve afectado.

Selección para aprender desarrollo web

Domina el desarrollo web moderno con prácticas SEO

Consejo personal Este curso me ayudó a entender cómo SEO técnico, datos estructurados y estándares web modernos se combinan en proyectos reales.

  • Aprende a implementar meta etiquetas HTML, Open Graph y datos estructurados JSON-LD.
  • Estrategias SEO prácticas para mejorar visibilidad y posicionamiento.
  • Proyectos prácticos sobre diseño responsive y optimización de rendimiento.
Explorar el curso de desarrollo web

Tipos principales de schema y cuándo usarlos

Schema.org define cientos de tipos, pero unos pocos cubren la mayoría del contenido web. Estos son los que activan resultados enriquecidos en Google.

Tipo de schema Caso de uso Tipo de resultado enriquecido
Article Entradas de blog, guías, noticias Carrusel de artículos, Noticias destacadas
FAQPage Páginas con preguntas y respuestas Desplegable FAQ en resultados de búsqueda
BreadcrumbList Cualquier página con jerarquía de navegación Migas de pan bajo la URL
WebSite / WebPage Página principal, hubs, páginas de destino Caja de búsqueda de enlaces, reconocimiento de entidad
SoftwareApplication Apps, herramientas, productos de software Resultado enriquecido de app con valoración y precio

Vocabulario de Schema.org

Todos los tipos schema están definidos en schema.org. La propiedad @context en cada bloque JSON-LD indica a los analizadores que usen ese vocabulario. Puedes combinar varios tipos en una página; Google procesa cada bloque por separado.

Implementación del esquema Article

El esquema Article es el más importante para sitios de contenido. Indica a Google el título, descripción, fecha de publicación, autor y editor — el mínimo para resultados enriquecidos.

La clase C# siguiente es el modelo de serialización. Cada propiedad se asigna directamente al campo JSON-LD correspondiente con atributos JsonPropertyName.

C#Clase C# ArticleSchema (JsonLdService.cs)
private class ArticleSchema
{
    [JsonPropertyName("@context")]
    public string Context { get; } = "https://schema.org";

    [JsonPropertyName("@type")]
    public string Type { get; } = "Article";

    [JsonPropertyName("headline")]
    public string? Headline { get; set; }

    [JsonPropertyName("description")]
    public string? Description { get; set; }

    [JsonPropertyName("image")]
    public string? Image { get; set; }

    [JsonPropertyName("url")]
    public string? Url { get; set; }

    [JsonPropertyName("author")]
    public Organization? Author { get; set; }

    [JsonPropertyName("publisher")]
    public ArticlePublisher? Publisher { get; set; }

    [JsonPropertyName("datePublished")]
    public string? DatePublished { get; set; }

    [JsonPropertyName("dateModified")]
    public string? DateModified { get; set; }

    [JsonPropertyName("articleSection")]
    public List<string>? ArticleSection { get; set; }
}

Las propiedades obligatorias son: headline, image, datePublished, dateModified, author y publisher. El array articleSection es opcional pero recomendado — indica el ámbito temático del artículo a Google.

HTMLSalida JSON-LD del esquema Article
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "JSON-LD Schema Markup: Complete SEO Implementation Guide",
  "description": "Learn how to implement JSON-LD structured data for Article, FAQPage, BreadcrumbList, WebSite, and WebPage schema types.",
  "image": "https://ghostlyinc.com/images/web/jsonldguide/opengraph/hero-1200.png",
  "url": "https://ghostlyinc.com/en/json-ld-schema-markup-seo-guide/",
  "author": {
    "@type": "Organization",
    "name": "GhostlyInc",
    "url": "https://ghostlyinc.com"
  },
  "publisher": {
    "@type": "Organization",
    "name": "GhostlyInc",
    "logo": {
      "@type": "ImageObject",
      "url": "https://ghostlyinc.com/images/logo.png"
    }
  },
  "datePublished": "2026-03-28T10:00:00Z",
  "dateModified": "2026-03-28T10:00:00Z",
  "articleSection": [
    "What is JSON-LD and why it matters for SEO",
    "JSON-LD vs. Microdata vs. RDFa",
    "Core schema types and when to use them",
    "Article schema implementation"
  ]
}
</script>

El autor y editor se tipan como Organization. En blogs personales, el autor puede ser una Person con nombre y url.

Esquema FAQ para fragmentos enriquecidos

El esquema FAQPage crea resultados enriquecidos FAQ — pares de preguntas y respuestas desplegables que aparecen en Google justo debajo de tu listado. Aumenta el espacio vertical, mejorando visibilidad y clics.

La clase FaqPage contiene una lista de preguntas. Cada una debe tener un nombre (la pregunta) y una acceptedAnswer con la propiedad text (la respuesta).

C#Clase C# FaqPage (JsonLdService.cs)
private class FaqPage
{
    [JsonPropertyName("@context")]
    public string Context { get; } = "https://schema.org";

    [JsonPropertyName("@type")]
    public string Type { get; } = "FAQPage";

    [JsonPropertyName("@id")]
    public string? Id { get; set; }

    [JsonPropertyName("name")]
    public string? Name { get; set; }

    [JsonPropertyName("mainEntity")]
    public List<FaqEntity>? MainEntity { get; set; }
}

private class FaqEntity
{
    [JsonPropertyName("@type")]
    public string Type { get; } = "Question";

    [JsonPropertyName("name")]
    public string? Name { get; set; }

    [JsonPropertyName("acceptedAnswer")]
    public FaqAnswer? AcceptedAnswer { get; set; }
}

private class FaqAnswer
{
    [JsonPropertyName("@type")]
    public string Type { get; } = "Answer";

    [JsonPropertyName("text")]
    public string? Text { get; set; }
}

La salida es un bloque FAQPage con un array mainEntity. Cada elemento es un tipo Question con acceptedAnswer. Google admite hasta diez preguntas por página para resultados enriquecidos.

HTMLSalida JSON-LD del esquema FAQ
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "@id": "https://ghostlyinc.com/en/json-ld-schema-markup-seo-guide/#faq",
  "name": "Frequently asked questions",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is the difference between JSON-LD and Microdata?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "JSON-LD is a separate script block that lives in the head and does not touch HTML. Microdata adds attributes directly to HTML elements. Google recommends JSON-LD for its maintainability."
      }
    },
    {
      "@type": "Question",
      "name": "How many FAQ questions can I mark up?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Google supports up to ten questions per page for the FAQ rich result. Additional questions are still valid schema but will not appear in the search result enhancement."
      }
    }
  ]
}
</script>

El @id en el bloque FAQPage ancla el esquema a un fragmento URL específico. Es buena práctica para páginas con varios bloques schema, permitiendo identificar cada entidad sin ambigüedades.

Esquemas WebSite y WebPage

Los esquemas WebSite y WebPage establecen el grafo de entidades base de un sitio. WebSite identifica el sitio — nombre, URL, idioma y editor. WebPage describe la página individual y la vincula al WebSite padre con isPartOf.

Ambas clases siguen el mismo patrón JSON-LD. El @id de WebSite es la raíz del dominio; el @id de WebPage es la URL completa de la página.

C#Clases C# WebSiteSchema y WebPageSchema (JsonLdService.cs)
private class WebSiteSchema
{
    [JsonPropertyName("@context")]
    public string Context { get; } = "https://schema.org";

    [JsonPropertyName("@type")]
    public string Type { get; } = "WebSite";

    [JsonPropertyName("name")]
    public string? Name { get; set; }

    [JsonPropertyName("url")]
    public string? Url { get; set; }

    [JsonPropertyName("inLanguage")]
    public string? InLanguage { get; set; }

    [JsonPropertyName("publisher")]
    public Organization? Publisher { get; set; }
}

private class WebPageSchema
{
    [JsonPropertyName("@context")]
    public string Context { get; } = "https://schema.org";

    [JsonPropertyName("@type")]
    public string Type { get; } = "WebPage";

    [JsonPropertyName("@id")]
    public string? Id { get; set; }

    [JsonPropertyName("name")]
    public string? Name { get; set; }

    [JsonPropertyName("description")]
    public string? Description { get; set; }

    [JsonPropertyName("url")]
    public string? Url { get; set; }

    [JsonPropertyName("inLanguage")]
    public string? InLanguage { get; set; }

    [JsonPropertyName("isPartOf")]
    public WebSiteReference? IsPartOf { get; set; }
}

La propiedad inLanguage usa códigos BCP 47 (ej. en, de, fr). El enlace isPartOf vincula WebPage con WebSite referenciando el @id del dominio. Esto ayuda a Google a construir un modelo completo de entidades del sitio.

HTMLSalida JSON-LD de los esquemas WebSite y WebPage
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "GhostlyInc",
  "url": "https://ghostlyinc.com",
  "inLanguage": "en",
  "publisher": {
    "@type": "Organization",
    "name": "GhostlyInc",
    "url": "https://ghostlyinc.com"
  }
}
</script>

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "@id": "https://ghostlyinc.com/en/json-ld-schema-markup-seo-guide/",
  "name": "JSON-LD Schema Markup: Complete SEO Implementation Guide",
  "description": "Learn how to implement JSON-LD structured data for Article, FAQPage, BreadcrumbList, WebSite, and WebPage schema types.",
  "url": "https://ghostlyinc.com/en/json-ld-schema-markup-seo-guide/",
  "inLanguage": "en",
  "isPartOf": {
    "@type": "WebSite",
    "@id": "https://ghostlyinc.com"
  }
}
</script>

Buenas prácticas de implementación

El método auxiliar WrapInScriptTag es el punto único donde las cadenas JSON se convierten en bloques JSON-LD válidos. Envuelve cualquier esquema serializado en la etiqueta script requerida con MIME type application/ld+json.

Este método es llamado por todos los constructores de schema en el servicio — Article, FAQPage, BreadcrumbList, WebSite y WebPage pasan su JSON serializado a esta utilidad.

C#Método WrapInScriptTag (JsonLdService.cs)
private static MarkupString WrapInScriptTag(string json)
{
    var builder = new StringBuilder();
    builder.AppendLine("<script type=\"application/ld+json\">");
    builder.AppendLine(json);
    builder.AppendLine("</script>");

    return new MarkupString(builder.ToString());
}

El objeto SchemaContext es la entrada para el método BuildSchema. Contiene todos los datos necesarios para construir el conjunto completo de bloques schema para una página — tipo, metadatos, lista FAQ, jerarquía de migas y datos del artículo.

C#Lógica de despacho BuildSchema (JsonLdService.cs)
public SchemaBuildResult BuildSchema(SchemaContext context)
{
    if (context == null) throw new ArgumentNullException(nameof(context));

    var jsonLd = new List<MarkupString>();

    switch (context.PageType)
    {
        case PageSchemaType.Home:
            jsonLd.Add(WebSite(context));
            jsonLd.Add(WebPage(context));
            break;
        case PageSchemaType.Article:
            jsonLd.Add(Article(context.Article!));
            break;
        case PageSchemaType.Tool:
            jsonLd.Add(WebPage(context));
            jsonLd.Add(SoftwareApplication(context.SoftwareApplication!));
            break;
        case PageSchemaType.Hub:
            jsonLd.Add(WebPage(context));
            break;
    }

    if (context.Faqs != null && context.Faqs.Count > 0)
    {
        jsonLd.Add(FAQ(context.Faqs.ToList(), context.FaqTitle, context.Url));
    }

    if (context.ParentHierarchy.Count > 0)
    {
        jsonLd.Add(BreadcrumbList(BuildBreadcrumbItems(context)));
    }

    return new SchemaBuildResult(jsonLd, context.PageType == PageSchemaType.Article);
}

El switch de despacho hace que el constructor schema sea componible. FAQs y migas se añaden siempre si están presentes, sin importar el tipo de página. Así, cualquier tipo puede tener bloque FAQ o migas sin cambiar la lógica central.

Pruebas y validación de tu schema

Una sintaxis JSON-LD válida no garantiza elegibilidad para resultados enriquecidos. Las herramientas de Google verifican validez y cumplimiento de políticas para cada tipo de resultado.

Test de Resultados Enriquecidos

Usa search.google.com/test/rich-results para probar cualquier URL o pegar HTML. Google confirma los tipos de resultados detectados y señala propiedades obligatorias faltantes.

Comprobador oficial de elegibilidad de Google

Validador de marcado Schema

validator.schema.org verifica tu marcado según la especificación schema.org, independiente de las políticas de resultados enriquecidos de Google. Útil para detectar errores de nombres y tipos.

Validación de sintaxis Schema.org

Google Search Console

La sección Mejoras en Search Console informa errores y avisos de schema a gran escala en tus páginas indexadas. Úsala para monitorizar tras la validación inicial.

Monitorización a gran escala tras lanzamiento

Preguntas frecuentes

Respuestas a preguntas comunes sobre marcado JSON-LD