Strukturierte Daten
für Astro
Typisierte Astro-Komponenten für JSON-LD. Seit Version 2 prüft jede Komponente ihre Props – ungültige Daten brechen den Build ab, statt online zu gehen.
Kein handgeschriebenes JSON im Template.
Die Integration hält globale Defaults wie Publisher, Marke oder Firmensitz. Die Komponenten übernehmen sie, prüfen ihre Props mit Zod und rendern das fertige <script type="application/ld+json">. Eine Middleware ergänzt nach dem Rendern Meta-Tags und auf Wunsch einen gemeinsamen @graph-Block.
- 01Typisiert — Prop-Typen und ein Zod-Schema für jeden Schema-Typ
- 02Strikt — ungültige oder unbekannte Props brechen den Build ab
- 03Keine erfundenen Werte — fehlende Pflichtangaben werden gemeldet, nicht aufgefüllt
- 04Meta-Tags —
generateMetaleitet Open Graph, Twitter Cards, Canonical und hreflang ab
Drei Schritte bis zum ersten Schema.
- 1Installieren
Paket hinzufügen
Abhängigkeiten sind nur
schema-dtsundzod. Peer Dependency: Astro 5, 6 oder 7.npm install @casoon/astro-structured-data - 2Konfigurieren
Integration eintragen
siteodersiteUrlist Pflicht. Unbekannte Optionen brechen den Build ab.integrations: [structuredData()] - 3Einbinden
Komponente setzen
Normale
.astro-Komponenten mit typisierten Props – im Layout oder direkt auf der Seite.<ArticleSchema title="…" />
Was Version 2 prüft.
Props gegen Zod
Jede Komponente prüft ihre Props beim Rendern. Ein Verstoß beendet den Build – im SSR die Anfrage – mit Komponente, Seite und Feld.
Unbekannte Props
Tippfehler fallen auf, statt Daten still zu verlieren. Nur Astro-Attribute wie slot und data-astro-* werden ignoriert.
Formate
Datum und Dauer nach ISO 8601, Währungen nach ISO 4217, URLs absolut oder root-relativ, keine leeren Textfelder.
Abhängige Felder
price nur mit priceCurrency, ratingValue nur mit reviewCount, ein Enddatum nie vor dem Startdatum.
Regeln pro Seite
Im Graph-Modus braucht jede Seite mit Schemas genau ein <SchemaGraph />. Sitemap-Hinweise aller Schemas einer Seite müssen übereinstimmen.
Prüfung nach dem Build
Jedes JSON-LD im Output wird geparst. Ungültiges JSON bricht ab, fehlende empfohlene Felder erscheinen als Warnung.
Konfiguration, Komponente, Fehlermeldung.
// astro.config.mjs
import { defineConfig } from 'astro/config';
import structuredData from '@casoon/astro-structured-data';
export default defineConfig({
site: 'https://example.com',
integrations: [
structuredData({
generateMeta: true,
siteName: 'Example',
locale: 'de_DE',
defaultArticlePublisher: {
name: 'Example GmbH',
logo: { url: 'https://example.com/logo.png' },
},
}),
],
});---
import { ArticleSchema, AutoBreadcrumbSchema }
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}
inLanguage="de"
/>
<AutoBreadcrumbSchema ignoreSegments={['en']} />$ astro build
[astro-structured-data] <EventSchema> on /events/meetup/
received invalid props:
✖ Must be an ISO 4217 currency code like "EUR"
→ at priceCurrency
[structured-data] Organization is missing recommended
field "sameAs" — add it for richer search results.Komponenten für die gängigen Seitentypen.
Artikel, FAQ, Rezept, Video
BlogPosting oder NewsArticle mit Autor, Serie und Lesezeit, FAQPage, Recipe mit Zutaten und Schritten, VideoObject mit Dauer und Upload-Datum.
Produkte und Listen
Product mit Angebot, Marke, GTIN, Bewertungen, Versand- und Rückgabebedingungen. CollectionPage für Kategorie- und Archivseiten.
Firma, Standort, Termine, Jobs
LocalBusiness mit Adresse und Öffnungszeiten, Organization, Event mit Präsenz-, Online- oder Hybrid-Ort, JobPosting inklusive Remote-Stellen.
Website, Seite, Profil, App
WebSite mit optionaler Sitelinks-Suche, WebPage für alles ohne spezielleren Typ, ProfilePage und SoftwareApplication.
Breadcrumbs
BreadcrumbList aus einem Array – oder AutoBreadcrumbSchema leitet sie aus dem URL-Pfad ab, mit eigenen Labels und ausgelassenen Sprachsegmenten.
Generisch und Graph
<Schema> gibt jedes schema.org-Objekt aus, ohne dessen Inhalt zu prüfen. <SchemaGraph /> markiert die Stelle für den gemeinsamen @graph-Block.
Vom Prop zum fertigen HTML.
- Beim Rendern
Komponente
Führt Props und globale Defaults zusammen, prüft sie mit dem Zod-Schema und erzeugt escaptes JSON-LD, aus dem Inhalte nicht ausbrechen können.
- Nach dem Rendern
Middleware
Sieht die vollständige Seite: setzt den
@graph-Block, fügt Meta-Tags in den<head>ein und prüft Regeln pro Seite. - Nach dem Build
Output-Prüfung
Parst jedes JSON-LD im erzeugten HTML. Ungültiges JSON bricht den Build ab, fehlende empfohlene Felder werden geloggt.
Rich-Result-Vorschau im Dev-Server.
Google-ähnliche Darstellung für Article, FAQ, Product, Breadcrumb, Event, JobPosting, LocalBusiness und SoftwareApplication.
Pflicht- und empfohlene Felder je Typ, direkt für die aktuelle Seite.
JSON-LD als Rohtext einblenden oder in die Zwischenablage kopieren.
Ein Klick öffnet validator.schema.org. Das Panel erscheint nur in astro dev.
Was das Paket nicht übernimmt.
Strukturierte Daten beschreiben eine Seite. Ob daraus ein Rich Result wird, entscheidet die Suchmaschine.
Keine Zusage für Rich Results
Das Paket erzeugt Markup nach schema.org und den Google-Richtlinien. Die Darstellung in der Suche liegt nicht in seiner Hand.
HTML wird gepuffert
Die Middleware braucht die vollständige Seite. HTML-Antworten werden deshalb nicht gestreamt.
`<Schema>` prüft nicht
Die generische Komponente verlangt nur @type und gibt das Objekt so aus, wie es übergeben wird.
Upgrade von 1.x
Version 2 bricht bei Daten ab, die 1.x still gerendert hat. Der erste Build nach dem Update listet alles, was anzupassen ist.
Häufige Fragen.
Was ist JSON-LD und wofür brauche ich es?
JSON-LD ist das von Google empfohlene Format für strukturierte Daten. Es beschreibt maschinenlesbar, was eine Seite enthält – einen Artikel, ein Produkt, eine FAQ oder ein Unternehmen. Suchmaschinen nutzen diese Angaben unter anderem für Rich Results.
Was hat sich mit Version 2.0 geändert?
Alle Daten werden streng validiert: ungültige oder unbekannte Props und Optionen brechen den Build ab. Fehlende Pflichtwerte wie der Name einer Organisation werden nicht mehr erfunden. Meta-Tags und der @graph-Block entstehen in einer Middleware nach dem Rendern. Version 2.0.1 behebt einen Fehler mit dem slot-Attribut.
Wie aufwendig ist das Upgrade von 1.x?
Ein Build zeigt jede ungültige Angabe mit Komponente, Seite und Feld. Typische Anpassungen: fehlende Namen ergänzen, baseSalary eine unit geben, employmentType, operatingSystem und applicationCategory explizit setzen und im Graph-Modus genau ein SchemaGraph im Layout behalten.
Was macht der @graph-Modus?
Mit useGraph: true fasst die Middleware alle Schemas einer Seite zu einem @graph-Block zusammen. Das spart wiederholte @context-Angaben und erlaubt Verknüpfungen über @id. SchemaGraph im Layout legt nur fest, an welcher Stelle der Block steht.
Kann ich die Zod-Schemas in Content Collections nutzen?
Ja. Alle Schemas sind unter @casoon/astro-structured-data/zod exportiert und ignorieren zusätzliche Frontmatter-Felder. Dazu kommt validateRecommended, das fehlende empfohlene Felder als Liste zurückgibt.
Wie berechne ich die Lesezeit für ArticleSchema?
calculateReadingTime aus @casoon/astro-structured-data/utils nimmt Text oder HTML und liefert wordCount, readingTimeMinutes und timeRequired im ISO-8601-Format, zum Beispiel PT4M. Standard sind 200 Wörter pro Minute.
Welche Astro-Versionen werden unterstützt?
Version 2.0 unterstützt Astro 5, 6 und 7 und setzt Node.js ab Version 18 voraus.
Arbeitet das Paket mit astro-post-audit und astro-site-files zusammen?
Ja. @casoon/astro-post-audit kann nach dem Build prüfen, ob JSON-LD vorhanden und gültig ist. @casoon/astro-site-files liest die Sitemap-Hinweise changefreq und priority, die jede Komponente als data-Attribut am Script-Tag ablegt.
Strukturierte Daten, geprüft beim Build.
Typisierte Komponenten, strenge Validierung, MIT-lizenziert.