Holarch

SysML v2

API und MCP in SysML v2-Projekten

Lesen, durchsuchen und prüfen Sie SysML v2-Modelle aus Skripten und KI-Werkzeugen mit einem persönlichen Zugriffstoken, schlagen Sie Änderungen vor, die Sie in Holarch prüfen und anwenden, und lesen und committen Sie über die Systems Modeling API, in der Branches Änderungsanträge sind.

So gehen Sie vor →

Auf dieser Seite
  1. Überblick
  2. Konzepte
  3. So setzen Sie es ein
    1. Ein SysML v2-Projekt mit curl lesen
    2. SysML-Text prüfen, bevor Sie ihn vorschlagen
    3. Eine Änderung vorschlagen und anwenden
    4. Ein KI-Werkzeug mit einem SysML v2-Projekt verbinden
    5. Ausgeführtes Beispiel: die Hybrid-Car-Demo
    6. Tipps
  4. REST-Routen für SysML v2-Projekte
    1. Werte
  5. MCP-Werkzeuge für SysML v2-Projekte
    1. Elementbearbeitungen
    2. Vorgeschlagener Text
  6. Vorschläge in SysML v2-Projekten
    1. Einen SysML v2-Vorschlag prüfen
  7. Systems Modeling API
    1. Änderungen committen
  8. Meldungen
  9. Grenzen
  10. Verwandte Seiten

Überblick

SysML v2-Projekte arbeiten mit derselben REST-API, demselben MCP-Endpunkt und denselben persönlichen Zugriffstoken wie LML-Projekte. Skripte und KI-Werkzeuge lesen das Modell als Elemente und SysML-Text, prüfen Text, bevor sie etwas ändern, und schlagen Änderungen vor. Nichts im Modell ändert sich, bis eine Person den Vorschlag in Holarch prüft und anwendet.

Drei Zugänge:

  • REST-API: https://app.holarch.app/api/v1/projects/<project>/… für Skripte und Dashboards. Sie liest Elemente, Anforderungen, Diagnosen und SysML-Text und fügt Änderungen zu einem Vorschlag hinzu.
  • MCP: https://app.holarch.app/mcp für KI-Werkzeuge wie Claude. Die SysML v2-Werkzeuge lesen, durchsuchen und prüfen das Modell und schlagen Änderungen vor.
  • Systems Modeling API: https://app.holarch.app/api/v1/sysml/…, in den Formen der OMG Systems Modeling API für andere SysML v2-Werkzeuge. Der Branch main ist das Live-Modell und schreibgeschützt; jeder andere Branch ist ein Änderungsantrag, und Commits gehen in ihn. Das Live-Modell ändert sich nur, wenn ein Genehmiger den Änderungsantrag in Holarch anwendet.

Token, Scopes, Projektlisten, der Organisationswechsel, Ratenlimits und das Verbinden von Claude sind dieselben wie bei LML-Projekten. Siehe API und MCP zum Erstellen eines Tokens und Verbinden eines KI-Werkzeugs. Die Aufrufe der Programmkarte (GET /api/v1/program-map, GET /api/v1/projects/<project>/items/<item>/trace und die MCP-Werkzeuge program_map und trace_chain) schließen SysML v2-Projekte und ihre Elemente ein.

Konzepte

  • Element: ein Element des SysML v2-Modells, etwa eine Part-Definition, ein Port oder eine Anforderung. Jedes Element hat eine id (eine UUID). Wo immer eine Route oder ein Werkzeug eine ID verlangt, funktioniert auch ein qualifizierter Name wie Vehicles::Car::powertrain.
  • Kurzform: die kurze Form eines Elements in Listen: id, type (die Metaklasse, etwa PartUsage), name, shortName, qualifiedName und owner.
  • Package der obersten Ebene: ein Package, das nicht in einem anderen Element liegt. Der SysML-Text eines Projekts ist ein Text pro Package der obersten Ebene, plus ein Text für die Elemente außerhalb von Packages.
  • Diagnose: ein Problem, das der Sprachkern findet, mit code, severity (error oder warning), elementId, element und args. Syntaxdiagnosen geben statt eines Elements line und col an.
  • Vorschlag: die Änderungen, die ein API-Client oder KI-Werkzeug zur Prüfung sammelt. Pro Token und Projekt ist ein Vorschlag offen. Der Client sendet ihn mit Titel und Zusammenfassung zur Prüfung.
  • Seitenweise Antworten: Listen kommen in Seiten (limit, offset). Langer SysML-Text kommt in Seiten von Zeilen (line, lines). Eine Antwort, die etwas ausgelassen hat, sagt truncated: true.

So setzen Sie es ein

Verwenden Sie die API, wenn ein Skript oder KI-Werkzeug das Modell benötigt: um über Anforderungen ohne erfüllende oder verifizierende Elemente zu berichten, um den SysML-Text eines Teams gegen das Modell zu prüfen oder um ein KI-Werkzeug Modelländerungen entwerfen zu lassen, die eine Ingenieurin oder ein Ingenieur dann prüft.

Ein SysML v2-Projekt mit curl lesen

  1. Erstellen Sie ein Token unter Kontoeinstellungen → API-Token (siehe API und MCP).
  2. Listen Sie Ihre Projekte auf:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects

SysML v2-Projekte haben "language": "sysml2".

  1. Die Modellzusammenfassung abrufen:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects/<project>/model

Sie sehen die Elementanzahlen pro Metaklasse, die Packages der obersten Ebene und die Anzahl der Fehler und Warnungen.

  1. Elemente finden, zum Beispiel jede Part-Definition:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/elements?type=part%20def&limit=100"
  1. Den SysML-Text eines Packages lesen:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/sysml?root=Vehicles"

Ein langer Text endet mit "truncated": true und "next": der Zeile, die als Nächstes mit line abzufragen ist.

SysML-Text prüfen, bevor Sie ihn vorschlagen

  1. Den neuen Text eines Packages an die Prüfroute senden:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"root": "Vehicles", "text": "package Vehicles { … }"}' \
  https://app.holarch.app/api/v1/projects/<project>/sysml/check
  1. Lesen Sie die Antwort. ok ist true, wenn der Text keine Syntaxfehler hat. diagnostics listet Syntaxfehler mit line und col auf sowie die Fehler, die der Text dem Modell hinzufügen würde. changes ist die Anzahl der Modelländerungen, die der Text vornimmt.

Die Prüfung ändert nichts. Sie benötigt nur ein Lese-Token.

Eine Änderung vorschlagen und anwenden

Ein Schreib-Token fügt Änderungen zum offenen Vorschlag des Tokens hinzu. Der Client sendet den Vorschlag dann zur Prüfung.

  1. Fügen Sie eine Änderung hinzu. Senden Sie entweder den vollständigen neuen Text eines Packages oder Elementbearbeitungen:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"edits": [{"op": "create", "kind": "attribute", "owner": "Vehicles::Car", "name": "range", "typedBy": ["LengthValue"]}]}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal/changes

Sie erhalten 201 mit dem Vorschlag, der Zusammenfassung der Änderung und den Elementen, die sie hinzufügt, ändert und entfernt. Eine Änderung, die Fehlerdiagnosen hinzufügt, wird abgelehnt (siehe Vorschläge in SysML v2-Projekten).

  1. Fügen Sie weitere Änderungen auf dieselbe Weise hinzu. Jede Änderung wird gegen das Modell geprüft, auf das die früheren Änderungen des Vorschlags angewendet sind.
  2. Den Vorschlag zur Prüfung senden:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"title": "Add range attribute", "summary": "Adds Car::range for the range requirement."}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal
  1. Öffnen Sie in Holarch das Projekt und dann ✦ KI ▾ → „Add range attribute“ prüfen… (oder die Benachrichtigung unter der Glocke).
  2. Prüfen Sie die Zeilen und klicken Sie auf Auswahl anwenden.

    Die Änderungen mit Häkchen werden mit Ihrem Namen im Verlauf angewendet, und ein einziges Rückgängigmachen nimmt alles zurück.

Ein KI-Werkzeug mit einem SysML v2-Projekt verbinden

  1. Verbinden Sie das KI-Werkzeug mit https://app.holarch.app/mcp über ein Token oder über eine Anmeldung (siehe API und MCP).
  2. Fragen Sie nach dem Modell, zum Beispiel „Summarize the Hybrid Car model in Holarch“ oder „Which requirements in the Hybrid Car project are not verified?“.

    Das KI-Werkzeug verwendet model_summary, list_elements, list_requirements und die anderen Lesewerkzeuge.

  3. Bitten Sie um eine Änderung, zum Beispiel „Propose a range attribute on Car“.

    Das KI-Werkzeug liest das Package mit get_sysml, schlägt Text oder Elementbearbeitungen vor und behebt alle Diagnosen, die die Prüfung zurückgibt.

  4. Prüfen Sie den Vorschlag in Holarch und klicken Sie auf Auswahl anwenden.

Ausgeführtes Beispiel: die Hybrid-Car-Demo

Erstellen Sie die Demo mit Projekte verwalten → Projektdateien ▾ → Neues Demoprojekt → Hybrid Car (SysML v2) und erstellen Sie dann ein Lese- und Schreib-Token dafür.

  1. GET /api/v1/projects/<project>/model listet die Packages der obersten Ebene auf, darunter Vehicles, HybridCarArchitecture und VehicleBehavior.
  2. GET /api/v1/projects/<project>/elements?query=Engine&type=part%20def findet Vehicles::Engine.
  3. GET /api/v1/projects/<project>/elements/Vehicles::Engine gibt die Part-Definition mit ihrem SysML-Text zurück, ihre Member (displacement, cylinders, maxPower, die Ports fuelIn, output und ecu) und die durch sie typisierten Usages.
  4. GET /api/v1/projects/<project>/elements/Vehicles::Car/connections listet das Interface driveShaft von powertrain.output nach frontAxle.input auf.
  5. GET /api/v1/projects/<project>/requirements?status=unverified listet die Anforderungen auf, die kein Verification Case verifiziert, mit ihren IDs wie VR-4.1.
  6. POST /api/v1/projects/<project>/proposal/changes mit {"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]} fügt die Änderung zum Vorschlag hinzu. POST /api/v1/projects/<project>/proposal mit einem Titel sendet ihn.
  7. In Holarch zeigt ✦ KI ▾ → „…“ prüfen Geändert: mit der Part-Definition und dem Feld doc sowie den Textdiff von Vehicles. Auswahl anwenden wendet sie an.

Tipps

  • Lesen Sie ein Package mit get_sysml (oder GET …/sysml?root=), bevor Sie neuen Text dafür vorschlagen. Elemente, die im vorgeschlagenen Text fehlen, werden entfernt.
  • Bevorzugen Sie für kleine Änderungen Elementbearbeitungen. Sie ändern nur die genannten Elemente und lassen den übrigen Package-Text unverändert.
  • Prüfen Sie Text zuerst mit check_sysml (oder POST …/sysml/check). Es gibt dieselben Diagnosen zurück, mit denen ein Vorschlag abgelehnt würde.
  • Benennen Sie Elemente in Skripten über den qualifizierten Namen. IDs bleiben gleich, wenn ein Element umbenannt wird; qualifizierte Namen nicht.
  • Geben Sie einem KI-Werkzeug ein Nur-Lese-Token, wenn es nur Fragen zum Modell beantwortet.

REST-Routen für SysML v2-Projekte

Basisadresse: https://app.holarch.app/api/v1. Antworten sind JSON. /api/v1/openapi.json (OpenAPI 3.1) beschreibt diese Routen zusammen mit den anderen.

Methode und PfadWas sie tut
GET /projects/<project>/modelElementanzahlen pro Metaklasse, die Packages der obersten Ebene mit ihren Elementanzahlen und die Anzahl der Fehler und Warnungen
GET /projects/<project>/elementsSuche: query (oder q; Text im Namen, Kurznamen, qualifizierten Namen oder Doc), type, owner, limit (1–500, Standard 50), offset; sortiert nach qualifiziertem Namen
GET /projects/<project>/elements/<id>Ein Element mit seinen Feldern, Doc, SysML-Text, Membern und den durch es typisierten Usages; members (0–200, Standard 100)
GET /projects/<project>/elements/<id>/connectionsConnections, Interfaces, Bindings, Flows (mit dem Item), Successions, Transitions, Allocations und Dependencies am Element oder an seinen Features sowie die darin enthaltenen; limit (Standard 100)
GET /projects/<project>/requirementsAnforderungen mit ihrer ID, ihrem Statement (doc), satisfiedBy und verifiedBy; owner, status (unsatisfied oder unverified), limit (Standard 100), offset
GET /projects/<project>/diagnosticsDie Diagnosen des Modells, Fehler zuerst; ids (kommagetrennt: nur diese Elemente und ihre Member), limit (Standard 200, höchstens 500)
GET /projects/<project>/sysmlSysML-Text eines Packages der obersten Ebene (root), der Elemente außerhalb von Packages (kein root) oder eines Elements (element); line (erste Zeile, ab 1), lines (Standard 2000, höchstens 5000)
POST /projects/<project>/sysml/checktext als neuen Text von root (oder der Elemente außerhalb von Packages) prüfen; ändert nichts
POST /projects/<project>/proposal/changesEine Änderung zum offenen Vorschlag hinzufügen: {text, root} oder {edits}
GET /projects/<project>/proposalDer offene Vorschlag oder einer über die proposal-ID, mit seinem Status und seinen Änderungen
POST /projects/<project>/proposalDen offenen Vorschlag zur Prüfung senden: title, summary
DELETE /projects/<project>/proposalDen offenen Vorschlag verwerfen, bevor er gesendet wird

GET /projects und GET /projects/<project> funktionieren auch für SysML v2-Projekte. Sie geben "language": "sysml2" an, und die Projektantwort ergänzt elements und types (Elementanzahlen pro Metaklasse).

Die LML-Entitätsrouten (/entities, /relationships, /schema, Modellprüfungen und die Qualitätsprüfung) antworten in einem SysML v2-Projekt mit 409 wrong-project-type. Die SysML v2-Routen antworten in einem LML-Projekt ebenso.

Werte

  • type: eine Metaklasse wie PartUsage oder RequirementDefinition oder ein Schlüsselwort, wie es im SysML-Text geschrieben wird: part, part def, attribute, port, requirement, action, package und die anderen Element-Schlüsselwörter.
  • owner, id, element, root: eine ID oder ein qualifizierter Name. root nimmt auch den Namen eines Packages der obersten Ebene an. root muss ein Package der obersten Ebene sein; um den Text eines einzelnen Elements zu lesen, verwenden Sie element.
  • Lange Werte: Ein Doc in einer Liste wird bei 4.000 Zeichen abgeschnitten, ein Doc eines einzelnen Elements bei 20.000 und der eigene SysML-Text eines Elements bei 16.000 Zeichen.

MCP-Werkzeuge für SysML v2-Projekte

Der MCP-Endpunkt listet diese Werkzeuge neben den LML-Werkzeugen auf. Ein KI-Werkzeug findet SysML v2-Projekte mit list_projects (language: sysml2). Jedes Werkzeug nimmt project an.

Die Lesewerkzeuge nehmen auch einen optionalen change_request an (CR-12 oder seine ID), um das Modell so zu lesen, wie dieser Änderungsantrag es machen würde; propose_sysml und propose_element_changes nehmen einen an, um die Änderung gegen das Modell des Antrags zu berechnen und sie nach der Prüfung in diesen Entwurf anzuwenden. Siehe Änderungsanträge für die Regeln.

WerkzeugZugriffWas sie tut
model_summaryLesenElementanzahlen pro Metaklasse, die Packages der obersten Ebene und die Anzahl der Diagnosen
list_elementsLesenElemente über Text (query), type und owner finden; seitenweise mit limit und offset
get_elementLesenEin Element (id) mit seinen Typen, Spezialisierungen, Multiplizität, Wert, Enden, Doc, SysML-Text, Membern (members, höchstens 200) und den durch es typisierten Usages
get_connectionsLesenDie Connections, Interfaces, Bindings, Flows, Successions, Transitions, Allocations und Dependencies eines Elements (id, limit)
list_requirementsLesenAnforderungen mit ihrer ID, ihrem Statement, satisfy und verify; owner, status (unsatisfied, unverified), limit, offset
get_sysmlLesenSysML-Text eines Packages der obersten Ebene (root), der Elemente außerhalb von Packages oder eines Elements (element); line, lines (höchstens 5000); die Antwort gibt next an
get_sysml_textLesenSysML-Text des gesamten Modells (jedes Package der obersten Ebene, dann die Elemente außerhalb von Packages) oder eines package, bis zu 200.000 Zeichen pro Antwort; die Antwort nennt die ausgelassenen Packages
check_sysmlLesenOhne text: die Diagnosen des Modells (ids, limit). Mit text (und root): Syntaxfehler mit Zeile und Spalte sowie die Fehler, die der Text hinzufügen würde. Ändert nichts
propose_sysmlLesen und SchreibenDen vollständigen neuen text eines Packages der obersten Ebene (root) oder der Elemente außerhalb von Packages vorschlagen (kein root; auch dort, wo ein neues Package hinkommt)
propose_element_changesLesen und Schreibenedits (höchstens 100) vorschlagen, ohne Text neu zu schreiben: erstellen, aktualisieren, verschieben oder entfernen

list_diagrams, get_diagram und get_matrix funktionieren auch in SysML v2-Projekten: list_diagrams listet die Ansichten (mit ihrer Art, etwa InterconnectionView) und die unter einem Element gehaltenen Analysediagramme auf; get_diagram gibt die Elemente an, die eine Ansicht nach ihren Filtern zeigt (über Element-ID oder qualifizierten Namen); get_matrix gibt jede Anforderung mit dem an, was sie erfüllt und verifiziert.

Die Vorschlagswerkzeuge von LML-Projekten funktionieren hier genauso: propose_changes sendet den Vorschlag mit Titel und Zusammenfassung, discard_proposal verwirft ihn, und get_proposal und list_proposals zeigen seinen Status. Ein Nur-Lese-Token listet nur die Lesewerkzeuge auf.

Werkzeugfehler kommen als Werkzeugergebnis mit der Meldung und den Diagnosen zurück, sodass das KI-Werkzeug seinen Text korrigieren und es erneut versuchen kann.

Elementbearbeitungen

Jede Bearbeitung in edits (MCP) oder {"edits": […]} (REST) ist ein Objekt mit op:

opFelder
createkind (ein Schlüsselwort wie part, part def, attribute, port, requirement, action, package) oder type (eine Metaklasse); owner (weggelassen: oberste Ebene); name (erforderlich); optional shortName, typedBy, specializes, subsets, redefines, multiplicity, value, doc, direction (in, out, inout)
updateid und die zu ändernden Felder, wie bei create; null oder "" leert ein Feld
moveid und der neue owner
removeid; entfernt das Element mit seinen Membern
  • typedBy, specializes, subsets und redefines sind Listen mit bis zu 20 Namen: IDs, qualifizierte Namen oder Namen, wie sie im Text geschrieben werden (Bibliotheksnamen wie MassValue funktionieren).
  • Spätere Bearbeitungen können Elemente, die früher im selben Aufruf erstellt wurden, in der Reihenfolge ihrer Erstellung als new:1, new:2 … benennen, zum Beispiel als owner. Die Antwort listet sie unter created mit ihren neuen IDs auf.
  • Das Umbenennen eines Elements aktualisiert auch die Referenzen, die es mit seinem alten Namen benannten.

Vorgeschlagener Text

  • propose_sysml ersetzt den gesamten Text des Packages. Elemente behalten ihre IDs, wo der Text sie noch deklariert. Im Text fehlende Elemente werden entfernt.
  • Der Text muss sich parsen lassen, ohne dass etwas unangewendet bleibt. Text, der das Modell nicht ändert, wird abgelehnt (no-change).

Vorschläge in SysML v2-Projekten

Jede vorgeschlagene Änderung wird vom Sprachkern geprüft, bevor sie in den Vorschlag aufgenommen wird:

  • Der Text lässt sich ohne Syntaxfehler parsen, und Elementbearbeitungen lassen sich anwenden.
  • Die geänderten Packages lassen sich weiterhin als SysML-Text ausgeben und erneut parsen.
  • Die Änderung fügt dem Modell keine Fehlerdiagnosen hinzu, etwa nicht aufgelöste Namen oder Typfehler. Fehler, die das Modell bereits hatte, zählen nicht.

Eine Änderung, die durchfällt, wird mit den zu behebenden Diagnosen (bis zu 50) abgelehnt. Nichts wird gespeichert. Warnungen führen nicht zur Ablehnung einer Änderung.

Vorschlagen erfordert ein Lese- und Schreib-Token und die Rolle Editor oder Owner im Projekt. Ein Vorschlag enthält höchstens 200 Änderungen und 8 MB.

Einen SysML v2-Vorschlag prüfen

Öffnen Sie das Projekt und dann ✦ KI ▾ → „<title>“ prüfen…. Jede Änderung ist eine Zeile mit einem Kontrollkästchen:

  • Hinzugefügt, Geändert und Entfernt listen die Elemente mit den geänderten Feldern auf (jeweils die ersten 20; „und n weitere“ für den Rest).
  • Ein Textdiff, beschriftet mit dem Package, zeigt den SysML-Text vorher und nachher.
  • Eine Änderung, die Elemente entfernt, wird markiert und beginnt ohne Häkchen.
  • Das SysML v2-Modell öffnen, um diese Änderung anzuwenden. Das Modell ist nicht geladen; öffnen Sie eine SysML v2-Seite des Projekts.
  • Das Package ist nicht mehr im Modell; übersprungen. Das Package wurde entfernt, nachdem die Änderung vorgeschlagen worden war.

Auswahl anwenden gleicht jede Textänderung erneut mit dem aktuellen Modell ab und behält Bearbeitungen, deren Elemente noch existieren. Es prüft die gesamte Menge und wendet sie als einen Rückgängig-Schritt an. Änderungen, die nicht mehr passen, werden übersprungen und in einer Meldung genannt. Ablehnen und Später funktionieren wie bei LML-Vorschlägen, ebenso Rollen, Ablauf (7 Tage) und Aufbewahrung (siehe Vorschläge von KI-Clients).

Systems Modeling API

Andere SysML v2-Werkzeuge lesen und ändern Holarch-Modelle über Routen in den Formen der OMG Systems Modeling API (REST/HTTP). Die Basisadresse ist https://app.holarch.app/api/v1/sysml. Sie verwendet dieselben Token; jede Projektrolle kann lesen, und Editoren und Owner können committen.

  • Projekte: Nur SysML v2-Projekte werden aufgeführt. Die @id eines Projekts ist eine UUID, die diese API ihm gibt; die Holarch-Projekt-ID funktioniert ebenfalls. Die Antwort enthält holarchId und url.
  • Branches: main ist das Live-Modell und kann über die API nicht geändert werden. Jeder andere Branch ist ein laufender Änderungsantrag, benannt "CR-12 Title" und mit holarchChangeRequest (id, label, status, url). Änderungsanträge, die in den letzten 30 Tagen umgesetzt oder zurückgezogen wurden, werden weiterhin aufgeführt, mit gesetztem deleted.
  • Commits: Ein Commit schreibt Änderungen in den Branch eines Änderungsantrags. Nur Branch-Heads werden bereitgestellt: Der Head von main ist das Live-Modell, der Head eines Änderungsantrags-Branches ist das Live-Modell mit den Änderungen des Antrags. Ältere Commit-IDs antworten mit 404; holen Sie den aktuellen Head vom Branch.
  • Elemente: Jedes Element hat jede Eigenschaft seiner Metaklasse im OMG-JSON-Schema, abgeleitete eingeschlossen (owner, ownedElement, qualifiedName, feature, type und dergleichen). Elemente der Standardbibliothek werden über ihre Standard-IDs referenziert, die IDs, die andere SysML v2-Werkzeuge für dasselbe Bibliothekselement verwenden.
  • Tags und gespeicherte Abfragen: keine; ihre Listen sind leer.
Methode und PfadWas sie tut
GET /sysml/projectsIhre SysML v2-Projekte
POST /sysml/projectsEin leeres SysML v2-Projekt erstellen (name, description)
GET /sysml/projects/<projectId>Ein Projekt mit seinem Standard-Branch
GET /sysml/projects/<projectId>/branchesmain und die Änderungsantrags-Branches
POST /sysml/projects/<projectId>/branchesEinen Branch erstellen: einen neuen Änderungsantrag im Status Draft (name ist sein Titel, description seine Begründung)
GET /sysml/projects/<projectId>/branches/<branchId>Der Branch (seine @id oder main), mit head
DELETE /sysml/projects/<projectId>/branches/<branchId>Den Änderungsantrag zurückziehen
GET /sysml/projects/<projectId>/commitsDie Heads und die an die Branches gesendeten Commits, neueste zuerst
POST /sysml/projects/<projectId>/commits?branchId=<branchId>Änderungen in einen Branch committen (unten)
GET /sysml/projects/<projectId>/commits/<commitId>Ein Head-Commit
GET /sysml/projects/<projectId>/commits/<commitId>/changesWas der Branch gegenüber dem Live-Modell ändert: ein DataVersion pro Element
GET /sysml/projects/<projectId>/commits/<commitId>/elementsAlle Elemente des Commits, seitenweise
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>Ein Element
GET /sysml/projects/<projectId>/commits/<commitId>/rootsDie Elemente der obersten Ebene, seitenweise
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>/relationshipsDie Beziehungen mit dem Element als Quelle oder Ziel; direction ist in, out oder both (Standard), seitenweise
POST /sysml/projects/<projectId>/query-resultsDie Elemente, die einer Abfrage entsprechen (Body unten), seitenweise; commitId muss ein Head sein
GET /sysml/projects/<projectId>/tags, /queries, /commits/<commitId>/elements/<elementId>/projectUsagesLeere Listen

Listenantworten sind JSON-Arrays. Listen werden seitenweise mit page[size] (Standard 100, höchstens 1000) und page[after] (die @id des letzten Eintrags der vorherigen Seite) oder page[before] (die @id des ersten Eintrags der nächsten Seite) abgerufen. Der Header Link gibt die nächste Seite mit rel="next" und die vorherige mit rel="prev" an.

Eine Abfrage ist ein JSON-Objekt mit einem optionalen where (ein PrimitiveConstraint mit property, operator (=, in, <, <=, >, >= oder instanceOf), value und inverse, oder ein CompositeConstraint mit operator and oder or und constraint), scope (Element-IDs: Die Suche umfasst sie und was sie besitzen) und select (die zurückzugebenden Eigenschaften; @id und @type kommen immer zurück):

curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  "https://app.holarch.app/api/v1/sysml/projects/<projectId>/query-results" \
  -d '{"@type": "Query", "where": {"@type": "PrimitiveConstraint", "property": "@type", "operator": "=", "value": "PartDefinition", "inverse": false}, "select": ["name", "qualifiedName"]}'

Die Elemente eines Modells lesen:

curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/sysml/projects
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/sysml/projects/<projectId>/branches/main
curl -i -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/sysml/projects/<projectId>/commits/<head id>/elements?page[size]=500"

Änderungen committen

Schreiben erfordert ein Token mit Lese- und Schreibzugriff, die Rolle Editor oder Owner, den Team-Tarif (auch für akademische und Kurskonten) und eingeschaltetes Branch-Review für das Projekt (Änderungsanträge → Einstellungen). Ein Genehmiger prüft den Änderungsantrag und wendet ihn in Holarch an; Token stimmen nie ab und wenden nie an.

  1. Einen Branch erstellen: POST /branches mit {"@type": "Branch", "name": "Cabin heater"}. Die Antwort ist der Branch mit seinem holarchChangeRequest.
  2. Den Head des Branches und seine Elemente lesen.
  3. POST /commits?branchId=<branch @id> mit einer Liste von DataVersions:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  "https://app.holarch.app/api/v1/sysml/projects/<projectId>/commits?branchId=<branch id>" \
  -d '{"@type": "Commit", "description": "Add the heater",
       "previousCommit": {"@id": "<head id>"},
       "change": [{"@type": "DataVersion", "identity": {"@id": "<new uuid>"},
                   "payload": {"@type": "PartDefinition", "declaredName": "CabinHeater", "owner": {"@id": "<package id>"}}}]}'
  • Ein Element ändern: Senden Sie das Element so, wie Sie es gelesen haben, mit den geänderten Eigenschaften. Nur eigene Eigenschaften zählen (declaredName, ownedRelationship, isAbstract und dergleichen); abgeleitete werden ignoriert, sodass das Zurücksenden des Gelesenen nichts ändert. Eine Eigenschaft, die Sie weglassen, behält ihren Wert; senden Sie null oder [], um sie zu leeren.
  • Neue Elemente: Geben Sie dem Element eine neue UUID und entweder seine besitzende Membership (im selben Commit gesendet) oder owner, das die Membership für Sie erstellt.
  • Ein Element entfernen: payload: null entfernt es mit allem, was es besitzt.
  • Prüfungen: Jedes Package, das der Commit berührt, muss sich erneut ausgeben und parsen lassen, und der Commit darf keine Fehlerdiagnosen hinzufügen; andernfalls 422 mit den zu behebenden diagnostics.
  • previousCommit: der Head, auf dem Ihre Änderung vorgenommen wurde. Wenn sich der Branch seitdem bewegt hat, lautet die Antwort 409 stale-head mit dem aktuellen head; lesen Sie erneut und committen Sie darauf.
  • Wiederholungen: Senden Sie einen Header Idempotency-Key. Eine Wiederholung mit demselben Schlüssel und Body innerhalb von 24 Stunden erhält erneut die erste Antwort.
  • Commits auf main: Ein Commit ohne branchId oder mit main geht in den eigenen Entwurfs-Änderungsantrag Ihres Tokens ("API changes from <token name>"), der beim ersten solchen Commit erstellt wird. Die Antwort nennt ihn in holarchChangeRequest und in einem Header Warning.
  • Neue Projekte: Ein mit POST /sysml/projects erstelltes Projekt hat Branch-Review eingeschaltet. Sein erster Commit auf main, solange Sie sein einziges Mitglied sind, wird einmalig direkt in das Modell geschrieben; spätere Commits laufen über Änderungsanträge.

Reichen Sie den Änderungsantrag mit POST /api/v1/projects/<project>/change-requests/<CR-12>/submit zur Prüfung ein (API und MCP). Tags, Merges und das Umbenennen oder Löschen eines Projekts antworten mit 405 und dem, was stattdessen zu tun ist. Fehler tragen @type Error und eine description, wie die OMG-API sie definiert.

Meldungen

Es gelten die Codes von API und MCP. SysML v2-Routen und -Werkzeuge ergänzen:

CodeStatusBedeutung
wrong-project-type409Ein LML-Vorgang in einem SysML v2-Projekt oder ein SysML v2-Vorgang in einem LML-Projekt
syntax422Der vorgeschlagene Text hat Syntaxfehler; die Diagnosen geben Zeile und Spalte an
invalid-model422Die Änderung fügt dem Modell Fehlerdiagnosen hinzu; sie werden aufgeführt
not-printable422Die Änderung kann nicht als SysML-Text geschrieben werden
invalid422Die Änderung konnte nicht auf das Modell angewendet werden
no-change400Der Text ändert das Modell nicht
too-large413Der Text ist länger als 1.000.000 Zeichen, oder der Vorschlag ist größer als 8 MB
too-many413 oder 409Mehr als 100 Bearbeitungen in einem Aufruf (413), oder der Vorschlag enthält bereits 200 Änderungen (409)
stale409Eine frühere Textänderung des Vorschlags lässt sich nicht mehr auf das Modell anwenden
not-found404Kein solches Projekt, Element, Branch oder Commit (die Systems Modeling API stellt nur Branch-Heads bereit)
not-writable405Tags, Merges, Umbenennen oder Löschen eines Projekts über die Systems Modeling API; tun Sie dies in Holarch
main-protected405Löschen von main; löschen Sie stattdessen einen Änderungsantrags-Branch
stale-head409Der Branch hat sich seit previousCommit bewegt; lesen Sie seinen head und committen Sie erneut
branch-base409Ein neuer Branch muss vom Head von main ausgehen
branch-review-off409Das Projekt verwendet kein Branch-Review; ein Owner schaltet es unter Änderungsanträge → Einstellungen ein
cr-not-draft409Der Änderungsantrag ist eingereicht oder geschlossen; er kann nur im Status Draft oder Rejected beschrieben werden
cr-full409Der Änderungsantrag enthält 5.000 geänderte Elemente, oder das Projekt 20 MB an Änderungsantragsentwürfen
plan-limit403Schreibzugriffe auf Änderungsanträge erfordern den Tarif Team
orphan422Ein neues Element hat keinen Besitzer; senden Sie seine besitzende Mitgliedschaft oder owner
unknown-metaclass422Der @type einer Nutzlast ist keine SysML-v2-Metaklasse
idempotency-key-reused422Der Idempotency-Key wurde mit einem anderen Body verwendet; senden Sie einen neuen Schlüssel
token-projects403Ein Token, das auf eine Liste von Projekten beschränkt ist, kann kein Projekt erstellen
bad-request400Ein fehlender oder falscher Wert, etwa ein root, das kein Package der obersten Ebene ist, ein unbekanntes op oder ein neues Element ohne Namen

Grenzen

WasGrenze
Elemente, Anforderungen oder Verbindungen pro Seite500
Mit einem Element aufgeführte Mitglieder200
Diagnosen pro Antwort500
Zeilen SysML-Text pro Antwort5.000 und höchstens 400.000 Byte (an einer Zeile abgeschnitten)
Doc-Text4.000 Zeichen in Listen, 20.000 für ein einzelnes Element
Der eigene SysML-Text eines Elements16.000 Zeichen
Text in einem propose_sysml-Aufruf1.000.000 Zeichen
Bearbeitungen in einem Aufruf100
Als hinzugefügt, geändert oder entfernt aufgeführte Elemente in einer Änderungje 300
Änderungen in einem Vorschlag200 und 8 MB
Seite der Systems Modeling API1.000 Elemente (Standard 100)
DataVersions in einem Commit5,000
Geänderte Elemente in einem Änderungsantrag5,000
Commit-Body32 MB

Ratenlimits, Anfragegröße und Token-Regeln sind die von API und MCP.

SysML® und OMG® sind eingetragene Marken der Object Management Group, Inc. in den Vereinigten Staaten und anderen Ländern.