Schema.org & Semantic Knowledge Graph in Server Components: schema-dts — SEO & Core Web Vitals

Architectural Foundations#

Semantic metadata structured under the Schema.org standard serves as the fundamental bridge between unstructured HTML markup and modern artificial intelligence crawlers and entity graphs (such as Google Knowledge Graph). Structured data enables search engines to unequivocally identify business entities, authors, commercial product offerings, breadcrumb hierarchies, and expert editorial content, producing enriched SERP presentations (Rich Results).

Historically, the React ecosystem implemented structured data via client-side libraries (react-helmet, next-seo) or imperatively manipulated the DOM within client useEffect hooks. This pattern introduces three systemic architectural defects:

Client Bundle Bloat: Massive TypeScript definitions, schema builders, and extensive JSON data structures compile into client JavaScript bundles, inflating downloaded script sizes, exacerbating TBT, and degrading INP.
XSS Injection Vulnerabilities: Naive serialization using JSON.stringify() without escaping reserved HTML characters allows attackers to execute arbitrary JavaScript by injecting closing </script> tags into unescaped user-generated text fields.
Entity Disconnection: Many platforms output fragmented <script type="application/ld+json"> elements across disconnected layout components. Search engines parse disjointed data islands rather than a unified semantic knowledge graph linking products, merchant entities, brands, and parent digital properties.

The React Server Components (RSC) architecture in Next.js 15 eliminates these deficiencies through the Zero Client-Side JS paradigm. Schema.org knowledge graphs are formulated exclusively in the isolated server runtime using the compile-time type-safety library schema-dts.

The browser receives pure, pre-serialized static HTML requiring zero client-side JavaScript for hydration and imposing zero overhead on the browser's main thread.

Mental Model#

Rather than scattering isolated JSON-LD snippets throughout the document, modern web semantics mandates assembling an integrated entity graph via the @graph property.

Every node in the graph possesses a globally deterministic identifier (@id) formulated as a canonical URI anchored by a fragment identifier (hash anchor). Nodes reference each other via these @id keys, establishing a Directed Graph that accurately reflects the domain ontology.

text

+-----------------------------------------------------------------------------------------+
|                               SEMANTIC KNOWLEDGE GRAPH @graph                           |
+-----------------------------------------------------------------------------------------+

  [Organization] (https://agenticlab.dev/#organization)
        ▲
        │ publisher / brand
        │
  [WebSite] (https://agenticlab.dev/#website)
        ▲
        │ isPartOf
        │
  [WebPage] (https://agenticlab.dev/products/server-v5#webpage)
        │
        ├─────────────────────────────┬─────────────────────────────┐
        │ breadcrumb                  │ mainEntity                  │ primaryImageOfPage
        ▼                             ▼                             ▼
  [BreadcrumbList]               [Product]                      [ImageObject]
  (#breadcrumb)                  (#product)                     (#main-image)
                                      │
                                      ├─────────────────────────────┐
                                      │ offers                      │ aggregateRating
                                      ▼                             ▼
                                 [AggregateOffer]            [AggregateRating]
                                 (#offers)                   (#rating)

Core primitives of semantic graph architecture:

schema-dts — the compile-time semantic typing layer.
@graph Property — the entity graph container.
Entity @id URI — the relational anchor of the knowledge graph.
Zero Client-Side JS — bundle size and performance optimization.

Production Applications#

Enterprise E-Commerce & Marketplaces: Composing interconnected graphs of Product + AggregateOffer + MerchantReturnPolicy + ShippingDetails to unlock Product Rich Snippets and synchronize with Google Merchant Center feeds.
Technical Engineering Publications & Documentation: Linking TechArticle entries with verified Person author nodes (linking sameAs references to GitHub, LinkedIn, and ORCID) and the publishing Organization to satisfy Google's E-E-A-T criteria.
Corporate Enterprise Portals: Solidifying corporate branding in Google Knowledge Panels by describing the Organization with official social profiles, tax identifiers (taxID), support contact points, and physical headquarters geo-coordinates.
EdTech Platforms & Course Catalogs: Semantically describing Course entities, curricula, VideoObject modules, and interactive FAQPage accordions for education carousels in search results.

Implementation Mechanics#

1. Secure Server Component Architecture: JsonLdGraph#

Injecting JSON-LD via React's dangerouslySetInnerHTML carries Cross-Site Scripting (XSS) risks. If malicious text in a review or description contains </script><script>alert(1)</script>, the browser HTML parser prematurely terminates the data block and executes the script in the user's origin.

To neutralize this vector, reserved HTML characters (<, >, &) are replaced with their safe Unicode escape sequences (\u003c, \u003e, \u0026).

typescriptcomponents/seo/JsonLdGraph.tsx (Secure Zero-JS Schema.org Component)

import type { Graph, Thing, WithContext } from 'schema-dts';

interface JsonLdGraphProps {
  /** Nodes belonging to the Schema.org semantic graph */
  nodes: Thing[];
}

/**
 * Sanitizes JSON strings by substituting dangerous HTML characters with Unicode escapes.
 * Prevents XSS attacks triggered by premature </script> tag termination.
 */
function sanitizeJsonLd(data: WithContext<Graph>): string {
  return JSON.stringify(data)
    .replace(/</g, '\\u003c')
    .replace(/>/g, '\\u003e')
    .replace(/&/g, '\\u0026');
}

/**
 * React Server Component for secure, zero-overhead Schema.org graph injection.
 * Zero Client-Side JS: Imposes 0 bytes on the client JavaScript bundle!
 */
export function JsonLdGraph({ nodes }: JsonLdGraphProps) {
  // Assemble top-level Linked Data graph
  const graph: WithContext<Graph> = {
    '@context': 'https://schema.org',
    '@graph': nodes,
  };

  const safeJson = sanitizeJsonLd(graph);

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

2. Type-Safe Entity Factory via schema-dts#

Create a centralized factory module enforcing strict Schema.org types for global entities:

typescriptlib/seo/schema-factory.ts (Centralized Type-Safe Entity Builders)

import type {
  Organization,
  WebSite,
  BreadcrumbList,
  Thing,
} from 'schema-dts';

const SITE_ORIGIN = 'https://agenticlab.dev';

export const ORGANIZATION_ID = `${SITE_ORIGIN}/#organization`;
export const WEBSITE_ID = `${SITE_ORIGIN}/#website`;

/**
 * Generates the root Organization node
 */
export function createOrganizationEntity(): Organization {
  return {
    '@type': 'Organization',
    '@id': ORGANIZATION_ID,
    name: 'Fullstack Agentic Lab',
    url: SITE_ORIGIN,
    logo: {
      '@type': 'ImageObject',
      '@id': `${SITE_ORIGIN}/#logo`,
      url: `${SITE_ORIGIN}/assets/logo.png`,
      caption: 'Fullstack Agentic Lab Brand Mark',
    },
    sameAs: [
      'https://github.com/agenticlab-dev',
      'https://twitter.com/agenticlab_dev',
      'https://linkedin.com/company/agenticlab',
    ],
    contactPoint: {
      '@type': 'ContactPoint',
      contactType: 'technical support',
      email: '[email protected]',
      availableLanguage: ['English', 'Spanish', 'Ukrainian'],
    },
  };
}

/**
 * Generates the root WebSite node linked to the Organization
 */
export function createWebSiteEntity(): WebSite {
  return {
    '@type': 'WebSite',
    '@id': WEBSITE_ID,
    url: SITE_ORIGIN,
    name: 'Fullstack Agentic Lab',
    publisher: {
      '@id': ORGANIZATION_ID,
    },
    potentialAction: {
      '@type': 'SearchAction',
      target: `${SITE_ORIGIN}/search?q={search_term_string}`,
      'query-input': 'required name=search_term_string',
    },
  };
}

interface BreadcrumbItemInput {
  name: string;
  path: string;
}

/**
 * Generates an ordered BreadcrumbList node
 */
export function createBreadcrumbsEntity(items: BreadcrumbItemInput[]): BreadcrumbList {
  return {
    '@type': 'BreadcrumbList',
    itemListElement: items.map((item, index) => ({
      '@type': 'ListItem',
      position: index + 1,
      name: item.name,
      item: `${SITE_ORIGIN}${item.path}`,
    })),
  };
}

3. Composing the Interconnected Graph in RSC#

Here is a complete server component for a product details page assembling an integrated @graph:

typescriptapp/products/[slug]/page.tsx (Interconnected Product Knowledge Graph)

import { notFound } from 'next/navigation';
import type { Metadata } from 'next';
import type { Product, AggregateOffer, AggregateRating } from 'schema-dts';
import { JsonLdGraph } from '@/components/seo/JsonLdGraph';
import {
  createOrganizationEntity,
  createWebSiteEntity,
  createBreadcrumbsEntity,
  ORGANIZATION_ID,
} from '@/lib/seo/schema-factory';

interface ProductPageProps {
  params: Promise<{ slug: string }>;
}

interface ProductData {
  id: string;
  slug: string;
  name: string;
  description: string;
  sku: string;
  gtin13: string;
  currency: string;
  price: number;
  ratingValue: number;
  reviewCount: number;
  imageUrl: string;
}

async function fetchProductData(slug: string): Promise<ProductData | null> {
  if (slug !== 'enterprise-server-license') return null;

  return {
    id: 'prod_98412',
    slug: 'enterprise-server-license',
    name: 'Fullstack Agentic Lab Enterprise Core Server',
    description: 'High-throughput server runtime engineered for Next.js 15 and Partial Prerendering.',
    sku: 'AG-SRV-2026',
    gtin13: '4601234567890',
    currency: 'USD',
    price: 1990,
    ratingValue: 4.95,
    reviewCount: 48,
    imageUrl: 'https://agenticlab.dev/images/products/server.png',
  };
}

export async function generateMetadata({ params }: ProductPageProps): Promise<Metadata> {
  const { slug } = await params;
  const product = await fetchProductData(slug);
  if (!product) return { title: 'Product Not Found' };

  return {
    title: `${product.name} — Fullstack Agentic Lab`,
    description: product.description,
    alternates: {
      canonical: `https://agenticlab.dev/products/${product.slug}`,
    },
  };
}

export default async function ProductDetailsPage({ params }: ProductPageProps) {
  const { slug } = await params;
  const product = await fetchProductData(slug);

  if (!product) {
    notFound();
  }

  const pageCanonicalUrl = `https://agenticlab.dev/products/${product.slug}`;
  const productId = `${pageCanonicalUrl}#product`;

  // 1. Product Entity Node
  const productEntity: Product = {
    '@type': 'Product',
    '@id': productId,
    name: product.name,
    description: product.description,
    sku: product.sku,
    gtin13: product.gtin13,
    image: product.imageUrl,
    brand: {
      '@id': ORGANIZATION_ID, // Link to global Organization node
    },
    offers: {
      '@type': 'AggregateOffer',
      priceCurrency: product.currency,
      lowPrice: product.price,
      highPrice: product.price * 1.2,
      offerCount: 1,
      offers: [
        {
          '@type': 'Offer',
          url: pageCanonicalUrl,
          price: product.price,
          priceCurrency: product.currency,
          availability: 'https://schema.org/InStock',
          itemCondition: 'https://schema.org/NewCondition',
          seller: {
            '@id': ORGANIZATION_ID,
          },
        },
      ],
    } as AggregateOffer,
    aggregateRating: {
      '@type': 'AggregateRating',
      ratingValue: product.ratingValue,
      reviewCount: product.reviewCount,
      bestRating: 5,
      worstRating: 1,
    } as AggregateRating,
  };

  // 2. Navigation Breadcrumbs Node
  const breadcrumbsEntity = createBreadcrumbsEntity([
    { name: 'Home', path: '/' },
    { name: 'Products', path: '/products' },
    { name: product.name, path: `/products/${product.slug}` },
  ]);

  // 3. Unify nodes into cohesive Linked Data ontology
  const schemaNodes = [
    createOrganizationEntity(),
    createWebSiteEntity(),
    breadcrumbsEntity,
    productEntity,
  ];

  return (
    <>
      {/* Semantic graph rendered via RSC with Zero Client JS */}
      <JsonLdGraph nodes={schemaNodes} />

      <main className="max-w-5xl mx-auto px-4 py-12 space-y-6">
        <h1 className="text-3xl font-extrabold text-slate-100">{product.name}</h1>
        <p className="text-lg text-slate-300">{product.description}</p>
        <div className="text-2xl font-bold text-accent-cyan">
          ${product.price.toLocaleString('en-US')} {product.currency}
        </div>
      </main>
    </>
  );
}

4. Automated Microdata Verification with Vitest#

Validating structured data involves two testing layers:

W3C / Schema.org Specification: Checking graph connections using the Schema Markup Validator.
Google Rich Results Criteria: Ensuring compliance with rich snippet criteria via the Google Rich Results Test.

In continuous integration pipelines, verify graph integrity through automated unit tests:

typescript__tests__/seo-schema.test.ts

import { describe, it, expect } from 'vitest';
import type { Graph, Product } from 'schema-dts';

describe('Schema.org Graph Integrity', () => {
  it('should generate valid interconnected @graph with deterministic @id URIs', () => {
    const rawJsonLd = `{
      "@context": "https://schema.org",
      "@graph": [
        {
          "@type": "Organization",
          "@id": "https://agenticlab.dev/#organization",
          "name": "Fullstack Agentic Lab"
        },
        {
          "@type": "Product",
          "@id": "https://agenticlab.dev/products/server#product",
          "name": "Enterprise Server",
          "brand": { "@id": "https://agenticlab.dev/#organization" }
        }
      ]
    }`;

    const parsed = JSON.parse(rawJsonLd) as Graph;
    const nodes = parsed['@graph'];

    expect(nodes).toBeDefined();
    expect(nodes).toHaveLength(2);

    const product = nodes?.find((n) => n['@type'] === 'Product') as Product;
    expect(product).toBeDefined();
    expect(product.brand).toEqual({ '@id': 'https://agenticlab.dev/#organization' });
  });
});

Common Pitfalls#

Ошибка: Naive JSON.stringify Serialization Without Sanitization (XSS Vulnerability)

If user-generated input (such as customer review content or author bios) contains </script>, the browser HTML parser prematurely terminates the script element and executes following text as live JavaScript.

tsx

// ❌ ANTIPATTERN: Critical XSS Vulnerability!
<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }}
/>

Solution: Always escape <, >, and & characters in JSON strings using Unicode representations via sanitizeJsonLd.

Ошибка: Scattering Fragmented, Disconnected JSON-LD Blocks

Embedding separate <script type="application/ld+json"> elements across disconnected layout components (e.g., Organization in the header, WebSite in the footer, Product on the page). Search crawlers perceive disconnected data fragments. When entity names or URLs diverge across blocks, Google loses confidence in the data, revoking Rich Results eligibility.

Solution: Combine all entity nodes into a single @graph array using deterministic @id URIs.

Ошибка: Rendering JSON-LD Inside Client Components ('use client')

Placing Schema.org generation logic inside client components forces Next.js to package heavy schema dictionaries and data structures into client JavaScript bundles. The client expends CPU cycles serializing JSON-LD into the DOM, while first-phase search crawlers (without JavaScript execution) miss the markup entirely.

Solution: Render JsonLdGraph strictly within React Server Components (RSC).

Ошибка: Discrepancy Between Structured Data and Rendered Visual Content

Declaring a price of $99 or a 5.0 rating (450 reviews) in JSON-LD when the visible UI shows $149 or lacks review records. Google flags this manipulation, triggering a Structured Data Manual Action Penalty that strips all Rich Results from the domain.

Solution: Derive Schema.org nodes directly from the authoritative server records used to render the visual JSX.

RSC Semantic Graph Compilation & Validation Pipeline

1. Server-Side Entity RetrievalRSC-Fetch

The Server Component queries strongly typed records from databases or internal microservices.

const product = await fetchProduct(slug);

2. Ontology Construction via schema-dtsType-Check

Schema.org objects are synthesized with compile-time TypeScript type verification without any casts.

const productNode: Product = { ... };

3. Entity Interconnection into @graphGraph-Link

Nodes (Organization, WebSite, Breadcrumbs, Product) interlink through deterministic @id URI keys.

brand: { '@id': ORGANIZATION_ID }

4. Sanitization & HTML Pre-renderingZero-JS-HTML

JSON strings undergo Unicode XSS sanitization (< replaced with \u003c) and render into static script tags.

safeJsonLd(graph) -> Static HTML Tag

5. Google Rich Results CI GateCI-Gate

Automated test suites parse generated HTML to guarantee schema validity before merging pull requests.

pnpm test:seo-schema

Interview Questions & Answers#

, browser HTML parsers interpret as the termination of the JSON-LD block, executing subsequent markup as active JavaScript. Sanitizing <, >, and & into Unicode escape sequences (\\u003c, \\u003e, \\u0026) preserves JSON-LD syntax while eliminating premature tag termination."}},{"@type":"Question","name":"How should @id URIs be structured in an interconnected knowledge graph?","acceptedAnswer":{"@type":"Answer","text":"An @id must be an absolute canonical URI incorporating a unique fragment identifier (hash anchor). For example: https://agenticlab.dev/#organization for the company, https://agenticlab.dev/#website for the platform, and https://agenticlab.dev/products/item-123#product for a specific SKU. This enables third-party crawlers to reference individual graph nodes unambiguously."}}]}

Interview Questions7 questions