Schnittstelle (OpenAPI)

Pfade benennen Ressourcen, nicht Nachrichten: /products, /tariff-inquiry, /calculations, /business-cases/{caseId}/calculation.

Die Methode folgt der Bedeutung. GET liest und ist cachebar; die Eingaben einer Auskunft stehen in Query-Parametern, etwa GET /products?date=2022-06-01. POST auf eine Sammlung erzeugt ein Geschäftsobjekt und antwortet mit 201 Created und dessen Adresse in Location. Die Tarifauskunft ist POST, weil sie eine vollständige Instanz als Body braucht; sie speichert trotzdem nichts.

Bearbeitungen sind benannte Methoden am Geschäftsobjekt: POST /business-cases/{caseId}/calculation:addComponent. Der Name nach dem Doppelpunkt ist die operationId.

Die IRI eines Geschäftsobjekts ist seine Adresse. GET auf die IRI der Berechnung liefert die Berechnung, die Knoten ihres Entwurfs liegen darunter (…/calculation/instance, …/calculation/c1).

Keine Angabe doppelt. Was im Pfad steht, etwa der Geschäftsfall, steht nicht im Body.

Auskünfte weisen den Weg. listProducts nennt jedes Produkt mit Bezeichnung und den Folgeschritten readProductKnowledge, readDefaultInstance und, mit Entwurf am Server, createCalculation. readDefaultInstance liefert die Default-Instanz – Pflichtbausteine in Mindestzahl, Attribute mit Vorbelegung – mit den IRIs der Tarifauskunft (…/tariff-inquiry#instance, #c1). Um die Risikoobjekte ergänzt, ist sie der Body von inquireTariff; der Folgeschritt nennt die Shapes der Risikoobjekte. Die Verweisregel bc:riskObjectRule an einem Knoten sagt, dass die Risikoobjekte dort mit i:riskObject hängen, meist an der Wurzel.

Nutzdaten sind JSON-LD (application/ld+json) im Vokabular der Norm. Ihre Struktur legen die SHACL-Shapes fest. Die Erweiterung x-omds-request-shape nennt je Operation die Shape des Requests. Die Request-Shapes sind Teil der Norm, in SHACL Core; ein Client oder KI-Agent prüft einen Request damit vor dem Absenden, auch ob ein Prädikat falsch geschrieben ist. x-omds-request-shape-from-catalogue kennzeichnet Operationen, bei denen der Katalog des Versicherers eigene Shapes ergänzt, etwa für die Fahrzeugvorlagen.

Request-Schemas. Den Body jeder Operation mit Request beschreibt ein JSON Schema (2020-12), das aus ihrer Request-Shape erzeugt ist und die kanonische Form zeigt. Die Referenzseite listet damit die Felder je Operation, Code-Generatoren und MCP-Server erhalten ein Eingabeschema. Das JSON Schema prüft die Struktur; maßgeblich bleibt die Shape. Die Antworten sind JSON-LD ohne eigenes Schema.

Folgeschritte. Jede Antwort zu einem Geschäftsfall nennt die zulässigen Folgeschritte (bc:nextStep). Deren bc:operation ist die operationId der OpenAPI-Datei und bc:expects eine der Shapes aus x-omds-request-shape. Ein Client folgt den Folgeschritten, statt den Ablauf vorab zu kennen. Für KI-Agenten ist die operationId zugleich der Name des Werkzeugs eines MCP-Servers, der auf der OpenAPI-Datei aufsetzt.

Operationsarten. x-omds-operation-kind ordnet jede Operation einer Operationsart zu: inquiry (Auskunft), creation (Erzeugung) und editing (Bearbeitung).

Fehler sind Problem Details nach RFC 9457 mit einem type unter https://vvo.at/omds/ld/problems/, etwa target-not-in-draft oder wrong-state. Eine abgelehnte Anfrage ändert nichts.

Beispiele. Jede Operation hat ein Beispiel für Request und Antwort. Jede Beispielantwort ist die echte Antwort der Muster-Versicherung auf den Beispiel-Request, mit dem Geschäftsfall https://insurer.example/omds-ld/api/business-cases/4711.

"@context" verweist auf den normativen Context https://vvo.at/omds/ld/context.jsonld. Er enthält die Präfixe der Vokabulare der Norm und legt für die Prädikate der Request-Shapes fest, ob ihr Wert eine IRI, ein Datum oder eine Menge ist. Die IRI ist ein Name: Server und Clients bilden sie auf ihre Kopie der Norm ab und laden sie nicht aus dem Netz. Eine Kopie liegt neben der Referenzseite (context.jsonld), ebenso die Request-Schemas (schemas/<Klasse>.schema.json).

Klassen und Prädikate stehen als CURIEs (bc:AddComponentRequest, bc:target), IRIs und Daten als Zeichenketten. IRIs aus den Katalogen der Versicherer sind ausgeschrieben. Der Wert eines Attributs (bc:value) ist ein Wertobjekt mit @value und @type, weil sein Datentyp vom Attribut abhängt.

Ein Prädikat, das mehrere Werte haben kann, steht immer als Array, auch mit einem Wert (bc:riskObject).

Die Tarifauskunft sendet die Instanz als @graph mit genau einem Knoten i:Instance und seinen Teilen.