# Structured Data

> JSON-LD structured data with Thing base type and BreadcrumbList.

- Name: `structured-data`
- Categories: seo
- Detail page: https://open-types.dev/types/structured-data

## Install

```bash
# Types only
npx shadcn add @open-types/structured-data

# Types + Zod v4 validators
npx shadcn add @open-types/structured-data-zod

# Types + real-world examples
npx shadcn add @open-types/structured-data-examples
```

## Types

```typescript
export interface JsonLdBreadcrumbItem {
  "@type": "ListItem";
  position: number;
  name: string;
  item?: string;
}

export interface JsonLdBreadcrumbList {
  "@context"?: string;
  "@type": "BreadcrumbList";
  itemListElement: JsonLdBreadcrumbItem[];
}

export interface JsonLdThing {
  "@context"?: string;
  "@type": string;
  name?: string;
  description?: string;
  url?: string;
  image?: string;
  [key: string]: unknown;
}
```

## Zod validator

```typescript
import * as z from "zod";
import type {
  JsonLdBreadcrumbItem,
  JsonLdBreadcrumbList,
  JsonLdThing,
} from "../types/structured-data";

export const jsonLdBreadcrumbItemSchema = z.object({
  "@type": z.literal("ListItem"),
  position: z.number(),
  name: z.string(),
  item: z.string().optional(),
}) satisfies z.ZodType<JsonLdBreadcrumbItem>;

export const jsonLdBreadcrumbListSchema = z.object({
  "@context": z.string().optional(),
  "@type": z.literal("BreadcrumbList"),
  itemListElement: z.array(jsonLdBreadcrumbItemSchema),
}) satisfies z.ZodType<JsonLdBreadcrumbList>;

export const jsonLdThingSchema = z
  .object({
    "@context": z.string().optional(),
    "@type": z.string(),
    name: z.string().optional(),
    description: z.string().optional(),
    url: z.string().optional(),
    image: z.string().optional(),
  })
  .passthrough() satisfies z.ZodType<JsonLdThing>;

export type {
  JsonLdBreadcrumbItem,
  JsonLdBreadcrumbList,
  JsonLdThing,
} from "../types/structured-data";
```

## Examples

```typescript
// Source: https://schema.org/, https://developers.google.com/search/docs/appearance/structured-data
// Captured: 2026-05
import type {
  JsonLdBreadcrumbItem,
  JsonLdBreadcrumbList,
  JsonLdThing,
} from "../types/structured-data";

const breadcrumbHome = {
  "@type": "ListItem",
  position: 1,
  name: "Home",
  item: "https://open-types.dev/",
} as const satisfies JsonLdBreadcrumbItem;

const breadcrumbBlog = {
  "@type": "ListItem",
  position: 2,
  name: "Blog",
  item: "https://open-types.dev/blog",
} as const satisfies JsonLdBreadcrumbItem;

const breadcrumbCurrent = {
  "@type": "ListItem",
  position: 3,
  name: "Why we built OpenTypes",
} as const satisfies JsonLdBreadcrumbItem;

export const jsonLdBreadcrumbItemExamples = {
  home: breadcrumbHome,
  section: breadcrumbBlog,
  currentWithoutItem: breadcrumbCurrent,
} as const;

export const jsonLdBreadcrumbListExamples = {
  standard: {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    itemListElement: [breadcrumbHome, breadcrumbBlog, breadcrumbCurrent],
  } satisfies JsonLdBreadcrumbList,
  twoLevel: {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    itemListElement: [breadcrumbHome, breadcrumbBlog],
  } satisfies JsonLdBreadcrumbList,
  noContext: {
    "@type": "BreadcrumbList",
    itemListElement: [breadcrumbHome],
  } satisfies JsonLdBreadcrumbList,
} as const;

export const jsonLdThingExamples = {
  organization: {
    "@context": "https://schema.org",
    "@type": "Organization",
    name: "OpenTypes",
    description: "Community-curated TypeScript type registry.",
    url: "https://open-types.dev",
    image: "https://open-types.dev/og-image.png",
    sameAs: ["https://github.com/marcotisi/opentypes"],
  } satisfies JsonLdThing,
  article: {
    "@context": "https://schema.org",
    "@type": "Article",
    name: "Why we built OpenTypes",
    description: "Origin story for the OpenTypes registry.",
    url: "https://open-types.dev/blog/why",
    author: { "@type": "Person", name: "Marco Tisi" },
    datePublished: "2026-05-16",
  } satisfies JsonLdThing,
  product: {
    "@context": "https://schema.org",
    "@type": "Product",
    name: "Premium Widget",
    description: "A high-quality widget.",
    image: "https://cdn.example.com/products/widget.jpg",
    offers: { "@type": "Offer", price: "29.99", priceCurrency: "USD" },
  } satisfies JsonLdThing,
  minimal: { "@type": "Thing" } satisfies JsonLdThing,
} as const;
```