SysML v2
API e MCP nei progetti SysML v2
Leggere, cercare e controllare i modelli SysML v2 da script e strumenti di IA con un token di accesso personale, proporre modifiche da rivedere e applicare in Holarch, e leggere e salvare tramite la Systems Modeling API, dove i rami sono richieste di modifica.
In questa pagina
Panoramica
I progetti SysML v2 funzionano con la stessa REST API, lo stesso endpoint MCP e gli stessi token di accesso personali dei progetti LML. Script e strumenti di IA leggono il modello come elementi e testo SysML, controllano il testo prima di modificare qualsiasi cosa e propongono modifiche. Nulla nel modello cambia finché una persona non revisiona la proposta in Holarch e la applica.
Tre modi di accesso:
- REST API:
https://app.holarch.app/api/v1/projects/<project>/…per script e dashboard. Legge elementi, requisiti, diagnostica e testo SysML e aggiunge modifiche a una proposta. - MCP:
https://app.holarch.app/mcpper strumenti di IA come Claude. Gli strumenti SysML v2 leggono, cercano e controllano il modello e propongono modifiche. - Systems Modeling API:
https://app.holarch.app/api/v1/sysml/…, nelle forme della OMG Systems Modeling API per altri strumenti SysML v2. Il ramomainè il modello attivo ed è di sola lettura; ogni altro ramo è una richiesta di modifica e i commit vanno lì. Il modello attivo cambia solo quando un approvatore applica la richiesta di modifica in Holarch.
Token, ambiti, elenchi di progetti, il selettore dell'organizzazione, i limiti di frequenza e la connessione di Claude sono gli stessi dei progetti LML. Vedere API e MCP per creare un token e collegare uno strumento di IA. Le chiamate della Mappa del programma (GET /api/v1/program-map, GET /api/v1/projects/<project>/items/<item>/trace e gli strumenti MCP program_map e trace_chain) includono i progetti SysML v2 e i loro elementi.
Concetti
- Elemento: un elemento del modello SysML v2, come una definizione di parte, una porta o un requisito. Ogni elemento ha un id (un UUID). Ovunque una route o uno strumento chieda un id, funziona anche un nome qualificato come
Vehicles::Car::powertrain. - Forma breve: la forma breve di un elemento negli elenchi:
id,type(la metaclasse, comePartUsage),name,shortName,qualifiedNameeowner. - Package di primo livello: un package che non si trova all'interno di un altro elemento. Il testo SysML di un progetto è un testo per ogni package di primo livello, più un testo per gli elementi fuori dai package.
- Diagnostica: un problema trovato dal nucleo del linguaggio, con
code,severity(errorowarning),elementId,elementeargs. La diagnostica di sintassi riportalineecolinvece di un elemento. - Proposta: le modifiche che un client API o uno strumento di IA raccoglie per la revisione. È aperta una proposta per token e progetto. Il client la invia per la revisione con un titolo e un riepilogo.
- Risposte paginate: gli elenchi arrivano in pagine (
limit,offset). Il testo SysML lungo arriva in pagine di righe (line,lines). Una risposta che ha omesso qualcosa riportatruncated: true.
Come usarlo
Usare l'API quando uno script o uno strumento di IA ha bisogno del modello: per segnalare requisiti senza elementi che li soddisfano o li verificano, per controllare il testo SysML di un team rispetto al modello, o per far redigere a uno strumento di IA modifiche al modello che un ingegnere poi revisiona.
Leggere un progetto SysML v2 con curl
- Creare un token in Impostazioni account → Token API (vedere API e MCP).
- Elencare i propri progetti:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
I progetti SysML v2 hanno "language": "sysml2".
- Ottenere il riepilogo del modello:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects/<project>/model
Compaiono il numero di elementi per metaclasse, i package di primo livello e il numero di errori e avvisi.
- Trovare elementi, per esempio ogni definizione di parte:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/elements?type=part%20def&limit=100"
- Leggere il testo SysML di un package:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/sysml?root=Vehicles"
Un testo lungo termina con "truncated": true e "next": la riga da richiedere dopo con line.
Controllare il testo SysML prima di proporlo
- Inviare il nuovo testo di un package alla route di controllo:
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
- Leggere la risposta.
okètruequando il testo non ha errori di sintassi.diagnosticselenca gli errori di sintassi conlineecol, e gli errori che il testo aggiungerebbe al modello.changesè il numero di modifiche al modello prodotte dal testo.
Il controllo non modifica nulla. Richiede solo un token di lettura.
Proporre una modifica e applicarla
Un token di scrittura aggiunge modifiche alla proposta aperta del token. Il client invia poi la proposta per la revisione.
- Aggiungere una modifica. Inviare il nuovo testo completo di un package oppure modifiche agli elementi:
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
Si riceve 201 con la proposta, il riepilogo della modifica e gli elementi che aggiunge, modifica e rimuove. Una modifica che aggiunge diagnostica di errore viene rifiutata (vedere Proposte nei progetti SysML v2).
- Aggiungere altre modifiche allo stesso modo. Ogni modifica viene controllata rispetto al modello con le modifiche precedenti della proposta applicate.
- Inviare la proposta per la revisione:
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
- In Holarch, aprire il progetto, quindi aprire ✦ IA ▾ → Revisiona “Add range attribute”… (o la notifica sotto la campanella).
- Controllare le righe e fare clic su Applica selezionati.
Le modifiche spuntate vengono applicate con il proprio nome nella cronologia, e un solo annullamento revoca tutto.
Collegare uno strumento di IA a un progetto SysML v2
- Collegare lo strumento di IA a
https://app.holarch.app/mcpcon un token o con l'accesso (vedere API e MCP). - Fare domande sul modello, per esempio “Riassumi il modello Hybrid Car in Holarch” o “Quali requisiti del progetto Hybrid Car non sono verificati?”.
Lo strumento di IA usa
model_summary,list_elements,list_requirementse gli altri strumenti di lettura. - Chiedere una modifica, per esempio “Proponi un attributo
rangesuCar”.Lo strumento di IA legge il package con
get_sysml, propone testo o modifiche agli elementi e corregge la diagnostica restituita dal controllo. - Revisionare la proposta in Holarch e fare clic su Applica selezionati.
Esempio guidato: la demo Hybrid Car
Creare la demo con Gestisci progetti → File di progetto ▾ → Nuovo progetto demo → Hybrid Car (SysML v2), quindi creare per essa un token di lettura e scrittura.
GET /api/v1/projects/<project>/modelelenca i package di primo livello, tra cuiVehicles,HybridCarArchitectureeVehicleBehavior.GET /api/v1/projects/<project>/elements?query=Engine&type=part%20deftrovaVehicles::Engine.GET /api/v1/projects/<project>/elements/Vehicles::Enginerestituisce la definizione di parte con il suo testo SysML, i suoi membri (displacement,cylinders,maxPower, le portefuelIn,outputedecu) e gli usi tipizzati da essa.GET /api/v1/projects/<project>/elements/Vehicles::Car/connectionselenca l'interfacciadriveShaftdapowertrain.outputafrontAxle.input.GET /api/v1/projects/<project>/requirements?status=unverifiedelenca i requisiti che nessun caso di verifica verifica, con i loro id comeVR-4.1.POST /api/v1/projects/<project>/proposal/changescon{"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]}aggiunge la modifica alla proposta.POST /api/v1/projects/<project>/proposalcon un titolo la invia.- In Holarch, ✦ IA ▾ → Revisiona “…” mostra Modificato: con la definizione di parte e il campo
doc, e il diff del testo diVehicles. Applica selezionati la applica.
Suggerimenti
- Leggere un package con
get_sysml(oGET …/sysml?root=) prima di proporre un nuovo testo per esso. Gli elementi omessi dal testo proposto vengono rimossi. - Per piccole modifiche preferire le modifiche agli elementi. Cambiano solo gli elementi nominati e lasciano il resto del testo del package com'è.
- Controllare prima il testo con
check_sysml(oPOST …/sysml/check). Restituisce la stessa diagnostica con cui una proposta verrebbe rifiutata. - Negli script, nominare gli elementi per nome qualificato. Gli id restano invariati quando un elemento viene rinominato; i nomi qualificati no.
- Dare a uno strumento di IA un token di sola lettura quando si limita a rispondere a domande sul modello.
Route REST per i progetti SysML v2
Indirizzo di base: https://app.holarch.app/api/v1. Le risposte sono in JSON. /api/v1/openapi.json (OpenAPI 3.1) descrive queste route insieme alle altre.
| Metodo e percorso | Che cosa fa |
|---|---|
GET /projects/<project>/model | Numero di elementi per metaclasse, i package di primo livello con il rispettivo numero di elementi, e il numero di errori e avvisi |
GET /projects/<project>/elements | Ricerca: query (o q; testo nel nome, nel nome breve, nel nome qualificato o nel doc), type, owner, limit (1–500, predefinito 50), offset; ordinati per nome qualificato |
GET /projects/<project>/elements/<id> | Un elemento con i suoi campi, doc, testo SysML, membri e gli usi tipizzati da esso; members (0–200, predefinito 100) |
GET /projects/<project>/elements/<id>/connections | Connessioni, interfacce, binding, flussi (con l'item), successioni, transizioni, allocazioni e dipendenze sull'elemento o sulle sue feature, e quelle possedute al suo interno; limit (predefinito 100) |
GET /projects/<project>/requirements | Requisiti con id, enunciato (doc), satisfiedBy e verifiedBy; owner, status (unsatisfied o unverified), limit (predefinito 100), offset |
GET /projects/<project>/diagnostics | La diagnostica del modello, prima gli errori; ids (separati da virgole: solo quegli elementi e i loro membri), limit (predefinito 200, al massimo 500) |
GET /projects/<project>/sysml | Testo SysML di un package di primo livello (root), degli elementi fuori dai package (senza root) o di un elemento (element); line (prima riga, da 1), lines (predefinito 2000, al massimo 5000) |
POST /projects/<project>/sysml/check | Controlla text come nuovo testo di root (o degli elementi fuori dai package); non modifica nulla |
POST /projects/<project>/proposal/changes | Aggiunge una modifica alla proposta aperta: {text, root} o {edits} |
GET /projects/<project>/proposal | La proposta aperta, o una indicata dall'id proposal, con il suo stato e le sue modifiche |
POST /projects/<project>/proposal | Invia la proposta aperta per la revisione: title, summary |
DELETE /projects/<project>/proposal | Scarta la proposta aperta prima che venga inviata |
GET /projects e GET /projects/<project> funzionano anche per i progetti SysML v2. Restituiscono "language": "sysml2", e la risposta del progetto aggiunge elements e types (numero di elementi per metaclasse).
Le route delle entità LML (/entities, /relationships, /schema, i controlli del modello e il controllo di qualità) rispondono 409 wrong-project-type in un progetto SysML v2. Le route SysML v2 rispondono allo stesso modo in un progetto LML.
Valori
- type: una metaclasse come
PartUsageoRequirementDefinition, o una parola chiave come scritta nel testo SysML:part,part def,attribute,port,requirement,action,packagee le altre parole chiave degli elementi. - owner, id, element, root: un id o un nome qualificato.
rootaccetta anche il nome di un package di primo livello.rootdeve essere un package di primo livello; per leggere il testo di un singolo elemento, usareelement. - Valori lunghi: un doc in un elenco viene troncato a 4.000 caratteri, il doc di un singolo elemento a 20.000, e il testo SysML proprio di un elemento a 16.000 caratteri.
Strumenti MCP per i progetti SysML v2
L'endpoint MCP elenca questi strumenti accanto agli strumenti LML. Uno strumento di IA trova i progetti SysML v2 con list_projects (language: sysml2). Ogni strumento accetta project.
Gli strumenti di lettura accettano anche un change_request facoltativo (CR-12 o il suo id) per leggere il modello come lo renderebbe quella richiesta di modifica; propose_sysml e propose_element_changes ne accettano una per calcolare la modifica rispetto al modello della richiesta e applicarla in quella bozza dopo la revisione. Vedere Richieste di modifica per le regole.
| Strumento | Accesso | Che cosa fa |
|---|---|---|
model_summary | Lettura | Numero di elementi per metaclasse, i package di primo livello e il numero di diagnostiche |
list_elements | Lettura | Trova elementi per testo (query), type e owner; paginato con limit e offset |
get_element | Lettura | Un elemento (id) con tipi, specializzazioni, molteplicità, valore, estremità, doc, testo SysML, membri (members, al massimo 200) e gli usi tipizzati da esso |
get_connections | Lettura | Connessioni, interfacce, binding, flussi, successioni, transizioni, allocazioni e dipendenze di un elemento (id, limit) |
list_requirements | Lettura | Requisiti con id, enunciato, satisfy e verify; owner, status (unsatisfied, unverified), limit, offset |
get_sysml | Lettura | Testo SysML di un package di primo livello (root), degli elementi fuori dai package o di un elemento (element); line, lines (al massimo 5000); la risposta fornisce next |
get_sysml_text | Lettura | Testo SysML dell'intero modello (ogni package di primo livello, poi gli elementi fuori dai package) o di un package, fino a 200.000 caratteri per risposta; la risposta nomina i package omessi |
check_sysml | Lettura | Senza text: la diagnostica del modello (ids, limit). Con text (e root): errori di sintassi con riga e colonna, e gli errori che il testo aggiungerebbe. Non modifica nulla |
propose_sysml | Lettura e scrittura | Propone il nuovo text completo di un package di primo livello (root) o degli elementi fuori dai package (senza root; anche dove va un nuovo package) |
propose_element_changes | Lettura e scrittura | Propone edits (al massimo 100) senza riscrivere il testo: create, update, move o remove |
list_diagrams, get_diagram e get_matrix funzionano anche nei progetti SysML v2: list_diagrams elenca le viste (con il loro tipo, come InterconnectionView) e i diagrammi di analisi conservati sotto un elemento; get_diagram fornisce gli elementi che una vista espone dopo i suoi filtri (per id dell'elemento o nome qualificato); get_matrix fornisce ogni requisito con ciò che lo soddisfa e lo verifica.
Gli strumenti per le proposte dei progetti LML funzionano qui allo stesso modo: propose_changes invia la proposta con un titolo e un riepilogo, discard_proposal la scarta, e get_proposal e list_proposals ne mostrano lo stato. Un token di sola lettura elenca solo gli strumenti di lettura.
Gli errori degli strumenti tornano come risultato dello strumento con il messaggio e la diagnostica, così lo strumento di IA può correggere il proprio testo e riprovare.
Modifiche agli elementi
Ogni modifica in edits (MCP) o in {"edits": […]} (REST) è un oggetto con op:
| op | Campi |
|---|---|
create | kind (una parola chiave come part, part def, attribute, port, requirement, action, package) o type (una metaclasse); owner (omesso: primo livello); name (obbligatorio); facoltativi shortName, typedBy, specializes, subsets, redefines, multiplicity, value, doc, direction (in, out, inout) |
update | id e i campi da modificare, come per create; null o "" svuota un campo |
move | id e il nuovo owner |
remove | id; rimuove l'elemento con i suoi membri |
typedBy,specializes,subsetseredefinessono elenchi di fino a 20 nomi: id, nomi qualificati o nomi come scritti nel testo (funzionano i nomi di libreria comeMassValue).- Le modifiche successive possono nominare gli elementi creati in precedenza nella stessa chiamata come
new:1,new:2… nell'ordine di creazione, per esempio comeowner. La risposta li elenca increatedcon i loro nuovi id. - Rinominare un elemento aggiorna anche i riferimenti che lo nominavano con il vecchio nome.
Testo proposto
propose_sysmlsostituisce l'intero testo del package. Gli elementi mantengono i loro id dove il testo li dichiara ancora. Gli elementi omessi dal testo vengono rimossi.- Il testo deve essere analizzato senza che nulla resti non applicato. Un testo che non modifica il modello viene rifiutato (
no-change).
Proposte nei progetti SysML v2
Ogni modifica proposta viene controllata dal nucleo del linguaggio prima di entrare nella proposta:
- Il testo viene analizzato senza errori di sintassi e le modifiche agli elementi si applicano.
- I package modificati si stampano ancora come testo SysML e vengono analizzati di nuovo.
- La modifica non aggiunge diagnostica di errore al modello, come nomi non risolti o errori di tipo. Gli errori che il modello aveva già non contano.
Una modifica che non supera i controlli viene rifiutata con la diagnostica (fino a 50) da correggere. Nulla viene memorizzato. Gli avvisi non causano il rifiuto di una modifica.
Per proporre servono un token di lettura e scrittura e il ruolo di editor o proprietario nel progetto. Una proposta contiene al massimo 200 modifiche e 8 MB.
Revisionare una proposta SysML v2
Aprire il progetto, quindi ✦ IA ▾ → Revisiona “<title>”…. Ogni modifica è una riga con una casella di spunta:
- Aggiunto, Modificato e Rimosso elencano gli elementi, con i campi modificati (i primi 20 di ciascuno; “e altri n” per il resto).
- Un diff del testo, etichettato con il package, mostra il testo SysML prima e dopo.
- Una modifica che rimuove elementi viene segnalata e parte senza spunta.
- Aprire il modello SysML v2 per applicare questa modifica. Il modello non è caricato; aprire una pagina SysML v2 del progetto.
- Il package non è più nel modello; saltato. Il package è stato rimosso dopo che la modifica è stata proposta.
Applica selezionati sincronizza di nuovo ogni modifica al testo con il modello attuale e mantiene le modifiche i cui elementi esistono ancora. Controlla l'intero insieme e lo applica come un passo di annullamento. Le modifiche che non sono più adatte vengono saltate e nominate in un messaggio. Rifiuta e Più tardi funzionano come per le proposte LML, così come ruoli, scadenza (7 giorni) e conservazione (vedere Proposte dai client di IA).
Systems Modeling API
Altri strumenti SysML v2 leggono e modificano i modelli Holarch tramite route nelle forme della OMG Systems Modeling API (REST/HTTP). L'indirizzo di base è https://app.holarch.app/api/v1/sysml. Usa gli stessi token; qualsiasi ruolo nel progetto può leggere, ed editor e proprietari possono eseguire commit.
- Progetti: vengono elencati solo i progetti SysML v2. Il
@iddi un progetto è un UUID assegnato da questa API; funziona anche l'id del progetto Holarch. La risposta includeholarchIdeurl. - Rami:
mainè il modello attivo e non si può modificare tramite l'API. Ogni altro ramo è una richiesta di modifica in corso, denominata “CR-12 Titolo” e conholarchChangeRequest(id,label,status,url). Le richieste di modifica implementate o ritirate negli ultimi 30 giorni sono ancora elencate, condeletedimpostato. - Commit: un commit scrive modifiche nel ramo di una richiesta di modifica. Vengono serviti solo i commit di testa dei rami: la testa di
mainè il modello attivo, la testa del ramo di una richiesta di modifica è il modello attivo con le modifiche della richiesta. Gli id di commit più vecchi rispondono404; ottenere la testa attuale dal ramo. - Elementi: ogni elemento ha tutte le proprietà della sua metaclasse nello schema JSON OMG, comprese quelle derivate (
owner,ownedElement,qualifiedName,feature,typee simili). Gli elementi della libreria standard sono referenziati con i loro id standard, gli stessi id che altri strumenti SysML v2 usano per lo stesso elemento di libreria. - Tag e query salvate: nessuno; i loro elenchi sono vuoti.
| Metodo e percorso | Che cosa fa |
|---|---|
GET /sysml/projects | I propri progetti SysML v2 |
POST /sysml/projects | Crea un progetto SysML v2 vuoto (name, description) |
GET /sysml/projects/<projectId> | Un progetto, con il suo ramo predefinito |
GET /sysml/projects/<projectId>/branches | main e i rami delle richieste di modifica |
POST /sysml/projects/<projectId>/branches | Crea un ramo: una nuova richiesta di modifica in bozza (name è il titolo, description il motivo) |
GET /sysml/projects/<projectId>/branches/<branchId> | Il ramo (il suo @id o main), con head |
DELETE /sysml/projects/<projectId>/branches/<branchId> | Ritira la richiesta di modifica |
GET /sysml/projects/<projectId>/commits | Le teste e i commit inviati ai rami, dal più recente |
POST /sysml/projects/<projectId>/commits?branchId=<branchId> | Esegue il commit di modifiche in un ramo (vedere sotto) |
GET /sysml/projects/<projectId>/commits/<commitId> | Un commit di testa |
GET /sysml/projects/<projectId>/commits/<commitId>/changes | Cosa cambia il ramo rispetto al modello attivo: un DataVersion per elemento |
GET /sysml/projects/<projectId>/commits/<commitId>/elements | Tutti gli elementi del commit, paginati |
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId> | Un elemento |
GET /sysml/projects/<projectId>/commits/<commitId>/roots | Gli elementi di primo livello, paginati |
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>/relationships | Le relazioni con l'elemento come origine o destinazione; direction è in, out o both (predefinito), paginate |
POST /sysml/projects/<projectId>/query-results | Gli elementi che corrispondono a una query (corpo sotto), paginati; commitId deve essere una testa |
GET /sysml/projects/<projectId>/tags, /queries, /commits/<commitId>/elements/<elementId>/projectUsages | Elenchi vuoti |
Le risposte con elenchi sono array JSON. Gli elenchi sono paginati con page[size] (predefinito 100, al massimo 1000) e page[after] (l'@id dell'ultimo elemento della pagina precedente) o page[before] (l'@id del primo elemento della pagina successiva). L'intestazione Link fornisce la pagina successiva con rel="next" e quella precedente con rel="prev".
Una query è un oggetto JSON con un where facoltativo (un PrimitiveConstraint con property, operator (=, in, <, <=, >, >= o instanceOf), value e inverse, oppure un CompositeConstraint con operator and o or e constraint), scope (id di elementi: la ricerca copre questi e ciò che possiedono) e select (le proprietà da restituire; @id e @type vengono sempre restituiti):
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"]}'
Leggere gli elementi di un modello:
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"
Eseguire il commit delle modifiche
Per scrivere servono un token con accesso in lettura e scrittura, il ruolo di editor o proprietario, il piano Team (anche per gli account accademici e di classe) e la revisione dei rami attiva per il progetto (Richieste di modifica → Impostazioni). Un approvatore revisiona e applica la richiesta di modifica in Holarch; i token non votano né applicano mai.
- Creare un ramo: POST
/branchescon{"@type": "Branch", "name": "Cabin heater"}. La risposta è il ramo con il suoholarchChangeRequest. - Leggere la testa del ramo e i suoi elementi.
- POST
/commits?branchId=<branch @id>con un elenco diDataVersion:
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>"}}}]}'
- Modificare un elemento: inviare l'elemento così come è stato letto, con le proprietà modificate. Contano solo le proprietà possedute (
declaredName,ownedRelationship,isAbstracte simili); quelle derivate vengono ignorate, quindi rinviare ciò che si è letto non modifica nulla. Una proprietà omessa mantiene il suo valore; inviarenullo[]per svuotarla. - Nuovi elementi: assegnare all'elemento un nuovo UUID e la sua membership proprietaria (inviata nello stesso commit) oppure
owner, che crea la membership automaticamente. - Rimuovere un elemento:
payload: nulllo rimuove con tutto ciò che possiede. - Controlli: ogni package toccato dal commit deve essere stampato e analizzato di nuovo, e il commit non deve aggiungere diagnostica di errore; altrimenti
422con ladiagnosticsda correggere. - previousCommit: la testa su cui è stata fatta la modifica. Se nel frattempo il ramo è avanzato, la risposta è
409stale-headcon laheadattuale; rileggere ed eseguire il commit sopra di essa. - Nuovi tentativi: inviare un'intestazione
Idempotency-Key. Un nuovo tentativo con la stessa chiave e lo stesso corpo entro 24 ore riceve di nuovo la prima risposta. - Commit su
main: un commit senzabranchId, o conmain, va nella richiesta di modifica in bozza propria del token (“API changes from <token name>”), creata al primo commit di questo tipo. La risposta indica quale inholarchChangeRequeste in un'intestazioneWarning. - Nuovi progetti: un progetto creato con POST
/sysml/projectsha la revisione dei rami attiva. Il suo primo commit sumain, finché si è l'unico membro, viene scritto direttamente nel modello, una sola volta; i commit successivi passano per le richieste di modifica.
Inviare la richiesta di modifica per la revisione con POST /api/v1/projects/<project>/change-requests/<CR-12>/submit (API e MCP). Tag, merge e rinomina o eliminazione di un progetto rispondono 405 indicando cosa fare invece. Gli errori hanno @type Error e una description, come li definisce l'API OMG.
Messaggi
Si applicano i codici di API e MCP. Le route e gli strumenti SysML v2 aggiungono:
| Codice | Stato | Significato |
|---|---|---|
wrong-project-type | 409 | Un'operazione LML in un progetto SysML v2, o un'operazione SysML v2 in un progetto LML |
syntax | 422 | Il testo proposto ha errori di sintassi; la diagnostica indica riga e colonna |
invalid-model | 422 | La modifica aggiunge diagnostica di errore al modello; viene elencata |
not-printable | 422 | La modifica non si può scrivere come testo SysML |
invalid | 422 | Non è stato possibile applicare la modifica al modello |
no-change | 400 | Il testo non modifica il modello |
too-large | 413 | Il testo supera 1.000.000 di caratteri, o la proposta supera 8 MB |
too-many | 413 o 409 | Più di 100 modifiche in una chiamata (413), o la proposta contiene già 200 modifiche (409) |
stale | 409 | Una modifica al testo precedente della proposta non si applica più al modello |
not-found | 404 | Progetto, elemento, ramo o commit inesistente (la Systems Modeling API serve solo le teste dei rami) |
not-writable | 405 | Tag, merge, rinomina o eliminazione di un progetto tramite la Systems Modeling API; farlo in Holarch |
main-protected | 405 | Eliminazione di main; eliminare invece il ramo di una richiesta di modifica |
stale-head | 409 | Il ramo è avanzato dopo previousCommit; leggerne la head ed eseguire di nuovo il commit |
branch-base | 409 | Un nuovo ramo deve partire dalla testa di main |
branch-review-off | 409 | Il progetto non usa la revisione dei rami; un proprietario la attiva in Richieste di modifica → Impostazioni |
cr-not-draft | 409 | La richiesta di modifica è inviata o chiusa; si può scrivere solo mentre è in bozza o rifiutata |
cr-full | 409 | La richiesta di modifica contiene 5.000 elementi modificati, o il progetto 20 MB di bozze di richieste di modifica |
plan-limit | 403 | Le scritture nelle richieste di modifica richiedono il piano Team |
orphan | 422 | Un nuovo elemento non ha proprietario; inviare la sua membership proprietaria o owner |
unknown-metaclass | 422 | Il @type di un payload non è una metaclasse SysML v2 |
idempotency-key-reused | 422 | L'Idempotency-Key è stata usata con un altro corpo; inviare una nuova chiave |
token-projects | 403 | Un token limitato a un elenco di progetti non può creare un progetto |
bad-request | 400 | Un valore mancante o errato, come un root che non è un package di primo livello, un op sconosciuto o un nuovo elemento senza nome |
Limiti
| Cosa | Limite |
|---|---|
| Elementi, requisiti o connessioni per pagina | 500 |
| Membri elencati con un elemento | 200 |
| Diagnostiche per risposta | 500 |
| Righe di testo SysML per risposta | 5.000, e al massimo 400.000 byte (troncato a fine riga) |
| Testo doc | 4.000 caratteri negli elenchi, 20.000 per un singolo elemento |
| Il testo SysML proprio di un elemento | 16.000 caratteri |
Testo in una chiamata propose_sysml | 1.000.000 di caratteri |
| Modifiche in una chiamata | 100 |
| Elementi elencati come aggiunti, modificati o rimossi in una modifica | 300 ciascuno |
| Modifiche in una proposta | 200, e 8 MB |
| Pagina della Systems Modeling API | 1.000 elementi (predefinito 100) |
| DataVersion in un commit | 5,000 |
| Elementi modificati in una richiesta di modifica | 5,000 |
| Corpo del commit | 32 MB |
Limiti di frequenza, dimensione delle richieste e regole dei token sono quelli di API e MCP.
Pagine correlate
- API e MCP
- Primi passi con i progetti SysML v2
- L'Editor di testo e il Browser
- Scambio di modelli SysML v2
- Requisiti e verifica nei progetti SysML v2
SysML® e OMG® sono marchi registrati di Object Management Group, Inc. negli Stati Uniti e in altri paesi.