Guia Completo de Implementação de JSON-LD para SEO
Dados estruturados JSON-LD informam aos mecanismos de busca exatamente sobre o seu conteúdo. A marcação correta libera resultados enriquecidos no Google — FAQs, carrosséis de artigos, trilhas de navegação e mais — direto na página de resultados.
Este guia apresenta os principais tipos de schema com código real em C# e o JSON exato gerado. Todos os exemplos vêm de um código Blazor em produção.
Sumário
O que é JSON-LD e por que é importante para SEO
JSON-LD (JavaScript Object Notation for Linked Data) é um método de codificar dados estruturados em JSON. Motores de busca como o Google usam esses dados para entender o significado do seu conteúdo, não só as palavras-chave.
Quando o Google interpreta seus dados estruturados, sua página pode exibir resultados enriquecidos — listagens visuais com avaliações, FAQs, imagens, breadcrumbs e mais, aumentando cliques em relação a links comuns.
O Google recomenda JSON-LD em vez de Microdata e RDFa porque pode ser colocado em qualquer parte da página — inclusive no head — sem alterar o HTML existente. Os dados ficam totalmente separados do markup.
Elegibilidade para resultados enriquecidos
Marcação schema válida torna suas páginas elegíveis para FAQs, carrosséis, breadcrumbs e outros recursos no Google Search.
Mais cliques com o mesmo posicionamento
Clareza semântica
Dados estruturados eliminam ambiguidades. Uma página de perguntas e respostas é declarada como FAQPage, para o Google exibir resultado enriquecido de FAQ.
Informe aos buscadores exatamente o que você tem
Sem alterações no HTML
JSON-LD fica em uma tag script no head, sem tocar no HTML visível, evitando riscos de quebrar o layout ou acessibilidade.
Separação clara de responsabilidades
JSON-LD vs. Microdata vs. RDFa
Existem três formatos para inserir dados schema.org em páginas web. Todos são reconhecidos pelo Google, mas diferem na aplicação e manutenção.
| Formato | Local da sintaxe | Manutenção | Impacto no SEO | Recomendação do Google |
|---|---|---|---|---|
| JSON-LD | Tag script separada | Fácil — sem alterações no HTML | Suporte completo a resultados enriquecidos | Recomendado |
| Microdata | Atributos inline no HTML | Alto — fortemente ligado ao markup | Suporte completo a resultados enriquecidos | Suportado |
| RDFa | Atributos inline no HTML | Alto — fortemente ligado ao markup | Suporte completo a resultados enriquecidos | Suportado |
Por que JSON-LD é mais fácil de manter
Com Microdata e RDFa, atributos schema ficam espalhados no HTML. Mudanças no design podem quebrar os dados. JSON-LD é um bloco único — atualize o script e o HTML não é afetado.
Domine Desenvolvimento Web moderno com SEO eficaz
Dica minha Achei este curso valioso para entender como SEO técnico, dados estruturados e padrões web modernos funcionam juntos em projetos reais.
- Aprenda a implementar meta tags HTML, Open Graph e dados estruturados JSON-LD.
- Estratégias práticas de SEO para melhorar visibilidade e ranking nos buscadores.
- Projetos práticos sobre design responsivo e otimização de desempenho.
Principais tipos de schema e quando usar
Schema.org define centenas de tipos, mas poucos cobrem a maior parte do conteúdo web. São esses que liberam resultados enriquecidos no Google.
| Tipo de schema | Caso de uso | Tipo de resultado enriquecido |
|---|---|---|
| Article | Posts, guias, notícias | Carrossel de artigos, principais notícias |
| FAQPage | Páginas com perguntas e respostas | FAQ expansível nos resultados |
| BreadcrumbList | Qualquer página com hierarquia de navegação | Trilha breadcrumb abaixo da URL |
| WebSite / WebPage | Página inicial, hubs, landing pages | Caixa de busca de sitelinks, reconhecimento de entidade |
| SoftwareApplication | Apps, ferramentas, softwares | Resultado enriquecido de app com avaliação e preço |
Vocabulário Schema.org
Todos os tipos de schema estão definidos em schema.org. A propriedade @context em cada bloco JSON-LD orienta o parser a usar esse vocabulário. Você pode combinar vários schemas na mesma página — o Google processa cada bloco separadamente.
Implementação do schema de artigo
O schema de artigo é o mais importante para sites de conteúdo. Informa ao Google título, descrição, data, autor e editor — o mínimo para resultados enriquecidos.
A classe C# abaixo é o modelo de serialização. Cada propriedade corresponde ao campo JSON-LD via atributos JsonPropertyName.
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; }
}As propriedades obrigatórias são: headline, image, datePublished, dateModified, author e publisher. O array articleSection é opcional, mas recomendado — indica o escopo do artigo para o Google.
<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>Autor e editor são do tipo Organization. Para blogs pessoais, o autor pode ser Person com nome e URL.
Schema FAQ para snippets enriquecidos
O schema FAQPage cria resultados FAQ — perguntas e respostas expansíveis exibidas diretamente nos resultados do Google, aumentando visibilidade e cliques.
A classe FaqPage contém uma lista de perguntas. Cada uma deve ter um nome (pergunta) e uma acceptedAnswer com texto (resposta).
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; }
}A saída é um bloco FAQPage com um array mainEntity. Cada item é do tipo Question com acceptedAnswer. O Google suporta até dez perguntas por página.
<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>O @id no bloco FAQPage vincula o schema a um fragmento de URL específico. É boa prática para páginas com múltiplos schemas, facilitando a identificação.
Schema WebSite e WebPage
Schemas WebSite e WebPage formam o grafo de entidades do site. WebSite identifica o site — nome, URL, idioma e editor. WebPage descreve a página e a vincula ao WebSite via isPartOf.
Ambas as classes seguem o mesmo padrão JSON-LD. O @id do WebSite é a raiz do domínio; o do WebPage é a URL completa da página.
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; }
}A propriedade inLanguage usa códigos BCP 47 (ex: en, de, fr). O link isPartOf conecta o WebPage ao WebSite pelo @id do domínio, ajudando o Google a montar o modelo completo do site.
<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>Melhores práticas de implementação
O método WrapInScriptTag é o ponto único onde strings JSON viram blocos JSON-LD válidos. Ele envolve o schema serializado na tag script com MIME application/ld+json.
Este método é chamado por todos os construtores de schema no serviço — Article, FAQPage, BreadcrumbList, WebSite e WebPage enviam seu JSON serializado para esta utilidade.
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());
}O objeto SchemaContext é a entrada para o método BuildSchema. Ele carrega todos os dados para construir o conjunto completo de schemas da página — tipo, metadados, FAQs, breadcrumbs e dados do artigo.
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);
}O switch de despacho torna o construtor de schema componível. FAQs e breadcrumbs são sempre adicionados se existirem, independente do tipo de página. Assim, qualquer página pode ter FAQ ou breadcrumb sem alterar a lógica principal.
Testando e validando seu schema
Sintaxe JSON-LD válida não garante elegibilidade para resultados enriquecidos. As ferramentas do Google verificam sintaxe e conformidade com políticas para cada tipo de resultado.
Teste de Resultados Enriquecidos
Use search.google.com/test/rich-results para testar URLs ou colar HTML. O Google confirma os tipos de resultados detectados e aponta propriedades obrigatórias faltantes.
Validador oficial de elegibilidade do Google
Validador de Marcação Schema
validator.schema.org verifica seu markup contra a especificação schema.org, independente das políticas do Google. Útil para detectar erros de nomes e tipos.
Validação de sintaxe schema.org
Google Search Console
A seção Melhorias no Search Console reporta erros e avisos de schema em larga escala nas páginas indexadas. Use para monitoramento contínuo após validação inicial.
Monitorar em larga escala após lançamento