Automatizando Knowledge Graphs desde MDX

Al implementar el sistema de Knowledge Graphs de campa.dev, el objetivo no era generar JSON-LD. Era evitar que contenido y structured data diverjan. Los datos ya existían en el frontmatter, validados por Zod 4; el problema era conectarlos con Schema.org sin duplicar lo que ya estaba ahí.

La respuesta fue un transformer.

src/utils/schema.ts

import type { CollectionEntry } from "astro:content";

export function generateArticleSchema(entry: CollectionEntry<"blog">) {
  return {
    "@context": "https://schema.org",
    "@type": "TechArticle",
    headline: entry.data.title,
    description: entry.data.aiSummary ?? entry.data.description,
    datePublished: entry.data.pubDate.toISOString(),
    dateModified:
      entry.data.updatedDate?.toISOString() ?? entry.data.pubDate.toISOString(),
    author: { "@type": "Person", name: entry.data.author },
    mentions: entry.data.geoEntities?.map((name) => ({
      "@type": "Thing",
      name,
    })) ?? [],
    keywords: entry.data.tags.join(", "),
  };
}

geoEntities[] del frontmatter se convierte en mentions: [{ @type: Thing, name }]. mentions le da señales semánticas explícitas a crawlers y sistemas de retrieval basados en entidades. El transformer no valida nada; Zod ya lo hizo en build time. Si el schema pasa, el JSON-LD es estructuralmente correcto.

Para inyectarlo en el layout:

src/layouts/BlogPost.astro

---
import { generateArticleSchema } from "@/utils/schema";
const schema = generateArticleSchema(entry);
---
<script type="application/ld+json" set:html={JSON.stringify(schema)} />

Resultado: 0 desincronizaciones entre frontmatter y JSON-LD. Implementar el transformer desde el día uno de campa.dev fue exactamente la razón por la que nunca hubo que "arreglar" datos estructurados rotos: el build los genera, Zod los valida, no hay forma de que diverjan.

Trade-off: cada campo opcional del schema Zod (como geoEntities) necesita el operador ?. en el transformer; si no, el build rompe con undefined. No es complejo, pero es un punto de mantenimiento que crece con el schema.

Cuando el Knowledge Graph se deriva del schema tipado, el structured data deja de ser mantenimiento y pasa a ser compilación.

🔗 Sugerencias de lectura

GEO: citabilidad y JSON-LD para el índice de IA: La base de por qué este structured data importa.
Google ya no indexa como antes: El contexto de por qué el Knowledge Graph es el nuevo campo de batalla.
Zod 4: esquemas dinámicos y transformaciones complejas: Para extender el transformer con validaciones más avanzadas.
GEO: el nuevo SEO para la era de la IA: El artículo completo que da el marco estratégico.

…g CO₂