Inhalt
Sie haben sich für Headless WordPress entschieden — und stehen jetzt vor der Frage, die in der Praxis am meisten Geld bewegt: Wie modellieren Sie Ihre Inhalte? Die Antwort lautet feldbasiert statt layoutbasiert. Konkret heisst das: ein Custom Post Type pro echtem Inhaltstyp, eine ACF Field Group pro Typ, alle exponierten Gruppen via show_in_graphql im Schema, und das gesamte Datenmodell per Local JSON in Git versioniert. Diese Entscheidungen treffen Sie einmal — und sie bestimmen danach, wie bequem Redakteure arbeiten und wie teuer eine spätere Migration wird.
Dieser Leitfaden ist kein weiteres generisches Dev-How-to. Davon gibt es englischsprachig hunderte. Er ist für die buyer-adjazente technische Leitung geschrieben, die verstehen will, warum ein Modell-Entscheid heute über das Budget von übermorgen entscheidet. Wo wir Mechanik nur streifen, verweisen wir auf die Sibling-Beiträge: wie Gutenberg-Blöcke im Headless-Frontend gerendert werden, WPGraphQL vs. REST API als Transport-Schicht und unser Überblick zu Headless WordPress. Dieser Beitrag füllt die Lücke dazwischen — das Datenmodell selbst.
Warum Content-Modeling über Editor-Komfort und Migrationskosten entscheidet
Das Datenmodell, das Sie heute festlegen, ist die teuerste Entscheidung im Headless-Projekt — teurer als Frontend-Framework oder Hosting. Es bestimmt, wie bequem Redakteure arbeiten und wie viel eine spätere Migration kostet. Felder, die früh sauber strukturiert sind, lassen sich verlustfrei umziehen; layoutverklebte Inhalte nicht.
Der Grund ist, dass Modell-Entscheidungen sticky sind. Sobald eine Field Group definiert ist, wird sie in Dutzende, hunderte oder tausende Beiträge geschrieben. Ein Feld nachträglich umzubenennen oder neu zu schneiden bedeutet, vorhandene Daten zu migrieren — und genau das ist später kaum noch sauber rückgängig zu machen. Was Sie zu Beginn an Disziplin investieren, sparen Sie hinten als vier- bis fünfstelliges Migrationsbudget.
Der zweite Hebel ist der menschliche. Ein schlecht geschnittenes Modell führt dazu, dass Redakteure es umgehen — sie kippen am Ende alles in einen einzigen WYSIWYG-Block, weil die strukturierten Felder zu umständlich sind. Damit verliert das Frontend genau die Struktur, für die Sie überhaupt auf Headless gewechselt sind: Es kann Inhalte nicht mehr typsicher und konsistent rendern. Strukturierte Felder sind portabel, layoutverklebte Inhalte sind es nicht — sie verursachen die grössten Stolperfallen bei der Headless-Migration und untergraben die Redaktions- und Editor-UX, die wir in eigenen Beiträgen vertiefen.
Das Datenmodell ist die teuerste Entscheidung im Headless-Projekt — teurer als Framework oder Hosting, weil es sich in jeden einzelnen Inhalt einbrennt.
Custom Post Types: ein Typ pro echtem Inhaltstyp
Legen Sie einen Custom Post Type pro semantisch eigenständigem Inhalt an — Projekt, Mitarbeiter, Standort —, nicht pro Seitenlayout. Die Faustregel: Wenn ein Inhalt eine eigene Liste, eigene Felder oder eine eigene URL-Logik hat, ist es ein CPT. Registrieren Sie CPTs mit show_in_graphql und einem expliziten graphql_single_name sowie graphql_plural_name — sonst fehlt der Typ im Schema.
Der häufigste Fehler ist die Verwechslung von Seite und Datentyp. Eine Seite ist kein CPT. Marketing-Seiten — Startseite, Leistungen, Über uns — bleiben pages. Nur wiederkehrende, gleichförmige Daten werden zu Custom Post Types: die Referenzprojekte, das Team, die Standorte, die Stellenangebote. Das Kriterium ist nicht das Aussehen, sondern die Struktur: eigene Archiv-Logik, eigene Feldstruktur oder eigene URL ergeben einen eigenen Typ.
Taxonomien behandeln Sie analog — für Filter und Navigation, etwa Projektkategorien oder Branchen, ebenfalls mit show_in_graphql. Seit ACF 6.1 lassen sich Custom Post Types und Taxonomien direkt in ACF anlegen und über Local JSON versionieren (Advanced Custom Fields, Local JSON). Das ist praktisch, weil so Inhaltstyp und Feldstruktur in derselben versionierten Quelle leben — und nicht in zwei getrennten Welten (Code für den CPT, Datenbank für die Felder) auseinanderdriften.
ACF Field Groups: wie viele pro Typ und wie schneiden Sie sie
Eine Field Group pro Inhaltstyp ist der Standard; mehrere nur, wenn unterschiedliche Location Rules oder unterschiedliche Redaktions-Rollen es erzwingen. Jede Gruppe braucht zwingend einen GraphQL Field Name und show_in_graphql=true — ohne beides erscheint sie nicht im Schema. Halten Sie Feldnamen stabil, denn sie werden zu GraphQL-Feldnamen.
Teilen Sie Field Groups nicht aus Ordnungssinn auf. Die Versuchung ist gross, einen CPT in „Basisdaten", „SEO" und „Sonstiges" zu splitten — aber jede zusätzliche Gruppe erhöht die Schema-Komplexität und das Risiko von Feldnamen-Kollisionen. Aufteilen lohnt sich nur, wenn eine Gruppe an einer anderen Stelle erscheinen soll (Location Rule) oder eine bestimmte Rolle sie bearbeitet, eine andere nicht. Sonst gilt: eine Gruppe pro Typ.
Der entscheidende Denkfehler, den wir in Audits immer wieder sehen: Feldnamen werden als beliebig behandelt. Sie sind es nicht. Ein Feldname ist ein API-Vertrag. Sobald das Frontend query { project { projectClient } } abfragt, bricht jedes Umbenennen die Queries — und bei einer Migration auch das Mapping der Altdaten. WPGraphQL for ACF bildet jede Field Group, die auf show_in_graphql gesetzt ist, im Schema ab (WPGraphQL for ACF, Dokumentation) — Feldnamen werden dabei zu GraphQL-Feldnamen, weshalb sie stabil bleiben müssen. Eine konsistente Namens-Konvention — snake_case mit Typ-Präfix, etwa project_client statt nur client — verhindert Schema-Kollisionen, sobald mehrere CPTs Felder mit ähnlicher Bedeutung tragen.
ACF bringt dafür reichlich Material mit: 35 Feldtypen in sechs Kategorien (Basic, Choice, Content, jQuery, Layout, Relational), darunter die Layout-Felder Flexible Content, Repeater, Group und Clone (Advanced Custom Fields, Feldtypen). Repeater wird im Schema zu einer Objektliste, Group zu einem verschachtelten Objekt — beides sauber abfragbar, solange die Gruppe exponiert ist.
Flexible Content vs. Inner Blocks: wann was?
Nutzen Sie ACF Flexible Content für strukturierte, klar definierte Seiten-Bausteine — Hero, Teaser-Reihe, CTA —, bei denen Sie das Set an Layouts kontrollieren wollen. Nutzen Sie Gutenberg-Blöcke, wenn Redakteure freien Fliesstext mit eingestreuten Elementen brauchen. Die Faustregel: Flexible Content ist ein kuratiertes Baukasten-System, Blöcke sind der offene Editor.
Der praktische Unterschied liegt im Frontend. Flexible Content liefert eine endliche, typsichere Liste von Layout-Bausteinen, die sich als GraphQL-Union abfragen lässt — das Frontend kennt jeden möglichen Baustein und rendert ihn deterministisch. Gutenberg-Blöcke geben der Redaktion mehr Freiheit, verlangen dafür aber eine komplexere Render-Schicht: Das Frontend muss beliebige Blockstrukturen parsen und abbilden. Wie das technisch sauber gelöst wird, behandeln wir separat in wie Gutenberg-Blöcke im Headless-Frontend gerendert werden — hier geht es nur um die Modellierungs-Entscheidung davor.
Der wichtigste Rat: Mischen Sie beide Ansätze nicht auf demselben Feld. Wer Flexible Content und Blöcke im gleichen Inhaltsfeld kombiniert, verdoppelt die Render-Logik im Frontend, ohne der Redaktion echten Mehrwert zu geben. Das eigentliche Entscheidungskriterium ist nüchtern: Wie viel gestalterische Freiheit braucht die Redaktion wirklich? Bei einem klar kuratierten Marketing-Auftritt ist das Baukasten-System fast immer die stabilere Wahl.
| Ansatz | Wann einsetzen | Editor-Erfahrung | GraphQL-Abbildung | Migrations-Risiko |
|---|---|---|---|---|
| Feste ACF Field Groups | Strukturierte Daten wie Projekt, Mitarbeiter, Standort | Klare, geführte Eingabemasken | Direkte Felder am Objekt-Typ | Niedrig — sauber portabel |
| ACF Flexible Content | Kuratierte Seiten-Baukästen mit festem Layout-Set | Baukasten mit kontrollierten Bausteinen | GraphQL-Union pro Layout | Mittel — Layout-Set ist Vertrag |
| Gutenberg-Blöcke / Inner Blocks | Freier redaktioneller Schreibfluss | Offener Editor, maximale Freiheit | Geparste Blockstruktur, komplexes Rendering | Höher — beliebige Struktur |
Wie exponiere ich ACF-Felder korrekt im GraphQL-Schema?
Felder erscheinen nicht automatisch im GraphQL-Schema — das ist Absicht, kein Fehler. Setzen Sie show_in_graphql auf Field-Group-Ebene und vergeben Sie GraphQL Field Names. WPGraphQL for ACF bildet jede Gruppe als Object Type ab, der das AcfFieldGroup-Interface implementiert; Flexible Content wird zur Union, Repeater zu einer Objektliste. Ohne die Opt-in-Flags bleibt die Gruppe aus der API.
Dieses Opt-in-by-Design ist ein Sicherheits-Feature, kein Hindernis. Es schützt davor, dass interne Felder — Notizen, Workflow-Status, halbfertige Inhalte — versehentlich über die öffentliche API erreichbar werden. Sie entscheiden bewusst, was nach aussen geht.
Wichtig für die Langzeit-Wartung: Die aktuelle Architektur ist WPGraphQL for ACF v2.x (eine vollständige Re-Architecture). Das alte wp-graphql-acf-Repository wurde am 23. Juli 2024 archiviert und durch den Nachfolger ersetzt (WPGraphQL for ACF, README). Die aktuelle stabile Version im Plugin-Verzeichnis ist 2.6.3 mit über 10'000 aktiven Installationen und setzt mindestens WordPress 5.9 sowie PHP 7.3 voraus (WordPress.org, WPGraphQL for ACF). Wer noch auf der archivierten Variante sitzt, sollte den Umstieg einplanen.
Ein letzter, oft übersehener Punkt: ACF liefert Rohwerte ohne Auto-Escaping. Was im Backend eingegeben wird, kommt unverändert durch die API. Das Escaping gehört ins Frontend — niemals darauf verlassen, dass das CMS Markup oder Sonderzeichen entschärft. Welche Transport-Schicht Sie dabei wählen, GraphQL oder REST, ist eine eigene Abwägung, die wir in WPGraphQL vs. REST API als Transport-Schicht führen.
Schweizer Realität: ACF, Secure Custom Fields und die Lizenz-Frage
Seit dem WP-Engine-Streit gibt es zwei Stränge: das kommerzielle ACF (Pro) und den WordPress.org-Fork Secure Custom Fields (SCF), am 12. Oktober 2024 abgespalten. Für Schweizer Projekte heisst das: Lizenz- und Update-Pfad bewusst wählen. WPGraphQL ist seit Oktober 2024 kanonischer Plugin-Kandidat unter Automattic — ein langfristig stabiler Unterbau.
Konkret zur Abspaltung: Mit dem SCF-Fork am 12. Oktober 2024 wurden ACF-Free-Installationen mit aktivem Auto-Update auf Secure Custom Fields umgestellt; ACF-Pro-Installationen blieben unberührt (WordPress.org News, Secure Custom Fields). Funktional sind ACF Pro und SCF im Kern identisch — Repeater, Flexible Content, Clone sind in beiden vorhanden. Der Unterschied liegt im Update- und Support-Pfad, nicht in den Features.
Parallel hat WPGraphQL einen Stabilitäts-Gewinn erlebt: Maintainer Jason Bahl wechselte zu Automattic, und WPGraphQL wird zum kanonischen Community-Plugin — frei und Open Source, aber mit institutioneller Pflege im Rücken (WPGraphQL, Ankündigung Oktober 2024). Für ein Projekt mit fünf bis zehn Jahren Lebensdauer ist das eine relevante Risiko-Reduktion.
Unsere Empfehlung für DACH-Projekte mit planbarer Wartung: eine ACF-Pro-Lizenz plus Local JSON, und die Plugin-Herkunft sauber dokumentieren — also festhalten, ob ACF Pro oder SCF im Einsatz ist, damit der Update-Pfad über Jahre nachvollziehbar bleibt. Konkret heisst das dreierlei: Bei planbarer Wartung und langem Lebenszyklus setzen wir auf ACF Pro plus Local JSON, weil Update- und Support-Pfad definiert und die Herkunft dokumentierbar sind. Free-Installationen mit Auto-Update wurden seit dem 12. Oktober 2024 ohnehin automatisch auf SCF umgestellt — diesen Wechsel prüfen Sie besser bewusst, als ihn passiv hinzunehmen. Die Kern-Features (Repeater, Flexible Content, Clone) sind in beiden Varianten identisch; der Unterschied liegt im Update- und Support-Pfad, nicht im Funktionsumfang. Ein angenehmer Nebeneffekt eines feldbasierten Modells: Es erleichtert das revDSG-konforme Daten-Mapping, weil personenbezogene Felder klar benannt und lokalisierbar sind statt in Fliesstext-Blöcken zu verschwinden. Das ersetzt keine Rechtsberatung, vereinfacht aber jede Datenschutz-Auskunft.
Unsere Modellierungs-Regeln auf einen Blick
Diese Regeln sind verbindlich in unseren Projekten: ein CPT pro Inhaltstyp, eine Field Group pro Typ, alles via Local JSON in Git versioniert, alle exponierten Gruppen mit explizitem GraphQL Field Name, Flexible Content nur für kuratierte Layouts, Output im Frontend escapen. Sie kosten zu Beginn Disziplin und sparen später vier- bis fünfstellige Migrationsbudgets.
- Local JSON aktivieren und committen. Der
acf-json/-Ordner gehört ins Theme und in die Versionskontrolle, nicht nur in die Datenbank. ACF Local JSON speichert Field Groups, Post Types und Taxonomien als JSON, reduziert Datenbank-Queries und macht Definitionen über Environments synchronisierbar — seit ACF 6.2 sogar mit Filtern zur Pfad- und Dateinamen-Steuerung (Advanced Custom Fields, Local JSON). - Feldnamen einmal festlegen, dann einfrieren. Sie sind ein API-Vertrag. Umbenennen bricht Frontend-Queries und Migrations-Mappings.
- Keine Layout-Logik in Inhaltsfeldern. Präsentation gehört ins Frontend, nicht ins CMS. Ein Feld speichert was, nicht wie es aussieht.
- Editor-Komfort früh mit echten Redakteuren testen. Ein Modell, das im Schema elegant ist, aber im Backend mühsam, wird umgangen. Mehr dazu in Redaktions- und Editor-UX in Headless WordPress.
Nächster Schritt
Content-Modeling ist die Entscheidung, die Sie am liebsten nur einmal treffen. Wenn Sie vor einem Headless-Projekt stehen oder ein bestehendes Modell prüfen lassen wollen, bevor es in tausend Beiträge eingebrannt ist, sprechen wir das gern konkret durch — in einem unverbindlichen Erstgespräch. Wie wir Architektur, Datenmodell und Frontend in der Umsetzung zusammenführen, zeigt unsere Übersicht zu Leistungen rund um Headless WordPress.