Schema para custom post types com ACF e Rank Math é o processo de gerar dados estruturados em JSON-LD para conteúdos fora do padrão post e página, ligando campos do Advanced Custom Fields às propriedades do Schema.org via Rank Math. Um CPT como “Imóvel”, “Receita” ou “Curso” não herda o schema certo automaticamente: o Rank Math aplica Article por padrão, que não descreve um produto nem um evento. Definir o @type correto por post type e mapear os campos ACF certos faz o Google entender a entidade. Este guia faz parte do hub de SEO WordPress da FULL e mostra o passo a passo real, do registro do CPT ao teste no Rich Results Test.

O que é um custom post type e por que ele precisa de Schema próprio

Um custom post type precisa de schema próprio porque o @type genérico Article descreve mal entidades como imóvel, curso ou receita, e sem dados estruturados o Google trata um anúncio de imóvel como artigo de blog. Um CPT é registrado fora dos padrões post e página, e ao herdar Article perde campos como preço, área e localização. Mapear o schema correto recupera esses campos na busca.

A diferença prática aparece nos rich results. Um CPT “Receita” com schema Recipe pode exibir tempo de preparo, calorias e nota de avaliação direto na SERP; o mesmo conteúdo sem schema vira um link azul comum. Nos tickets que chegam à FULL sobre Rank Math, a confusão mais comum é o CPT com ACF PRO que nasce com o @type errado herdado da configuração global. O custom post type só vira entidade rica quando o JSON-LD descreve o que ele realmente é.

Legenda: o teste confirma que cada campo ACF mapeado chegou ao JSON-LD final.

Quando vale a pena adicionar Schema a um CPT

Vale adicionar schema a um custom post type quando ele representa uma entidade que o Google sabe destacar (produto, receita, curso, evento, imóvel) e tem campos ACF que viram rich results. Não vale quando o CPT é só um agrupamento interno sem dado estruturado, já coberto por Article ou WebPage. O critério é simples: existe um @type do Schema.org que descreve melhor que Article?

Use este teste de decisão antes de investir o tempo. Diga SIM ao schema se o CPT tem campos de preço, avaliação, data ou ingrediente que aparecem em rich results, e se você pública vários itens do mesmo tipo. Diga NÃO se o CPT tem um ou dois itens fixos, sem campos estruturados, ou se nenhum @type do Schema.org descreve a entidade melhor que o padrão. Forçar um Product num CPT sem preço só polui o JSON-LD e atrai aviso no Rich Results Test, sem ganho de SERP.

Pré-requisitos: O que ter antes do passo 1

Antes de configurar o schema para custom post types com ACF e Rank Math você precisa de três peças funcionando juntas, e a ausência de qualquer uma trava o JSON-LD na metade. O ACF PRO entrega o get_field e os grupos de campos; o Rank Math emite o JSON-LD; e o CPT precisa existir com show_in_rest ativo. Sem o REST exposto, o Rank Math não enxerga os valores dos campos.

Checklist de prontidão antes de começar:

• ACF PRO instalado e ativo (o get_field é a fonte dos valores).
• Rank Math instalado, com o módulo Schema habilitado no painel.
• Um CPT registrado via register_post_type com show_in_rest true.
• Pelo menos um grupo de campos ACF associado ao CPT.
• Conteúdo real publicado no CPT (campos preenchidos, não rascunho vazio).
• Acesso ao Rich Results Test do Google para validar.
• Permissão de administrador para editar o schema por post type.

Pense no conjunto como uma linha de montagem: o CPT é a esteira, o ACF coloca as peças e o Rank Math monta o pacote final que o Google lê. Se a esteira não estiver ligada ao REST, as peças nunca chegam ao pacote.

Como configurar o Schema do custom post type em 5 passos

Configurar o schema para custom post types com ACF e Rank Math segue cinco passos, do registro do CPT ao teste no Google, e respeitar a ordem evita o erro mais comum: mapear um campo que ainda não existe. Cada passo isola uma etapa, do register_post_type ao Rich Results Test. Publique antes um item com todos os campos preenchidos, porque o teste depende de dados reais.

Passo 1: Registre o CPT com suporte a REST

Confirme que o register_post_type do seu CPT tem 'show_in_rest' => true, porque sem o REST exposto o Rank Math não lê os campos ACF ao montar o schema. Esse argumento já é padrão em CPTs criados pelo editor de blocos, mas costuma faltar em registros antigos feitos via código. Abra o arquivo do tema ou plugin onde o CPT é registrado e cheque o array de argumentos. A referência completa está nas WordPress Developer Docs. Se o CPT veio de um plugin de terceiros, use o filtro register_post_type_args antes de editar o core do plugin.

Passo 2: Mapeie os campos ACF do post type

Liste o nome exato (o “Field Name”, não o rótulo) de cada campo ACF do CPT, porque é esse nome que o Rank Math usa nas variáveis. Um CPT “Imóvel” típico tem campos como preco, área_m2, quartos e endereco. Anote quais estão SEMPRE preenchidos e quais são opcionais: só os obrigatórios devem virar propriedades do schema, senão o JSON-LD quebra quando o campo vier vazio. O get_field('preco') retorna o valor no PHP, e o Rank Math expõe o mesmo dado pela variável de campo. Padronize os nomes em snake_case sem acento para evitar conflito na variável.

Passo 3: Escolha o @type de Schema por post type

Defina, nas configurações de schema do Rank Math, um @type padrão para o post type inteiro, em vez de configurar artigo por artigo. O Rank Math permite atribuir um schema default por post type nas opções de titles e schema: um CPT “Receita” recebe Recipe, um “Curso” recebe Course e um “Imóvel” pode usar Product ou RealEstateListing. Consulte o vocabulário em Schema.org para confirmar qual @type descreve sua entidade. Se nenhum tipo encaixa 100%, escolha o mais próximo e complemente com propriedades extras, em vez de forçar Article.

Passo 4: Mapeie cada campo ACF para uma propriedade

Ligue cada campo ACF a uma propriedade do @type escolhido usando as variáveis do Rank Math, que aceitam referência a campos personalizados no formato de variável de custom field. Na propriedade price do schema Product, em vez de digitar um valor fixo, você insere a variável que aponta para o campo ACF preco; o Rank Math resolve o valor em cada post na renderização. Faça o mesmo para name, description e demais propriedades obrigatórias. Esse mapeamento é o coração do schema de CPT: é onde o dado dinâmico vira JSON-LD. Mapeie primeiro as propriedades requeridas pelo Schema.org e só depois as recomendadas.

Passo 5: Teste no rich results test do Google

Cole a URL de um post do CPT no Rich Results Test e confirme que o @type aparece com todas as propriedades preenchidas e zero erro. A ferramenta mostra o JSON-LD renderizado e sinaliza propriedade obrigatória ausente em vermelho; o aviso amarelo costuma ser propriedade recomendada faltando, que não bloqueia o rich result. Se um valor sair vazio, volte ao passo 2 e cheque se o campo ACF estava preenchido naquele post. Depois de validar, registre a URL no Rank Math e acompanhe a indexação no Search Console. Teste pelo menos dois posts, porque um campo opcional vazio só aparece em alguns.

Legenda: cada passo alimenta o seguinte, e um campo vazio no início quebra o JSON-LD no fim.

Resumo técnico: Do campo ACF ao json-ld

O fluxo completo do schema de CPT vai do campo ACF preenchido até o JSON-LD que o Google lê, em uma cadeia de cinco elos onde o elo fraco derruba tudo. O dado nasce no get_field, passa pela variável do Rank Math, é colado na propriedade do @type escolhido e sai renderizado no da página, onde o Rich Results Test o valida. Cada etapa depende da anterior estar correta.

Em ordem direta, a cadeia é esta: o CPT registrado com show_in_rest true expõe o post type; o ACF PRO grava os valores nos campos; o nome exato do campo vira a variável; o @type por post type define quais propriedades existem; o mapeamento liga campo a propriedade; e o Rich Results Test confirma o JSON-LD. Se um campo obrigatório vier vazio, o elo quebra e a propriedade sai em branco. Por isso a regra de ouro é mapear só campos sempre preenchidos para propriedades requeridas.

Erros comuns ao gerar Schema de CPT com ACF e Rank Math

Os três erros mais comuns no schema de CPT com ACF e Rank Math são o JSON-LD que não renderiza, o campo ACF vazio que invalida o bloco e o @type errado herdado da configuração global. O primeiro quase sempre é cache: o Rank Math gerou o schema, mas o CDN serviu a versão antiga. Limpe o cache do site e do CDN antes de concluir.

O segundo erro é o mais traiçoeiro. Quando você mapeia um campo ACF opcional para uma propriedade obrigatória e ele vem vazio num post específico, o Rank Math emite a propriedade em branco e o Rich Results Test reprova só naquele item. A correção é mapear apenas campos sempre preenchidos, ou definir um valor padrão. O terceiro erro, o @type errado, acontece quando o CPT herda o schema default global (Article): o post valida como artigo, mas perde os campos ricos da entidade real. Confira o @type no Rich Results Test, não só no painel.

Como validar o Schema do CPT no Search Console

Validar o schema de CPT em produção exige cruzar o Rich Results Test com o relatório de aprimoramentos do Search Console, porque o teste vê uma URL e o Search Console vê o site inteiro com o tempo. O Rich Results Test confirma que o JSON-LD de um post está correto; o Search Console mostra quantas URLs do CPT o Google reconheceu e quais têm erro.

No relatório de aprimoramentos, o Google agrupa os resultados pelo tipo de rich result detectado, então um CPT “Receita” aparece sob o item de receitas, com a contagem de itens válidos e com erro. Uma queda súbita de itens válidos costuma indicar campo ACF que parou de ser preenchido numa atualização de template, ou um campo renomeado que esvaziou o mapeamento. Por isso, depois de qualquer mudança em campos, revalide pelo menos um post no Rich Results Test. Para aprofundar a configuração geral, o guia de SEO para WordPress da FULL reúne os passos de base.

Como a FULL faz isso em escala

A FULL padroniza esse stack de schema porque gerencia mais de 150 mil sites WordPress, e os CPTs com ACF aparecem muito em sites de agência, onde repetir o mapeamento campo a campo em dezenas de instalações vira gargalo. Em vez de licença avulsa, o ACF PRO e o Rank Math PRO entram no bundle e o padrão por post type fica replicável entre sites.

No plano PRO da FULL, por R$849, o ACF PRO e o Rank Math PRO já vêm no pacote para até dez sites, o que dá R$85 por site em vez de pagar cada licença separada. Para uma agência que mantém vários CPTs com schema, isso troca um custo recorrente espalhado por um padrão único, e o mesmo mapeamento de campo para propriedade pode ser reusado de um site para outro sem refazer a configuração do zero a cada projeto.

Checklist final do Schema de CPT

O checklist final do schema de CPT confirma, em uma passada, que cada elo da cadeia está fechado antes de você dar o trabalho por concluído. Rode esta lista depois do passo 5 e de qualquer alteração futura nos grupos de campos ACF, porque é justamente após uma edição de campo que o schema costuma esvaziar em silêncio.

Antes de declarar pronto, confirme:

• O register_post_type tem show_in_rest true.
• O @type escolhido descreve a entidade melhor que Article.
• Só campos sempre preenchidos viram propriedades obrigatórias.
• O nome do campo ACF bate com a variável do Rank Math.
• O cache do site e do CDN foi limpo após gerar o schema.
• O Rich Results Test passou em dois posts diferentes, sem erro.
• O relatório de aprimoramentos do Search Console está sendo acompanhado.

Se qualquer item falhar, volte ao passo correspondente antes de publicar mais itens do CPT.

Perguntas frequentes sobre Schema para custom post types com ACF e Rank Math

Próximos passos para estruturar seus cpts

Adicionar schema para custom post types com ACF e Rank Math é, no fundo, traduzir os campos que você já tem em uma linguagem que o Google entende: registre o CPT com REST ativo, mapeie só os campos sempre preenchidos, escolha o @type que descreve a entidade de verdade e teste cada mudança no Rich Results Test antes de comemorar. O erro do campo vazio é o que mais derruba schema em produção, então revalide depois de qualquer alteração nos grupos de campos. Para padronizar o ACF PRO e o Rank Math em vários sites sem licença avulsa, conheça os planos da FULL, e para continuar aprendendo, o FULL Academy reúne os tutoriais de WordPress em um só lugar.