useSchemaOrg() · Unhead

[Unhead Home](https://unhead.unjs.io/ "Home")

- [Docs](https://unhead.unjs.io/docs/nuxt/head/guides/get-started/overview)
- [Tools](https://unhead.unjs.io/tools)
- [Learn](https://unhead.unjs.io/learn/guides/what-is-capo)

[Releases](https://unhead.unjs.io/releases)

Search…```k`` /`

[Unhead on GitHub](https://github.com/unjs/unhead)

[User Guides](https://unhead.unjs.io/docs/nuxt/head/guides/get-started/overview)

[API](https://unhead.unjs.io/docs/nuxt/head/api/get-started/overview)

[Releases](https://unhead.unjs.io/docs/nuxt/releases/v3)

Nuxt

- [Switch to Nuxt](https://unhead.unjs.io/docs/nuxt/schema-org/api/composables/use-schema-org)
- [Switch to TypeScript](https://unhead.unjs.io/docs/typescript/schema-org/api/composables/use-schema-org)
- [Switch to Vue](https://unhead.unjs.io/docs/vue/schema-org/api/composables/use-schema-org)
- [Switch to React](https://unhead.unjs.io/docs/react/schema-org/api/composables/use-schema-org)
- [Switch to Svelte](https://unhead.unjs.io/docs/svelte/schema-org/api/composables/use-schema-org)
- [Switch to Solid.js](https://unhead.unjs.io/docs/solid-js/schema-org/api/composables/use-schema-org)
- [Switch to Angular](https://unhead.unjs.io/docs/angular/schema-org/api/composables/use-schema-org)

v3 (stable)

Schema.org

- [Discord Support](https://discord.com/invite/275MBUBvgP)

- Composables
  - [`useSchemaOrg()`](https://unhead.unjs.io/docs/nuxt/schema-org/api/composables/use-schema-org)
- Nodes
  - [Article](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/article)
  - [Book Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/book)
  - [Breadcrumb Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/breadcrumb)
  - [Comment Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/comment)
  - [Course Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/course)
  - [Dataset Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/dataset)
  - [Event Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/event)
  - [Food Establishment Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/food-establishment)
  - [HowTo](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/how-to)
  - [Image Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/image)
  - [ItemList](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/item-list)
  - [JobPosting](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/job-posting)
  - [LocalBusiness](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/local-business)
  - [Movie Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/movie)
  - [Music Album Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/music-album)
  - [Music Group Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/music-group)
  - [Music Playlist Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/music-playlist)
  - [Music Recording Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/music-recording)
  - [Organization](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/organization)
  - [Person Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/person)
  - [Podcast Episode Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/podcast-episode)
  - [Podcast Season Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/podcast-season)
  - [Podcast Series Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/podcast-series)
  - [Product Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/product)
  - [Question Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/question)
  - [Recipe Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/recipe)
  - [Service Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/service)
  - [SoftwareApplication](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/software-app)
  - [TV Episode Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/tv-episode)
  - [TV Season Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/tv-season)
  - [TV Series Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/tv-series)
  - [Video Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/video)
  - [WebPage Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/webpage)
  - [WebSite Schema](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/website)

Composables

# useSchemaOrg()

[Copy for LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/schema-org/5.api/0.composables/0.use-schema-org.md)

Last updated Apr 5, 2026 by [Harlan Wilton](https://github.com/harlan-zw) in [docs: documentation content audit and formatting improvements (#718)](https://github.com/unjs/unhead/pull/718).

On this page

- [Example](#example)
- [Input](#input)
- [Options](#options)
- [Entry API](#entry-api)
- [XSS safety](#xss-safety)
- [Common Questions](#common-questions)
- [See Also](#see-also)

The `useSchemaOrg()` composable is the primary way to add Schema.org structured data to your pages.

**Quick Start:**

```
useSchemaOrg([
  defineWebSite({ name: 'My Site' }),
  defineWebPage({ name: 'Home' })
])
```

```
useSchemaOrg(input, options)
```

## [Example](#example)

Define an article with structured data for Google Rich Results:

```
useSchemaOrg([
  defineArticle({
    headline: 'My Blog Post',
    image: '/images/post.jpg',
    datePublished: new Date(),
  })
])
```

## [Input](#input)

The input accepts an array of Schema.org node definitions created using `define*` functions:

```
type SchemaOrgInput = SchemaOrgNode | SchemaOrgNode[]
```

Available node functions include:

- `defineWebSite()` - Site-level metadata
- `defineWebPage()` - Page-level metadata
- `defineArticle()` - Blog posts and articles
- `defineProduct()` - E-commerce products
- `defineOrganization()` - Company/organization info
- `definePerson()` - Author/person profiles
- `defineBreadcrumb()` - Navigation breadcrumbs
- And [many more](https://unhead.unjs.io/docs/schema-org/api/schema/article)

## [Options](#options)

The second parameter to `useSchemaOrg` is the `HeadEntryOptions`. This allows you to apply options to the entry, meaning all tags that exist within the `input`.

```
export interface HeadEntryOptions {
  processTemplateParams?: boolean
  tagPriority?: number | 'critical' | 'high' | 'low' | \`before:${string}\` | \`after:${string}\`
  tagPosition?: 'head' | 'bodyClose' | 'bodyOpen'
  transform?: (input: unknown) => unknown
  head?: Unhead
}
```

## [Entry API](#entry-api)

The `useSchemaOrg` composable returns an API to manage the lifecycle of the schema entry. Using this you can either `patch` or `dispose` of the entry.

```
const schemaEntry = useSchemaOrg([
  defineWebPage({ name: 'My Page' })
])

// removes the schema nodes
schemaEntry.dispose()
```

## [XSS safety](#xss-safety)

The `useSchemaOrg` function only applies minimal sanitization on input to improve the developer experience.

Be careful, **do not** use this function with any unknown / third party input, that isn't sanitised. It is not possible to guarantee that the output is safe when dealing with unknown input.

If you need XSS safety, sanitise your input or look at using the [useSeoMeta](https://unhead.unjs.io/docs/head/api/composables/use-seo-meta) or [useHeadSafe](https://unhead.unjs.io/docs/head/api/composables/use-head-safe) composables instead. If you're having issues working around the default nodes, you should disable them.

```
// nuxt.config.ts
export default defineNuxtConfig({
  schemaOrg: {
    defaults: false
  }
})
```

## [Common Questions](#common-questions)

### [How do I add multiple schema types to a page?](#how-do-i-add-multiple-schema-types-to-a-page)

Pass an array to `useSchemaOrg()` - each item becomes a node in the graph.

```
useSchemaOrg([
  defineWebPage({ name: 'Product Page' }),
  defineProduct({ name: 'Widget', price: 29.99 }),
  defineBreadcrumb({
    itemListElement: [
      { name: 'Home', item: '/' },
      { name: 'Products', item: '/products' },
    ]
  })
])
```

### [Do I need to set @id manually?](#do-i-need-to-set-id-manually)

No, Unhead automatically generates unique IDs and links related nodes.

### [How does Schema.org get page metadata?](#how-does-schemaorg-get-page-metadata)

It automatically infers data from your `<head>` tags like `<title>`, meta description, canonical URL, and og:image.

## [See Also](#see-also)

- [useHead()](https://unhead.unjs.io/docs/head/api/composables/use-head) - General head management
- [useSeoMeta()](https://unhead.unjs.io/docs/head/api/composables/use-seo-meta) - SEO meta tag management
- [Schema.org Nodes](https://unhead.unjs.io/docs/schema-org/api/schema/) - All available schema types

[Edit this page](https://github.com/unjs/unhead/edit/main/docs/schema-org/5.api/0.composables/0.use-schema-org.md)

[Markdown For LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/schema-org/5.api/0.composables/0.use-schema-org.md)

Did this page help you?

[Site Search Add SearchAction to WebSite schema with defineSearchAction(). Enable Google Sitelinks Searchbox for your site in search results.](https://unhead.unjs.io/docs/schema-org/guides/recipes/site-search) [Article Implement Article structured data with Unhead. JSON-LD examples for BlogPosting, NewsArticle, TechArticle with datePublished and author markup.](https://unhead.unjs.io/docs/schema-org/api/schema/article)

On this page

- [Example](#example)
- [Input](#input)
- [Options](#options)
- [Entry API](#entry-api)
- [XSS safety](#xss-safety)
- [Common Questions](#common-questions)
- [See Also](#see-also)

[GitHub](https://github.com/unjs/unhead) [ Discord](https://discord.com/invite/275MBUBvgP)

[ /llms.txt](https://unhead.unjs.io/llms.txt)

[Part of the UnJS ecosystem](https://unjs.io/)

### Head Management

- [Getting Started](https://unhead.unjs.io/docs/nuxt/head/guides/get-started/overview)
- [useHead](https://unhead.unjs.io/docs/nuxt/head/api/composables/use-head)
- [useSeoMeta](https://unhead.unjs.io/docs/nuxt/head/api/composables/use-seo-meta)
- [useHeadSafe](https://unhead.unjs.io/docs/nuxt/head/api/composables/use-head-safe)
- [useScript](https://unhead.unjs.io/docs/nuxt/head/api/composables/use-script)

### Schema.org

- [Getting Started](https://unhead.unjs.io/docs/nuxt/schema-org/guides/get-started/overview)
- [useSchemaOrg](https://unhead.unjs.io/docs/nuxt/schema-org/api/composables/use-schema-org)
- [Nodes](https://unhead.unjs.io/docs/nuxt/schema-org/guides/core-concepts/nodes)
- [Recipes](https://unhead.unjs.io/docs/nuxt/schema-org/guides/recipes/identity)

### Guides

- [Titles](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/titles)
- [Streaming SSR](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/streaming)
- [DOM Events](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/dom-event-handling)
- [Plugins](https://unhead.unjs.io/docs/nuxt/head/guides/plugins/template-params)

### Tools

- [Meta Tag Generator](https://unhead.unjs.io/tools/meta-tag-generator)
- [OG Image Generator](https://unhead.unjs.io/tools/og-image-generator)
- [Schema.org Generator](https://unhead.unjs.io/tools/schema-generator)
- [Capo.js Analyzer](https://unhead.unjs.io/tools/capo-analyzer)

### Articles

- [What is Capo.js?](https://unhead.unjs.io/learn/guides/what-is-capo)

### Research

- [State of <head> in 2026](https://unhead.unjs.io/learn/research/state-of-head-2026)
- [Streaming Head Performance](https://unhead.unjs.io/learn/research/streaming-head-performance)
- [Capo.js Performance Research](https://unhead.unjs.io/learn/research/capo-performance-research)

Copyright © 2025-2026 Harlan Wilton - [MIT License](https://github.com/unjs/unhead/blob/main/license)