Was ist neu in Arazzo 1.1? Die Neuerungen der OpenAPI-Workflow-Spezifikation

Mit Version 1.1.0 hat die OpenAPI Initiative Arazzo zum ersten Mal seit dem Patch 1.0.1 inhaltlich erweitert. Arazzo beschreibt mehrstufige API-Workflows, also die Reihenfolge, in der mehrere API-Aufrufe zu einem fachlichen Ablauf zusammenfinden. Das neue Release vergrößert den Beschreibungsumfang an drei Stellen, bei der Unterstützung von AsyncAPI, beim Aufrufen anderer Workflows und bei der Datenextraktion aus Antworten.

Was Arazzo grundsätzlich ist und wie es sich zu OpenAPI verhält, klärt der Artikel Was ist Arazzo. Dieser Beitrag konzentriert sich auf die Neuerungen der Version 1.1.0 und darauf, was sie in realen Projekten verändern.

Die Versionshistorie im Überblick

Arazzo folgt semantischer Versionierung. Der erste öffentliche Stand 1.0.0 erschien im Mai 2024, ein knappes Jahr später schärfte der Patch 1.0.1 einige Formulierungen und beseitigte kleinere Unklarheiten. Version 1.1.0 ist der erste Schritt, der neue Felder einführt.

Für den praktischen Umgang zählt vor allem die Stelle hinter dem Punkt. Ein Minor-Release fügt Funktionen hinzu, ohne bestehende zu entfernen. Wer heute eine 1.0-Datei pflegt, verwendet sie unverändert weiter und ergänzt die neuen Felder gezielt dort, wo sie einen Vorteil bringen.

Dass die erste funktionale Erweiterung erst rund anderthalb Jahre nach dem ersten Release kommt, sagt auch etwas über die Spezifikation selbst. Arazzo wächst langsam und in kleinen, abwärtskompatiblen Schritten. Für Teams, die darauf aufbauen, ist dieser ruhige Takt ein Vorteil, weil bestehende Workflows nicht mit jedem Release nachgezogen werden müssen.

Was der AsyncAPI-Support ermöglicht

Die auffälligste Neuerung betrifft AsyncAPI. Bisher kannte Arazzo im Feld sourceDescriptions nur OpenAPI- und andere Arazzo-Dokumente. Jede Quelle beschrieb damit synchrone Aufrufe nach dem Request-Response-Muster. Version 1.1.0 erlaubt zusätzlich AsyncAPI-Beschreibungen als Quelle.

Der Hintergrund dieser Erweiterung liegt in der Verbreitung event-getriebener Architekturen. Viele Systeme kommunizieren heute über synchrone REST-Aufrufe und zugleich über Message-Broker, Webhooks und Event-Streams. AsyncAPI hat sich als Beschreibungssprache für genau diese asynchrone Kommunikation etabliert. Indem Arazzo solche Beschreibungen als Quelle zulässt, schließt es einen Workflow an beide Welten an.

Damit kann ein Workflow Schritte enthalten, die Nachrichten senden oder empfangen. Ein sendender Schritt stößt ein Event an, ein empfangender Schritt wartet auf eine eintreffende Nachricht. Beide Arten unterstützen Correlation-Identifier, über die sich eine Antwort der ursprünglichen Anfrage zuordnen lässt, sowie Timeouts für den Fall, dass eine erwartete Nachricht ausbleibt.

Der Schritt wartet auf eine eintreffende Nachricht, prüft über successCriteria, ob sie den erwarteten Zustand meldet, und stellt einzelne Werte aus der Nachricht als outputs bereit. Für den restlichen Workflow verhält sich ein solcher Schritt wie jeder andere. Er liefert Ausgaben, auf die nachfolgende Schritte zugreifen. Der Unterschied liegt allein darin, dass die Ausgabe aus einer Nachricht stammt und nicht aus der Antwort eines synchronen Aufrufs.

Der umgekehrte Fall, ein sendender Schritt, ist ähnlich nützlich. Ein Workflow kann an einer definierten Stelle selbst ein Event auslösen, etwa eine Benachrichtigung an ein nachgelagertes System, und den Ablauf danach fortsetzen. Damit lässt sich auch die ausgehende Seite eines Prozesses festhalten, die in einer reinen REST-Sicht häufig unsichtbar blieb.

Wer reale Geschäftsprozesse betrachtet, erkennt schnell, warum das zählt. Die wenigsten Abläufe sind durchgehend synchron. Fast immer wartet irgendwo ein Schritt auf ein Ereignis, etwa eine Zahlungsbestätigung, eine Provisionierung oder die Freigabe durch ein nachgelagertes System. Genau dieser Teil ließ sich in Arazzo 1.0 nicht abbilden und wanderte in Fußnoten oder separate Dokumente. Damit ist 1.1 mehr als ein reines Feature-Update. Das Release verschiebt, was Arazzo überhaupt beschreiben kann. Aus einer Sprache für REST-Ketten wird eine Sprache für gemischte Abläufe, die synchrone Aufrufe und Events in einem Workflow zusammenführen.

Andere Workflows aus einem Schritt aufrufen

Die zweite Erweiterung betrifft die Struktur größerer Abläufe. In Arazzo 1.1.0 kann ein Schritt einen anderen Workflow aufrufen und ihm über parameters Eingaben übergeben. Die Ergebnisse des aufgerufenen Workflows stehen anschließend als outputs zur Verfügung und lassen sich in den folgenden Schritten weiterverwenden.

Das Beispiel ruft aus einem übergeordneten Ablauf den eigenständigen Workflow creditRatingCheck auf und reicht die Partner-ID aus einem vorherigen Schritt hinein. Das Ergebnis steht danach als rating bereit. So entstehen größere Prozesse aus kleineren, klar abgegrenzten Bausteinen.

Ein vollständiges End-to-End-Beispiel, in dem auch die Verkettung ihren Platz findet, zeigt die Anleitung Arazzo in der Praxis. Der Nutzen zeigt sich vor allem bei Logik, die an mehreren Stellen vorkommt. In einem B2B-Marktplatz war der Onboarding-Workflow über die Zeit auf mehr als zwanzig Schritte angewachsen. Die Bonitätsprüfung darin tauchte in drei weiteren Abläufen erneut auf, jedes Mal kopiert. Mit verketteten Workflows ließ sich die Prüfung als eigener Workflow auslagern und an allen vier Stellen aufrufen. Eine spätere Änderung an der Prüflogik war danach an einer Stelle erledigt statt an vier.

Mit der Auslagerung kommt eine Frage hinzu, die vorher keine Rolle spielte. Ein wiederverwendeter Workflow braucht eine klare Schnittstelle aus inputs und outputs, weil mehrere Aufrufer sich darauf verlassen. Eine Änderung an dieser Schnittstelle wirkt sich auf alle aufrufenden Workflows aus, ähnlich wie eine Änderung an einer gemeinsam genutzten API. Verkettung lohnt sich deshalb vor allem für Teilabläufe, die stabil und fachlich abgeschlossen sind.

Das Selector Object

Die dritte Neuerung ist das Selector Object. Es erweitert die Art, wie ein Schritt Werte aus einer Antwort herauszieht. In Arazzo 1.0 geschah das überwiegend über Runtime-Expressions, die auf eine feste Stelle im Body verweisen. Das Selector Object ergänzt gezielte Abfragen über jsonpath, xpath oder jsonpointer.

Damit lassen sich auch Werte aus tief verschachtelten Strukturen oder aus XML-Antworten sauber adressieren. Ein jsonpath-Ausdruck wie $.items[0].id greift etwa die ID des ersten Eintrags einer Liste heraus, ohne dass der Workflow den gesamten Body weiterreichen muss. Bei Schnittstellen, die ihre Daten in verschachtelten Objekten oder als XML liefern, war diese Extraktion zuvor häufig umständlich.

Der Unterschied wird an einem Beispiel greifbar. Liefert eine API ihre Daten als verschachteltes Objekt mit einer Liste von Positionen, musste ein Workflow in 1.0 oft den gesamten Abschnitt weiterreichen und die Auswertung einem späteren Schritt überlassen. Mit einem Selector adressiert der Schritt direkt den benötigten Wert, etwa den Status der ersten Position oder einen Betrag aus einem tief liegenden Feld. Das hält die Datenübergaben zwischen den Schritten schlank und macht den Workflow leichter lesbar.

Die drei Neuerungen im Zusammenspiel

Einzeln betrachtet wirken die drei Erweiterungen wie unabhängige Detailverbesserungen. In einem realen Workflow greifen sie oft ineinander. Ein Bestellprozess kann mit einem synchronen Aufruf beginnen, der die Bestellung anlegt, danach über einen empfangenden Schritt auf die Zahlungsbestätigung warten und schließlich einen ausgelagerten Versand-Workflow aufrufen.

In diesem Ablauf kommt jede Neuerung an einer Stelle zum Tragen. Der AsyncAPI-Support beschreibt das Warten auf die Zahlungsbestätigung. Das Selector Object zieht aus der Bestätigungs-Nachricht genau die Transaktions-ID heraus, die der Versand benötigt. Die Verkettung bindet den Versand-Workflow ein, der an anderer Stelle ohnehin schon existiert. Was zuvor drei lose verbundene Beschreibungen in verschiedenen Dokumenten waren, steht damit als ein zusammenhängender Workflow in einer Datei.

Für die Dokumentation bedeutet das einen Sprung in der Aussagekraft. Wo vorher mehrere Teams ihre Teilstücke getrennt pflegten, beschreibt eine Datei den gesamten Weg von der Bestellung bis zum Versand. So werden Lücken zwischen den Systemen, an denen Abläufe in der Praxis oft scheitern, sichtbar und prüfbar.

Was 1.1 bewusst nicht verändert

Bei aller Erweiterung bleibt der Charakter von Arazzo gleich. Die Spezifikation beschreibt Abläufe, sie führt sie nicht aus. Auch in 1.1.0 entscheidet weiterhin das jeweilige Werkzeug, ob ein Testrunner, ein SDK-Generator oder ein Agent die Beschreibung abarbeitet. Themen einer Laufzeitumgebung, etwa langlaufende Retry-Strategien oder das parallele Ausführen vieler Workflows, bleiben bewusst außerhalb der Spezifikation.

Auch die neue AsyncAPI-Unterstützung ändert daran nichts. Arazzo legt fest, dass ein Schritt auf eine Nachricht wartet und wann er als erfolgreich gilt. Wie diese Nachricht technisch zugestellt wird, über welchen Broker und mit welcher Zustellgarantie, gehört in die AsyncAPI-Beschreibung selbst und nicht in den Workflow. Diese Trennung hält Arazzo schlank und über verschiedene Werkzeuge hinweg portabel.

Was das für bestehende Arazzo-Dateien bedeutet

Als Minor-Release bleibt Arazzo 1.1.0 abwärtskompatibel. Bestehende Dokumente mit arazzo: 1.0.0 bleiben gültig und müssen nicht angepasst werden. Wer die neuen Felder nutzen will, hebt das Versionsfeld auf 1.1.0 an und kann anschließend AsyncAPI-Quellen, verkettete Workflows und das Selector Object einsetzen.

Ein Umstieg lohnt sich vor allem dort, wo bisher Teile eines Ablaufs außerhalb der Spec dokumentiert waren. Ein Workflow, der einen synchronen Aufruf absetzt und danach auf ein Event wartet, lässt sich in 1.1.0 erstmals vollständig in einer Datei beschreiben. Für rein synchrone REST-Abläufe ändert sich dagegen wenig, weil die bisherigen Felder unverändert weiterfunktionieren.

Der Umstieg selbst ist überschaubar. Heben Sie das Versionsfeld auf 1.1.0 an, ergänzen Sie die benötigten Quellen in sourceDescriptions und führen Sie die Workflows anschließend gegen Ihren bestehenden Testrunner aus. Weil die 1.0-Felder unverändert gelten, läuft ein bestehender Ablauf ohne Anpassung weiter. Erst die Schritte, die Sie aktiv um AsyncAPI, Verkettung oder einen Selector erweitern, bringen neues Verhalten mit.

Warum 1.1 für AI-ready APIs zählt

Arazzo wird 2026 vor allem im Zusammenhang mit KI-Agenten genannt. Ein Agent, der einen Geschäftsprozess ausführen soll, braucht eine verlässliche Vorlage für die Reihenfolge der Aufrufe. Die Arbeit an AI-Ready APIs zielt darauf, Schnittstellen für maschinelle Konsumenten nutzbar zu machen, und Arazzo liefert dafür die Ablaufbeschreibung.

Konkret liest ein Agent eine Arazzo-Beschreibung als Bauplan und muss die richtige Reihenfolge der Aufrufe nicht selbst erschließen. Die Schritte, ihre Datenübergaben und die Erfolgskriterien stehen bereits fest. Der Agent füllt die Eingaben, reagiert auf die Ergebnisse und bricht ab, wenn ein Schritt scheitert. Für Abläufe, die korrekt und wiederholbar sein müssen, senkt das die Fehlerquote spürbar, weil weniger dem Modell überlassen bleibt.

Mit der AsyncAPI-Unterstützung deckt diese Beschreibung jetzt auch Schritte ab, die auf Events warten. Für Agenten ist das relevant, weil reale Prozesse selten innerhalb eines einzigen synchronen Aufrufs abgeschlossen sind. Wie sich deterministische Arazzo-Workflows und dynamische Agentic Workflows ergänzen, bleibt dieselbe Frage wie zuvor, gilt nun aber für einen größeren Bereich an Abläufen. Den Überblick über das gesamte Feld gibt der Pillar zur API-Orchestrierung.

Auf dem Stand bleiben

Arazzo entwickelt sich weiter, und die Abstände zwischen den Releases sind überschaubar. Wer die Spezifikation produktiv einsetzt, sollte die Releases der OpenAPI Initiative im Blick behalten, weil jede Minor-Version den Beschreibungsumfang erweitern kann.

Setzen Sie in einer bestehenden Arazzo-Datei das Feld arazzo auf 1.1.0 und prüfen Sie, ob einer Ihrer Workflows einen Schritt enthält, der bisher außerhalb der Spec auf ein Event gewartet hat. Genau dieser Schritt ist der erste Kandidat für die neue AsyncAPI-Unterstützung.