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.
Auf dieser Seite
Ü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/mcpfü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 Branchmainist 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, etwaPartUsage),name,shortName,qualifiedNameundowner. - 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(erroroderwarning),elementId,elementundargs. Syntaxdiagnosen geben statt eines Elementslineundcolan. - 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, sagttruncated: 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
- Erstellen Sie ein Token unter Kontoeinstellungen → API-Token (siehe API und MCP).
- Listen Sie Ihre Projekte auf:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
SysML v2-Projekte haben "language": "sysml2".
- 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.
- 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"
- 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
- 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
- Lesen Sie die Antwort.
okisttrue, wenn der Text keine Syntaxfehler hat.diagnosticslistet Syntaxfehler mitlineundcolauf sowie die Fehler, die der Text dem Modell hinzufügen würde.changesist 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.
- 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).
- 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.
- 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
- Öffnen Sie in Holarch das Projekt und dann ✦ KI ▾ → „Add range attribute“ prüfen… (oder die Benachrichtigung unter der Glocke).
- 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
- Verbinden Sie das KI-Werkzeug mit
https://app.holarch.app/mcpüber ein Token oder über eine Anmeldung (siehe API und MCP). - 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_requirementsund die anderen Lesewerkzeuge. - Bitten Sie um eine Änderung, zum Beispiel „Propose a
rangeattribute onCar“.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. - 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.
GET /api/v1/projects/<project>/modellistet die Packages der obersten Ebene auf, darunterVehicles,HybridCarArchitectureundVehicleBehavior.GET /api/v1/projects/<project>/elements?query=Engine&type=part%20deffindetVehicles::Engine.GET /api/v1/projects/<project>/elements/Vehicles::Enginegibt die Part-Definition mit ihrem SysML-Text zurück, ihre Member (displacement,cylinders,maxPower, die PortsfuelIn,outputundecu) und die durch sie typisierten Usages.GET /api/v1/projects/<project>/elements/Vehicles::Car/connectionslistet das InterfacedriveShaftvonpowertrain.outputnachfrontAxle.inputauf.GET /api/v1/projects/<project>/requirements?status=unverifiedlistet die Anforderungen auf, die kein Verification Case verifiziert, mit ihren IDs wieVR-4.1.POST /api/v1/projects/<project>/proposal/changesmit{"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>/proposalmit einem Titel sendet ihn.- In Holarch zeigt ✦ KI ▾ → „…“ prüfen Geändert: mit der Part-Definition und dem Feld
docsowie den Textdiff vonVehicles. Auswahl anwenden wendet sie an.
Tipps
- Lesen Sie ein Package mit
get_sysml(oderGET …/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(oderPOST …/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 Pfad | Was sie tut |
|---|---|
GET /projects/<project>/model | Elementanzahlen pro Metaklasse, die Packages der obersten Ebene mit ihren Elementanzahlen und die Anzahl der Fehler und Warnungen |
GET /projects/<project>/elements | Suche: 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>/connections | Connections, 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>/requirements | Anforderungen mit ihrer ID, ihrem Statement (doc), satisfiedBy und verifiedBy; owner, status (unsatisfied oder unverified), limit (Standard 100), offset |
GET /projects/<project>/diagnostics | Die Diagnosen des Modells, Fehler zuerst; ids (kommagetrennt: nur diese Elemente und ihre Member), limit (Standard 200, höchstens 500) |
GET /projects/<project>/sysml | SysML-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/check | text als neuen Text von root (oder der Elemente außerhalb von Packages) prüfen; ändert nichts |
POST /projects/<project>/proposal/changes | Eine Änderung zum offenen Vorschlag hinzufügen: {text, root} oder {edits} |
GET /projects/<project>/proposal | Der offene Vorschlag oder einer über die proposal-ID, mit seinem Status und seinen Änderungen |
POST /projects/<project>/proposal | Den offenen Vorschlag zur Prüfung senden: title, summary |
DELETE /projects/<project>/proposal | Den 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
PartUsageoderRequirementDefinitionoder ein Schlüsselwort, wie es im SysML-Text geschrieben wird:part,part def,attribute,port,requirement,action,packageund die anderen Element-Schlüsselwörter. - owner, id, element, root: eine ID oder ein qualifizierter Name.
rootnimmt auch den Namen eines Packages der obersten Ebene an.rootmuss ein Package der obersten Ebene sein; um den Text eines einzelnen Elements zu lesen, verwenden Sieelement. - 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.
| Werkzeug | Zugriff | Was sie tut |
|---|---|---|
model_summary | Lesen | Elementanzahlen pro Metaklasse, die Packages der obersten Ebene und die Anzahl der Diagnosen |
list_elements | Lesen | Elemente über Text (query), type und owner finden; seitenweise mit limit und offset |
get_element | Lesen | Ein 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_connections | Lesen | Die Connections, Interfaces, Bindings, Flows, Successions, Transitions, Allocations und Dependencies eines Elements (id, limit) |
list_requirements | Lesen | Anforderungen mit ihrer ID, ihrem Statement, satisfy und verify; owner, status (unsatisfied, unverified), limit, offset |
get_sysml | Lesen | SysML-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_text | Lesen | SysML-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_sysml | Lesen | Ohne 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_sysml | Lesen und Schreiben | Den 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_changes | Lesen und Schreiben | edits (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:
| op | Felder |
|---|---|
create | kind (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) |
update | id und die zu ändernden Felder, wie bei create; null oder "" leert ein Feld |
move | id und der neue owner |
remove | id; entfernt das Element mit seinen Membern |
typedBy,specializes,subsetsundredefinessind Listen mit bis zu 20 Namen: IDs, qualifizierte Namen oder Namen, wie sie im Text geschrieben werden (Bibliotheksnamen wieMassValuefunktionieren).- 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 alsowner. Die Antwort listet sie untercreatedmit ihren neuen IDs auf. - Das Umbenennen eines Elements aktualisiert auch die Referenzen, die es mit seinem alten Namen benannten.
Vorgeschlagener Text
propose_sysmlersetzt 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
@ideines Projekts ist eine UUID, die diese API ihm gibt; die Holarch-Projekt-ID funktioniert ebenfalls. Die Antwort enthältholarchIdundurl. - Branches:
mainist das Live-Modell und kann über die API nicht geändert werden. Jeder andere Branch ist ein laufender Änderungsantrag, benannt "CR-12 Title" und mitholarchChangeRequest(id,label,status,url). Änderungsanträge, die in den letzten 30 Tagen umgesetzt oder zurückgezogen wurden, werden weiterhin aufgeführt, mit gesetztemdeleted. - Commits: Ein Commit schreibt Änderungen in den Branch eines Änderungsantrags. Nur Branch-Heads werden bereitgestellt: Der Head von
mainist das Live-Modell, der Head eines Änderungsantrags-Branches ist das Live-Modell mit den Änderungen des Antrags. Ältere Commit-IDs antworten mit404; 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,typeund 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 Pfad | Was sie tut |
|---|---|
GET /sysml/projects | Ihre SysML v2-Projekte |
POST /sysml/projects | Ein leeres SysML v2-Projekt erstellen (name, description) |
GET /sysml/projects/<projectId> | Ein Projekt mit seinem Standard-Branch |
GET /sysml/projects/<projectId>/branches | main und die Änderungsantrags-Branches |
POST /sysml/projects/<projectId>/branches | Einen 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>/commits | Die 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>/changes | Was der Branch gegenüber dem Live-Modell ändert: ein DataVersion pro Element |
GET /sysml/projects/<projectId>/commits/<commitId>/elements | Alle Elemente des Commits, seitenweise |
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId> | Ein Element |
GET /sysml/projects/<projectId>/commits/<commitId>/roots | Die Elemente der obersten Ebene, seitenweise |
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>/relationships | Die Beziehungen mit dem Element als Quelle oder Ziel; direction ist in, out oder both (Standard), seitenweise |
POST /sysml/projects/<projectId>/query-results | Die Elemente, die einer Abfrage entsprechen (Body unten), seitenweise; commitId muss ein Head sein |
GET /sysml/projects/<projectId>/tags, /queries, /commits/<commitId>/elements/<elementId>/projectUsages | Leere 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.
- Einen Branch erstellen: POST
/branchesmit{"@type": "Branch", "name": "Cabin heater"}. Die Antwort ist der Branch mit seinemholarchChangeRequest. - Den Head des Branches und seine Elemente lesen.
- POST
/commits?branchId=<branch @id>mit einer Liste vonDataVersions:
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,isAbstractund dergleichen); abgeleitete werden ignoriert, sodass das Zurücksenden des Gelesenen nichts ändert. Eine Eigenschaft, die Sie weglassen, behält ihren Wert; senden Sienulloder[], 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: nullentfernt 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
422mit den zu behebendendiagnostics. - previousCommit: der Head, auf dem Ihre Änderung vorgenommen wurde. Wenn sich der Branch seitdem bewegt hat, lautet die Antwort
409stale-headmit dem aktuellenhead; 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 ohnebranchIdoder mitmaingeht in den eigenen Entwurfs-Änderungsantrag Ihres Tokens ("API changes from <token name>"), der beim ersten solchen Commit erstellt wird. Die Antwort nennt ihn inholarchChangeRequestund in einem HeaderWarning. - Neue Projekte: Ein mit POST
/sysml/projectserstelltes Projekt hat Branch-Review eingeschaltet. Sein erster Commit aufmain, 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:
| Code | Status | Bedeutung |
|---|---|---|
wrong-project-type | 409 | Ein LML-Vorgang in einem SysML v2-Projekt oder ein SysML v2-Vorgang in einem LML-Projekt |
syntax | 422 | Der vorgeschlagene Text hat Syntaxfehler; die Diagnosen geben Zeile und Spalte an |
invalid-model | 422 | Die Änderung fügt dem Modell Fehlerdiagnosen hinzu; sie werden aufgeführt |
not-printable | 422 | Die Änderung kann nicht als SysML-Text geschrieben werden |
invalid | 422 | Die Änderung konnte nicht auf das Modell angewendet werden |
no-change | 400 | Der Text ändert das Modell nicht |
too-large | 413 | Der Text ist länger als 1.000.000 Zeichen, oder der Vorschlag ist größer als 8 MB |
too-many | 413 oder 409 | Mehr als 100 Bearbeitungen in einem Aufruf (413), oder der Vorschlag enthält bereits 200 Änderungen (409) |
stale | 409 | Eine frühere Textänderung des Vorschlags lässt sich nicht mehr auf das Modell anwenden |
not-found | 404 | Kein solches Projekt, Element, Branch oder Commit (die Systems Modeling API stellt nur Branch-Heads bereit) |
not-writable | 405 | Tags, Merges, Umbenennen oder Löschen eines Projekts über die Systems Modeling API; tun Sie dies in Holarch |
main-protected | 405 | Löschen von main; löschen Sie stattdessen einen Änderungsantrags-Branch |
stale-head | 409 | Der Branch hat sich seit previousCommit bewegt; lesen Sie seinen head und committen Sie erneut |
branch-base | 409 | Ein neuer Branch muss vom Head von main ausgehen |
branch-review-off | 409 | Das Projekt verwendet kein Branch-Review; ein Owner schaltet es unter Änderungsanträge → Einstellungen ein |
cr-not-draft | 409 | Der Änderungsantrag ist eingereicht oder geschlossen; er kann nur im Status Draft oder Rejected beschrieben werden |
cr-full | 409 | Der Änderungsantrag enthält 5.000 geänderte Elemente, oder das Projekt 20 MB an Änderungsantragsentwürfen |
plan-limit | 403 | Schreibzugriffe auf Änderungsanträge erfordern den Tarif Team |
orphan | 422 | Ein neues Element hat keinen Besitzer; senden Sie seine besitzende Mitgliedschaft oder owner |
unknown-metaclass | 422 | Der @type einer Nutzlast ist keine SysML-v2-Metaklasse |
idempotency-key-reused | 422 | Der Idempotency-Key wurde mit einem anderen Body verwendet; senden Sie einen neuen Schlüssel |
token-projects | 403 | Ein Token, das auf eine Liste von Projekten beschränkt ist, kann kein Projekt erstellen |
bad-request | 400 | Ein fehlender oder falscher Wert, etwa ein root, das kein Package der obersten Ebene ist, ein unbekanntes op oder ein neues Element ohne Namen |
Grenzen
| Was | Grenze |
|---|---|
| Elemente, Anforderungen oder Verbindungen pro Seite | 500 |
| Mit einem Element aufgeführte Mitglieder | 200 |
| Diagnosen pro Antwort | 500 |
| Zeilen SysML-Text pro Antwort | 5.000 und höchstens 400.000 Byte (an einer Zeile abgeschnitten) |
| Doc-Text | 4.000 Zeichen in Listen, 20.000 für ein einzelnes Element |
| Der eigene SysML-Text eines Elements | 16.000 Zeichen |
Text in einem propose_sysml-Aufruf | 1.000.000 Zeichen |
| Bearbeitungen in einem Aufruf | 100 |
| Als hinzugefügt, geändert oder entfernt aufgeführte Elemente in einer Änderung | je 300 |
| Änderungen in einem Vorschlag | 200 und 8 MB |
| Seite der Systems Modeling API | 1.000 Elemente (Standard 100) |
| DataVersions in einem Commit | 5,000 |
| Geänderte Elemente in einem Änderungsantrag | 5,000 |
| Commit-Body | 32 MB |
Ratenlimits, Anfragegröße und Token-Regeln sind die von API und MCP.
Verwandte Seiten
- API und MCP
- Erste Schritte mit SysML v2-Projekten
- Texteditor und Browser
- SysML v2-Modelle austauschen
- Anforderungen und Verifikation in SysML v2-Projekten
SysML® und OMG® sind eingetragene Marken der Object Management Group, Inc. in den Vereinigten Staaten und anderen Ländern.