Datos estructurados JSON-LD: ejemplos listos para usar y un generador PHP

Los datos estructurados JSON-LD son una forma de decirle a los motores de búsqueda, en un formato legible por máquina, qué es una página: un artículo, un producto con un precio, una empresa con datos de contacto, una lista de preguntas y respuestas. Es invisible para los visitantes, no reemplaza el buen contenido y por sí solo no mejora la clasificación. Lo que hace es hacer que una página sea elegible para obtener resultados enriquecidos, ayudar a los motores a conectar sus páginas con la entidad correcta y brindar a la búsqueda basada en IA una fuente más limpia para leer. Lo generamos en cada página de integrono.com y nuestros otros sitios, y esta guía es la versión práctica de ese trabajo.

JSON-LD frente a Microdata frente a RDFa

El vocabulario de Schema.org se puede integrar en tres sintaxis. Microdata y RDFa colocan atributos en sus etiquetas HTML, lo que confunde el marcado con las plantillas. JSON-LD vive en un bloque de script, separado del diseño, por lo que es más fácil de generar, probar y cambiar. Google afirma que recomienda JSON-LD y es lo que usamos en todas partes.

Principios antes que ejemplos.

• Describir el contenido visible. Si el precio, la calificación o las preguntas frecuentes no están en la página, no los incluya en el marcado.
• Utilice URL absolutas y la URL canónica de la página.
• Sea completo con las propiedades requeridas y agregue las recomendadas cuando tenga datos reales.
• Utilice @id para vincular entidades. El autor del artículo es la organización definida una vez con un @id, no una copia nueva cada vez.
• Utilice fechas en ISO 8601 (2026-10-28 o con hora y zona).
• No inventes reseñas ni valoraciones. Los datos falsos AggregateRating son una causa común de acciones manuales.

Ejemplo 1. Organización (y sitio web)

Coloque esto en la página de inicio o en un gráfico de todo el sitio. Define la entidad a la que se refiere otro marcado.

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://example.com/#organization",
  "name": "Example Studio",
  "url": "https://example.com/",
  "logo": "https://example.com/images/logo.png",
  "email": "[email protected]",
  "sameAs": [
    "https://github.com/example",
    "https://www.linkedin.com/company/example"
  ]
}

Ejemplo 2. Lista de rutas de navegación

El marcado de ruta de navegación permite a Google mostrar la ruta de la página en lugar de una URL sin formato en los resultados. Debe coincidir con las migas de pan visibles.

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {"@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/"},
    {"@type": "ListItem", "position": 2, "name": "Blog", "item": "https://example.com/blog"},
    {"@type": "ListItem", "position": 3, "name": "JSON-LD guide", "item": "https://example.com/blog/json-ld-guide"}
  ]
}

Ejemplo 3. Artículo

Para publicaciones de blogs y guías. Las propiedades que importan: título, fechas, autor, editor, imagen y URL de la página.

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "JSON-LD structured data: examples",
  "description": "Short summary of the article.",
  "url": "https://example.com/blog/json-ld-guide",
  "mainEntityOfPage": "https://example.com/blog/json-ld-guide",
  "inLanguage": "en",
  "datePublished": "2026-08-23",
  "dateModified": "2026-10-28",
  "author": {"@id": "https://example.com/#organization"},
  "publisher": {"@id": "https://example.com/#organization"},
  "image": {"@type": "ImageObject", "url": "https://example.com/images/blog/json-ld.webp", "width": 1200, "height": 630}
}

Cambiar dateModified sólo cuando el contenido realmente cambia. Golpearlo en cada implementación es una forma silenciosa de perder la confianza.

Ejemplo 4. Producto con oferta

Para páginas de productos con precio visible. Incluir disponibilidad y moneda; agregue aggregateRating o review solo si se muestran reseñas reales en la página.

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Example product",
  "description": "What it is and who it is for.",
  "image": ["https://example.com/images/product.webp"],
  "sku": "EX-001",
  "brand": {"@type": "Brand", "name": "Example"},
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/product/ex-001",
    "priceCurrency": "EUR",
    "price": "49.00",
    "availability": "https://schema.org/InStock",
    "itemCondition": "https://schema.org/NewCondition"
  }
}

Ejemplo 5. Servicio con Oferta

Para servicios pagos, como una auditoría de precio fijo o una consulta por horas. Usamos este patrón en nuestras propias páginas de servicio.

{
  "@context": "https://schema.org",
  "@type": "Service",
  "name": "Architecture review",
  "serviceType": "Software architecture analysis",
  "provider": {"@id": "https://example.com/#organization"},
  "areaServed": "Worldwide",
  "offers": {
    "@type": "Offer",
    "price": "200",
    "priceCurrency": "EUR",
    "url": "https://example.com/services/architecture-review"
  }
}

Ejemplo 6. Página de preguntas frecuentes

El marcado de preguntas frecuentes describe una lista de preguntas y respuestas que son visibles en la página. Tenga en cuenta que desde 2023 Google muestra resultados enriquecidos de preguntas frecuentes solo para un conjunto limitado de sitios autorizados, por lo que no espere respuestas ampliables en los resultados. El marcado sigue siendo válido, aún puede ser leído por otros motores de búsqueda y sistemas de inteligencia artificial, y mantiene las preguntas frecuentes estructuradas de manera que las máquinas puedan citarlas.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Do I need structured data to rank?",
      "acceptedAnswer": {"@type": "Answer", "text": "No. It is not a ranking requirement, but it can make pages eligible for rich results."}
    }
  ]
}

Combina todo en un @graph

Una página rara vez tiene una sola entidad. Colóquelos todos en un script usando @graph y haga referencia a entidades compartidas mediante @id:

{
  "@context": "https://schema.org",
  "@graph": [
    {"@type": "Organization", "@id": "https://example.com/#organization", "name": "Example Studio"},
    {"@type": "Article", "headline": "...", "author": {"@id": "https://example.com/#organization"}},
    {"@type": "BreadcrumbList", "itemListElement": []},
    {"@type": "FAQPage", "mainEntity": []}
  ]
}

Generando JSON-LD de forma segura en PHP

No concatene JSON manualmente. Una cita en un título rompe todo el guión y el motor de búsqueda la ignora silenciosamente. Construya una matriz PHP y codifíquela. Dos banderas importan: mantener Unicode legible y proteger el contexto HTML evitando barras y etiquetas.

function jsonLdScript(array $graph): string
{
    $data = ['@context' => 'https://schema.org', '@graph' => $graph];
    $json = json_encode(
        $data,
        JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_HEX_TAG | JSON_HEX_AMP | JSON_THROW_ON_ERROR
    );
    return '<script type="application/ld+json">' . $json . '</script>';
}

$graph = [
    ['@type' => 'Organization', '@id' => $site . '/#organization', 'name' => 'Example Studio', 'url' => $site . '/'],
    [
        '@type'         => 'Article',
        'headline'      => $title,
        'url'           => $canonical,
        'datePublished' => $published,
        'dateModified'  => $modified,
        'author'        => ['@id' => $site . '/#organization'],
    ],
];
echo jsonLdScript($graph);

JSON_HEX_TAG convierte < y > en secuencias de escape para que el contenido del usuario nunca pueda cerrar la etiqueta del script antes de tiempo. Alimente el generador con los mismos datos que representan la página (título, precio, fechas), para que el marcado y el contenido visible no puedan separarse. En un sitio multilingüe, traduzca los campos de texto y configúrelo inLanguage por configuración regional; así es como se producen los artículos de este blog y el marcado de preguntas frecuentes.

Validar y monitorear

1. Rich Results Test de elegibilidad de los tipos de resultados enriquecidos de Google.
2. Schema Markup Validator para la sintaxis general schema.org de cualquier tipo.
3. Informes de mejora Search Console (rutas de navegación, productos, preguntas frecuentes, etc.) para errores y advertencias a escala, después de que Google haya rastreado sus páginas.
4. Una prueba unitaria que representa cada plantilla y verifica que JSON-LD analiza y contiene las claves requeridas evita regresiones después de las refactorizaciones.

Errores que te cuestan

• Marcado para contenido que no está en la página (preguntas frecuentes ocultas, calificaciones inventadas, precios que difieren del precio visible).
• Varios bloques en conflicto de un complemento y una plantilla, cada uno con una Organization diferente.
• URL relativas, fechas incorrectas o falta un @id.
• JSON roto debido a la creación manual de cadenas y comillas sin escape.
• Tratar el esquema como un truco de clasificación. Es una herramienta de claridad; la página todavía tiene que merecer clasificarse.

¿Cómo podemos ayudar?

Los datos estructurados son una parte de nuestro trabajo técnico de SEO: diseñamos el esquema para sus plantillas, implementamos el generador en su pila y configuramos la validación para que siga siendo correcto después de los lanzamientos. Si desea obtener una descripción general de lo que está mal en su sitio, comience con nuestra lista de verificación de auditoría técnica de SEO o reserve una consulta.