JSON-LD para documentação: tipos de esquema que importam

JSON-LD é dados estruturados incorporados no seu HTML que informam os motores de busca e agentes de IA sobre que tipo de conteúdo está na página. Para documentação, os tipos de esquema corretos tornam o tipo da página, etapas, breadcrumbs e identidade do produto legíveis por máquina em vez de deixá-los implícitos pelo layout.

Este post lista os tipos de esquema que valem a pena adicionar, nomeia aquele cujo resultado rico o Google restringiu desde então e fornece exemplos funcionais. Não promete uma classificação ou uma citação: nenhuma técnica revisada tem um efeito causal estável e cross-platform em qualquer um deles.

TL;DR#

Se você fizer apenas um, faça TechArticle e BreadcrumbList. O Docsbook adiciona isso automaticamente.

Por que JSON-LD em vez de Microdata ou RDFa#

JSON-LD vence porque:

1. É um bloco <script> separado, desacoplado do seu markup HTML
2. O Google prefere explicitamente ("recomendado" em sua documentação)
3. Mais fácil de manter — altere o esquema sem tocar no layout
4. Agentes de IA o analisam de forma mais confiável do que o markup inline

Microdata e RDFa ainda funcionam, mas são legados em 2026.

TechArticle: o padrão para docs#

Para a maioria das páginas de documentação, TechArticle é o esquema certo:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "How to authenticate with OAuth",
  "description": "Step-by-step guide to authenticating users with OAuth 2.0",
  "author": {
    "@type": "Organization",
    "name": "Acme",
    "url": "https://acme.com"
  },
  "datePublished": "2026-01-15",
  "dateModified": "2026-03-20",
  "publisher": {
    "@type": "Organization",
    "name": "Acme",
    "logo": {
      "@type": "ImageObject",
      "url": "https://acme.com/logo.png"
    }
  },
  "mainEntityOfPage": "https://docs.acme.com/auth/oauth"
}
</script>

O que isso lhe oferece:

• O Google marca a página como conteúdo técnico autoritativo
• Agentes de IA tendem a classificar páginas marcadas com TechArticle mais alto em citações
• dateModified informa aos crawlers que a página é nova

FAQPage: rich snippets gold#

Se a sua página tiver uma estrutura de Q&A, o esquema FAQPage faz com que o Google mostre essas Q&As diretamente nos resultados de busca.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "How do I revoke an API key?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Open the dashboard, navigate to API Keys, find the key, click Revoke. Revocation is immediate."
    }
  }, {
    "@type": "Question",
    "name": "Can I have multiple API keys?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Yes. Replace this answer with the real limit from your own product."
    }
  }]
}
</script>

O markup FAQPage ainda produz um resultado rico no Google?#

Para quase todos os sites de documentação, não. O Google restringiu o resultado rico de FAQ em 2023, e sua própria documentação agora afirma que o recurso "é mostrado apenas para sites governamentais e de saúde bem conhecidos e autoritários" (Google Search Central, dados estruturados FAQPage, lido em 2026-09-03). Qualquer guia que promete um aumento de cliques a partir de trechos de FAQ em um site de documentação de produtos está descrevendo o mundo anterior a 2023.

Isso não é uma razão para deletar o markup. FAQPage ainda faz uma coisa bem: afirma, em uma forma que um parser não pode interpretar mal, que este bloco é uma pergunta e que aquele bloco é sua resposta. Mantenha-o onde a página é genuinamente uma lista de perguntas e respostas, e não espere nenhuma mudança visual no Google.

Como Fazer: guias passo a passo#

Se você tiver um guia passo a passo numerado, use HowTo:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "Set up a custom domain for documentation",
  "step": [{
    "@type": "HowToStep",
    "text": "Open the dashboard and go to Settings → Domain"
  }, {
    "@type": "HowToStep",
    "text": "Enter your subdomain (docs.yourcompany.com)"
  }, {
    "@type": "HowToStep",
    "text": "Add a CNAME record in DNS pointing to cname.vercel-dns.com"
  }, {
    "@type": "HowToStep",
    "text": "Wait for SSL to provision (under 5 minutes)"
  }]
}
</script>

Resultado: O Google pode mostrar resultados ricos passo a passo com cada etapa expandida.

SoftwareApplication: página do produto#

Sua página de visão geral do produto deve ser marcada como SoftwareApplication:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "Acme",
  "applicationCategory": "DeveloperApplication",
  "operatingSystem": "Web",
  "offers": {
    "@type": "Offer",
    "price": "150",
    "priceCurrency": "USD"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.8",
    "ratingCount": "247"
  }
}
</script>

Isso exibe preços e classificações nos resultados ricos do Google. Seja honesto sobre as classificações — o Google penaliza aggregateRating inflacionadas.

BreadcrumbList: cada página#

Cada página deve ter breadcrumbs em JSON-LD. O Google os exibe nos resultados de busca, agentes de IA os utilizam para entender a hierarquia:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [{
    "@type": "ListItem",
    "position": 1,
    "name": "Docs",
    "item": "https://docs.acme.com"
  }, {
    "@type": "ListItem",
    "position": 2,
    "name": "Authentication",
    "item": "https://docs.acme.com/auth"
  }, {
    "@type": "ListItem",
    "position": 3,
    "name": "OAuth",
    "item": "https://docs.acme.com/auth/oauth"
  }]
}
</script>

WebSite: caixa de pesquisa do site#

Na sua página inicial, declare a pesquisa do site:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://docs.acme.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": "https://docs.acme.com/search?q={search_term_string}",
    "query-input": "required name=search_term_string"
  }
}
</script>

Isso desbloqueia a caixa de pesquisa diretamente sob seu resultado no Google.

Múltiplos esquemas em uma página#

Você pode empilhar esquemas. Uma página de documento pode ter:

• TechArticle para o tipo de conteúdo
• BreadcrumbList para navegação
• FAQPage se houver uma seção de perguntas e respostas

Todos os três em três blocos <script type="application/ld+json"> separados. O Google lê todos eles.

O que os agentes de IA fazem com JSON-LD#

Três comportamentos observados:

1. Filtragem de tipo — agentes que procuram tutoriais preferem TechArticle e HowTo em vez de Article
2. Atalhos de extração — o esquema FAQPage é extraído quase que literalmente
3. Sinais de confiança — esquemas com Organization e publisher adequados são ponderados mais alto

Como o Docsbook envia JSON-LD#

O Docsbook adiciona automaticamente:

• TechArticle a cada página de documentação
• BreadcrumbList a cada página
• FAQPage a páginas onde detecta padrões de Q&A
• SoftwareApplication à sua página inicial se os metadados forem fornecidos
• WebSite com SearchAction à raiz do site

Sem configuração. O esquema é construído a partir do seu markdown e frontmatter existentes.

Validação#

Duass ferramentas:

• Teste de Resultados Ricos do Google — https://search.google.com/test/rich-results
• Validador do Schema.org — https://validator.schema.org/

Execute ambos nas páginas de documentação. Corrija quaisquer avisos. Erros são bloqueadores; avisos não são.

Leitura relacionada#

• Guia de SEO para documentação
• Como fazer com que os docs sejam citados pelo ChatGPT
• llms.txt: o guia completo

Docsbook adiciona JSON-LD automaticamente em cada página. Publique seus docs →