SEO and structured data

Generate canonical metadata, breadcrumbs, listing markup, and JobPosting JSON-LD.

Build search artifacts from the same Board API objects you render. This prevents titles, canonical URLs, and structured data from drifting away from the visible job.

Prerequisites

A public, absolute HTTPS origin.
Canonical routes built with @cavuno/board/paths.
Server rendering for metadata and JSON-LD.
A policy that excludes non-published or expired jobs from active JobPosting markup.

Build a job detail SEO model

createJobPostingJsonLd is the SDK method that creates the Schema.org JobPosting object. It does not decide whether a job is currently eligible for Google for Jobs; make that decision before calling it.

1// src/data/job-seo.ts
2import { isNotFound } from '@cavuno/board';
3import { jobDetailPath } from '@cavuno/board/paths';
4import {
5  buildJobBreadcrumbs,
6  createBreadcrumbJsonLd,
7  createJobPostingJsonLd,
8} from '@cavuno/board/seo';
9
10import { board } from '../lib/board';
11
12const origin = 'https://jobs.example.com';
13
14export async function loadJobSeo(jobSlug: string) {
15  try {
16    const [job, context] = await Promise.all([
17      board.jobs.retrieve(jobSlug),
18      board.context(),
19    ]);
20
21    if (!job.slug || !job.company?.slug) return null;
22
23    const path = jobDetailPath(job.company.slug, job.slug);
24    const canonical = `${origin}${path}`;
25    const expiresAt = job.expiresAt ? Date.parse(job.expiresAt) : null;
26    const isActive =
27      job.status === 'published' &&
28      (expiresAt === null || expiresAt > Date.now());
29
30    // Structural crumbs: chrome kinds (`home` / `jobs`) have no display
31    // name — the application supplies those words. Data crumbs carry `name`.
32    const breadcrumbs = buildJobBreadcrumbs(job);
33    const crumbLabel = (crumb: (typeof breadcrumbs)[number]) => {
34      switch (crumb.kind) {
35        case 'home':
36          return 'Home'; // application-owned
37        case 'jobs':
38          return 'Jobs'; // application-owned
39        default:
40          return crumb.name;
41      }
42    };
43
44    return {
45      title: `${job.title} | ${context.name}`,
46      description: `Apply for ${job.title} at ${job.company?.name ?? context.name}.`,
47      canonical,
48      jobPosting: isActive
49        ? createJobPostingJsonLd({ job, board: context, shareUrl: canonical })
50        : null,
51      breadcrumbs: createBreadcrumbJsonLd(
52        breadcrumbs.map((crumb) => ({
53          label: crumbLabel(crumb),
54          href: crumb.path,
55        })),
56        { origin },
57      ),
58    };
59  } catch (error) {
60    if (isNotFound(error)) return null;
61    throw error;
62  }
63}

The helper derives the identifier, dates, employment type, hiring organization, physical or remote location requirements, salary, education, experience, and canonical URL from PublicJob and the board context.

Emit JSON-LD safely

Your framework owns the <script> element. Escape < in serialized JSON so stored text cannot terminate the script element.

tsx

1export function JsonLd({ value }: { value: Record<string, unknown> | null }) {
2  if (!value) return null;
3
4  const html = JSON.stringify(value).replace(/</g, '\\u003c');
5
6  return (
7    <script
8      type="application/ld+json"
9      dangerouslySetInnerHTML={{ __html: html }}
10    />
11  );
12}

Render the JobPosting and breadcrumb objects as separate JSON-LD scripts, or as a framework-supported graph. Keep every structured value consistent with visible page content.

Build listing metadata

1import { listingHead, listingJsonLd } from '@cavuno/board/seo';
2
3const page = await board.jobs.list({ limit: 20 });
4const heading = 'Jobs';
5const countLabel = new Intl.NumberFormat(context.language).format(page.count);
6// Application owns title/description composition (counters, order, separators).
7const title = messages.listingTitle({
8  count: page.count,
9  countLabel,
10  heading,
11  boardName: context.name,
12});
13const description = messages.listingDescription({
14  count: page.count,
15  countLabel,
16  heading,
17  boardName: context.name,
18});
19
20const head = listingHead({
21  title,
22  origin,
23  path: '/jobs',
24  description,
25});
26
27const jsonLd = listingJsonLd({
28  origin,
29  breadcrumbs: [{ name: 'Home', path: '/' }, { name: 'Jobs' }],
30  jobs: page.data,
31});

Map the returned meta and links descriptors into your framework’s head API.

Expected result

An active job detail returns one canonical URL, a JobPosting object, and breadcrumb markup derived from the same job. Listings return head descriptors and breadcrumb/ItemList JSON-LD for their visible cards.

Verify the result

The canonical URL matches the visible route and public origin.
JobPosting markup appears only on active job detail pages.
Remote jobs contain the location requirements derived from the job data.
JSON-LD text cannot close its own script element.
Breadcrumb and listing URLs are absolute in the rendered output.

Start with Cavuno’s JobPosting schema validator, then confirm search eligibility with Google’s Rich Results Test. Inspect the raw server-rendered HTML, not only the hydrated DOM.

Errors and edge cases

createJobPostingJsonLd can return null; omit the script in that case.
Missing salary, education, experience, or address data (such as a street address or postal code) is omitted rather than fabricated.
Expired jobs can remain useful pages, but must not masquerade as active postings.
board.seo() separately returns canonicalBase, verification, manifest.name, adsTxt, and the IndexNow key. Icons and theme color are application-owned.

Production cautions

Do not add structured fields that users cannot see on the page.
Keep job expiry handling synchronized between routing, metadata, and sitemaps.
Validate representative on-site, hybrid, remote, salaried, and salary-less jobs.
Revalidate SEO output when job or board settings change.

Next, publish every indexable route with Sitemap generation.