Structured Data for Astro
Schema.org components directly in Astro – Article, FAQ, Product, Breadcrumb and more. Type-safe with schema-dts, integrated in two lines.
GitHubSchema.org components directly in Astro – Article, FAQ, Product, Breadcrumb and more. Type-safe with schema-dts, integrated in two lines.
npm install @casoon/astro-structured-dataWhat is @casoon/astro-structured-data?
A collection of Astro components that generate Schema.org JSON-LD for the most common page types. Type-safe with schema-dts, no boilerplate, no manual JSON.
The integration registers an Astro config with global defaults. Components read these defaults and render the finished <script type="application/ld+json"> tag – no manual JSON.stringify anymore. With generateMeta: true the integration also renders Open Graph, Twitter Card, canonical and hreflang tags automatically into <head>.
When do you need this?
Structured data improves rich results and AI visibility – when implemented correctly.
Article Pages with Rich Results
BlogPosting and NewsArticle markup for every article in your content collection – automatically populated with publisher data from the global configuration.
FAQ Sections for Google
FAQPage markup directly on landing pages and service pages – increases the chance of enhanced search results with expandable answers.
Local Business Pages
LocalBusiness schema with address, opening hours and GeoCoordinates for company websites that want to be visible in local search.
E-Commerce Product Pages
Product schema with price, availability and ratings enables product cards in Google Shopping and search results.
Integration in Two Steps
import structuredData from '@casoon/astro-structured-data';
export default defineConfig({
site: 'https://example.com',
integrations: [
structuredData({
defaultArticlePublisher: {
name: 'My Site',
logo: { '@type': 'ImageObject', url: 'https://example.com/logo.png' },
},
}),
],
}); ---
import { ArticleSchema, BreadcrumbSchema }
from '@casoon/astro-structured-data/components';
---
<ArticleSchema
title="My Article"
description="Short description"
datePublished="2025-01-01"
authorName="Jane Doe"
imageUrl="https://example.com/image.webp"
/>
<BreadcrumbSchema items={[
{ name: 'Home', url: 'https://example.com' },
{ name: 'Blog', url: 'https://example.com/blog/' },
]} />
Schema components are standard Astro components – usable in any .astro file.
Available Schema Components
All components are type-safe and render valid Schema.org JSON-LD.
ArticleSchema
BlogPosting or NewsArticle – headline, author, publisher with logo, image, published and modified date.
FAQSchema
FAQPage with Question/Answer pairs – shown directly in Google search results as rich results.
ProductSchema
Product with price, currency and availability. Brand, description and GTIN fields included.
BreadcrumbSchema
BreadcrumbList from a simple `items` array – or automatically from the URL path with AutoBreadcrumbSchema.
LocalBusinessSchema
LocalBusiness with address, opening hours, coordinates and contact details. Ideal for local SEO.
OrganizationSchema
Organization with logo, social links, address, phone and email. Builds on the global `defaultArticlePublisher`.
WebSiteSchema & more
WebSite, Event, ProfilePage, JobPosting, SoftwareApplication, CollectionPage – the complete Schema.org toolkit for Astro.
Schema Graph
With `useGraph: true` all schemas are merged into a single optimized `@graph` block – less HTTP overhead, cleaner entity linking.
What's under the hood?
More than just JSON.stringify – a well-thought-out integration into the Astro build process.
Type-safe with schema-dts
All Schema.org types come from `schema-dts` – TypeScript immediately reports missing required fields or incorrectly typed values.
Global Defaults
Define publisher, LocalBusiness and brand once in `astro.config.mjs` – all components use them as a fallback.
Dev Toolbar Integration
The Astro Dev Toolbar shows all rendered JSON-LD blocks of the current page in a dedicated panel – instantly validatable.
Zod Validation
The integration validates options in `astro.config.mjs` at build time with Zod. Invalid values produce clear error messages.
Automatic Meta Tags
With `generateMeta: true` the integration renders Open Graph, Twitter Card, canonical and hreflang tags automatically – no manual `<head>` work.
Why @casoon/astro-structured-data?
Maintaining structured data manually is error-prone – typos in @type, forgotten required fields, wrong date formats.
Zero Runtime Overhead
JSON-LD is rendered statically at build time. No schema processing code reaches the browser.
Astro-Native
Standard `.astro` components. No custom renderer, no framework lock-in, no separate tooling required.
Schema.org Compliant
All types are based on `schema-dts` – the official TypeScript typings for Schema.org.
MIT License
Open source, free, no dependency on external APIs or paid services.
Complement: Build-Time Validation with post-audit
structured-data generates the JSON-LD – post-audit validates it at build time. With structured_data: { check_json_ld: true }, @casoon/astro-post-audit validates syntax, semantics and cross-page consistency of JSON-LD blocks.
The CASOON Ecosystem
structured-data is part of a toolchain of open source plugins – all MIT-licensed, all built for Astro.
@casoon/astro-post-audit
Checks canonical, headings, meta tags, Open Graph, JSON-LD and accessibility directly at build time.
@casoon/astro-site-files
Generates robots.txt, sitemap.xml with i18n hreflang, llms.txt and security.txt at build time.
@casoon/astro-speed-measure
Measures build performance at integration, Vite plugin and page level.
astro-v6-template
Monorepo starter with all CASOON plugins pre-configured. Cloudflare Workers, i18n, Playwright.
Frequently Asked Questions
What is JSON-LD and why do I need it in Astro?
JSON-LD is the format recommended by Google for structured data. It tells search engines and AI systems what a page means – article, product, FAQ, local business. Implemented correctly, it improves rich results in search and the likelihood of being cited by AI searches.
What is the difference between schema components and the generic Schema import?
The specific components (ArticleSchema, FAQSchema, etc.) provide typed props for the most common fields and automatically populate publisher defaults. The generic `Schema` component accepts any schema-dts object and is suitable for edge cases.
What does @graph mode do?
With `useGraph: true`, all schema components register their data via `Astro.locals`. At the end, a `SchemaGraph` component renders everything as a single `@graph` block. This reduces redundant `@context` entries and enables cleaner entity linking via `@id` references.
Does this package work together with post-audit?
Yes. `@casoon/astro-post-audit` checks after the build whether JSON-LD is present and syntactically correct. Both packages are part of the CASOON Astro ecosystem and are designed to work together.
Which Astro versions are supported?
Astro 5.x, 6.x and 7.x. The package uses the `astro:config:setup` hook API and Vite virtual modules – both stable Astro APIs.
Is the package free?
Yes. @casoon/astro-structured-data is published under the MIT license and is fully open source.