Ausgabetypen
im Mapping

Jedes Mapping-Feld eines Inhaltselements kann einen Ausgabetyp deklarieren. Damit legst du fest, welche Form der gemappte Wert in der API hat — und zwar bereits beim Erstellen des Inhaltselements, nicht erst beim Platzieren auf einer Seite. Genau das macht die generierte OpenAPI-Spezifikation und damit ein typisiertes SDK verlässlich.

• Was der Ausgabetyp bewirkt
• Beziehungen: die Spalten der Einträge deklarieren
• Die Response
• Wissenswertes

Was der Ausgabetyp bewirkt

Ohne Ausgabetyp darf in ein Mapping-Feld jedes beliebige Feld gemappt werden, auch mehrere Felder und statischer Text gemischt. Der Wert kann entsprechend alles sein, und die generierte Spezifikation lässt den Typ offen.

Mit einem Ausgabetyp gilt:

• in der Administration werden nur noch Felder angeboten, die diesen Ausgabetyp erzeugen — oder die sich über einen Konvertierungsfilter dorthin bringen lassen;
• pro Feld ist genau ein Wert erlaubt, kein Zusammensetzen aus mehreren Feldern und keinen statischen Text (Ausnahme: der Ausgabetyp «Text», der genau das weiterhin zulässt);
• die generierte Spezifikation beschreibt das Feld typisiert.

Die Ausgabetypen sind bewusst keine Feldtypen: Bild und Datei liefern dieselbe Struktur, ebenso Dropdown und Radio-Buttons. Deshalb wählst du die Ausgabeform und nicht den Feldtyp.

Beziehungen: die Spalten der Einträge deklarieren

Der Ausgabetyp «Entitäten – Mehrere Einträge (array)» beschreibt eine 1:n-Beziehung. Ein solcher Wert ist kein einzelner Wert, sondern eine Liste von Einträgen — und welche Felder ein Eintrag mitbringen soll, gehört zum Inhaltselement, nicht zur einzelnen Seite. Sonst könnte dasselbe Inhaltselement auf jeder Seite etwas anderes zurückgeben und der generierte Typ wäre wertlos.

Deshalb deklarierst du beim Inhaltselement direkt die Spalten, die jeder Eintrag zurückgibt:

Spalte	Ausgabetyp
name	Text (string)
portrait	Bild / Datei – Einzeleintrag (object)

Beim Platzieren des Inhaltselements wählst du dann

1. die Datenquelle — die Beziehung des Content-Pools, deren Einträge ausgegeben werden, und
2. pro deklarierter Spalte, welches Feld der verknüpften Entität sie füllt.

Die Spalten-Zuordnung ist ein vollwertiges Mapping: du kannst statischen Text ergänzen und Filter anwenden, sofern der Ausgabetyp der Spalte das zulässt. Massgebend sind die Felder der verknüpften Entität, denn jede Spalte wird pro Eintrag der Beziehung aufgelöst.

Mindestens eine Spalte ist erforderlich. Ohne Spalten könnte niemand etwas mit den Einträgen anfangen ausser deren Identifikation.

Die Response

Für das Beispiel oben liefert der Pages-Endpunkt pro iteriertem Eintrag eine flache Liste von Einträgen:

{
  "identifier": "author_list",
  "items": [
    {
      "authors": [
        {
          "id": 40787,
          "unique_id": "QyS91qDn",
          "routes": { "detail": "/de/autoren/basil-suter" },
          "name": "Basil Suter",
          "portrait": {
            "source": "https://storage.flyo.cloud/basil_a1b2c3.jpg",
            "caption": "Basil Suter",
            "copyright": "",
            "name": "basil.jpg",
            "id": 154311,
            "mime_type": "image/jpeg"
          }
        }
      ],
      "link": { "entity_unique_id": "ix8Rhnqx", "entity_slug": "beitrag-1", "entity_type_id": 2, "routes": {} }
    }
  ]
}

Jeder Eintrag bringt immer id, unique_id und routes mit — die Identifikation der verknüpften Entität und ihre aufgelösten Detailseiten-Pfade — und danach genau die deklarierten Spalten. Eine deklarierte, aber auf dieser Seite nicht zugeordnete Spalte ist null; der Schlüssel fehlt nie.

Weil die Spalten aus dem Inhaltselement stammen, beschreibt die generierte Spezifikation genau diese Struktur:

"authors": {
  "title": "Autoren",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": { "type": "number" },
      "unique_id": { "type": "string" },
      "routes": { "type": "object", "additionalProperties": { "type": "string" } },
      "name": { "title": "Name", "type": "string" },
      "portrait": { "title": "Portrait", "type": "object", "properties": { "source": { "type": "string" } } }
    }
  }
}

Aus einem generierten SDK heraus ist item.authors[0].name damit typisiert verfügbar.

TIP

Die Spezifikation eines Inhaltselements siehst du direkt im Editor, noch bevor du speicherst. So lässt sich die Wirkung einer Deklaration sofort prüfen.

Wissenswertes

routes kann ein leeres Array sein. Hat die verknüpfte Entität keine konfigurierte Detailseiten-Route, wird routes als [] und nicht als {} ausgegeben. Behandle den Wert also als «eventuell leer», bevor du darauf zugreifst.

Eine Spalte bezieht sich immer auf die verknüpfte Entität. Ein Feld der iterierten Entität selbst lässt sich nicht in eine Spalte mappen — dafür verwendest du ein eigenes Mapping-Feld auf der obersten Ebene des Inhaltselements.

Die Spalten-Identifier id, unique_id und routes sind reserviert, weil sie die Identifikation des Eintrags bilden.

Mapping-Felder ohne Ausgabetyp bleiben unverändert. Sie erlauben weiterhin das freie Mapping einer Beziehung samt deren Unterfelder. Der Wert ist dann ein Objekt, das unter dem Namen des Beziehungsfeldes eine Liste der Einträge enthält, und der generierte Typ bleibt offen. Für neue Inhaltselemente empfehlen wir die Deklaration von Spalten.