A primeira vez que adicionei marcação de esquema a um site cliente, digitei a manualmente Product bloqueie o cabeçalho do tema, implantei-o e continuei sentindo-se inteligente Duas semanas depois, o Teste de Resultados Ricos me disse que o objeto de oferta estava faltando @type, o preço era um número onde o Google queria uma string, e uma vírgula perdida invalidou silenciosamente todo o bloco O Google vinha ignorando isso o tempo todo. Essa é a coisa sobre a qual ninguém avisa com dados estruturados: JSON-LD inválido não comete um erro ou deixa nada vermelho. Ele simplesmente silenciosamente não faz nada, e você descobre meses depois, quando o rico resultado com o qual você contava nunca aparece.
O vocabulário em si é publicado em schema.org, e o que o Google realmente mostrará um resultado rico é uma lista mais restrita documentação de dados estruturados.
Eu construo ferramentas para viver - Toolz.dev, o plugin WP Adminify, uma pilha de aplicativos Laravel e React - e dados estruturados são uma daquelas tarefas que faço com frequência suficiente para me ressentir de fazê-lo manualmente e raramente o suficiente para esquecer os nomes exatos das propriedades a cada vez. Então eu construí o Gerador de marcação de esquema para remover os dois modos de falha que mais me custam: aninhamento errado e invalidade silenciosa Este guia percorre o que a marcação do esquema realmente faz, como o gerador a constrói e os erros específicos que impedem a marcação de aparência válida de obter resultados ricos.
tl;dr: Marcação de esquema são dados estruturados (usando o vocabulário schema.org) que informa aos mecanismos de pesquisa exatamente do que se trata uma página, tornando-a elegível para resultados ricos, como acordeões de perguntas frequentes, preços de produtos e migalhas de pão O Google recomenda o formato JSON-LD - um formato independente
<script type="application/ld+json">bloco. O gerador constrói JSON-LD válido para nove tipos comuns, ninhos sub-objetos comoPostalAddresseOffercorretamente, faltam sinalizadores nos campos obrigatórios e recomendados e são executados 100% no seu navegador para que nada do que você digita seja carregado.
O que é marcação de esquema e por que isso importa?
Marcação de esquema é uma maneira padronizada de descrever o conteúdo de uma página para que as máquinas possam entendê-lo, não apenas renderizá-lo O vocabulário vem do schema.org, um projeto compartilhado apoiado pelo Google, Microsoft, Yahoo e Yandex Quando você marca uma página como um Article& quot; está a dizer a um motor de busca esta é uma notícia ou artigo de blog, aqui está a sua manchete, aqui está quem a escreveu, aqui está quando foi publicada." essa descrição estruturada é o que torna uma página elegível para resultados ricos - as listagens melhoradas com classificações de estrelas, preços, quedas de perguntas frequentes, datas de eventos e trilhas de migalhas de pão que ocupam mais espaço e ganham mais cliques do que um link azul simples.
A razão pela qual importa mudou ao longo dos últimos anos Costumava ser puramente sobre resultados ricos no Google Agora dados estruturados também alimenta motores de resposta AI e Google' s AI Overviews Quando ChatGPT, Perplexity, ou Gemini tentar resumir o que seu negócio faz ou qual produto corresponde a uma consulta, dados estruturados limpos é um dos sinais que os ajuda a obter os fatos certos Uma página que claramente se declara um Organization com um nome, logotipo e perfis sociais é muito mais fácil para qualquer máquina raciocinar do que aquela que deixa tudo implícito no HTML.
A captura é que os dados estruturados são implacáveis É código, e o código tem que estar exatamente certo Uma propriedade soletrada datePublish em vez de datePublished é simplesmente ignorado. An Offer sem um @type não é reconhecido como uma oferta E porque nenhum desses erros quebrar a página visível, eles se escondem na produção indefinidamente Essa é a lacuna que um gerador preenche - não escrever os conceitos para você, mas obter a sintaxe e estrutura direita cada vez.
Por que JSON-LD em vez de Microdata ou RDFa?
Existem três maneiras de adicionar dados schema.org a uma página e isso ajuda a entender por que o gerador produz apenas uma delas.
Microdados e RDFa teca os dados estruturados diretamente em seu HTML visível usando atributos extras - itemscope, itemprop, property, e assim por diante. Seu <div> para uma análise de produto ganha atributos que rotulam cada pedaço de texto visível Isso funciona, mas acopla firmemente sua marcação à estrutura da sua página Altere o layout e você corre o risco de quebrar o esquema Também é prolixo e difícil de ler.
JSON-LD adota a abordagem oposta. Ele coloca todos os dados estruturados em um único sistema independente <script type="application/ld+json"> bloqueio, geralmente no <head>, completamente separado do HTML visível O Google recomenda o JSON-LD há anos precisamente por causa dessa separação: você pode adicioná-lo, atualizá-lo ou injetá-lo através de um gerenciador de tags sem tocar em seus modelos É o formato que todo tutorial de esquema moderno ensina, e é o que o gerador gera.
| formato | Onde vive | Facilidade de manutenção | Postura do Google' |
|---|---|---|---|
| JSON-LD | Single <script> bloco, separado do HTML |
Mais fácil - edite um bloco | recomendado |
| Microdados | Atributos dentro do HTML visível | Mais difícil - acoplado ao layout | suportado |
| RDFa | Atributos dentro do HTML visível | Mais difícil - acoplado ao layout | suportado |
Se você está trabalhando no WordPress, JSON-LD também é o que a maioria dos plugins de SEO injetam, e que ferramenta como WP Adminify fica ao lado de forma limpa Porque é um bloco autônomo, você pode gerá-lo aqui e colá-lo em um campo HTML personalizado, um gerenciador de tags, ou um layout Laravel Blade sem qualquer ginástica específica do quadro.
Como uso o Gerador de Marcação de Esquema?
O fluxo de trabalho é construído em torno de escolher um tipo e preencher um formulário curto, com uma visualização ao vivo para que você veja o JSON-LD montar como você digita.
Passo 1 - Escolha um tipo de esquema. Escolha na Organização, LocalBusiness, WebSite, Artigo, Produto, FAQPage, BreadcrumbList, Pessoa ou Evento O formulário imediatamente muda para os campos que o tipo precisa Esses nove cobrem a esmagadora maioria do que os sites de pequeno e médio porte realmente precisam de marcação.
Passo 2 - Preencha os campos. Os campos obrigatórios são marcados com um asterisco À medida que você digita, a ferramenta monta o JSON-LD e solta qualquer campo que você deixar em branco, para que você nunca acabe vazio "" propriedades que poluem a saída Para tipos baseados em endereços como LocalBusiness e Event, os campos de endereço individuais são dobrados em um digitado corretamente PostalAddress objeto automaticamente.
Passo 3 - Assista à validação. O gerador sinaliza dois tipos de problemas Erros (falta de campos obrigatórios, URLs malformados) bloqueiam um resultado limpo e são mostrados em vermelho. Avisos (falta de campos recomendados pelo Google como image ou datePublished, ou um modelo de URL de pesquisa sem espaço reservado) são mostrados em âmbar - a marcação ainda é válida, mas você está deixando um potencial de resultado rico na tabela.
Passo 4 - Copiar e implantar. Alterne entre o cheio <script> tag (pronto para colar em seu <head>) e o JSON bruto (para gerenciadores de tags e campos CMS).A saída do script escapa dos caracteres que, de outra forma, deixariam um stray </script> em seus dados quebrar a página Em seguida, valide a página ao vivo com Google' s Rich Results Test.
Como tudo é executado no lado do cliente, isso é seguro para uso em páginas de produtos não publicadas, ambientes de preparação e trabalho do cliente sob NDA Seus preços, detalhes do evento e URLs internos nunca saem do navegador - a mesma postura de privacidade por trás de todas as ferramentas do site, sobre as quais escrevi no Guia de privacidade de dados.
Que tipos de esquema devo realmente usar?
Nem toda página precisa de marcação, e empilhar em tipos que você não pode suportar é pior do que nenhum Aqui está como EU penso sobre os nove que o gerador cobre.
Organização pertence à sua página inicial ou página sobre - é o esquema que alimenta painéis de conhecimento e ajuda o Google a conectar sua marca aos seus perfis sociais via sameAs. Site emparelha-se com ele e pode declarar uma caixa de pesquisa Sitelinks através de um SearchAction, permitindo que os usuários pesquisem seu site diretamente na página de resultados. Negócios Locais é essencial se você tiver uma localização física: ele carrega seu endereço, telefone, faixa de preço e horário de funcionamento, e sustenta os resultados locais do pacote e do mapa.
Artigo (com o qual o gerador emite Article type, igualmente válido para postagens de blog) marca o conteúdo editorial com uma manchete, autor, editor e datas de publicação. Produto descreve algo à venda, com um aninhado Offer preço de transporte, moeda e disponibilidade - é isso que alimenta os trechos de preço e disponibilidade. Evento cobre qualquer coisa com data e local, desde uma conferência até um webinar.
Página de perguntas frequentes e Lista de migalhas de pão são estruturais e não sobre um & quot;coisa." FAQPage marca o conteúdo de perguntas e respostas; observe que o Google reduziu os resultados ricos de perguntas frequentes a sites governamentais e de saúde confiáveis, mas a marcação ainda ajuda outros mecanismos de pesquisa e mecanismos de resposta de IA a analisar seu Q& A. BreadcrumbList produz a trilha de migalhas mostradas em seu título em resultados, o que melhora a leitura da estrutura da sua URL. Pessoa marca um indivíduo - um autor, fundador ou figura pública - e é útil para biografias de autores e sinais EEAT.
A regra que EU sigo: marque o que a página é genuinamente sobre, e apenas reivindicar propriedades que refletem o conteúdo realmente visível na página Google' s diretrizes são explícitas que os dados estruturados devem descrever o conteúdo real, visível - marcando um preço que não aparece na página é uma violação, não um atalho.
Como o gerador mantém a marcação válida?
O valor está nos detalhes que são fáceis de errar à mão Alguns vale a pena chamar.
Correto aninhamento com @type. No JSON-LD, objetos aninhados não são subobjetos simples - cada um precisa dos seus @type. Um endereço é a PostalAddress, uma oferta é um Offer, um artigo's autor é a Person, sua editora é uma Organization cujo logotipo é um ImageObject. O gerador constrói cada um deles com o tipo certo para que o analisador os reconheça em vez de tratá-los como bolhas anônimas.
Poda esvazia. Deixar um campo em branco deve remover a propriedade, e não emitir "telephone": "". Strings vazias e matrizes vazias são retiradas da saída automaticamente, então o que você copia está sempre limpo.
Escapagem segura para scripts. O personagem mais perigoso no JSON-LD em linha é um < - especificamente a sequência </script> aparecendo dentro de seus dados (digamos, em uma descrição), o que encerraria o bloco de script mais cedo e quebraria a página O gerador escapa <, >, e & na saída da tag de script usando escapes unicode, que é exatamente o que o Google' exemplos próprios fazem.
Consciência necessária e recomendada. Cada tipo carrega sua própria lista do que o Google exige versus recomenda O artigo realmente quer um image e datePublished; O produto quer um price; Evento precisa de a startDate. A ferramenta distingue os requisitos rígidos (que trata como erros) das recomendações (avisos), para que saiba a diferença entre o & quot; isto não funcionará & quot; e o & quot; isto poderá funcionar melhor. & quot;
Se você estiver montando um fluxo de trabalho técnico mais amplo, o gerador de esquema fica naturalmente ao lado dos outros utilitários de SEO - o Gerador de meta tags para o seu título, descrição e tags Open Graph e o Gerador de mapas de sites XML para enviar seus URLs. Juntos, eles cobrem a maior parte da superfície técnica de SEO na página, e eu os agrupei por esse motivo no visão geral do kit de ferramentas para desenvolvedores web.
Como faço para testar e implantar dados estruturados?
Gerar JSON-LD válido é metade do trabalho; a outra metade está confirmando que o Google lê da maneira que você pretende.
Comece com Google's Teste de resultados ricos, que busca uma URL ou aceita código colado e relata para quais tipos de resultados ricos a página se qualifica, além de quaisquer erros ou avisos. Em seguida, execute a mesma marcação através do Validador de marcação de esquema no validator.schema.org, que verifica a conformidade com o vocabulário schema.org em si, em vez dos requisitos de resultados ricos do Google' Os dois capturam coisas diferentes: o Teste de Resultados Ricos informa se você se qualifica para um recurso específico do Google, enquanto o validador informa se a marcação é estruturalmente sólida schema.org.
Assim que a página estiver ativa, o aprimoramento será relatado Console de pesquisa do Google acompanhe o desempenho ao longo do tempo e sinalize erros que o Google encontra durante o rastreamento É aqui que você detecta problemas que só aparecem em escala - um modelo que emite posições duplicadas de migalhas de pão, digamos, ou um feed de produto que ocasionalmente omite um campo obrigatório.
Para implantação, cole o <script> bloqueie no <head> da página específica que descreve Não coloque um único bloco de Produto em um modelo global que seja executado em cada página - a marcação tem que corresponder à página em que vive Em um CMS, use qualquer campo personalizado-HTML ou SEO que a plataforma lhe der Em um gerenciador de tags, use uma tag HTML personalizada e copie o JSON Em um aplicativo React ou Laravel, injete o lado do servidor de blocos para que os rastreadores o vejam no HTML inicial, em vez de após a hidratação.
Erros comuns que ainda vejo
Alguns erros aparecem repetidas vezes, e cada um deles produz uma marcação que parece boa, mas não faz nada.
O clássico é marcando conteúdo invisível - adicionando uma avaliação de avaliação ou preço que não aparece em nenhum lugar da página O Google proíbe isso explicitamente e pode emitir uma ação manual para isso O segundo é o tipo errado em um objeto aninhado, geralmente um desaparecido @type em um endereço ou oferta. O terceiro é confundindo tipos semelhantes, como usar Product marcação em uma página de listagem de categorias em vez de um único produto E o quarto, meu inimigo pessoal, é um erro de sintaxe da edição manual - uma vírgula final ou citação não escapada que invalida todo o bloco.
Cada um deles é por isso que um gerador ganha seu sustento Ele não pode saber se o seu preço está visível na página - isso está em você - mas nunca emitirá uma vírgula à direita, uma falta @type, ou uma propriedade vazia Isso sozinho remove a maioria das maneiras pelas quais os dados estruturados falham silenciosamente Para um fundo mais profundo nos fluxos de trabalho do desenvolvedor em torno desse tipo de ferramenta, o Guia de ferramentas de codificação é uma boa leitura de acompanhante.
Perguntas frequentes
O que é marcação de esquema?
Marcação de esquema são dados estruturados que descrevem um conteúdo page' s para motores de busca usando o vocabulário schema.org compartilhado Adicionando ele pode fazer uma página elegível para resultados ricos, como acordeões FAQ, preços de produtos, estrelas de revisão e breadcrumbs JSON-LD, o formato que esta ferramenta produz, é a sintaxe que o Google recomenda porque vive em uma única tag de script separada do seu HTML visível.
Qual é a diferença entre JSON-LD, Microdata e RDFA?
Todas as três são formas de adicionar dados estruturados do schema.org a uma página. Microdados e RDFA são atributos entrelaçados em seu HTML visível, enquanto JSON-LD é um bloco independente de JSON em uma tag de script. O Google recomenda JSON-LD porque é mais fácil adicionar, atualizar e manter separado da marcação da página. Esta ferramenta gera JSON-LD por esse motivo.
Onde coloco o JSON-LD gerado?
Cole o cheio <script type="application/ld+json"> marque no <head> da página que descreve, ou em qualquer lugar do <body> - O Google lê em qualquer local Se você usar o Gerenciador de tags do Google, copie o JSON e adicione-o através de uma tag HTML personalizada Sempre coloque a marcação na mesma página cujo conteúdo ele descreve, não um modelo que o aplica em todos os lugares.
A adição de marcação de esquema garante resultados ricos?
não Os dados estruturados válidos tornam a página elegível para resultados avançados, mas o Google decide se os mostra com base na qualidade, relevância e em suas próprias diretrizes. Sua marcação também deve refletir o conteúdo que é realmente visível na página. Pense no esquema como um requisito para resultados ricos, não como um interruptor que os ativa.
Como faço para testar meus dados estruturados?
Execute a marcação gerada através do teste de resultados ricos do Google' s e do validador de marcação de esquema (validador do esquema.org' s).Ambos analisam seu JSON-LD e relatam campos obrigatórios ausentes ou erros de sintaxe Depois que a página está ativa, os relatórios de aprimoramentos do Google Search Console rastreiam como seus dados estruturados funcionam ao longo do tempo.
Quais campos são necessários para cada tipo?
Os requisitos variam de acordo com o tipo: o artigo precisa de um título, o produto precisa de um nome, um nome e um evento de início e FAQPage precisa de pelo menos uma pergunta e uma resposta. Essa ferramenta marca os campos obrigatórios e a saída dos blocos até serem preenchidos, enquanto também alerta sobre os campos recomendados que melhoram suas chances de obter um resultado rico.
Posso gerar o esquema de perguntas frequentes para minha página?
Sim. Escolha o tipo de página de FAQ, adicione cada pergunta com sua resposta e a ferramenta cria o array MainEntity de objetos de perguntas e respostas automaticamente. Observe que o Google agora mostra resultados ricos em perguntas frequentes principalmente para sites de governo e saúde autoritários, mas a marcação permanece válida e útil para outros mecanismos de pesquisa e mecanismos de resposta de IA.
Meus dados são mantidos privados?
Sim. o JSON-LD é montado inteiramente em seu navegador com JavaScript simples Nada do que você digita - incluindo preços não publicados, detalhes de eventos ou URLs privados - é transmitido, registrado ou armazenado, e o gerador continua a funcionar sem conexão de rede depois de carregado.
