Datos estructurados en WordPress sin caos: Yoast, filtros PHP y la IA como copiloto

Por qué un único sistema, y por qué el de Yoast

La regla fundamental que cualquier especialista en SEO técnico conoce es que Google interpreta cada bloque <script type="application/ld+json"> como un grafo independiente. Si en una página tienes dos bloques distintos, aunque ambos hablen de la misma organización, Google los trata como dos entidades separadas. Si una de ellas tiene @id consistentes con el resto del sitio y la otra no, lo que percibe Google es ruido: dos cosas que se parecen pero que no termina de saber si son la misma.

El concepto clave es el @graph único: un array dentro de un solo bloque JSON-LD donde todos los nodos están conectados entre sí por referencias @id. La WebPage referencia a la Organization por su @id, la Organization referencia a su logo por @id, el Article referencia a su autor por @id, y así sucesivamente. Cuando ese tejido de referencias está bien construido, Google puede reconstruir un mapa coherente de la entidad y sus relaciones — y ahí es donde aparecen los rich results, el Knowledge Panel y el reconocimiento de marca.

Yoast SEO emite por defecto un @graph razonablemente completo: Organization, WebSite, WebPage, BreadcrumbList, ImageObject para la imagen principal, y Article para entradas de blog. Lo hace con @id consistentes en todo el sitio y respetando las convenciones de schema.org. La pregunta entonces no es "qué sistema usar para emitir datos estructurados", sino "cómo extender el sistema que ya está funcionando bien sin romperlo".

La respuesta son los filtros PHP que Yoast expone para este propósito. Hay varios, cada uno con un alcance distinto:

• wpseo_schema_organization modifica el nodo Organization global en todas las páginas.
• wpseo_schema_webpage modifica el nodo WebPage de la página actual.
• wpseo_schema_article modifica el nodo Article en entradas de blog.
• wpseo_schema_person modifica un Person que Yoast ya esté generando (página de autor).
• wpseo_schema_graph_pieces añade nodos completamente nuevos al grafo (Event, Service, Book, Person nuevo, Product no-Woo, etc.).

La regla práctica es simple: si modificas un nodo que Yoast ya emite, usas el filtro específico. Si añades un nodo nuevo, usas wpseo_schema_graph_pieces. En ningún caso inyectas un bloque <script> aparte, ni instalas otro plugin de Schema en paralelo, ni editas el HTML de salida con regex. Todo lo que entre al grafo entra por uno de estos filtros.

La estructura del archivo PHP

Una vez aceptada esa restricción, la siguiente pregunta es cómo organizar el código. Yo trabajo con plugins single-file desplegables por FTP en toda la flota — es mi patrón habitual y encaja bien aquí porque cada sitio tiene sus particularidades de Schema y conviene tener un archivo dedicado por sitio en lugar de una librería compartida.

La cabecera y la estructura general son siempre las mismas:

<?php
/**
 * Plugin Name: AB Schema Yoast Extension — [nombre del sitio]
 * Description: Extensiones del grafo Schema.org de Yoast.
 * Version: 1.0.0
 */

if ( ! defined( 'ABSPATH' ) ) exit;

// 1. Modificar Organization global
add_filter( 'wpseo_schema_organization', 'ab_schema_organization' );
function ab_schema_organization( $data ) {
    // Datos globales que aplican a todas las páginas
    return $data;
}

// 2. Añadir nodos nuevos por tipo de página
add_filter( 'wpseo_schema_graph_pieces', 'ab_schema_pieces', 11, 2 );
function ab_schema_pieces( $pieces, $context ) {
    if ( is_singular( 'profesional' ) ) $pieces[] = ab_node_persona( $context );
    if ( is_singular( 'evento' ) )      $pieces[] = ab_node_evento( $context );
    if ( is_singular( 'libro' ) )       $pieces[] = ab_node_libro( $context );
    return $pieces;
}

// 3. Helpers — un nodo por función
function ab_node_persona( $context )  { /* ... */ }
function ab_node_evento( $context )   { /* ... */ }
function ab_node_libro( $context )    { /* ... */ }

Esa estructura tiene una propiedad que valoro mucho cuando vuelves al código tres meses después: cada cambio en el grafo es localizable en una sola función. Si el cliente me pide añadir un campo nuevo a la ficha de un profesional, sé exactamente dónde tocar. Si Yoast actualiza algo y rompe la integración, sé qué bloque revisar primero.

El problema de los @id

Hay un detalle del sistema que parece menor y resulta ser la fuente del 80% de los errores: los identificadores @id. Yoast usa una convención fija que conviene respetar al pie de la letra:

• https://dominio.com/#organization para la organización del sitio.
• https://dominio.com/#website para el sitio web.
• https://dominio.com/url-de-la-pagina/ para la WebPage actual.
• https://dominio.com/url-de-la-pagina/#breadcrumb para el breadcrumb.
• https://dominio.com/url-de-la-pagina/#primaryimage para la imagen principal.

Cuando creas un nodo nuevo, debes seguir el mismo patrón: URL-de-la-pagina/#tipo-slug. Por ejemplo, si la página de un médico es https://clinica.com/dr-garcia/, el @id del nodo Person que añadas debe ser https://clinica.com/dr-garcia/#person. Y cuando ese Person referencia a la organización, lo hace por @id, no duplicando los datos:

'worksFor' => array(
    '@id' => home_url( '/#organization' ),
),

El uso de home_url() en lugar de hardcodear el dominio es importante: hace el código portable entre staging y producción, y entre dominios distintos si reutilizas el snippet como base para otra web.

El error más común que he visto — y cometido — es duplicar la organización en lugar de referenciarla. Tienes un nodo Event y, en lugar de poner 'organizer' => array('@id' => home_url('/#organization')), copias todo el bloque de Organization ahí dentro. Resultado: dos organizaciones en el grafo, una de ellas con datos completos y otra recortada, ambas con el mismo nombre. Google interpreta que son entidades distintas y el reconocimiento de marca se diluye.

Casos prácticos

Caso 1: notariaboschbarcelona.com — Organización + Persona pública + Libros

Una notaría es un caso interesante porque combina varios tipos de entidad que conviven en el mismo sitio. La notaría como organización (LegalService, ProfessionalService), el notario como persona pública con autoridad profesional (Person), los libros que ha publicado (Book) y los servicios notariales que ofrece (Service).

El nodo Organization aprovecha tipos múltiples y campos de autoridad:

add_filter( 'wpseo_schema_organization', function( $data ) {
    $data['@type'] = array( 'Organization', 'LegalService', 'ProfessionalService' );
    $data['description']  = 'Notaría de Barcelona especializada en derecho mercantil y sucesiones.';
    $data['foundingDate'] = '1992';

    $data['address'] = array(
        '@type'           => 'PostalAddress',
        'streetAddress'   => 'Rambla de Catalunya, [...]',
        'addressLocality' => 'Barcelona',
        'addressRegion'   => 'Cataluña',
        'postalCode'      => '08007',
        'addressCountry'  => 'ES',
    );

    $data['telephone']  = '+34 93 [...]';
    $data['areaServed'] = array(
        '@type' => 'Country',
        'name'  => 'España',
    );

    return $data;
} );

Para la página del notario, la decisión clave es vincular la WebPage a la entidad Person mediante mainEntity. Eso le dice a Google que el contenido principal de esa página es esa persona, no un texto genérico:

add_filter( 'wpseo_schema_webpage', function( $data ) {
    if ( is_page( 'notario' ) ) {
        $data['mainEntity'] = array(
            '@id' => get_permalink() . '#person',
        );
    }
    return $data;
} );

function ab_node_persona_notario( $context ) {
    return array(
        '@type'       => 'Person',
        '@id'         => get_permalink() . '#person',
        'name'        => get_field( 'nombre_completo' ),
        'jobTitle'    => 'Notario',
        'worksFor'    => array( '@id' => home_url( '/#organization' ) ),
        'alumniOf'    => array(
            '@type' => 'EducationalOrganization',
            'name'  => 'Universidad de Barcelona',
        ),
        'knowsAbout'  => array(
            'Derecho mercantil',
            'Derecho de sucesiones',
            'Derecho inmobiliario',
        ),
        'sameAs'      => array(
            'https://www.linkedin.com/in/...',
        ),
    );
}

Para los libros del notario, el nodo Book se asocia al Person por @id igual que el Person se asoció a la Organization. Es el mismo patrón aplicado un nivel más abajo:

function ab_node_libro_notario( $context ) {
    return array(
        '@type'         => 'Book',
        '@id'           => get_permalink() . '#book',
        'name'          => get_the_title(),
        'author'        => array( '@id' => home_url( '/notario/#person' ) ),
        'isbn'          => get_field( 'isbn' ),
        'inLanguage'    => 'es',
        'datePublished' => get_field( 'fecha_publicacion' ),
        'publisher'     => array(
            '@type' => 'Organization',
            'name'  => get_field( 'editorial' ),
        ),
    );
}

El resultado es un grafo donde Google puede seguir el rastro: la organización tiene a esta persona como miembro, esta persona ha escrito estos libros, todo en una misma estructura coherente. Es justo el tipo de tejido de relaciones que alimenta el reconocimiento de E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness) que Google utiliza para evaluar la calidad de los contenidos profesionales.

Caso 2: idermic.es — Sector salud con tipos múltiples

Las clínicas son territorio de tipos médicos específicos de schema.org. La organización es MedicalBusiness o MedicalClinic, los profesionales son Physician (no solo Person), los tratamientos son MedicalProcedure o Service, y las enfermedades pueden modelarse como MedicalCondition.

Lo importante aquí es que Google tiene tratamientos especiales para el sector salud. Las páginas con datos estructurados médicos bien implementados pueden aparecer con información estructurada en el panel de búsqueda, especialmente para consultas locales tipo "dermatólogo en Barcelona". Pero también significa que Google es más estricto con la coherencia: si declaras Physician, la propiedad medicalSpecialty casi se vuelve obligatoria de facto, y debe usar uno de los valores del enum MedicalSpecialty (Dermatologic, Cardiovascular, Pediatric, etc.), no una string libre.

Para una ficha de profesional de Idermic:

function ab_node_persona_dermatologo( $context ) {
    return array(
        '@type'            => array( 'Person', 'Physician' ),
        '@id'              => get_permalink() . '#person',
        'name'             => get_the_title(),
        'jobTitle'         => 'Dermatólogo',
        'medicalSpecialty' => 'Dermatologic',
        'worksFor'         => array( '@id' => home_url( '/#organization' ) ),
        'hasCredential'    => array(
            '@type'             => 'EducationalOccupationalCredential',
            'credentialCategory'=> 'license',
            'name'              => 'Colegiado COMB nº [...]',
        ),
        'knowsAbout'       => array(
            'Dermatología clínica',
            'Dermatología estética',
            'Cirugía dermatológica',
        ),
    );
}

Y para un tratamiento, combinando Service con MedicalProcedure:

function ab_node_tratamiento( $context ) {
    return array(
        '@type'       => array( 'Service', 'MedicalProcedure' ),
        '@id'         => get_permalink() . '#service',
        'name'        => get_the_title(),
        'description' => get_field( 'descripcion_tratamiento' ),
        'provider'    => array( '@id' => home_url( '/#organization' ) ),
        'procedureType' => 'https://schema.org/TherapeuticProcedure',
    );
}

El detalle de procedureType con la URL completa de schema.org es un patrón frecuente: cuando una propiedad espera un valor de un enum oficial, se referencia con la URL absoluta de schema.org. Esto evita ambigüedades y es lo que recomienda la documentación.

Caso 3: raluy.com — Eventos itinerantes y municipios

Un circo itinerante es un caso particularmente bonito desde el punto de vista de Schema porque casi todo el contenido relevante son eventos: cada función en cada ciudad es un Event con su fecha, su lugar, sus precios. La organización es PerformingGroup además de Organization, los artistas son Person, y la lista de municipios donde actúa el circo se modela como areaServed en la organización o como location en cada evento.

El nodo de Event es uno de los más completos que se pueden modelar y también uno de los más estrictos: Google requiere name, startDate, location con address completa, y eventStatus. Sin esos campos no hay rich result. Si añades offers, también deben estar bien formados con price, priceCurrency y availability:

function ab_node_evento_circo( $context ) {
    $fecha_inicio = get_field( 'fecha_inicio' );
    $fecha_fin    = get_field( 'fecha_fin' );

    return array(
        '@type'              => array( 'Event', 'TheaterEvent' ),
        '@id'                => get_permalink() . '#event',
        'name'               => get_the_title(),
        'startDate'          => $fecha_inicio, // Formato ISO 8601: 2026-05-15T20:00:00+02:00
        'endDate'            => $fecha_fin,
        'eventStatus'        => 'https://schema.org/EventScheduled',
        'eventAttendanceMode'=> 'https://schema.org/OfflineEventAttendanceMode',
        'location' => array(
            '@type' => 'Place',
            'name'  => get_field( 'lugar_nombre' ),
            'address' => array(
                '@type'           => 'PostalAddress',
                'streetAddress'   => get_field( 'lugar_calle' ),
                'addressLocality' => get_field( 'lugar_ciudad' ),
                'postalCode'      => get_field( 'lugar_cp' ),
                'addressCountry'  => 'ES',
            ),
        ),
        'organizer' => array( '@id' => home_url( '/#organization' ) ),
        'image'     => get_the_post_thumbnail_url( get_the_ID(), 'full' ),
        'offers' => array(
            '@type'         => 'Offer',
            'url'           => get_field( 'url_entradas' ),
            'price'         => get_field( 'precio_desde' ),
            'priceCurrency' => 'EUR',
            'availability'  => 'https://schema.org/InStock',
            'validFrom'     => get_field( 'venta_desde' ),
        ),
    );
}

El detalle más delicado es el formato de las fechas. Google espera ISO 8601 con zona horaria: 2026-05-15T20:00:00+02:00. Si los campos de ACF guardan las fechas como Y-m-d o d/m/Y, hay que normalizarlas antes de inyectarlas — un error de formato hace que el evento desaparezca de los resultados enriquecidos sin avisar.

Para la organización del circo, los municipios se modelan como areaServed en formato array de City o AdministrativeArea. Esto refuerza la búsqueda local cuando alguien busca "circo en [ciudad]":

$data['areaServed'] = array(
    array( '@type' => 'City', 'name' => 'Barcelona' ),
    array( '@type' => 'City', 'name' => 'Madrid' ),
    array( '@type' => 'City', 'name' => 'Valencia' ),
    // ...
);

Caso 4: barretsinclair.com — WooCommerce y la regla de no duplicar

El último caso es importante porque es una excepción. WooCommerce inyecta su propio schema de Product en las fichas de producto, y lo hace bastante bien. Si añades un filtro de Yoast para Product por encima, te encuentras con dos Product en la página: el que emite WooCommerce y el tuyo. Es exactamente el tipo de duplicidad que el sistema unificado busca evitar.

La regla aquí es: si la web usa WooCommerce, los productos los emite WooCommerce. No se toca por Yoast. Si necesitas ampliar el Product con campos adicionales — por ejemplo, añadir material, color o size que no estén en los atributos estándar — se hace por los hooks propios de WooCommerce, no por los filtros de Yoast:

add_filter( 'woocommerce_structured_data_product', function( $markup, $product ) {
    $markup['material'] = get_post_meta( $product->get_id(), '_material', true );
    $markup['color']    = get_post_meta( $product->get_id(), '_color', true );
    return $markup;
}, 10, 2 );

Para una tienda de sombreros como Barret Sinclair, lo que sí se hace por Yoast es la Organization del sitio (["Organization", "Store"] o ["Organization", "OnlineStore"]) con los datos de la tienda física si la hay, y cualquier nodo adicional que no sea producto: AboutPage, ContactPage, posts del blog, etc. Los productos se quedan en su sitio.

Este caso ilustra una regla más general que vale para cualquier flota: antes de añadir un filtro propio para un tipo Schema, verificar si el ecosistema del sitio (WooCommerce, Easy Digital Downloads, Events Calendar, etc.) ya está emitiendo ese tipo. Si lo hace, la integración correcta es ampliar lo que emite ese plugin, no duplicarlo desde Yoast.

La IA como copiloto del proceso

Hasta aquí el contenido es técnico y, en cierto modo, atemporal: las reglas de Schema y los filtros de Yoast llevan años más o menos estables. Lo que sí ha cambiado mucho en los últimos años es cómo trabajo con todo esto. Y aquí entra el papel de la IA — concretamente Claude, que es la herramienta con la que articulo el flujo, aunque el patrón es generalizable a cualquier modelo capaz de razonar sobre código y JSON.

La IA no implementa el sistema por mí. Lo que hace es comprimir radicalmente cada uno de los tres momentos del trabajo donde antes se me iban las horas: el diagnóstico inicial, la generación de los snippets y la validación posterior.

En el diagnóstico inicial lo que hago es copiar el bloque <script type="application/ld+json"> de la página tal como está hoy y pegárselo. La IA es muy buena leyendo JSON-LD complejo, identificando si hay duplicidades, si los @id cierran entre sí, si hay propiedades inventadas o si faltan campos obligatorios para el tipo declarado. En cinco minutos tengo un diagnóstico que antes me llevaba media hora de revisión manual con la documentación de schema.org abierta en otra pestaña. No es magia: la IA tiene en su conocimiento la especificación de schema.org, las reglas de Google para rich results y los patrones habituales de error. Mi trabajo es validar el diagnóstico y, sobre todo, decidir qué hacer con él.

En la generación de los snippets el patrón es distinto. Le explico a la IA el objetivo, el tipo de página, los campos disponibles en ACF y cualquier particularidad del sitio, y pido que genere el filtro PHP siguiendo las plantillas que tengo establecidas en mi manual interno. La IA es muy buena replicando patrones de código consistentes: si le dejas claro que quieres home_url('/#organization') y no la URL hardcodeada, lo respetará en todas las funciones. Si le dices que el @id siempre tiene que seguir el patrón URL-pagina/#tipo, lo aplicará. Lo que sí me toca a mí es revisar que los nombres de los campos ACF coincidan con lo que realmente hay en el sitio — porque la IA puede inventarse get_field('fecha_evento') cuando en realidad el campo se llama fecha_inicio. Esa verificación final es responsabilidad del desarrollador, sin atajos.

En la validación posterior el flujo es el más sistemático. Después de subir el snippet por FTP y limpiar caché, recargo la página, copio el JSON-LD del View Source y lo pego tanto en validator.schema.org como en el chat con la IA. El validador me da los errores formales (propiedades mal escritas, tipos incorrectos). La IA me da una revisión semántica: ¿el grafo cuenta la historia que querías? ¿las referencias @id cierran? ¿hay algún nodo huérfano? ¿el rich result objetivo va a aparecer? Las dos revisiones son complementarias y se hacen en paralelo en menos de un minuto.

El cambio cualitativo en mi flujo de trabajo no está en que la IA escriba el código por mí — eso es lo de menos. Está en que cierra el bucle de feedback rápido. Antes, una iteración completa (diagnóstico, propuesta, implementación, validación) podía llevarme una tarde entera entre lo que tardaba en revisar la documentación y lo que tardaba en pillar errores sutiles. Ahora una iteración son veinte minutos. Y como cada iteración es más barata, puedo permitirme hacer más iteraciones, lo que se traduce en grafos más limpios y más completos.

Hay dos puntos donde la IA no sustituye al humano y conviene tenerlos claros:

El primero es la decisión de arquitectura. La IA puede generar el código de cualquier patrón, pero la decisión de qué patrón usar — Person con mainEntity en la WebPage, o Person como pieza independiente; Service con MedicalProcedure o solo Service; tipos múltiples sí o no — es una decisión de diseño SEO que requiere conocer el negocio y el objetivo. La IA puede ayudarte a explorar opciones, pero la responsabilidad de elegir es tuya.

El segundo es la verificación contra la realidad del sitio. La IA no puede ver tu base de datos, ni tu ACF, ni los CPTs reales que tienes registrados. Cualquier snippet que genere se basa en lo que tú le has dicho que hay. Si le dices que tienes un campo ACF que no existe, generará código que falla en silencio. La fase de "comprobar que los nombres de campo y los slugs de CPT coinciden con lo que hay en producción" es manual y no se delega.

Lo que cambia en el SEO cuando el grafo está limpio

Los datos estructurados no son una varita mágica. Un sitio con malos contenidos no se posiciona por mucho Schema que tenga, y un sitio con buenos contenidos se posiciona razonablemente sin él. Pero un grafo bien construido sí amplifica de forma medible un trabajo de contenidos que ya esté bien hecho, en tres planos concretos:

Reconocimiento de entidad. Cuando Google entiende sin ambigüedad que tu sitio representa a una entidad concreta — una notaría, una clínica, un circo, una tienda — y que esa entidad tiene atributos consistentes (dirección, fundación, perfiles sociales, miembros del equipo), la asocia con confianza a las búsquedas de marca y a las búsquedas locales. Esto se traduce en Knowledge Panel, en Business Profile más rico y, en sectores con autoridad profesional, en una ventaja competitiva clara frente a competidores con grafos rotos o ausentes.

Rich results. Algunos tipos generan rich result visibles directamente en la SERP: Event con su fecha y precio, Product con su rating, Recipe con su tiempo de preparación, Book con su autor. Cuando aparecen, el CTR mejora porque tu resultado ocupa más espacio visual y comunica más información antes de que el usuario haga clic.

E-E-A-T y autoridad. El tejido de referencias entre Organization, Person, Article y Book (cuando aplica) es justo lo que Google está aprendiendo a leer para evaluar la autoridad de los autores. Una entrada de blog firmada por un Person con worksFor apuntando a la Organization, con alumniOf indicando formación y sameAs apuntando a perfiles profesionales públicos, comunica algo muy distinto a una entrada de blog firmada por "Admin".

El error más caro: implementar y no validar

Si tuviera que quedarme con una sola lección de los últimos años trabajando con datos estructurados, sería esta: el coste de implementar un Schema mal y darlo por bueno es mucho mayor que el coste de no implementarlo. Un grafo roto puede tardar meses en notarse — Google sigue indexando, las páginas siguen apareciendo, los rich results no aparecen pero tampoco hay un mensaje claro de error. Para cuando te das cuenta, llevas un año dejando autoridad sobre la mesa.

La única forma de evitar esto es validar después de cada cambio, sin excepciones, con el ciclo completo: limpiar caché, recargar, copiar el JSON-LD, pegarlo en el validador, confirmar 0 errores y 0 warnings, comprobar que las referencias @id cierran, pasar por Rich Results Test, revisar en GSC. Es el momento del proceso donde la IA, paradójicamente, ayuda más: porque la validación es repetitiva, mecánica y se beneficia enormemente de tener un revisor que nunca se cansa de mirar JSON.

El sistema completo — Yoast como base, filtros PHP como única vía de extensión, IA como copiloto en diagnóstico y validación — no es una solución elegante en abstracto. Es la solución que sobrevive al uso real durante años en una flota de sitios heterogénea, sin acumular deuda técnica y sin que cada nueva web sea un proyecto desde cero. Para mí, esa es la prueba que importa.

Si gestionas una flota de sitios WordPress y los datos estructurados se te están convirtiendo en un problema de mantenimiento más que en una ventaja, vale la pena pararse a unificar el sistema antes de seguir añadiendo capas. El trabajo de un día limpiando el grafo se amortiza solo en menos de un mes.