Holarch

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.

Come usarlo →

In questa pagina
  1. Panoramica
  2. Concetti
  3. Come usarlo
    1. Leggere un progetto SysML v2 con curl
    2. Controllare il testo SysML prima di proporlo
    3. Proporre una modifica e applicarla
    4. Collegare uno strumento di IA a un progetto SysML v2
    5. Esempio guidato: la demo Hybrid Car
    6. Suggerimenti
  4. Route REST per i progetti SysML v2
    1. Valori
  5. Strumenti MCP per i progetti SysML v2
    1. Modifiche agli elementi
    2. Testo proposto
  6. Proposte nei progetti SysML v2
    1. Revisionare una proposta SysML v2
  7. Systems Modeling API
    1. Eseguire il commit delle modifiche
  8. Messaggi
  9. Limiti
  10. Pagine correlate

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/mcp per 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 ramo main è 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, come PartUsage), name, shortName, qualifiedName e owner.
  • 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 (error o warning), elementId, element e args. La diagnostica di sintassi riporta line e col invece 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 riporta truncated: 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

  1. Creare un token in Impostazioni account → Token API (vedere API e MCP).
  2. Elencare i propri progetti:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects

I progetti SysML v2 hanno "language": "sysml2".

  1. 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.

  1. 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"
  1. 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

  1. 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
  1. Leggere la risposta. ok è true quando il testo non ha errori di sintassi. diagnostics elenca gli errori di sintassi con line e col, 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.

  1. 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).

  1. Aggiungere altre modifiche allo stesso modo. Ogni modifica viene controllata rispetto al modello con le modifiche precedenti della proposta applicate.
  2. 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
  1. In Holarch, aprire il progetto, quindi aprire ✦ IA ▾ → Revisiona “Add range attribute”… (o la notifica sotto la campanella).
  2. 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

  1. Collegare lo strumento di IA a https://app.holarch.app/mcp con un token o con l'accesso (vedere API e MCP).
  2. 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_requirements e gli altri strumenti di lettura.

  3. Chiedere una modifica, per esempio “Proponi un attributo range su Car”.

    Lo strumento di IA legge il package con get_sysml, propone testo o modifiche agli elementi e corregge la diagnostica restituita dal controllo.

  4. 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.

  1. GET /api/v1/projects/<project>/model elenca i package di primo livello, tra cui Vehicles, HybridCarArchitecture e VehicleBehavior.
  2. GET /api/v1/projects/<project>/elements?query=Engine&type=part%20def trova Vehicles::Engine.
  3. GET /api/v1/projects/<project>/elements/Vehicles::Engine restituisce la definizione di parte con il suo testo SysML, i suoi membri (displacement, cylinders, maxPower, le porte fuelIn, output ed ecu) e gli usi tipizzati da essa.
  4. GET /api/v1/projects/<project>/elements/Vehicles::Car/connections elenca l'interfaccia driveShaft da powertrain.output a frontAxle.input.
  5. GET /api/v1/projects/<project>/requirements?status=unverified elenca i requisiti che nessun caso di verifica verifica, con i loro id come VR-4.1.
  6. POST /api/v1/projects/<project>/proposal/changes con {"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]} aggiunge la modifica alla proposta. POST /api/v1/projects/<project>/proposal con un titolo la invia.
  7. In Holarch, ✦ IA ▾ → Revisiona “…” mostra Modificato: con la definizione di parte e il campo doc, e il diff del testo di Vehicles. Applica selezionati la applica.

Suggerimenti

  • Leggere un package con get_sysml (o GET …/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 (o POST …/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 percorsoChe cosa fa
GET /projects/<project>/modelNumero 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>/elementsRicerca: 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>/connectionsConnessioni, 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>/requirementsRequisiti con id, enunciato (doc), satisfiedBy e verifiedBy; owner, status (unsatisfied o unverified), limit (predefinito 100), offset
GET /projects/<project>/diagnosticsLa 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>/sysmlTesto 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/checkControlla text come nuovo testo di root (o degli elementi fuori dai package); non modifica nulla
POST /projects/<project>/proposal/changesAggiunge una modifica alla proposta aperta: {text, root} o {edits}
GET /projects/<project>/proposalLa proposta aperta, o una indicata dall'id proposal, con il suo stato e le sue modifiche
POST /projects/<project>/proposalInvia la proposta aperta per la revisione: title, summary
DELETE /projects/<project>/proposalScarta 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 PartUsage o RequirementDefinition, o una parola chiave come scritta nel testo SysML: part, part def, attribute, port, requirement, action, package e le altre parole chiave degli elementi.
  • owner, id, element, root: un id o un nome qualificato. root accetta anche il nome di un package di primo livello. root deve essere un package di primo livello; per leggere il testo di un singolo elemento, usare element.
  • 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.

StrumentoAccessoChe cosa fa
model_summaryLetturaNumero di elementi per metaclasse, i package di primo livello e il numero di diagnostiche
list_elementsLetturaTrova elementi per testo (query), type e owner; paginato con limit e offset
get_elementLetturaUn elemento (id) con tipi, specializzazioni, molteplicità, valore, estremità, doc, testo SysML, membri (members, al massimo 200) e gli usi tipizzati da esso
get_connectionsLetturaConnessioni, interfacce, binding, flussi, successioni, transizioni, allocazioni e dipendenze di un elemento (id, limit)
list_requirementsLetturaRequisiti con id, enunciato, satisfy e verify; owner, status (unsatisfied, unverified), limit, offset
get_sysmlLetturaTesto 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_textLetturaTesto 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_sysmlLetturaSenza 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_sysmlLettura e scritturaPropone 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_changesLettura e scritturaPropone 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:

opCampi
createkind (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)
updateid e i campi da modificare, come per create; null o "" svuota un campo
moveid e il nuovo owner
removeid; rimuove l'elemento con i suoi membri
  • typedBy, specializes, subsets e redefines sono elenchi di fino a 20 nomi: id, nomi qualificati o nomi come scritti nel testo (funzionano i nomi di libreria come MassValue).
  • Le modifiche successive possono nominare gli elementi creati in precedenza nella stessa chiamata come new:1, new:2 … nell'ordine di creazione, per esempio come owner. La risposta li elenca in created con i loro nuovi id.
  • Rinominare un elemento aggiorna anche i riferimenti che lo nominavano con il vecchio nome.

Testo proposto

  • propose_sysml sostituisce 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 @id di un progetto è un UUID assegnato da questa API; funziona anche l'id del progetto Holarch. La risposta include holarchId e url.
  • 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 con holarchChangeRequest (id, label, status, url). Le richieste di modifica implementate o ritirate negli ultimi 30 giorni sono ancora elencate, con deleted impostato.
  • 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 rispondono 404; 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, type e 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 percorsoChe cosa fa
GET /sysml/projectsI propri progetti SysML v2
POST /sysml/projectsCrea un progetto SysML v2 vuoto (name, description)
GET /sysml/projects/<projectId>Un progetto, con il suo ramo predefinito
GET /sysml/projects/<projectId>/branchesmain e i rami delle richieste di modifica
POST /sysml/projects/<projectId>/branchesCrea 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>/commitsLe 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>/changesCosa cambia il ramo rispetto al modello attivo: un DataVersion per elemento
GET /sysml/projects/<projectId>/commits/<commitId>/elementsTutti gli elementi del commit, paginati
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>Un elemento
GET /sysml/projects/<projectId>/commits/<commitId>/rootsGli elementi di primo livello, paginati
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>/relationshipsLe relazioni con l'elemento come origine o destinazione; direction è in, out o both (predefinito), paginate
POST /sysml/projects/<projectId>/query-resultsGli elementi che corrispondono a una query (corpo sotto), paginati; commitId deve essere una testa
GET /sysml/projects/<projectId>/tags, /queries, /commits/<commitId>/elements/<elementId>/projectUsagesElenchi 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.

  1. Creare un ramo: POST /branches con {"@type": "Branch", "name": "Cabin heater"}. La risposta è il ramo con il suo holarchChangeRequest.
  2. Leggere la testa del ramo e i suoi elementi.
  3. POST /commits?branchId=<branch @id> con un elenco di DataVersion:
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, isAbstract e simili); quelle derivate vengono ignorate, quindi rinviare ciò che si è letto non modifica nulla. Una proprietà omessa mantiene il suo valore; inviare null o [] 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: null lo 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 422 con la diagnostics da correggere.
  • previousCommit: la testa su cui è stata fatta la modifica. Se nel frattempo il ramo è avanzato, la risposta è 409 stale-head con la head attuale; 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 senza branchId, o con main, 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 in holarchChangeRequest e in un'intestazione Warning.
  • Nuovi progetti: un progetto creato con POST /sysml/projects ha la revisione dei rami attiva. Il suo primo commit su main, 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:

CodiceStatoSignificato
wrong-project-type409Un'operazione LML in un progetto SysML v2, o un'operazione SysML v2 in un progetto LML
syntax422Il testo proposto ha errori di sintassi; la diagnostica indica riga e colonna
invalid-model422La modifica aggiunge diagnostica di errore al modello; viene elencata
not-printable422La modifica non si può scrivere come testo SysML
invalid422Non è stato possibile applicare la modifica al modello
no-change400Il testo non modifica il modello
too-large413Il testo supera 1.000.000 di caratteri, o la proposta supera 8 MB
too-many413 o 409Più di 100 modifiche in una chiamata (413), o la proposta contiene già 200 modifiche (409)
stale409Una modifica al testo precedente della proposta non si applica più al modello
not-found404Progetto, elemento, ramo o commit inesistente (la Systems Modeling API serve solo le teste dei rami)
not-writable405Tag, merge, rinomina o eliminazione di un progetto tramite la Systems Modeling API; farlo in Holarch
main-protected405Eliminazione di main; eliminare invece il ramo di una richiesta di modifica
stale-head409Il ramo è avanzato dopo previousCommit; leggerne la head ed eseguire di nuovo il commit
branch-base409Un nuovo ramo deve partire dalla testa di main
branch-review-off409Il progetto non usa la revisione dei rami; un proprietario la attiva in Richieste di modifica → Impostazioni
cr-not-draft409La richiesta di modifica è inviata o chiusa; si può scrivere solo mentre è in bozza o rifiutata
cr-full409La richiesta di modifica contiene 5.000 elementi modificati, o il progetto 20 MB di bozze di richieste di modifica
plan-limit403Le scritture nelle richieste di modifica richiedono il piano Team
orphan422Un nuovo elemento non ha proprietario; inviare la sua membership proprietaria o owner
unknown-metaclass422Il @type di un payload non è una metaclasse SysML v2
idempotency-key-reused422L'Idempotency-Key è stata usata con un altro corpo; inviare una nuova chiave
token-projects403Un token limitato a un elenco di progetti non può creare un progetto
bad-request400Un valore mancante o errato, come un root che non è un package di primo livello, un op sconosciuto o un nuovo elemento senza nome

Limiti

CosaLimite
Elementi, requisiti o connessioni per pagina500
Membri elencati con un elemento200
Diagnostiche per risposta500
Righe di testo SysML per risposta5.000, e al massimo 400.000 byte (troncato a fine riga)
Testo doc4.000 caratteri negli elenchi, 20.000 per un singolo elemento
Il testo SysML proprio di un elemento16.000 caratteri
Testo in una chiamata propose_sysml1.000.000 di caratteri
Modifiche in una chiamata100
Elementi elencati come aggiunti, modificati o rimossi in una modifica300 ciascuno
Modifiche in una proposta200, e 8 MB
Pagina della Systems Modeling API1.000 elementi (predefinito 100)
DataVersion in un commit5,000
Elementi modificati in una richiesta di modifica5,000
Corpo del commit32 MB

Limiti di frequenza, dimensione delle richieste e regole dei token sono quelli di API e MCP.

SysML® e OMG® sono marchi registrati di Object Management Group, Inc. negli Stati Uniti e in altri paesi.