astro-structured-datav2.4.1

CASOON Open Source

Rich results, checked before you ship.

Put a component on the page and pass the data it already has. astro-structured-data writes the schema.org JSON-LD and meta tags that search engines read, and stops the build when the data would not be valid.

npm install @casoon/astro-structured-data
pnpm add @casoon/astro-structured-data
yarn add @casoon/astro-structured-data
MITnpm 2.4.1Astro 5 · 6 · 70 kB client JS
Terminal: a blog post page uses ArticleSchema with title 'Hello, Astro', description, datePublished 2026-10-01, author Ada Lovelace, an image and the publisher. astro build builds the page. The generated head contains canonical, description, author, og:title, og:description, og:url, og:image, og:site_name, og:type article, article:published_time, article:modified_time and the twitter tags with summary_large_image. The JSON-LD is a BlogPosting with headline, dates, mainEntityOfPage, author, publisher and image. With datePublished changed to 01.10.2026 the build stops: '<ArticleSchema> on /blog/hello-astro/ received invalid props: Must be an ISO 8601 date (YYYY-MM-DD) or date-time, or a Date, at datePublished'. On narrow screens the meta tags are left out.

What it is for

From the data on your page to a richer search result

Dates, prices, ratings and venues only show up in search when the page describes them as schema.org data. The components turn your props into exactly that.

Illustration with the data of three examples from the showcase. Whether and how a rich result appears is decided by the search engine.

Why it exists

How it works

Props in, JSON-LD and meta tags out

Each component validates its props and writes a JSON-LD block. Optionally, all schemas of a page are merged into one @graph, and canonical, Open Graph and Twitter tags are derived from the same data. Nothing is added to the JavaScript your visitors download.

How astro-structured-data turns props into JSON-LD and meta tagsYou pass your data as props to a schema component; integration options such as the site URL, a default publisher or brand fill in the rest. Each component validates its props against its Zod schema. Invalid data stops the build with the component, the page and the field. Valid data becomes schema.org JSON-LD, written as one script per schema. After the page has rendered, a middleware merges all schemas into one @graph block when useGraph is on and derives canonical, Open Graph and Twitter tags when generateMeta is on. After astro build, every JSON-LD block is checked for valid JSON and missing recommended fields.How astro-structured-data turns props into JSON-LD and meta tagsYour projectIntegrationYour pageProps → Valid?Options → Valid?Valid? → Build stops: noValid? → JSON-LD: yesJSON-LD → JSON-LD scriptJSON-LD → MiddlewareMiddleware → Meta tags: generateMetaMiddleware → JSON-LD script: useGraphJSON-LD script → Build check: astro buildnoyesgenerateMetauseGraphastro buildProps – <ArticleSchema …>Props<ArticleSchema …>Options – site, publisher, brandOptionssite, publisher, brandValid? – Zod schemaValid?Zod schemaBuild stops – page, fieldBuild stopspage, fieldJSON-LDJSON-LDMiddleware – after renderingMiddlewareafter renderingJSON-LD script – or one @graphJSON-LD scriptor one @graphMeta tags – canonical, OG, TwitterMeta tagscanonical, OG, TwitterBuild check – JSON, recommendedBuild checkJSON, recommended
How astro-structured-data turns props into JSON-LD and meta tagsYou pass your data as props to a schema component; integration options such as the site URL, a default publisher or brand fill in the rest. Each component validates its props against its Zod schema. Invalid data stops the build with the component, the page and the field. Valid data becomes schema.org JSON-LD, written as one script per schema. After the page has rendered, a middleware merges all schemas into one @graph block when useGraph is on and derives canonical, Open Graph and Twitter tags when generateMeta is on. After astro build, every JSON-LD block is checked for valid JSON and missing recommended fields.How astro-structured-data turns props into JSON-LD and meta tagsYour projectIntegrationYour pageProps → Valid?Options → Valid?Valid? → Build stops: noValid? → JSON-LD: yesJSON-LD → JSON-LD scriptJSON-LD → MiddlewareMiddleware → Meta tags: generateMetaMiddleware → JSON-LD script: useGraphJSON-LD script → Build check: astro buildnoyesgenerateMetauseGraphastro buildProps – <ArticleSchema …>Props<ArticleSchema …>Options – site, publisher, brandOptionssite, publisher, brandValid? – Zod schemaValid?Zod schemaBuild stops – page, fieldBuild stopspage, fieldJSON-LDJSON-LDMiddleware – after renderingMiddlewareafter renderingJSON-LD script – or one @graphJSON-LD scriptor one @graphMeta tags – canonical, OG, TwitterMeta tagscanonical, OG, TwitterBuild check – JSON, recommendedBuild checkJSON, recommended
How astro-structured-data turns props into JSON-LD and meta tagsYou pass your data as props to a schema component; integration options such as the site URL, a default publisher or brand fill in the rest. Each component validates its props against its Zod schema. Invalid data stops the build with the component, the page and the field. Valid data becomes schema.org JSON-LD, written as one script per schema. After the page has rendered, a middleware merges all schemas into one @graph block when useGraph is on and derives canonical, Open Graph and Twitter tags when generateMeta is on. After astro build, every JSON-LD block is checked for valid JSON and missing recommended fields.How astro-structured-data turnsprops into JSON-LD and meta tagsProps → Valid?Options → Valid?Valid? → Build stops: noValid? → JSON-LD: yesJSON-LD → JSON-LD scriptJSON-LD → MiddlewareMiddleware → Meta tags: generateMetaMiddleware → JSON-LD script: useGraphJSON-LD script → Build check: astro buildnoyesgenerateMetauseGraphastro buildProps – <ArticleSchema …>Props<ArticleSchema…>Options – site, publisher, brandOptionssite, publisher,brandValid? – Zod schemaValid?Zod schemaBuild stops – page, fieldBuild stopspage, fieldJSON-LDJSON-LDMiddleware – after renderingMiddlewareafter renderingJSON-LD script – or one @graphJSON-LDscriptor one @graphMeta tags – canonical, OG, TwitterMeta tagscanonical, OG,TwitterBuild check – JSON, recommendedBuild checkJSON,recommended
How astro-structured-data turns props into JSON-LD and meta tagsYou pass your data as props to a schema component; integration options such as the site URL, a default publisher or brand fill in the rest. Each component validates its props against its Zod schema. Invalid data stops the build with the component, the page and the field. Valid data becomes schema.org JSON-LD, written as one script per schema. After the page has rendered, a middleware merges all schemas into one @graph block when useGraph is on and derives canonical, Open Graph and Twitter tags when generateMeta is on. After astro build, every JSON-LD block is checked for valid JSON and missing recommended fields.How astro-structured-data turnsprops into JSON-LD and meta tagsProps → Valid?Options → Valid?Valid? → Build stops: noValid? → JSON-LD: yesJSON-LD → JSON-LD scriptJSON-LD → MiddlewareMiddleware → Meta tags: generateMetaMiddleware → JSON-LD script: useGraphJSON-LD script → Build check: astro buildnoyesgenerateMetauseGraphastro buildProps – <ArticleSchema …>Props<ArticleSchema…>Options – site, publisher, brandOptionssite, publisher,brandValid? – Zod schemaValid?Zod schemaBuild stops – page, fieldBuild stopspage, fieldJSON-LDJSON-LDMiddleware – after renderingMiddlewareafter renderingJSON-LD script – or one @graphJSON-LDscriptor one @graphMeta tags – canonical, OG, TwitterMeta tagscanonical, OG,TwitterBuild check – JSON, recommendedBuild checkJSON,recommended
Validation rulesMeta tagsGraph mode

Components

One component for each kind of page

Blogs, shops, local businesses, events, job boards: each component knows which fields its rich result needs. The generic <Schema> covers any other schema.org type.

Content

Shops and apps

Businesses

Site structure

Astro components, one per schema type plus generic and graph
18
Zod schemas for content collections and forms
16
tests, including real static, dev and SSR builds
277
client JavaScript added to your pages
0 kB

Quickstart

Register the integration once, then put the components on your pages. The documentation covers every component, prop and option.

  1. Install the package and add structuredData() to the integrations in astro.config.mjs, with site set.
  2. Import a component from @casoon/astro-structured-data/components and pass your data as props.
  3. Run astro build: wrong data stops the build, missing recommended fields are listed.
Read the documentation
src/layouts/Post.astroPage
---
import { ArticleSchema } from '@casoon/astro-structured-data/components';
const { post } = Astro.props;
---
<ArticleSchema
  title={post.data.title}
  description={post.data.description}
  datePublished={post.data.date}
  authorName={post.data.author}
  imageUrl={post.data.cover}
/>

New in v2.4.1

Changelog →

Frequently asked questions

What happens if I pass invalid data to a component?

The build fails with the component, the page and the offending field, for example a date that is not ISO 8601 or a currency that is not an ISO 4217 code. The markup never reaches production silently wrong.

Does this add any JavaScript to the pages my visitors load?

No. Every component runs at build time (or on the server in SSR) and only writes a JSON-LD script tag and meta tags into the HTML.

What if I leave out a field Google recommends but does not require?

The build still succeeds. After astro build, the integration lists each missing recommended field once per type, so you can decide whether to add it.

Can I combine several schemas on one page into a single JSON-LD block?

Yes. With useGraph set, all schemas of a page are merged into one @graph block wherever the SchemaGraph component is placed, instead of one script tag per component.

Which Astro and Node versions are supported?

Astro 5, 6 and 7, with Node 18 or later. The compatibility table in the README lists which package version matches which Astro range.