SysML v2
L'API et MCP dans les projets SysML v2
Lisez, recherchez et contrôlez des modèles SysML v2 depuis des scripts et des outils d'IA avec un jeton d'accès personnel, proposez des modifications que vous examinez et appliquez dans Holarch, et lisez et validez via la Systems Modeling API, où les branches sont des demandes de modification.
Sur cette page
Vue d'ensemble
Les projets SysML v2 fonctionnent avec la même API REST, le même point de terminaison MCP et les mêmes jetons d'accès personnels que les projets LML. Les scripts et les outils d'IA lisent le modèle sous forme d'éléments et de texte SysML, contrôlent le texte avant de modifier quoi que ce soit, et proposent des modifications. Rien ne change dans le modèle tant qu'une personne n'a pas examiné la proposition dans Holarch et ne l'a pas appliquée.
Trois points d'accès :
- API REST :
https://app.holarch.app/api/v1/projects/<project>/…pour les scripts et les tableaux de bord. Elle lit les éléments, les exigences, les diagnostics et le texte SysML, et ajoute des modifications à une proposition. - MCP :
https://app.holarch.app/mcppour les outils d'IA tels que Claude. Les outils SysML v2 lisent, recherchent et contrôlent le modèle et proposent des modifications. - API Systems Modeling :
https://app.holarch.app/api/v1/sysml/…, aux formats de l'OMG Systems Modeling API, pour les autres outils SysML v2. La branchemainest le modèle en service et est en lecture seule ; toute autre branche est une demande de modification, et les commits y sont ajoutés. Le modèle en service ne change que lorsqu'un approbateur applique la demande de modification dans Holarch.
Les jetons, portées, listes de projets, le changement d'organisation, les limites de débit et la connexion de Claude sont les mêmes que pour les projets LML. Voir API et MCP pour créer un jeton et connecter un outil d'IA. Les appels de la Carte de programme (GET /api/v1/program-map, GET /api/v1/projects/<project>/items/<item>/trace, et les outils MCP program_map et trace_chain) incluent les projets SysML v2 et leurs éléments.
Concepts
- Élément : un élément du modèle SysML v2, comme une définition de part, un port ou une exigence. Chaque élément a un id (un UUID). Partout où une route ou un outil demande un id, un nom qualifié tel que
Vehicles::Car::powertrainfonctionne aussi. - Forme brève : la forme courte d'un élément dans les listes :
id,type(la métaclasse, commePartUsage),name,shortName,qualifiedNameetowner. - Package de premier niveau : un package qui n'est pas à l'intérieur d'un autre élément. Le texte SysML d'un projet est un texte par package de premier niveau, plus un texte pour les éléments hors des packages.
- Diagnostic : un problème que trouve le cœur du langage, avec
code,severity(errorouwarning),elementId,elementetargs. Les diagnostics de syntaxe donnentlineetcolau lieu d'un élément. - Proposition : les modifications qu'un client API ou un outil d'IA rassemble pour revue. Une seule proposition est ouverte par jeton et par projet. Le client l'envoie en revue avec un titre et un résumé.
- Réponses paginées : les listes arrivent par pages (
limit,offset). Un long texte SysML arrive par pages de lignes (line,lines). Une réponse qui a omis quelque chose indiquetruncated: true.
Mode d'emploi
Utilisez l'API lorsqu'un script ou un outil d'IA a besoin du modèle : pour signaler les exigences sans éléments qui les satisfont ou les vérifient, pour contrôler le texte SysML d'une équipe par rapport au modèle, ou pour laisser un outil d'IA rédiger des modifications du modèle qu'un ingénieur examine ensuite.
Lire un projet SysML v2 avec curl
- Créez un jeton sous Paramètres du compte → Jetons API (voir API et MCP).
- Listez vos projets :
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
Les projets SysML v2 ont "language": "sysml2".
- Obtenez le résumé du modèle :
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects/<project>/model
Vous voyez le nombre d'éléments par métaclasse, les packages de premier niveau et le nombre d'erreurs et d'avertissements.
- Trouvez des éléments, par exemple chaque définition de part :
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/elements?type=part%20def&limit=100"
- Lisez le texte SysML d'un package :
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/sysml?root=Vehicles"
Un long texte se termine par "truncated": true et "next" : la ligne à demander ensuite avec line.
Contrôler le texte SysML avant de le proposer
- Envoyez le nouveau texte d'un package à la route de contrôle :
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
- Lisez la réponse.
okvauttruelorsque le texte n'a pas d'erreurs de syntaxe.diagnosticsliste les erreurs de syntaxe aveclineetcol, et les erreurs que le texte ajouterait au modèle.changesest le nombre de modifications du modèle que le texte produit.
Le contrôle ne modifie rien. Il ne demande qu'un jeton de lecture.
Proposer une modification et l'appliquer
Un jeton d'écriture ajoute des modifications à la proposition ouverte du jeton. Le client envoie ensuite la proposition en revue.
- Ajoutez une modification. Envoyez soit le nouveau texte complet d'un package, soit des modifications d'éléments :
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
Vous obtenez 201 avec la proposition, le résumé de la modification et les éléments qu'elle ajoute, modifie et supprime. Une modification qui ajoute des diagnostics d'erreur est refusée (voir Propositions dans les projets SysML v2).
- Ajoutez d'autres modifications de la même façon. Chaque modification est contrôlée par rapport au modèle avec les modifications précédentes de la proposition appliquées.
- Envoyez la proposition en revue :
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
- Dans Holarch, ouvrez le projet, puis ouvrez ✦ IA ▾ → Examiner « Add range attribute »… (ou la notification sous la cloche).
- Vérifiez les lignes et cliquez sur Appliquer la sélection.
Les modifications cochées sont appliquées avec votre nom dans l'historique, et une seule annulation défait le tout.
Connecter un outil d'IA à un projet SysML v2
- Connectez l'outil d'IA à
https://app.holarch.app/mcpavec un jeton ou par connexion (voir API et MCP). - Posez une question sur le modèle, par exemple « Résume le modèle Hybrid Car dans Holarch » ou « Quelles exigences du projet Hybrid Car ne sont pas vérifiées ? ».
L'outil d'IA utilise
model_summary,list_elements,list_requirementset les autres outils de lecture. - Demandez une modification, par exemple « Propose un attribut
rangesurCar».L'outil d'IA lit le package avec
get_sysml, propose du texte ou des modifications d'éléments, et corrige les diagnostics que renvoie le contrôle. - Examinez la proposition dans Holarch et cliquez sur Appliquer la sélection.
Exemple commenté : la démo Hybrid Car
Créez la démo avec Gérer les projets → Fichiers de projet ▾ → Nouveau projet de démonstration → Hybrid Car (SysML v2), puis créez un jeton de lecture et d'écriture pour celle-ci.
GET /api/v1/projects/<project>/modelliste les packages de premier niveau, parmi lesquelsVehicles,HybridCarArchitectureetVehicleBehavior.GET /api/v1/projects/<project>/elements?query=Engine&type=part%20deftrouveVehicles::Engine.GET /api/v1/projects/<project>/elements/Vehicles::Enginerenvoie la définition de part avec son texte SysML, ses membres (displacement,cylinders,maxPower, les portsfuelIn,outputetecu) et les usages typés par elle.GET /api/v1/projects/<project>/elements/Vehicles::Car/connectionsliste l'interfacedriveShaftdepowertrain.outputversfrontAxle.input.GET /api/v1/projects/<project>/requirements?status=unverifiedliste les exigences qu'aucun cas de vérification ne vérifie, avec leurs id tels queVR-4.1.POST /api/v1/projects/<project>/proposal/changesavec{"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]}ajoute la modification à la proposition.POST /api/v1/projects/<project>/proposalavec un titre l'envoie.- Dans Holarch, ✦ IA ▾ → Examiner « … » affiche Modifié : avec la définition de part et le champ
doc, ainsi que le diff de texte deVehicles. Appliquer la sélection l'applique.
Conseils
- Lisez un package avec
get_sysml(ouGET …/sysml?root=) avant de proposer un nouveau texte pour lui. Les éléments absents du texte proposé sont supprimés. - Préférez les modifications d'éléments pour les petites modifications. Elles ne changent que les éléments nommés et gardent le reste du texte du package tel quel.
- Contrôlez d'abord le texte avec
check_sysml(ouPOST …/sysml/check). Il renvoie les mêmes diagnostics que ceux qui feraient refuser une proposition. - Dans les scripts, nommez les éléments par leur nom qualifié. Les id restent les mêmes lorsqu'un élément est renommé ; les noms qualifiés, non.
- Donnez à un outil d'IA un jeton en lecture seule lorsqu'il ne fait que répondre à des questions sur le modèle.
Routes REST pour les projets SysML v2
Adresse de base : https://app.holarch.app/api/v1. Les réponses sont en JSON. /api/v1/openapi.json (OpenAPI 3.1) décrit ces routes avec les autres.
| Méthode et chemin | Ce qu'il fait |
|---|---|
GET /projects/<project>/model | Nombre d'éléments par métaclasse, les packages de premier niveau avec leur nombre d'éléments, et le nombre d'erreurs et d'avertissements |
GET /projects/<project>/elements | Recherche : query (ou q ; texte dans le nom, le nom court, le nom qualifié ou la doc), type, owner, limit (1–500, 50 par défaut), offset ; trié par nom qualifié |
GET /projects/<project>/elements/<id> | Un élément avec ses champs, sa doc, son texte SysML, ses membres et les usages typés par lui ; members (0–200, 100 par défaut) |
GET /projects/<project>/elements/<id>/connections | Connexions, interfaces, liaisons, flux (avec l'item), successions, transitions, allocations et dépendances sur l'élément ou ses features, et celles possédées à l'intérieur ; limit (100 par défaut) |
GET /projects/<project>/requirements | Exigences avec leur id, leur énoncé (doc), satisfiedBy et verifiedBy ; owner, status (unsatisfied ou unverified), limit (100 par défaut), offset |
GET /projects/<project>/diagnostics | Les diagnostics du modèle, les erreurs en premier ; ids (séparés par des virgules : seulement ces éléments et leurs membres), limit (200 par défaut, au plus 500) |
GET /projects/<project>/sysml | Texte SysML d'un package de premier niveau (root), des éléments hors des packages (sans root), ou d'un élément (element) ; line (première ligne, à partir de 1), lines (2000 par défaut, au plus 5000) |
POST /projects/<project>/sysml/check | Contrôler text comme nouveau texte de root (ou des éléments hors des packages) ; ne modifie rien |
POST /projects/<project>/proposal/changes | Ajouter une modification à la proposition ouverte : {text, root} ou {edits} |
GET /projects/<project>/proposal | La proposition ouverte, ou une proposition par son id proposal, avec son statut et ses modifications |
POST /projects/<project>/proposal | Envoyer la proposition ouverte en revue : title, summary |
DELETE /projects/<project>/proposal | Abandonner la proposition ouverte avant son envoi |
GET /projects et GET /projects/<project> fonctionnent aussi pour les projets SysML v2. Ils donnent "language": "sysml2", et la réponse du projet ajoute elements et types (nombre d'éléments par métaclasse).
Les routes d'entités LML (/entities, /relationships, /schema, les contrôles du modèle et le contrôle qualité) répondent 409 wrong-project-type dans un projet SysML v2. Les routes SysML v2 répondent de même dans un projet LML.
Valeurs
- type : une métaclasse telle que
PartUsageouRequirementDefinition, ou un mot-clé tel qu'il s'écrit dans le texte SysML :part,part def,attribute,port,requirement,action,packageet les autres mots-clés d'éléments. - owner, id, element, root : un id ou un nom qualifié.
rootaccepte aussi le nom d'un package de premier niveau.rootdoit être un package de premier niveau ; pour lire le texte d'un élément, utilisezelement. - Valeurs longues : une doc dans une liste est coupée à 4 000 caractères, la doc d'un élément seul à 20 000, et le texte SysML propre d'un élément à 16 000 caractères.
Outils MCP pour les projets SysML v2
Le point de terminaison MCP liste ces outils à côté des outils LML. Un outil d'IA trouve les projets SysML v2 avec list_projects (language: sysml2). Chaque outil prend project.
Les outils de lecture acceptent aussi un change_request facultatif (CR-12 ou son id) pour lire le modèle tel que cette demande de modification le rendrait ; propose_sysml et propose_element_changes en acceptent un pour calculer la modification par rapport au modèle de la demande et l'appliquer dans ce brouillon après revue. Voir Demandes de modification pour les règles.
| Outil | Accès | Ce qu'il fait |
|---|---|---|
model_summary | Lecture | Nombre d'éléments par métaclasse, les packages de premier niveau et le nombre de diagnostics |
list_elements | Lecture | Trouver des éléments par texte (query), type et owner ; paginé avec limit et offset |
get_element | Lecture | Un élément (id) avec ses types, spécialisations, multiplicité, valeur, extrémités, doc, texte SysML, membres (members, au plus 200) et les usages typés par lui |
get_connections | Lecture | Les connexions, interfaces, liaisons, flux, successions, transitions, allocations et dépendances d'un élément (id, limit) |
list_requirements | Lecture | Exigences avec leur id, leur énoncé, satisfy et verify ; owner, status (unsatisfied, unverified), limit, offset |
get_sysml | Lecture | Texte SysML d'un package de premier niveau (root), des éléments hors des packages, ou d'un élément (element) ; line, lines (au plus 5000) ; la réponse donne next |
get_sysml_text | Lecture | Texte SysML du modèle entier (chaque package de premier niveau, puis les éléments hors des packages) ou d'un package, jusqu'à 200 000 caractères par réponse ; la réponse nomme les packages omis |
check_sysml | Lecture | Sans text : les diagnostics du modèle (ids, limit). Avec text (et root) : les erreurs de syntaxe avec ligne et colonne, et les erreurs que le texte ajouterait. Ne modifie rien |
propose_sysml | Lecture et écriture | Proposer le nouveau text complet d'un package de premier niveau (root), ou des éléments hors des packages (sans root ; c'est aussi là que va un nouveau package) |
propose_element_changes | Lecture et écriture | Proposer des edits (au plus 100) sans réécrire de texte : create, update, move ou remove |
list_diagrams, get_diagram et get_matrix fonctionnent aussi dans les projets SysML v2 : list_diagrams liste les vues (avec leur genre, comme InterconnectionView) et les diagrammes d'analyse conservés sous un élément ; get_diagram donne les éléments qu'une vue expose après ses filtres (par id d'élément ou nom qualifié) ; get_matrix donne chaque exigence avec ce qui la satisfait et la vérifie.
Les outils de proposition des projets LML fonctionnent de la même façon ici : propose_changes envoie la proposition avec un titre et un résumé, discard_proposal l'abandonne, et get_proposal et list_proposals affichent son statut. Un jeton en lecture seule ne liste que les outils de lecture.
Les erreurs d'outil reviennent sous forme de résultat d'outil avec le message et les diagnostics, afin que l'outil d'IA puisse corriger son texte et réessayer.
Modifications d'éléments
Chaque modification dans edits (MCP) ou {"edits": […]} (REST) est un objet avec op :
| op | Champs |
|---|---|
create | kind (un mot-clé tel que part, part def, attribute, port, requirement, action, package) ou type (une métaclasse) ; owner (omis : premier niveau) ; name (obligatoire) ; facultatifs shortName, typedBy, specializes, subsets, redefines, multiplicity, value, doc, direction (in, out, inout) |
update | id et les champs à modifier, comme pour create ; null ou "" vide un champ |
move | id et le nouveau owner |
remove | id ; supprime l'élément avec ses membres |
typedBy,specializes,subsetsetredefinessont des listes de 20 noms au plus : des id, des noms qualifiés ou des noms tels qu'écrits dans le texte (les noms de bibliothèque commeMassValuefonctionnent).- Les modifications suivantes peuvent nommer les éléments créés plus tôt dans le même appel
new:1,new:2… dans l'ordre de leur création, par exemple commeowner. La réponse les liste souscreatedavec leurs nouveaux id. - Renommer un élément met aussi à jour les références qui le nommaient par son ancien nom.
Texte proposé
propose_sysmlremplace tout le texte du package. Les éléments gardent leurs id là où le texte les déclare encore. Les éléments absents du texte sont supprimés.- Le texte doit s'analyser sans que rien ne reste non appliqué. Un texte qui ne modifie pas le modèle est refusé (
no-change).
Propositions dans les projets SysML v2
Chaque modification proposée est contrôlée par le cœur du langage avant de rejoindre la proposition :
- Le texte s'analyse sans erreur de syntaxe, et les modifications d'éléments s'appliquent.
- Les packages modifiés s'impriment toujours en texte SysML et s'analysent à nouveau.
- La modification n'ajoute aucun diagnostic d'erreur au modèle, comme des noms non résolus ou des erreurs de type. Les erreurs que le modèle avait déjà ne comptent pas.
Une modification qui échoue est refusée avec les diagnostics (jusqu'à 50) à corriger. Rien n'est stocké. Les avertissements ne font pas refuser une modification.
Proposer exige un jeton de lecture et d'écriture et le rôle d'éditeur ou de propriétaire dans le projet. Une proposition contient au plus 200 modifications et 8 Mo.
Examiner une proposition SysML v2
Ouvrez le projet, puis ✦ IA ▾ → Examiner « <title> »…. Chaque modification est une ligne avec une case à cocher :
- Ajouté, Modifié et Retiré listent les éléments, avec les champs modifiés (les 20 premiers de chaque ; « et n de plus » pour le reste).
- Un diff de texte, étiqueté avec le package, affiche le texte SysML avant et après.
- Une modification qui supprime des éléments est signalée et démarre décochée.
- Ouvrez le modèle SysML v2 pour appliquer cette modification. Le modèle n'est pas chargé ; ouvrez une page SysML v2 du projet.
- Le package ne fait plus partie du modèle ; ignoré. Le package a été supprimé après que la modification a été proposée.
Appliquer la sélection resynchronise chaque modification de texte avec le modèle actuel et garde les modifications dont les éléments existent encore. Il contrôle l'ensemble et l'applique en une étape d'annulation. Les modifications qui ne conviennent plus sont ignorées et nommées dans un message. Refuser et Plus tard fonctionnent comme pour les propositions LML, de même que les rôles, l'expiration (7 jours) et la conservation (voir Propositions des clients d'IA).
Systems Modeling API
D'autres outils SysML v2 lisent et modifient les modèles Holarch par des routes aux formats de l'OMG Systems Modeling API (REST/HTTP). L'adresse de base est https://app.holarch.app/api/v1/sysml. Elle utilise les mêmes jetons ; tout rôle de projet peut lire, et les éditeurs et propriétaires peuvent faire des commits.
- Projets : seuls les projets SysML v2 sont listés. Le
@idd'un projet est un UUID que lui attribue cette API ; l'id de projet Holarch fonctionne aussi. La réponse inclutholarchIdeturl. - Branches :
mainest le modèle en service et ne peut pas être modifié par l'API. Toute autre branche est une demande de modification en cours, nommée « CR-12 Title » et portantholarchChangeRequest(id,label,status,url). Les demandes de modification mises en œuvre ou retirées au cours des 30 derniers jours sont encore listées, avecdeletedrenseigné. - Commits : un commit écrit des modifications dans la branche d'une demande de modification. Seules les têtes de branches sont servies : la tête de
mainest le modèle en service, la tête d'une branche de demande de modification est le modèle en service avec les modifications de la demande. Les id de commits plus anciens répondent404; obtenez la tête actuelle depuis la branche. - Éléments : chaque élément a toutes les propriétés de sa métaclasse dans le schéma JSON de l'OMG, propriétés dérivées comprises (
owner,ownedElement,qualifiedName,feature,typeet autres). Les éléments de la bibliothèque standard sont référencés par leurs id standard, ceux que les autres outils SysML v2 utilisent pour le même élément de bibliothèque. - Étiquettes et requêtes enregistrées : aucune ; leurs listes sont vides.
| Méthode et chemin | Ce qu'il fait |
|---|---|
GET /sysml/projects | Vos projets SysML v2 |
POST /sysml/projects | Créer un projet SysML v2 vide (name, description) |
GET /sysml/projects/<projectId> | Un projet, avec sa branche par défaut |
GET /sysml/projects/<projectId>/branches | main et les branches de demandes de modification |
POST /sysml/projects/<projectId>/branches | Créer une branche : une nouvelle demande de modification en Draft (name est son titre, description son motif) |
GET /sysml/projects/<projectId>/branches/<branchId> | La branche (son @id ou main), avec head |
DELETE /sysml/projects/<projectId>/branches/<branchId> | Retirer la demande de modification |
GET /sysml/projects/<projectId>/commits | Les têtes et les commits envoyés aux branches, les plus récents en premier |
POST /sysml/projects/<projectId>/commits?branchId=<branchId> | Valider des modifications dans une branche (ci-dessous) |
GET /sysml/projects/<projectId>/commits/<commitId> | Un commit de tête |
GET /sysml/projects/<projectId>/commits/<commitId>/changes | Ce que la branche modifie par rapport au modèle en service : un DataVersion par élément |
GET /sysml/projects/<projectId>/commits/<commitId>/elements | Tous les éléments du commit, paginés |
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId> | Un élément |
GET /sysml/projects/<projectId>/commits/<commitId>/roots | Les éléments de premier niveau, paginés |
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>/relationships | Les relations dont l'élément est la source ou la cible ; direction vaut in, out ou both (par défaut), paginées |
POST /sysml/projects/<projectId>/query-results | Les éléments qui correspondent à une requête (corps ci-dessous), paginés ; commitId doit être une tête |
GET /sysml/projects/<projectId>/tags, /queries, /commits/<commitId>/elements/<elementId>/projectUsages | Listes vides |
Les réponses en liste sont des tableaux JSON. Les listes sont paginées avec page[size] (100 par défaut, au plus 1000) et page[after] (le @id du dernier élément de la page précédente) ou page[before] (le @id du premier élément de la page suivante). L'en-tête Link donne la page suivante avec rel="next" et la précédente avec rel="prev".
Une requête est un objet JSON avec un where facultatif (une PrimitiveConstraint avec property, operator (=, in, <, <=, >, >= ou instanceOf), value et inverse, ou une CompositeConstraint avec operator and ou or et constraint), scope (des id d'éléments : la recherche couvre ces éléments et ce qu'ils possèdent) et select (les propriétés à renvoyer ; @id et @type sont toujours renvoyés) :
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"]}'
Lisez les éléments d'un modèle :
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"
Valider des modifications (commit)
L'écriture exige un jeton avec accès en lecture et en écriture, le rôle d'éditeur ou de propriétaire, l'offre Team (aussi pour les comptes académiques et de classe), et la revue de branche activée pour le projet (Demandes de modification → Paramètres). Un approbateur examine et applique la demande de modification dans Holarch ; les jetons ne votent ni n'appliquent jamais.
- Créez une branche : POST
/branchesavec{"@type": "Branch", "name": "Cabin heater"}. La réponse est la branche avec sonholarchChangeRequest. - Lisez la tête de la branche et ses éléments.
- POST
/commits?branchId=<branch @id>avec une liste deDataVersion:
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>"}}}]}'
- Modifier un élément : envoyez l'élément tel que vous l'avez lu, avec les propriétés modifiées. Seules les propriétés possédées comptent (
declaredName,ownedRelationship,isAbstractet autres) ; les propriétés dérivées sont ignorées, de sorte que renvoyer ce que vous avez lu ne modifie rien. Une propriété que vous omettez garde sa valeur ; envoyeznullou[]pour la vider. - Nouveaux éléments : donnez à l'élément un nouvel UUID et soit son membership propriétaire (envoyé dans le même commit), soit
owner, qui crée le membership pour vous. - Supprimer un élément :
payload: nullle supprime avec tout ce qu'il possède. - Contrôles : chaque package que touche le commit doit s'imprimer et s'analyser à nouveau, et le commit ne doit pas ajouter de diagnostics d'erreur ; sinon
422avec lesdiagnosticsà corriger. - previousCommit : la tête sur laquelle votre modification a été faite. Si la branche a avancé depuis, la réponse est
409stale-headavec laheadactuelle ; relisez et faites votre commit par-dessus. - Nouvelles tentatives : envoyez un en-tête
Idempotency-Key. Une nouvelle tentative avec la même clé et le même corps dans les 24 heures obtient à nouveau la première réponse. - Commits vers
main: un commit sansbranchId, ou avecmain, va dans la demande de modification brouillon propre à votre jeton (« API changes from <token name> »), créée au premier commit de ce type. La réponse indique laquelle dansholarchChangeRequestet dans un en-têteWarning. - Nouveaux projets : un projet créé avec POST
/sysml/projectsa la revue de branche activée. Son premier commit versmain, tant que vous en êtes le seul membre, est écrit directement dans le modèle, une seule fois ; les commits suivants passent par des demandes de modification.
Soumettez la demande de modification en revue avec POST /api/v1/projects/<project>/change-requests/<CR-12>/submit (API et MCP). Les étiquettes, les fusions et le renommage ou la suppression d'un projet répondent 405 avec ce qu'il faut faire à la place. Les erreurs portent @type Error et une description, comme les définit l'API de l'OMG.
Messages
Les codes d'API et MCP s'appliquent. Les routes et outils SysML v2 ajoutent :
| Code | Statut | Signification |
|---|---|---|
wrong-project-type | 409 | Une opération LML dans un projet SysML v2, ou une opération SysML v2 dans un projet LML |
syntax | 422 | Le texte proposé a des erreurs de syntaxe ; les diagnostics donnent la ligne et la colonne |
invalid-model | 422 | La modification ajoute des diagnostics d'erreur au modèle ; ils sont listés |
not-printable | 422 | La modification ne peut pas être écrite en texte SysML |
invalid | 422 | La modification n'a pas pu être appliquée au modèle |
no-change | 400 | Le texte ne modifie pas le modèle |
too-large | 413 | Le texte dépasse 1 000 000 de caractères, ou la proposition dépasse 8 Mo |
too-many | 413 ou 409 | Plus de 100 modifications en un appel (413), ou la proposition contient déjà 200 modifications (409) |
stale | 409 | Une modification de texte antérieure de la proposition ne s'applique plus au modèle |
not-found | 404 | Aucun projet, élément, branche ou commit de ce nom (l'API Systems Modeling ne sert que les têtes de branches) |
not-writable | 405 | Étiquettes, fusions, renommage ou suppression d'un projet par l'API Systems Modeling ; faites-le dans Holarch |
main-protected | 405 | Suppression de main ; supprimez plutôt une branche de demande de modification |
stale-head | 409 | La branche a avancé depuis previousCommit ; lisez sa head et refaites le commit |
branch-base | 409 | Une nouvelle branche doit partir de la tête de main |
branch-review-off | 409 | Le projet n'utilise pas la revue de branche ; un propriétaire l'active dans Demandes de modification → Paramètres |
cr-not-draft | 409 | La demande de modification est soumise ou close ; elle ne peut être écrite qu'en Draft ou Rejected |
cr-full | 409 | La demande de modification contient 5 000 éléments modifiés, ou le projet 20 Mo de brouillons de demandes de modification |
plan-limit | 403 | L'écriture dans les demandes de modification exige l'offre Team |
orphan | 422 | Un nouvel élément n'a pas de propriétaire ; envoyez son membership propriétaire ou owner |
unknown-metaclass | 422 | Le @type d'une charge utile n'est pas une métaclasse SysML v2 |
idempotency-key-reused | 422 | La Idempotency-Key a été utilisée avec un autre corps ; envoyez une nouvelle clé |
token-projects | 403 | Un jeton limité à une liste de projets ne peut pas créer de projet |
bad-request | 400 | Une valeur manquante ou erronée, comme un root qui n'est pas un package de premier niveau, un op inconnu ou un nouvel élément sans nom |
Limites
| Quoi | Limite |
|---|---|
| Éléments, exigences ou connexions par page | 500 |
| Membres listés avec un élément | 200 |
| Diagnostics par réponse | 500 |
| Lignes de texte SysML par réponse | 5 000, et au plus 400 000 octets (coupé à une ligne) |
| Texte de doc | 4 000 caractères dans les listes, 20 000 pour un élément |
| Le texte SysML propre d'un élément | 16 000 caractères |
Texte dans un appel propose_sysml | 1 000 000 de caractères |
| Modifications par appel | 100 |
| Éléments listés comme ajoutés, modifiés ou supprimés dans une modification | 300 chacun |
| Modifications dans une proposition | 200, et 8 Mo |
| Page de l'API Systems Modeling | 1 000 éléments (100 par défaut) |
| DataVersions dans un commit | 5,000 |
| Éléments modifiés dans une demande de modification | 5,000 |
| Corps du commit | 32 Mo |
Les limites de débit, la taille des requêtes et les règles des jetons sont celles d'API et MCP.
Pages associées
- API et MCP
- Bien démarrer avec les projets SysML v2
- L'éditeur de texte et le navigateur
- Échanger des modèles SysML v2
- Exigences et vérification dans les projets SysML v2
SysML® et OMG® sont des marques déposées d'Object Management Group, Inc. aux États-Unis et dans d'autres pays.