MERCHANTS.JSON: DAS DATENMODELL ALS NERVENSYSTEM

Die meisten Shop- und Vergleichssysteme haben kein Datenmodell. Sie haben Spuren eines Datenmodells: eine Tabelle im CMS, ein Feed für die Preisvergleiche, ein JSON-LD-Snippet im Template, eine Versandseite als Fließtext. Vier Orte, vier Wahrheiten.

Solange die Seite klein ist, merkt das niemand. Sobald das System skaliert, widersprechen sich die Orte. Die Rückgabefrist im Markup sagt 30 Tage, die Hilfeseite sagt 14. Der Preis im Feed ist von gestern.

Die These dieses Beitrags: Ein skalierendes Händlersystem braucht genau eine kanonische Datei, hier merchants.json genannt, und alles andere ist Projektion. Markup, Seiten und Feeds werden aus ihr erzeugt, nie von Hand gepflegt.

WARUM DAS MARKUP NICHT DIE QUELLE SEIN DARF

Strukturierte Daten werden oft als SEO-Aufgabe behandelt: Snippet schreiben, Rich Results Test grün, fertig. Google beschreibt die Rolle anders. In der Einführung zu strukturierten Daten empfiehlt Google JSON-LD und verlangt, dass das Markup den Inhalt der Seite beschreibt, auf der es steht. Angaben zu Informationen, die Nutzer auf der Seite nicht sehen, sollst du nicht auszeichnen, auch wenn sie stimmen.

Das ist eine Architekturvorgabe. Wenn Markup und sichtbarer Text dasselbe sagen müssen, dürfen sie nicht aus zwei Quellen kommen. Sie müssen aus derselben Quelle gerendert werden. Wer das Markup separat pflegt, baut den Widerspruch ein.

Dazu kommt: Laut der Organization-Dokumentation von Google gibt es keine Garantie, dass Features auf Basis strukturierter Daten in den Suchergebnissen erscheinen. Markup ist also kein Hebel, den man zieht. Es ist eine Schnittstelle, die stimmen muss.

MACHINE NOTE Das Markup ist kein Inhalt. Es ist ein Export.

DIE VIER ENTITÄTEN

Ein Händlermodell kommt mit vier Entitäten aus. Die Grenzen zwischen ihnen folgen den Typen, die schema.org und Google ohnehin verwenden.

Merchant. Die Organisation, die verkauft. schema.org/Organization bringt dafür eine ganze Reihe eindeutiger Kennungen mit: vatID, iso6523Code, leiCode, duns, globalLocationNumber. Die Seite empfiehlt ISO-6523-Codes gegenüber reinen Steuernummern, weil sie eindeutiger sind. Über sameAs verweist du auf Referenzseiten, die die Identität belegen, etwa einen Wikidata-Eintrag oder die offizielle Website. Google rät, den spezifischsten Subtyp zu wählen, für E-Commerce ausdrücklich OnlineStore statt OnlineBusiness.

Product. Das Ding, unabhängig davon, wer es verkauft. schema.org/Product trennt drei Kennungen, die in vielen Systemen durcheinandergehen: gtin (8, 12, 13 oder 14 Ziffern mit gültiger GS1-Prüfziffer), mpn (die Teilenummer des Herstellers) und sku (die Kennung des Händlers). Varianten hängen über isVariantOf an einer ProductGroup, die zugleich beschreibt, in welchen Dimensionen sich die Varianten unterscheiden.

Offer. Die Verbindung aus Merchant und Product zu einem Preis. schema.org/Offer führt seller, price, priceCurrency (nach ISO 4217, also EUR, nicht €), availability, priceValidUntil und shippingDetails. Für Merchant Listings verlangt die Google-Dokumentation zu Merchant Listings beim Produkt name, image und offers, beim Angebot Preis und Währung. Ein AggregateOffer reicht dort nicht, weil der Händler selbst Verkäufer sein muss.

Policy. Rückgabe und Versand. Hier liegt der größte Hebel für ein kanonisches Modell. Google empfiehlt laut Merchant-Listing-Seite, eine globale Rückgaberichtlinie auf Organization-Ebene zu hinterlegen und auf Angebotsebene nur dann eine eigene anzugeben, wenn einzelne Produkte abweichen. Die Angebotsebene unterstützt nur einen Teil der Felder, und du kannst die globale Richtlinie per @id referenzieren. Auf der Organization-Seite nennt Google dafür hasMerchantReturnPolicy, hasShippingService und hasMemberProgram.

DIE MAPPING-MATRIX

Das folgende Gerüst ist ein Beispiel, kein Standard. Es zeigt, wie du Felder im eigenen Modell an eine Entität, ein schema.org-Ziel und ein Gate bindest. Der eigene Blickwinkel liegt in der letzten Spalte: Jedes Feld bekommt eine Prüfregel, bevor es irgendwo erscheint.

Feld in merchants.json	schema.org-Ziel	Ebene	Gate im Build
merchant.id	@id	Organization	eindeutig, stabile URI, nie neu vergeben
merchant.legal.vat	vatID / iso6523Code	Organization	Format mit Länderpräfix
merchant.refs[]	sameAs	Organization	jede URL erreichbar
product.gtin	gtin	Product	8/12/13/14 Ziffern, Prüfziffer gültig
product.sku / product.mpn	sku / mpn	Product	getrennt geführt, nie vermischt
product.group	isVariantOf	Product	Gruppe existiert im Modell
offer.price	price + priceCurrency	Offer	Zahl > 0, Währung aus ISO-4217-Liste
offer.validUntil	priceValidUntil	Offer	Datum liegt in der Zukunft
policy.returns	hasMerchantReturnPolicy	Organization, Offer nur bei Abweichung	genau eine globale Definition

Die Ebenen-Spalte ist der eigentliche Gewinn. Weil die globale Rückgaberichtlinie nur einmal existiert, kann sie sich nicht an zwei Stellen widersprechen.

MACHINE NOTE Eine Regel, ein Ort. Alles andere ist Kopie.

DAS MODELL ERZWINGEN STATT HOFFEN

Ein kanonisches Modell ist nur so gut wie seine Durchsetzung. Dafür gibt es ein Werkzeug, das genau diesen Zweck hat. Die JSON-Schema-Spezifikation liegt aktuell in Version 2020-12 vor und besteht aus zwei Teilen: Core legt die Grundlage, Validation definiert die Prüf-Keywords. Damit beschreibst du merchants.json formal: Pflichtfelder, Typen, Formate, erlaubte Werte. Der Build bricht ab, wenn ein Datensatz das Schema verletzt.

Ein Punkt verdient dabei Aufmerksamkeit. Das Datenmodell von schema.org ist bewusst nachsichtig. Properties dürfen mehrere Werte und mehrere erwartete Typen haben, Text wird oft akzeptiert, wo eigentlich ein Objekt erwartet wird, und die Zuordnungen gelten als Richtlinien, nicht als formale Regeln. Das ist für ein offenes Vokabular sinnvoll. Für dein eigenes Modell ist es gefährlich.

Daraus folgt eine klare Arbeitsteilung, die ich für robuste Systeme für richtig halte: streng nach innen, nachsichtig nach außen. Dein JSON Schema ist enger als schema.org. Es erlaubt keine Marke als Freitext, wenn du sie als Entität mit ID führen kannst, und keinen Preis als String mit Komma. Die Projektion nach schema.org darf dann gefahrlos die nachsichtige Seite des Vokabulars bedienen, weil die Daten vorher schon sauber sind.

DREI PROJEKTIONEN AUS EINER QUELLE

Aus merchants.json entstehen im Build drei Ausgaben:

1. Seiten. Händlerprofil, Produktseite, Vergleich. Der sichtbare Text zieht Preis, Frist und Versand aus denselben Feldern wie das Markup.
2. JSON-LD. Das Organization-Markup gehört laut Google auf die Startseite oder eine einzelne Seite, die die Organisation beschreibt, nicht auf jede Seite. Produktseiten tragen Product und Offer und verweisen per @id auf Händler und Richtlinie.
3. Feeds. Exporte für Preisvergleiche oder Partner nutzen dieselben Kennungen. GTIN, SKU und MPN bleiben getrennte Felder bis in den Export.

Eine Einschränkung gehört dazu: Merchant Listings sind laut Google für Seiten gedacht, auf denen man direkt beim Händler kaufen kann. Ein Vergleichssystem, das nur auf Shops verlinkt, projiziert dieselben Daten, aber in einen anderen Markup-Typ. Das Modell bleibt gleich, die Projektion ändert sich.

MACHINE NOTE Die Seite ist Ausgabe. Die Datei ist das System.

OPERATOR CHECKLIST: MERCHANTS.JSON

• Lege vier Entitäten fest: Merchant, Product, Offer, Policy. Jede bekommt eine stabile ID.
• Führe GTIN, MPN und SKU als getrennte Felder und prüfe die GTIN-Prüfziffer im Build.
• Halte Rückgabe- und Versandregeln einmal global auf Händlerebene, Abweichungen nur pro Angebot.
• Beschreibe die Datei mit JSON Schema 2020-12 und lass den Build bei Verstößen abbrechen.
• Rendere Markup und sichtbaren Text aus denselben Feldern, nie getrennt gepflegt.
• Setze Organization-Markup nur auf die Start- oder Über-uns-Seite, Product und Offer auf die Produktseiten.
• Prüfe vor der Projektion, ob die Seite kaufbar ist oder nur verlinkt, und wähle danach den Markup-Typ.

FINAL THESIS

Wer strukturierte Daten pro Seite bastelt, pflegt Widersprüche in Serie. Ein kanonisches Händlermodell mit strengem Schema macht Markup, Seiten und Feeds zu Ableitungen derselben Wahrheit. Das Nervensystem ist die Datei, nicht das Template.