Respuesta breve: Schema debe ser una copia estructurada de los hechos de la página
Si llegaste buscando un prompt SKILL.md de Codex para SEO Schema JSON-LD, más abajo encontrarás uno listo para copiar. La regla detrás del código es más importante: los datos estructurados deben expresar hechos que una persona pueda verificar en la propia página. No son una oportunidad para crear el objeto JSON más extenso posible.
Codex resulta útil porque puede revisar la página, sus datos de contenido y el marcado existente antes de recomendar un tipo o escribir JSON-LD. El orden importa. Una petición ambigua como "añade todo el Schema que puedas" suele producir aggregateRating, precios, autores o fechas de publicación inventados. Esos campos pueden tener una sintaxis válida y aun así representar mal la página.
Google recomienda JSON-LD cuando la configuración del sitio lo permite porque suele ser más fácil de implementar y mantener. También deja claro que el marcado debe describir la página donde aparece, reflejar contenido visible para los usuarios y mantenerse preciso. Superar Rich Results Test no garantiza un resultado enriquecido.
| Objetivo | Lo que hace este Skill | Lo que se niega a hacer |
|---|---|---|
| Una página nueva necesita Schema | Recomienda el tipo más específico respaldado por hechos visibles | Añade tipos irrelevantes para inflar la cobertura |
| El JSON-LD existente está desordenado | Detecta propiedades duplicadas, conflictivas, obsoletas o sin respaldo | Sustituye silenciosamente el marcado de producción |
| El equipo quiere resultados enriquecidos | Consulta la documentación de Google para la función objetivo | Promete resultados enriquecidos, posiciones o tráfico |
| Se necesita un prompt repetible | Estandariza la auditoría, la generación y el QA | Revela rutas locales, credenciales o contexto privado |
Elige el tipo principal de la página antes de añadir objetos de apoyo
Empieza con una pregunta sencilla: ¿qué está viendo principalmente el visitante? La respuesta debe determinar el tipo principal de Schema.org. Las migas de pan, los datos de la organización y el vídeo pueden apoyar ese objeto cuando describen información visible en la misma página.
| Función real de la página | Tipo principal a considerar | Objetos de apoyo posibles | Hechos que deben existir en la página |
|---|---|---|---|
| Publica una pieza editorial con autor |
|
| El título, el cuerpo y los datos visibles de autor/fecha coinciden |
| Vende o explica un producto de software |
|
| Funciones, precio, valoraciones, sistema operativo y ofertas solo si se muestran |
| Publica una receta |
|
| Ingredientes, pasos y tiempos son visibles |
| Enseña una tarea completa |
|
| Los pasos y materiales son completos y visibles |
| Muestra una jerarquía de navegación | Mantén el tipo principal |
| Las etiquetas y destinos coinciden con la navegación real |
Schema.org tiene un vocabulario mucho más amplio que las funciones de resultados enriquecidos de Google. Para Google Search, la guía actual de Search Central de la función objetivo tiene más autoridad que el mero hecho de que una propiedad exista en Schema.org.
Empieza por la finalidad de la página. El tipo se deriva de los hechos visibles, no al revés.
Un flujo de Codex más seguro tiene cuatro controles
- Inventario de hechos. Extrae datos solo del texto visible, de campos fiables del CMS que se renderizan en la página o de datos confirmados expresamente por el usuario. Marca cada campo como confirmado, ausente o pendiente de confirmación humana.
- Decisión de tipo. Elige un tipo principal que coincida con la finalidad central de la página. Explica las alternativas en lugar de acumular todos los tipos plausibles.
- Código y mapeo. Produce JSON-LD con una fuente para cada valor emitido. Omite las propiedades desconocidas en vez de rellenarlas con marcadores de posición.
- Validación y publicación. Comprueba la sintaxis JSON, los requisitos específicos de la función, el DOM renderizado, URL Inspection y el informe correspondiente de Search Console.
El Skill siguiente convierte esos controles en una regla explícita. Pide a Codex que audite primero y modifique el código después, lo que reduce el riesgo de publicar marcado válido en apariencia pero desconectado de la página.
Copia este Skill de Codex para SEO Schema JSON-LD (SKILL.md)
Guarda el siguiente bloque como configuración de tu Skill. No contiene directorios del equipo, nombres de usuario, tokens de acceso, valores de variables de entorno ni rutas privadas. También obliga a Codex a excluir contexto sensible de sus respuestas.
---
name: seo-schema-jsonld
description: Audit visible page facts, recommend accurate Schema.org JSON-LD, implement it safely, and validate it against Google structured-data requirements.
---
# SEO Schema JSON-LD
Use this skill when a user asks to add, repair, review, or validate Schema.org JSON-LD / structured data for a website page, template, CMS entry, or component.
## Primary rule
Treat structured data as a structured representation of the page's user-visible facts. Never use it to invent, hide, exaggerate, or imply information that the page does not support.
## Privacy and output safety
- Never print absolute local paths, home directories, usernames, credentials, tokens, cookies, API keys, environment-variable values, private URLs, or repository-specific secrets.
- Refer to files with short, project-relative labels when needed, such as `src/pages/article.tsx` or `the page template`.
- Do not copy sensitive values into JSON-LD, examples, logs, commit messages, screenshots, or explanations.
- If input contains secrets or private identifiers, omit them and state that sensitive values were excluded.
## Required workflow
### 1. Inspect before generating
Read the relevant page, template, content data, and any existing structured data. Build a fact inventory using only:
- visible page text and user-visible UI;
- trusted CMS fields that are rendered on that page;
- verified product, organization, author, or breadcrumb data supplied by the user.
For every candidate property, label it `confirmed`, `missing`, or `needs human confirmation`. Do not infer missing values from brand names, URLs, conventions, or unrelated pages.
### 2. Choose the narrowest suitable type
Identify the page's primary purpose first. Recommend one primary Schema.org type that truthfully describes it. Add supporting objects only when they also describe user-visible information on the same page.
Explain the recommended primary type, supporting types, why each applies, and types deliberately rejected.
For Google rich-result eligibility, consult the current Google Search Central documentation for the target feature. Schema.org support alone does not establish Google feature support.
### 3. Apply strict data guardrails
Never generate these values unless they are confirmed and visible or otherwise explicitly verified by the user:
- `aggregateRating`, `review`, or review counts;
- price, currency, availability, offer dates, shipping, or return policy;
- author, publisher, logo, address, phone, social profile, or `sameAs`;
- publication dates, modification dates, images, video duration, or interaction counts;
- FAQ questions and answers that are not visibly present;
- event, job, medical, financial, legal, or local-business claims.
Never add misleading `FAQPage`, fake reviews, hidden content, keyword lists, or unrelated types. Prefer fewer complete and accurate properties over many uncertain ones.
### 4. Produce the implementation
Return these sections in order:
1. `Fact inventory` - property, value or status, and visible source.
2. `Schema decision` - primary type, supporting types, assumptions, and exclusions.
3. `JSON-LD` - valid JSON inside one `application/ld+json` script block. Use placeholders only in a clearly labeled illustrative example; never present placeholders as production-ready values.
4. `Implementation note` - the safe insertion point for the site's framework or CMS, without exposing private paths.
5. `Validation checklist` - syntax, rendered-page check, Google Rich Results Test when applicable, Schema Markup Validator, URL Inspection after deployment, and Search Console monitoring.
6. `Open questions` - every field that needs a human decision.
If editing code is requested, make the smallest scoped change. Preserve existing valid markup, avoid duplicate entities, and explain any conflict before replacing it.
## JSON-LD quality checks
Before finalizing, verify all of the following:
- JSON parses and uses `https://schema.org` as `@context`.
- The main type matches the page's main user-visible purpose.
- Every emitted value has a page-level source or explicit user confirmation.
- Required fields for the intended Google feature are present and accurate.
- URLs are canonical, publicly reachable URLs when the property requires a URL.
- Dates use ISO 8601 where required.
- Multiple entities are connected deliberately, not duplicated accidentally.
- The markup remains available to crawlers in the rendered response.
- The result contains no secrets, local paths, private identifiers, or fabricated claims.
## Limitations to state plainly
Valid structured data can help search engines understand a page and make it eligible for certain search appearances. It does not guarantee rich results, rankings, traffic, citations, or inclusion in AI answers.
Usa el Skill con una aprobación previa
No te limites a decir "añade Schema a esta página". Entrega a Codex la página y los criterios de aceptación. Este prompt es un buen punto de partida:
Use the SEO Schema JSON-LD skill to review this article page.
Goal: add accurate Article and BreadcrumbList JSON-LD if the visible content supports them.
First return the fact inventory and schema decision. Do not edit code until I approve the decision.
Do not create ratings, reviews, author details, dates, images, or organization fields that are absent from the page.
After approval, make the smallest implementation change and provide the validation checklist.
En una plantilla grande, conserva el control de "inventario de hechos y decisión primero". Añade una revisión breve, pero puede evitar que una suposición incorrecta se extienda a miles de URL.
De la auditoría a la publicación en 30 minutos
| Tiempo | Acción | Salida | Control de calidad |
|---|---|---|---|
| 0-8 minutos | Revisar una URL representativa, texto visible, migas de pan y JSON-LD actual | Inventario de hechos | Cada valor se remonta a la página o a datos verificados |
| 8-15 minutos | Elegir el tipo principal y consultar la guía de Google | Decisión de tipo | "Posiblemente relacionado" no significa "debe marcarse" |
| 15-22 minutos | Generar o reparar el cambio de código más pequeño | Diferencia JSON-LD | Sin marcadores, sin entidades duplicadas, JSON válido |
| 22-30 minutos | Inspeccionar el renderizado de preproducción y probar | Registro de validación | Rich Results Test aprobado cuando corresponda; cada problema tiene responsable |
Después de publicar, usa URL Inspection para confirmar que Google puede obtener y analizar la página. Después revisa el informe de mejoras correspondiente de Search Console para encontrar fallos de plantilla, despliegue o fuente de datos a escala. Uno comprueba una URL; el otro encuentra mejor los problemas sistémicos.
Cada capa detecta un fallo distinto. Un objeto con sintaxis válida todavía puede fallar por los hechos o por el despliegue.
Un ejemplo de página de artículo deliberadamente mínimo
Este código es ilustrativo, no un objeto listo para producción. Muestra la forma de BlogPosting y BreadcrumbList. Usa valores reales confirmados en la página para el título, descripción, URL, autor, fecha e imagen. Si un dato no existe, no lo añadas solo para que el objeto parezca más completo.
El ejemplo omite intencionadamente valoración, autor, fecha de publicación, imagen y editor. No son adornos SEO opcionales, sino afirmaciones que necesitan una fuente fiable.
Cinco formas en que un marcado técnicamente válido falla
Analizar JSON no comprueba la verdad
Un validador JSON confirma si la sintaxis se puede analizar. No sabe si la página contiene realmente las reseñas, el precio o el autor declarados, ni si Product describe un producto o una página de servicio. El inventario de hechos detecta pronto la mayoría de estos fallos.
Más objetos no significan mejor marcado
Una receta con un vídeo visible puede incluir legítimamente Recipe, VideoObject y migas de pan. Aun así, su finalidad principal debe estar clara. Añadir Article, Product, FAQPage y HowTo a una página genérica suele aumentar el trabajo de mantenimiento y el riesgo de incoherencias.
Visibilidad y actualidad necesitan el mismo responsable
Las directrices generales de Google exigen que los datos estructurados representen la página y que la información sensible al tiempo siga actualizada. Precios, existencias, fechas de eventos, empleos y valoraciones no deberían quedar como valores pegados una sola vez. Conecta los hechos dinámicos a una fuente controlada y vuelve a probar cuando cambie la plantilla.
FAQPage no es una decoración genérica de preguntas
Solo las preguntas y respuestas que el usuario puede ver pertenecen al marcado FAQ. Las funciones de Google pueden tener condiciones adicionales. Publica primero un FAQ genuino y completo; luego consulta la guía actual. No inventes preguntas solo para perseguir un formato de resultado.
Schema no evita el rastreo, la indexación ni la calidad de la página
Una página bloqueada por noindex, controles de acceso o reglas de rastreo no se vuelve elegible por contener JSON-LD. Schema es una capa del SEO técnico, no un sustituto del rastreo, el contenido útil o la experiencia. Para una revisión más amplia, elige el flujo adecuado en el directorio de herramientas SEO de Auspia .
Lista previa a la publicación
- [ ] El tipo principal de la página está indicado y puede justificarse en una frase.
- [ ] Cada valor JSON-LD tiene una fuente visible o un origen fiable que se renderiza.
- [ ] No se inventaron valoraciones, reseñas, precio, existencias, autor, fecha, imagen ni datos de organización.
- [ ] El cambio no duplica entidades emitidas por el CMS, un plugin u otro componente.
- [ ] El JSON se analiza y el marcado aparece en el DOM renderizado después del despliegue.
- [ ] Las propiedades requeridas para la función de Google se revisaron en la documentación actual.
- [ ] Se usaron Rich Results Test, cuando corresponde, y Schema Markup Validator.
- [ ] Hay una revisión programada en URL Inspection y Search Console después de publicar.
- [ ] El equipo entiende que un marcado válido aporta elegibilidad y claridad, no una garantía de resultado o posición.
Preguntas frecuentes
¿Puede un SKILL.md decidir qué Schema necesita mi sitio?
Puede recomendar a partir de los hechos e identificar incógnitas, pero no sustituye la confirmación. Los precios, reseñas, datos de organización, autores y fechas deben venir de una fuente fiable o del responsable correspondiente.
¿Debe ir JSON-LD en <head> o en <body>?
Google admite JSON-LD tanto en <head> como en <body>. Usa la ubicación estable que tu framework o CMS pueda mantener sincronizada con la página. La prueba importante es que Google pueda rastrear un marcado válido que coincida con el renderizado.
¿Por qué no cambió nada después de aprobar Rich Results Test?
Una prueba correcta confirma señales técnicas; no obliga a Google a mostrar un resultado enriquecido. Google elige el tratamiento según la consulta, dispositivo, ubicación, página y otras señales. Revisa la coherencia y la indexabilidad en lugar de añadir propiedades sin respaldo.
¿Debe Codex rellenar todas las propiedades de Schema.org?
No. Google prefiere pocas propiedades recomendadas completas y precisas a muchas incompletas o incorrectas. Esa restricción debe formar parte del Skill, no solo de un prompt puntual.
Referencias oficiales
- Google Search Central: Introduction to structured data markup
- Google Search Central: General structured data guidelines
- Google Rich Results Test
- Schema.org
Autor: Julian Mercer, profesional de SEO técnico con 14 años de experiencia en Auspia. Escribe sobre rastreo, renderizado, datos estructurados y sistemas técnicos que los equipos pueden operar con fiabilidad.
