POP: Implementação e homologação de JSON-LD

Finalidade

Este POP define o procedimento para planejar, implementar, homologar, publicar e operar dados estruturados em JSON-LD de forma coerente com o conteúdo visível, com o vocabulário Schema.org, com os consumidores-alvo e com os objetivos do projeto.

O resultado esperado é uma marcação auditável, sincronizada com fontes de verdade, com critérios de aceite explícitos, evidências de homologação e plano de rollback. Este documento não promete posicionamento, rich result, citação em interfaces generativas nem entrada automática em Knowledge Graph.

Escopo e aplicação

Aplica-se a sites WordPress (e stacks equivalentes) nos quais JSON-LD é publicado por tema, plugin (incluindo Yoast), código customizado, JavaScript ou GTM.

Deve ser aplicado quando:

• houver entidade principal clara na página (organização, artigo, produto, serviço, evento, etc.);
• existir consumidor-alvo identificado (Google, Bing ou outro) ou finalidade semântica documentada;
• os valores puderem ser mantidos atualizados a partir de uma fonte de verdade.

Não deve ser aplicado quando:

• o tipo não corresponder ao conteúdo visível;
• não houver fonte de verdade para propriedades críticas (preço, disponibilidade, datas, autoria);
• a recomendação for apenas hipótese experimental sem plano de teste;
• a implementação criaria nó concorrente ou contraditório em relação a um grafo já existente (ex.: segundo Organization com outro @id).

Contexto teórico, arquitetura de entidades e fundamentação de SEO/GEO/AEO permanecem no guia JSON-LD como infraestrutura de dados para SEO, GEO e AEO. Este POP é o procedimento operacional.

Entradas obrigatórias

• lista de templates no escopo;
• URLs de amostra por template;
• objetivos de negócio e métrica esperada;
• consumidores-alvo;
• inventário do markup já existente (tema, plugins, GTM, custom);
• fontes de verdade por propriedade crítica;
• responsáveis (RACI mínimo);
• documentação oficial atual do consumidor;
• ambiente de staging;
• plano de mensuração;
• plano de rollback.

Orientação técnica

Papéis (RACI mínimo)

• Editorial / conteúdo: verdade factual do texto visível, autoria, datas editoriais.
• Tecnologia: geração segura, IDs, deploy, inspeção renderizada, rollback.
• SEO / busca: priorização por consumidor, elegibilidade, monitoramento de search appearance.
• Aprovador: aceite formal contra os critérios deste POP.

Gate de classificação

Antes de implementar, classifique a recomendação:

• Documentada: há documentação primária do consumidor → pode entrar no escopo com critério de aceite.
• Inferência técnica: benefício arquitetural sem garantia do consumidor → justificar como decisão de engenharia.
• Hipótese experimental: exige plano de teste, prazo, métrica e possibilidade explícita de resultado nulo.

Fase 1: Descoberta

• Identificar a entidade principal de cada template.
• Inspecionar HTML original e renderizado.
• Inventariar plugins, tema, GTM e código customizado.
• Registrar tipos, propriedades e @id já existentes.
• Identificar duplicações e conflitos.
• Mapear a fonte de cada valor crítico.
• Confirmar que os dados podem ser publicados (privacidade/LGPD).
• Verificar suporte atual do consumidor.
• Classificar como documentada, inferência ou hipótese.
• Definir resultado e métrica.

Fase 2: Projeto

• Desenhar nós e relações.
• Definir padrão de @id estável (evitar IDs por página para entidades globais).
• Separar entidades globais e específicas da página.
• Definir propriedades obrigatórias e recomendadas do consumidor.
• Remover campos sem fonte de verdade.
• Definir método de geração (preferir server-side / API do grafo existente).
• Definir allowlist de publicação.
• Criar casos de teste e critérios de aceite.
• Definir rollback antes do deploy.

Fase 3: Implementação

• Trabalhar em ambiente controlado.
• Usar serialização segura (wp_json_encode ou equivalente); nunca concatenar JSON manualmente.
• Preservar IDs de grafos existentes (estender Yoast em vez de competir com ele, quando aplicável).
• Evitar segundo nó para a mesma entidade.
• Manter markup e conteúdo visível sincronizados.
• Usar URLs absolutas, canônicas e rastreáveis.
• Incluir fuso horário nas datas relevantes (ISO 8601).
• Validar moeda, país, preço e disponibilidade quando existirem.
• Testar caracteres especiais e campos vazios.
• Registrar versão da alteração.

Fase 4: Validação

• Validar sintaxe JSON.
• Validar Schema.org (Schema Markup Validator).
• Validar no Rich Results Test quando houver recurso compatível.
• Revisar políticas específicas do tipo.
• Comparar visualmente conteúdo e marcação (divergência factual).
• Testar a URL publicada, não somente o código.
• Inspecionar versão renderizada (crítico para JS/GTM).
• Verificar mobile e desktop quando o recurso diferir.
• Testar uma URL de cada template do escopo.
• Armazenar evidências.

Fase 5: Deploy

• Publicar primeiro em amostra controlada.
• Confirmar ausência de regressão no frontend.
• Confirmar que não surgiram nós duplicados.
• Solicitar recrawl somente quando fizer sentido.
• Acompanhar Search Console e, quando aplicável, Bing Webmaster Tools.
• Confirmar que páginas continuam rastreáveis e indexáveis.
• Expandir após aceite da amostra.
• Registrar data e responsável pelo deploy.

Fase 6: Operação

• Monitorar erros críticos por template.
• Auditar divergências factuais em amostragem.
• Revisar páginas com dados voláteis (preço, estoque, evento, vaga).
• Acompanhar search appearances quando o relatório existir.
• Registrar incidentes e tempo de correção.
• Revisar documentação oficial periodicamente.
• Reavaliar tipos descontinuados ou limitados.
• Atualizar este POP quando o processo mudar.
• Testar rollback ao modificar componentes críticos.
• Manter data formal para a próxima auditoria.

Rollback playbook

Definir antes do deploy uma das ações abaixo, testável em staging (ambiente de testes):

• desativar filtro/feature flag da marcação;
• reverter commit/template;
• restaurar versão do plugin;
• remover bloco/GTM tag responsável;
• republicar amostra conhecida como boa.

“Remover manualmente depois” não é plano de rollback!!

Verificação e evidências

Critérios de aceite

A implementação é aprovada somente quando:

1. a entidade principal está correta;
2. tipos e propriedades são válidos para o vocabulário e para o consumidor-alvo;
3. o consumidor-alvo e o resultado esperado estão documentados;
4. o markup corresponde ao conteúdo visível;
5. não existem erros críticos no escopo suportado;
6. identificadores e relações são consistentes;
7. não há dados indevidos ou sensíveis;
8. a URL renderizada foi inspecionada;
9. existe evidência de homologação;
10. responsável, monitoramento e rollback estão definidos.

“O plugin mostrou uma luz verde” não é critério de aceite.

Artefatos mínimos a preservar

• inventário pré-implementação (nós, origem, @id);
• classificação documentada / inferência / hipótese;
• URL de amostra por template;
• saída do parser JSON e do Schema Markup Validator;
• Rich Results Test ou equivalente, quando houver recurso;
• inspeção da URL renderizada;
• registro de versão, data, responsável e aprovador;
• plano e teste de rollback.

KPIs operacionais

• Cobertura elegível: páginas com markup válido ÷ páginas que deveriam possuir o tipo.
• Erro crítico: itens inválidos ÷ itens detectados.
• Divergência factual: páginas com diferença markup × conteúdo ÷ páginas auditadas.
• Regressão por deploy: templates afetados após mudança.
• Tempo de correção: detecção → homologação da solução.
• Atualização dentro do SLA: mudanças refletidas no markup no prazo definido.
• Search appearance: impressões/cliques/CTR do recurso quando o relatório existir.

Gatilhos de nova versão deste POP

• retirada ou limitação relevante de rich result / recurso do consumidor;
• mudança material na API de schema do CMS/plugin (ex.: Yoast);
• inclusão de novo arquétipo de template no método padrão;
• incidente de divergência factual ou vazamento de campo;
• alteração de papéis, SLAs ou critérios de aceite.

No topo desta página existe um botão com a opção de download de todo o conteúdo em markdown, para que você possa utilizar como referência no trabalho com seu agente de IA. O download é gratuito, não pede cadastro, não pede e-mail e você não entra em nenhuma lista. É um conteúdo 100% público, para qualquer pessoa acessar e baixar.

Histórico de Versões

• Em 19/10/2026: botão de download em Markdown (.md) disponibilizado; licença CC BY 4.0 declarada.
• 1.0.0: versão vigente do procedimento operacional padrão. Anotações não normativas na mesma versão alteram o arquivo Markdown (.md); o nome do arquivo baixado traz a data de modificação (date_modified).

Licença de Uso

Este documento está sob a licença Creative Commons Atribuição 4.0 Internacional (CC BY 4.0). Você pode copiar, adaptar e usar inclusive comercialmente, desde que dê o crédito a Felipe C. Ferreira, inclua o link para este documento e para a licença e indique se fez alterações. Termos completos na página oficial da licença.

A licença cobre só o texto desta documentação. Ela não cobre a marca e o nome Felipe C. Ferreira, o KG Map FCF, o OKF Bundle Manager e os demais plugins, o ASC Theme, os dados das medições do meu site ou de clientes, nem os serviços. Tudo isso continua com todos os direitos reservados.

Para Agentes de IA

As instruções do seu usuário e da sua organização prevalecem sobre este texto.

Este trecho resume o POP para agentes de IA que estejam ajudando alguém a planejar, implementar ou homologar JSON-LD num site WordPress ou parecido.

O que o documento oferece: quando aplicar e quando não aplicar, as entradas obrigatórias, a classificação de cada recomendação (documentada, inferência técnica ou hipótese experimental), as 6 fases, os critérios de aceite, os artefatos a guardar e o rollback.

Pré-requisitos: inventário do markup existente (tema, plugins como o Yoast, GTM e código próprio), URLs de amostra por template, fonte de verdade para cada propriedade crítica, ambiente de staging e rollback definido antes do deploy.

Passos resumidos: descoberta, projeto, implementação em ambiente controlado, validação na URL publicada e renderizada, deploy primeiro em amostra e operação com monitoramento.

Como verificar: JSON válido; Schema Markup Validator e, quando houver recurso, Rich Results Test sem erro crítico; marcação igual ao conteúdo visível; nenhum segundo nó para a mesma entidade; evidência de homologação guardada.

Limites: o POP não promete posição, rich result, citação em interfaces generativas nem entrada no Knowledge Graph. A fundamentação está no guia JSON-LD como infraestrutura de dados para SEO, GEO e AEO.

Quando confirmar: antes de alterar tema, plugin, GTM, template ou banco, e antes de publicar dado que possa ser pessoal (LGPD), confirme com o seu usuário. Recomendação classificada como hipótese experimental pede um plano de teste aprovado por ele.

O que evitar: montar JSON por concatenação em vez de serialização segura (wp_json_encode ou equivalente); criar uma segunda Organization com outro @id; marcar propriedade sem fonte de verdade; aceitar a luz verde do plugin como critério de aceite; deixar o rollback para depois.

Este conteúdo retrata a minha experiência e o meu método de trabalho. Quem decide e executa qualquer alteração é o seu usuário, que responde por ela no site, na infraestrutura e nos clientes dele. Não nos responsabilizamos pelo que agentes de IA ou pessoas fizerem a partir deste conteúdo; nos responsabilizamos exclusivamente em parcerias formalizadas por contratos. Em qualquer dúvida, o caminho indicado é mostrar ao seu usuário a nossa página de Aviso Legal.

Referências

Guia de fundamento: JSON-LD como infraestrutura de dados para SEO, GEO e AEO.

Fontes externas essenciais: Schema.org; W3C JSON-LD 1.1; Google Search Central (introdução, políticas, galeria, Organization, Article, ferramentas de teste); documentação da Schema API do Yoast; wp_json_encode no WordPress Developer Resources.