Datos Estructurados Schema.org y JSON-LD en React SPAs

+-------------------------------------------------------------------------+
|                  ARQUITECTURA DEL GRAFO SEMÁNTICO JSON-LD EN SPA        |
+-------------------------------------------------------------------------+

 [ Componente de Página en React SPA ]
        |
        | 1. Datos tipados de la entidad procedentes de la API (DTO)
        v
 +-----------------------------------------------------------------------+
 | Generador de Esquema Schema.org (schema-dts)                          |
 | - Validación estructural: @type: "TechArticle" | "Product" | "FAQPage"|
 | - Grafos vinculados: Autor (Person), Editorial (Organization)         |
 +-----------------------------------------------------------------------+
        |
        | 2. Sanitización contra XSS (Escape de </script>, <, >, &)
        v
 +-----------------------------------------------------------------------+
 | <script type="application/ld+json" id="jsonld-primary">               |
 |   {                                                                   |
 |     "@context": "https://schema.org",                                 |
 |     "@type": "Product",                                               |
 |     "name": "Mechanical Keyboard",                                    |
 |     "offers": { "@type": "Offer", "price": "149.00" }                 |
 |   }                                                                   |
 | </script>                                                             |
 +-----------------------------------------------------------------------+
        |
        | 3. Ingesta por WRS / Googlebot / Extractores de LLMs
        v
 +-----------------------------------------------------------------------+
 | Resultados de Búsqueda: Snippet Enriquecido / Resumen de IA           |
 | ★★★★★ 4.9 (128 valoraciones) | En stock | 149.00 USD                  |
 +-----------------------------------------------------------------------+

/**
 * Serializa de forma segura un objeto a cadena JSON para incrustarlo en <script>.
 * Neutraliza los caracteres <, >, & y separadores de línea Unicode para mitigar ataques XSS.
 */
export function serializeSafeJsonLd(data: unknown): string {
  const jsonString = JSON.stringify(data, null, process.env.NODE_ENV === 'development' ? 2 : 0);

  if (!jsonString) {
    return '{}';
  }

  // Escapar caracteres conflictivos conforme a las directrices W3C/HTML5
  return jsonString
    .replace(/</g, '\\u003c')
    .replace(/>/g, '\\u003e')
    .replace(/&/g, '\\u0026')
    .replace(/\u2028/g, '\\u2028') // Line Separator
    .replace(/\u2029/g, '\\u2029'); // Paragraph Separator
}

import React from 'react';
import type { Thing, WithContext } from 'schema-dts';
import { serializeSafeJsonLd } from '@/utils/safe-json-ld';

export interface JsonLdProps<T extends Thing> {
  schema: WithContext<T>;
  id?: string;
}

/**
 * Componente universal para inyección de datos estructurados JSON-LD.
 * Garantiza validación estricta de Schema.org y blindaje total ante XSS.
 */
export function JsonLd<T extends Thing>({ schema, id }: JsonLdProps<T>) {
  const scriptId = id || `jsonld-${schema['@type'] ? String(schema['@type']).toLowerCase() : 'schema'}`;

  return (
    <script
      id={scriptId}
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: serializeSafeJsonLd(schema) }}
    />
  );
}

import React from 'react';
import type { Product, BreadcrumbList, WithContext } from 'schema-dts';
import { JsonLd } from '@/components/seo/JsonLd';

interface ProductItem {
  id: string;
  name: string;
  sku: string;
  description: string;
  brand: string;
  price: number;
  currency: string;
  ratingValue: number;
  reviewCount: number;
  imageUrl: string;
}

interface ProductDetailsProps {
  product: ProductItem;
}

export const ProductDetailsPage: React.FC<ProductDetailsProps> = ({ product }) => {
  // 1. Construcción del esquema Product con ofertas y valoraciones
  const productSchema: WithContext<Product> = {
    '@context': 'https://schema.org',
    '@type': 'Product',
    name: product.name,
    image: product.imageUrl,
    description: product.description,
    sku: product.sku,
    brand: {
      '@type': 'Brand',
      name: product.brand,
    },
    offers: {
      '@type': 'Offer',
      url: `https://agenticlab.dev/products/${product.sku}`,
      priceCurrency: product.currency,
      price: product.price.toFixed(2),
      availability: 'https://schema.org/InStock',
      itemCondition: 'https://schema.org/NewCondition',
    },
    aggregateRating: {
      '@type': 'AggregateRating',
      ratingValue: product.ratingValue.toString(),
      reviewCount: product.reviewCount.toString(),
      bestRating: '5',
      worstRating: '1',
    },
  };

  // 2. Construcción del esquema BreadcrumbList
  const breadcrumbSchema: WithContext<BreadcrumbList> = {
    '@context': 'https://schema.org',
    '@type': 'BreadcrumbList',
    itemListElement: [
      {
        '@type': 'ListItem',
        position: 1,
        name: 'Inicio',
        item: 'https://agenticlab.dev',
      },
      {
        '@type': 'ListItem',
        position: 2,
        name: 'Catálogo',
        item: 'https://agenticlab.dev/products',
      },
      {
        '@type': 'ListItem',
        position: 3,
        name: product.name,
        item: `https://agenticlab.dev/products/${product.sku}`,
      },
    ],
  };

  return (
    <main className="container mx-auto p-6">
      {/* Inyección de Datos Estructurados */}
      <JsonLd schema={productSchema} id="product-jsonld" />
      <JsonLd schema={breadcrumbSchema} id="breadcrumbs-jsonld" />

      <h1 className="text-2xl font-bold">{product.name}</h1>
      <p className="text-gray-600">{product.description}</p>
      <div className="price-tag text-xl font-semibold mt-4">
        {product.price} {product.currency}
      </div>
    </main>
  );
};

import { chromium } from 'playwright';

export async function validateJsonLdOnPage(url: string): Promise<void> {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: 'networkidle' });

  // Extraer todos los bloques JSON-LD presentes en el DOM renderizado
  const jsonLdScripts = await page.locator('script[type="application/ld+json"]').allInnerTexts();

  if (jsonLdScripts.length === 0) {
    throw new Error(`[Schema Error]: No se encontraron bloques JSON-LD en ${url}`);
  }

  for (const scriptContent of jsonLdScripts) {
    try {
      const parsed = JSON.parse(scriptContent) as Record<string, unknown>;
      if (!parsed['@context'] || !parsed['@type']) {
        throw new Error(`[Schema Error]: Faltan las claves requeridas @context o @type`);
      }
      console.info(`[Schema Valid]: Parseo exitoso para @type: ${String(parsed['@type'])}`);
    } catch (err: unknown) {
      throw new Error(`[Schema Error]: JSON malformado: ${err instanceof Error ? err.message : 'Unknown'}`);
    }
  }

  await browser.close();
}