We built a structured data helper for Payload blocks, here's how it works

Payload's Lexical editor gives you structured rich text, not plain strings, and schema.org fields like description and reviewBody want plain text. We lean on convertLexicalToPlaintext from @payloadcms/richtext-lexical/plaintext everywhere a field could contain rich text:

typescript
1const description = block.richText ? convertLexicalToPlaintext({ data: block.richText }) : ''

For places where HTML sneaks in from elsewhere (CMS titles, mostly), there's a small sanitiser that strips scripts, styles, and tags before collapsing whitespace:

typescript
1function stripHtmlToPlainText(html: string): string {
2  return html
3    .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
4    .replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, '')
5    .replace(/<[^>]+>/g, ' ')
6    .replace(/\s+/g, ' ')
7    .trim()
8}

Nothing clever, just enough to guarantee nothing malformed ends up inside a <script type="application/ld+json"> tag.

A subtle bug we wanted to avoid: emitting a dateModified that's earlier than datePublished, which happens easily if you're pulling updatedAt from a different source than createdAt. The fix is a small resolver that clamps dateModified to never precede datePublished:

typescript
1function resolveSchemaDates(args: {
2  publishedAt?: string | Date | null
3  createdAt?: string | Date | null
4  updatedAt?: string | Date | null
5}): { datePublished?: string; dateModified?: string } {
6  const published = toIsoDate(args.publishedAt) || toIsoDate(args.createdAt)
7  const updated = toIsoDate(args.updatedAt)
8  const modified =
9    published && updated
10      ? new Date(updated) >= new Date(published)
11        ? updated
12        : published
13      : updated || published
14
15  return {
16    ...(published ? { datePublished: published } : {}),
17    ...(modified ? { dateModified: modified } : {}),
18  }
19}

It also refuses to invent a "now" timestamp when there's genuinely no date data, better to omit the field than fabricate one. Search engines penalise inconsistent date signals, and most structured data validators will flag the mismatch.

Breadcrumb structured data helps search engines understand your site hierarchy, and earns those breadcrumb trails in search results. Posts, work items, and nested pages all build their BreadcrumbList differently. Posts get Home → Blog → Post title. Work items get Home → Work → Project title. Regular pages walk whatever breadcrumb trail is stored on the document itself:

typescript
1function generateBreadcrumbList(args: {
2  collection?: keyof typeof collectionPrefixMap
3  doc: Partial<Page> | Partial<Post> | Partial<Work>
4  url: string
5  serverUrl: string
6}): WithContext<BreadcrumbList> | null {
7  if (args.url === '/') return null
8  // ...builds crumbs based on collection type, skips "home" segments,
9  // returns null if fewer than 2 crumbs would result
10}

Returning null for the homepage, instead of a single "Home" crumb, avoids the useless single-item breadcrumb lists that trip up some rich-result validators.

This was the hardest part to get right. Several block-level generators (banner, CTA, media-and-content, highlight text) all map to Article when they have enough content. But a blog post page also generates its own primary Article from the post metadata. Merge those together and you get duplicate Article headlines on the same page, which Google Rich Results flags outright.

The fix is a filter that strips block-level Article nodes before merging with the page-level one:

typescript
1function isArticleJsonLdNode(node: WithContext<Thing>): boolean {
2  const t = (node as { '@type'?: string | string[] })['@type']
3  if (t === 'Article') return true
4  if (Array.isArray(t) && t.includes('Article')) return true
5  return false
6}
7
8export function withoutBlockArticleStructuredData(
9  blockNodes: WithContext<Thing>[],
10): WithContext<Thing>[] {
11  return blockNodes.filter((node) => !isArticleJsonLdNode(node))
12}

Same logic applies to FAQPage, Google only accepts one per URL, so the FAQ group generator collapses multiple FAQ groups into a single FAQPage with a combined mainEntity array instead of emitting one FAQPage per group.

The last piece is a merge function that filters out null/undefined and hands back a flat array ready to serialise:

typescript
1export function mergeStructuredData(
2  ...entries: (WithContext<Thing> | null | undefined)[]
3): WithContext<Thing>[] {
4  return entries.filter(Boolean) as WithContext<Thing>[]
5}

At the page level, you call the relevant generators for whatever blocks are present, merge them, strip duplicate Article/FAQPage nodes, and drop the result into a <script type="application/ld+json"> tag. The page doesn't need to know which blocks are on it, the generators handle everything.