Holarch

SysML v2

API i MCP w projektach SysML v2

Odczytuj, przeszukuj i sprawdzaj modele SysML v2 ze skryptów i narzędzi AI za pomocą osobistego tokenu dostępu, proponuj zmiany, które przegląda się i stosuje w Holarch, oraz odczytuj i zatwierdzaj zmiany przez Systems Modeling API, w którym gałęzie są wnioskami o zmianę.

Jak z niego korzystać →

Na tej stronie
  1. Przegląd
  2. Pojęcia
  3. Jak z niego korzystać
    1. Odczyt projektu SysML v2 za pomocą curl
    2. Sprawdzenie tekstu SysML przed zaproponowaniem
    3. Zaproponowanie zmiany i jej zastosowanie
    4. Połączenie narzędzia AI z projektem SysML v2
    5. Przykład: projekt demonstracyjny Hybrid Car
    6. Wskazówki
  4. Trasy REST dla projektów SysML v2
    1. Wartości
  5. Narzędzia MCP dla projektów SysML v2
    1. Edycje elementów
    2. Proponowany tekst
  6. Propozycje w projektach SysML v2
    1. Przegląd propozycji SysML v2
  7. Systems Modeling API
    1. Zatwierdzanie zmian (commit)
  8. Komunikaty
  9. Limity
  10. Powiązane strony

Przegląd

Projekty SysML v2 działają z tym samym API REST, punktem końcowym MCP i osobistymi tokenami dostępu co projekty LML. Skrypty i narzędzia AI odczytują model jako elementy i tekst SysML, sprawdzają tekst, zanim cokolwiek zmienią, i proponują zmiany. Nic w modelu się nie zmienia, dopóki człowiek nie przejrzy propozycji w Holarch i jej nie zastosuje.

Trzy sposoby dostępu:

  • API REST: https://app.holarch.app/api/v1/projects/<project>/… dla skryptów i pulpitów. Odczytuje elementy, wymagania, diagnostyki i tekst SysML oraz dodaje zmiany do propozycji.
  • MCP: https://app.holarch.app/mcp dla narzędzi AI takich jak Claude. Narzędzia SysML v2 odczytują, przeszukują i sprawdzają model oraz proponują zmiany.
  • Systems Modeling API: https://app.holarch.app/api/v1/sysml/…, w kształtach OMG Systems Modeling API dla innych narzędzi SysML v2. Gałąź main to model bieżący, tylko do odczytu; każda inna gałąź jest wnioskiem o zmianę, a commity trafiają do niej. Model bieżący zmienia się tylko wtedy, gdy zatwierdzający zastosuje wniosek o zmianę w Holarch.

Tokeny, zakresy, listy projektów, przełącznik organizacji, limity żądań i łączenie Claude działają tak samo jak w projektach LML. Tworzenie tokenu i łączenie narzędzia AI opisuje strona API i MCP. Wywołania Mapy programu (GET /api/v1/program-map, GET /api/v1/projects/<project>/items/<item>/trace oraz narzędzia MCP program_map i trace_chain) obejmują projekty SysML v2 i ich elementy.

Pojęcia

  • Element: jedna pozycja modelu SysML v2, np. definicja części, port lub wymaganie. Każdy element ma id (UUID). Wszędzie tam, gdzie trasa lub narzędzie wymaga identyfikatora, działa również nazwa kwalifikowana, np. Vehicles::Car::powertrain.
  • Skrót: krótka postać elementu na listach: id, type (metaklasa, np. PartUsage), name, shortName, qualifiedName i owner.
  • Pakiet najwyższego poziomu: pakiet, który nie znajduje się wewnątrz innego elementu. Tekst SysML projektu to jeden tekst na każdy pakiet najwyższego poziomu oraz jeden tekst dla elementów spoza pakietów.
  • Diagnostyka: problem znaleziony przez rdzeń języka, z polami code, severity (error lub warning), elementId, element i args. Diagnostyki składni podają line i col zamiast elementu.
  • Propozycja: zmiany, które klient API lub narzędzie AI zbiera do przeglądu. Na token i projekt otwarta jest jedna propozycja. Klient wysyła ją do przeglądu z tytułem i podsumowaniem.
  • Odpowiedzi stronicowane: listy przychodzą stronami (limit, offset). Długi tekst SysML przychodzi stronami wierszy (line, lines). Odpowiedź, która coś pominęła, zawiera truncated: true.

Jak z niego korzystać

Używaj API, gdy skrypt lub narzędzie AI potrzebuje modelu: aby raportować wymagania bez elementów spełniających lub weryfikujących, aby sprawdzać tekst SysML zespołu względem modelu albo aby pozwolić narzędziu AI przygotować zmiany modelu, które następnie przegląda inżynier.

Odczyt projektu SysML v2 za pomocą curl

  1. Utwórz token w Ustawienia konta → Tokeny API (zobacz API i MCP).
  2. Wyświetl listę swoich projektów:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects

Projekty SysML v2 mają "language": "sysml2".

  1. Pobierz podsumowanie modelu:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects/<project>/model

Zobaczysz liczby elementów na metaklasę, pakiety najwyższego poziomu oraz liczbę błędów i ostrzeżeń.

  1. Znajdź elementy, na przykład każdą definicję części:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/elements?type=part%20def&limit=100"
  1. Odczytaj tekst SysML pakietu:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/sysml?root=Vehicles"

Długi tekst kończy się na "truncated": true i "next": wierszem, o który należy poprosić następnie za pomocą line.

Sprawdzenie tekstu SysML przed zaproponowaniem

  1. Wyślij nowy tekst pakietu na trasę sprawdzania:
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. Przeczytaj odpowiedź. ok ma wartość true, gdy tekst nie ma błędów składni. diagnostics wymienia błędy składni z line i col oraz błędy, które tekst dodałby do modelu. changes to liczba zmian modelu, które wprowadza tekst.

Sprawdzenie niczego nie zmienia. Wymaga tylko tokenu do odczytu.

Zaproponowanie zmiany i jej zastosowanie

Token do zapisu dodaje zmiany do otwartej propozycji tokenu. Klient wysyła następnie propozycję do przeglądu.

  1. Dodaj zmianę. Wyślij albo pełny nowy tekst pakietu, albo edycje elementów:
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

Otrzymasz 201 z propozycją, podsumowaniem zmiany oraz elementami, które dodaje, zmienia i usuwa. Zmiana, która dodaje diagnostyki błędów, jest odrzucana (zobacz Propozycje w projektach SysML v2).

  1. Dodawaj kolejne zmiany w ten sam sposób. Każda zmiana jest sprawdzana względem modelu z zastosowanymi wcześniejszymi zmianami propozycji.
  2. Wyślij propozycję do przeglądu:
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. W Holarch otwórz projekt, a następnie otwórz ✦ AI ▾ → Przejrzyj „Add range attribute”… (lub powiadomienie pod dzwonkiem).
  2. Sprawdź wiersze i kliknij Zastosuj zaznaczone.

    Zaznaczone zmiany są stosowane z Twoim nazwiskiem w historii, a jedno polecenie Cofnij wycofuje całość.

Połączenie narzędzia AI z projektem SysML v2

  1. Połącz narzędzie AI z https://app.holarch.app/mcp za pomocą tokenu lub logowania (zobacz API i MCP).
  2. Zapytaj o model, na przykład “Podsumuj model Hybrid Car w Holarch” lub “Które wymagania w projekcie Hybrid Car nie są zweryfikowane?”.

    Narzędzie AI używa model_summary, list_elements, list_requirements i innych narzędzi do odczytu.

  3. Poproś o zmianę, na przykład “Zaproponuj atrybut range w Car”.

    Narzędzie AI odczytuje pakiet za pomocą get_sysml, proponuje tekst lub edycje elementów i poprawia diagnostyki zwrócone przez sprawdzenie.

  4. Przejrzyj propozycję w Holarch i kliknij Zastosuj zaznaczone.

Przykład: projekt demonstracyjny Hybrid Car

Utwórz demo przez Zarządzaj projektami → Pliki projektów ▾ → Nowy projekt demonstracyjny → Hybrid Car (SysML v2), a następnie utwórz dla niego token do odczytu i zapisu.

  1. GET /api/v1/projects/<project>/model wymienia pakiety najwyższego poziomu, wśród nich Vehicles, HybridCarArchitecture i VehicleBehavior.
  2. GET /api/v1/projects/<project>/elements?query=Engine&type=part%20def znajduje Vehicles::Engine.
  3. GET /api/v1/projects/<project>/elements/Vehicles::Engine zwraca definicję części z jej tekstem SysML, składowymi (displacement, cylinders, maxPower, porty fuelIn, output i ecu) oraz typowanymi przez nią użyciami.
  4. GET /api/v1/projects/<project>/elements/Vehicles::Car/connections wymienia interfejs driveShaft z powertrain.output do frontAxle.input.
  5. GET /api/v1/projects/<project>/requirements?status=unverified wymienia wymagania, których nie weryfikuje żaden przypadek weryfikacji, z identyfikatorami takimi jak VR-4.1.
  6. POST /api/v1/projects/<project>/proposal/changes z {"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]} dodaje zmianę do propozycji. POST /api/v1/projects/<project>/proposal z tytułem ją wysyła.
  7. W Holarch ✦ AI ▾ → Przejrzyj „…” pokazuje Zmieniono: z definicją części i polem doc oraz różnice tekstu Vehicles. Zastosuj zaznaczone ją stosuje.

Wskazówki

  • Odczytaj pakiet za pomocą get_sysml (lub GET …/sysml?root=), zanim zaproponujesz dla niego nowy tekst. Elementy pominięte w proponowanym tekście są usuwane.
  • Przy małych zmianach preferuj edycje elementów. Zmieniają one tylko wskazane elementy, a resztę tekstu pakietu pozostawiają bez zmian.
  • Najpierw sprawdź tekst za pomocą check_sysml (lub POST …/sysml/check). Zwraca te same diagnostyki, z którymi propozycja zostałaby odrzucona.
  • W skryptach wskazuj elementy przez nazwę kwalifikowaną. Identyfikatory nie zmieniają się przy zmianie nazwy elementu; nazwy kwalifikowane tak.
  • Daj narzędziu AI token tylko do odczytu, gdy jedynie odpowiada na pytania o model.

Trasy REST dla projektów SysML v2

Adres bazowy: https://app.holarch.app/api/v1. Odpowiedzi są w JSON. /api/v1/openapi.json (OpenAPI 3.1) opisuje te trasy wraz z pozostałymi.

Metoda i ścieżkaCo robi
GET /projects/<project>/modelLiczby elementów na metaklasę, pakiety najwyższego poziomu z liczbami elementów oraz liczba błędów i ostrzeżeń
GET /projects/<project>/elementsWyszukiwanie: query (lub q; tekst w nazwie, nazwie skróconej, nazwie kwalifikowanej lub doc), type, owner, limit (1–500, domyślnie 50), offset; sortowane według nazwy kwalifikowanej
GET /projects/<project>/elements/<id>Jeden element z polami, doc, tekstem SysML, składowymi i typowanymi przez niego użyciami; members (0–200, domyślnie 100)
GET /projects/<project>/elements/<id>/connectionsPołączenia, interfejsy, wiązania, przepływy (z elementem przepływu), następstwa, przejścia, alokacje i zależności przy elemencie lub jego cechach oraz te, które posiada wewnątrz; limit (domyślnie 100)
GET /projects/<project>/requirementsWymagania z identyfikatorem, treścią (doc), satisfiedBy i verifiedBy; owner, status (unsatisfied lub unverified), limit (domyślnie 100), offset
GET /projects/<project>/diagnosticsDiagnostyki modelu, najpierw błędy; ids (rozdzielone przecinkami: tylko te elementy i ich składowe), limit (domyślnie 200, najwyżej 500)
GET /projects/<project>/sysmlTekst SysML pakietu najwyższego poziomu (root), elementów spoza pakietów (bez root) lub jednego elementu (element); line (pierwszy wiersz, od 1), lines (domyślnie 2000, najwyżej 5000)
POST /projects/<project>/sysml/checkSprawdza text jako nowy tekst root (lub elementów spoza pakietów); niczego nie zmienia
POST /projects/<project>/proposal/changesDodaje zmianę do otwartej propozycji: {text, root} lub {edits}
GET /projects/<project>/proposalOtwarta propozycja lub propozycja o identyfikatorze proposal, z jej statusem i zmianami
POST /projects/<project>/proposalWysyła otwartą propozycję do przeglądu: title, summary
DELETE /projects/<project>/proposalOdrzuca otwartą propozycję przed wysłaniem

GET /projects i GET /projects/<project> działają również dla projektów SysML v2. Zwracają "language": "sysml2", a odpowiedź dla projektu dodaje elements i types (liczby elementów na metaklasę).

Trasy encji LML (/entities, /relationships, /schema, kontrole modelu i kontrola jakości) zwracają w projekcie SysML v2 409 wrong-project-type. Trasy SysML v2 zwracają to samo w projekcie LML.

Wartości

  • type: metaklasa, np. PartUsage lub RequirementDefinition, albo słowo kluczowe zapisane jak w tekście SysML: part, part def, attribute, port, requirement, action, package i inne słowa kluczowe elementów.
  • owner, id, element, root: identyfikator lub nazwa kwalifikowana. root przyjmuje też nazwę pakietu najwyższego poziomu. root musi być pakietem najwyższego poziomu; aby odczytać tekst jednego elementu, użyj element.
  • Długie wartości: doc na liście jest obcinany do 4000 znaków, doc pojedynczego elementu do 20 000, a własny tekst SysML elementu do 16 000 znaków.

Narzędzia MCP dla projektów SysML v2

Punkt końcowy MCP wymienia te narzędzia obok narzędzi LML. Narzędzie AI znajduje projekty SysML v2 za pomocą list_projects (language: sysml2). Każde narzędzie przyjmuje project.

Narzędzia do odczytu przyjmują też opcjonalny change_request (CR-12 lub jego identyfikator), aby odczytać model w postaci, jaką nadałby mu ten wniosek o zmianę; propose_sysml i propose_element_changes przyjmują go, aby wyliczyć zmianę względem modelu wniosku i po przeglądzie zastosować ją w tej wersji roboczej. Zasady opisuje sekcja Wnioski o zmianę.

NarzędzieDostępCo robi
model_summaryOdczytLiczby elementów na metaklasę, pakiety najwyższego poziomu i liczba diagnostyk
list_elementsOdczytZnajduje elementy według tekstu (query), type i owner; stronicowane przez limit i offset
get_elementOdczytJeden element (id) z typami, specjalizacjami, licznością, wartością, końcami, doc, tekstem SysML, składowymi (members, najwyżej 200) i typowanymi przez niego użyciami
get_connectionsOdczytPołączenia, interfejsy, wiązania, przepływy, następstwa, przejścia, alokacje i zależności elementu (id, limit)
list_requirementsOdczytWymagania z identyfikatorem, treścią, satisfy i verify; owner, status (unsatisfied, unverified), limit, offset
get_sysmlOdczytTekst SysML pakietu najwyższego poziomu (root), elementów spoza pakietów lub jednego elementu (element); line, lines (najwyżej 5000); odpowiedź podaje next
get_sysml_textOdczytTekst SysML całego modelu (każdy pakiet najwyższego poziomu, a potem elementy spoza pakietów) lub jednego pakietu (package), do 200 000 znaków na odpowiedź; odpowiedź wymienia pominięte pakiety
check_sysmlOdczytBez text: diagnostyki modelu (ids, limit). Z text (i root): błędy składni z wierszem i kolumną oraz błędy, które tekst by dodał. Niczego nie zmienia
propose_sysmlOdczyt i zapisProponuje pełny nowy tekst (text) pakietu najwyższego poziomu (root) lub elementów spoza pakietów (bez root; także tam, gdzie trafia nowy pakiet)
propose_element_changesOdczyt i zapisProponuje edycje (edits, najwyżej 100) bez przepisywania tekstu: tworzenie, aktualizację, przeniesienie lub usunięcie

list_diagrams, get_diagram i get_matrix działają także w projektach SysML v2: list_diagrams wymienia widoki (z ich rodzajem, np. InterconnectionView) i diagramy analizy przechowywane pod elementem; get_diagram podaje elementy, które widok udostępnia po zastosowaniu filtrów (według identyfikatora elementu lub nazwy kwalifikowanej); get_matrix podaje każde wymaganie z tym, co je spełnia i weryfikuje.

Narzędzia propozycji z projektów LML działają tu tak samo: propose_changes wysyła propozycję z tytułem i podsumowaniem, discard_proposal ją odrzuca, a get_proposal i list_proposals pokazują jej status. Token tylko do odczytu wymienia tylko narzędzia do odczytu.

Błędy narzędzi wracają jako wynik narzędzia z komunikatem i diagnostykami, aby narzędzie AI mogło poprawić tekst i spróbować ponownie.

Edycje elementów

Każda edycja w edits (MCP) lub {"edits": […]} (REST) jest obiektem z op:

opPola
createkind (słowo kluczowe, np. part, part def, attribute, port, requirement, action, package) lub type (metaklasa); owner (pominięty: najwyższy poziom); name (wymagane); opcjonalnie shortName, typedBy, specializes, subsets, redefines, multiplicity, value, doc, direction (in, out, inout)
updateid i pola do zmiany, jak przy tworzeniu; null lub "" czyści pole
moveid i nowy owner
removeid; usuwa element wraz z jego składowymi
  • typedBy, specializes, subsets i redefines to listy do 20 nazw: identyfikatorów, nazw kwalifikowanych lub nazw zapisanych jak w tekście (działają nazwy z biblioteki, np. MassValue).
  • Późniejsze edycje mogą wskazywać elementy utworzone wcześniej w tym samym wywołaniu jako new:1, new:2 … w kolejności tworzenia, na przykład jako owner. Odpowiedź wymienia je w created z nowymi identyfikatorami.
  • Zmiana nazwy elementu aktualizuje też odwołania, które wskazywały go starą nazwą.

Proponowany tekst

  • propose_sysml zastępuje cały tekst pakietu. Elementy zachowują identyfikatory tam, gdzie tekst nadal je deklaruje. Elementy pominięte w tekście są usuwane.
  • Tekst musi dać się przeanalizować bez niczego niezastosowanego. Tekst, który nie zmienia modelu, jest odrzucany (no-change).

Propozycje w projektach SysML v2

Każda proponowana zmiana jest sprawdzana przez rdzeń języka, zanim trafi do propozycji:

  • Tekst daje się przeanalizować bez błędów składni, a edycje elementów dają się zastosować.
  • Zmienione pakiety nadal dają się wydrukować jako tekst SysML i ponownie przeanalizować.
  • Zmiana nie dodaje do modelu diagnostyk błędów, takich jak nierozwiązane nazwy lub błędy typów. Błędy, które model już miał, się nie liczą.

Zmiana, która nie przejdzie sprawdzenia, jest odrzucana z diagnostykami (do 50) do poprawienia. Nic nie jest zapisywane. Ostrzeżenia nie powodują odrzucenia zmiany.

Proponowanie wymaga tokenu do odczytu i zapisu oraz roli edytora lub właściciela w projekcie. Jedna propozycja zawiera najwyżej 200 zmian i 8 MB.

Przegląd propozycji SysML v2

Otwórz projekt, a następnie ✦ AI ▾ → Przejrzyj „<title>”…. Każda zmiana jest wierszem z polem wyboru:

  • Dodano, Zmieniono i Usunięto wymieniają elementy ze zmienionymi polami (pierwsze 20 z każdej grupy; “i n więcej” dla reszty).
  • Różnice tekstu, opisane nazwą pakietu, pokazują tekst SysML przed zmianą i po niej.
  • Zmiana, która usuwa elementy, jest oznaczona i domyślnie odznaczona.
  • Otwórz model SysML v2, aby zastosować tę zmianę. Model nie jest wczytany; otwórz stronę SysML v2 projektu.
  • Pakietu nie ma już w modelu; pominięto. Pakiet został usunięty po zaproponowaniu zmiany.

Zastosuj zaznaczone ponownie synchronizuje każdą zmianę tekstu z bieżącym modelem i zachowuje edycje, których elementy nadal istnieją. Sprawdza cały zestaw i stosuje go jako jeden krok cofania. Zmiany, które już nie pasują, są pomijane i wymieniane w komunikacie. Odrzuć i Później działają jak w propozycjach LML, podobnie role, wygasanie (7 dni) i przechowywanie (zobacz Propozycje od klientów AI).

Systems Modeling API

Inne narzędzia SysML v2 odczytują i zmieniają modele Holarch przez trasy w kształtach OMG Systems Modeling API (REST/HTTP). Adres bazowy to https://app.holarch.app/api/v1/sysml. Używa tych samych tokenów; każda rola w projekcie może odczytywać, a edytorzy i właściciele mogą wykonywać commity.

  • Projekty: wymieniane są tylko projekty SysML v2. @id projektu to UUID nadawany mu przez to API; działa też identyfikator projektu Holarch. Odpowiedź zawiera holarchId i url.
  • Gałęzie: main to model bieżący i nie można go zmienić przez API. Każda inna gałąź to trwający wniosek o zmianę, nazwany “CR-12 Title” i zawierający holarchChangeRequest (id, label, status, url). Wnioski o zmianę wdrożone lub wycofane w ciągu ostatnich 30 dni są nadal wymieniane, z ustawionym deleted.
  • Commity: commit zapisuje zmiany w gałęzi wniosku o zmianę. Udostępniane są tylko czoła gałęzi: czoło main to model bieżący, a czoło gałęzi wniosku o zmianę to model bieżący ze zmianami wniosku. Starsze identyfikatory commitów zwracają 404; pobierz bieżące czoło z gałęzi.
  • Elementy: każdy element ma każdą właściwość swojej metaklasy ze schematu JSON OMG, łącznie z pochodnymi (owner, ownedElement, qualifiedName, feature, type i podobne). Do elementów biblioteki standardowej odwołują się ich standardowe identyfikatory, te same, których inne narzędzia SysML v2 używają dla tego samego elementu biblioteki.
  • Tagi i zapisane zapytania: brak; ich listy są puste.
Metoda i ścieżkaCo robi
GET /sysml/projectsTwoje projekty SysML v2
POST /sysml/projectsTworzy pusty projekt SysML v2 (name, description)
GET /sysml/projects/<projectId>Jeden projekt z jego gałęzią domyślną
GET /sysml/projects/<projectId>/branchesmain i gałęzie wniosków o zmianę
POST /sysml/projects/<projectId>/branchesTworzy gałąź: nowy wniosek o zmianę w stanie Draft (name to jego tytuł, description jego uzasadnienie)
GET /sysml/projects/<projectId>/branches/<branchId>Gałąź (jej @id lub main) z head
DELETE /sysml/projects/<projectId>/branches/<branchId>Wycofuje wniosek o zmianę
GET /sysml/projects/<projectId>/commitsCzoła i commity wysłane do gałęzi, od najnowszych
POST /sysml/projects/<projectId>/commits?branchId=<branchId>Zatwierdza zmiany w gałęzi (commit; poniżej)
GET /sysml/projects/<projectId>/commits/<commitId>Commit czoła gałęzi
GET /sysml/projects/<projectId>/commits/<commitId>/changesCo gałąź zmienia względem modelu bieżącego: jeden DataVersion na element
GET /sysml/projects/<projectId>/commits/<commitId>/elementsWszystkie elementy commita, stronicowane
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>Jeden element
GET /sysml/projects/<projectId>/commits/<commitId>/rootsElementy najwyższego poziomu, stronicowane
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>/relationshipsRelacje, w których element jest źródłem lub celem; direction to in, out lub both (domyślnie), stronicowane
POST /sysml/projects/<projectId>/query-resultsElementy pasujące do zapytania (treść poniżej), stronicowane; commitId musi być czołem gałęzi
GET /sysml/projects/<projectId>/tags, /queries, /commits/<commitId>/elements/<elementId>/projectUsagesPuste listy

Odpowiedzi z listami to tablice JSON. Listy są stronicowane przez page[size] (domyślnie 100, najwyżej 1000) oraz page[after] (@id ostatniej pozycji poprzedniej strony) lub page[before] (@id pierwszej pozycji następnej strony). Nagłówek Link podaje następną stronę z rel="next" i poprzednią z rel="prev".

Zapytanie to obiekt JSON z opcjonalnymi polami where (PrimitiveConstraint z property, operator (=, in, <, <=, >, >= lub instanceOf), value i inverse albo CompositeConstraint z operator and lub or i constraint), scope (identyfikatory elementów: wyszukiwanie obejmuje je i to, co posiadają) oraz select (właściwości do zwrócenia; @id i @type są zwracane zawsze):

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"]}'

Odczytaj elementy modelu:

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"

Zatwierdzanie zmian (commit)

Zapis wymaga tokenu z dostępem do odczytu i zapisu, roli edytora lub właściciela, planu Team (także dla kont akademickich i zajęciowych) oraz włączonego przeglądu gałęzi w projekcie (Wnioski o zmianę → Ustawienia). Zatwierdzający przegląda i stosuje wniosek o zmianę w Holarch; tokeny nigdy nie głosują ani nie stosują zmian.

  1. Utwórz gałąź: POST /branches z {"@type": "Branch", "name": "Cabin heater"}. Odpowiedzią jest gałąź z jej holarchChangeRequest.
  2. Odczytaj czoło gałęzi i jego elementy.
  3. POST /commits?branchId=<branch @id> z listą obiektów 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>"}}}]}'
  • Zmiana elementu: wyślij element w postaci, w jakiej go odczytano, ze zmienionymi właściwościami. Liczą się tylko właściwości posiadane (declaredName, ownedRelationship, isAbstract i podobne); pochodne są ignorowane, więc odesłanie tego, co odczytano, niczego nie zmienia. Pominięta właściwość zachowuje swoją wartość; wyślij null lub [], aby ją wyczyścić.
  • Nowe elementy: nadaj elementowi nowy UUID i podaj albo jego członkostwo właścicielskie (wysłane w tym samym commicie), albo owner, który tworzy członkostwo automatycznie.
  • Usuwanie elementu: payload: null usuwa go wraz ze wszystkim, co posiada.
  • Kontrole: każdy pakiet, którego dotyczy commit, musi dać się wydrukować i ponownie przeanalizować, a commit nie może dodawać diagnostyk błędów; w przeciwnym razie 422 z diagnostics do poprawienia.
  • previousCommit: czoło, na którym wprowadzono zmianę. Jeśli gałąź od tego czasu się przesunęła, odpowiedzią jest 409 stale-head z bieżącym head; odczytaj ponownie i wykonaj commit na jego podstawie.
  • Ponowienia: wyślij nagłówek Idempotency-Key. Ponowienie z tym samym kluczem i treścią w ciągu 24 godzin otrzymuje ponownie pierwszą odpowiedź.
  • Commity do main: commit bez branchId lub z main trafia do własnego roboczego wniosku o zmianę tokenu (“API changes from <token name>”), tworzonego przy pierwszym takim commicie. Odpowiedź podaje, który to wniosek, w holarchChangeRequest i w nagłówku Warning.
  • Nowe projekty: projekt utworzony przez POST /sysml/projects ma włączony przegląd gałęzi. Jego pierwszy commit do main, gdy jesteś jego jedynym członkiem, jest jednorazowo zapisywany bezpośrednio w modelu; późniejsze commity przechodzą przez wnioski o zmianę.

Prześlij wniosek o zmianę do przeglądu przez POST /api/v1/projects/<project>/change-requests/<CR-12>/submit (API i MCP). Tagi, scalenia oraz zmiana nazwy lub usunięcie projektu zwracają 405 z informacją, co zrobić zamiast tego. Błędy mają @type Error i description, zgodnie z definicją w OMG API.

Komunikaty

Obowiązują kody ze strony API i MCP. Trasy i narzędzia SysML v2 dodają:

KodStatusZnaczenie
wrong-project-type409Operacja LML w projekcie SysML v2 lub operacja SysML v2 w projekcie LML
syntax422Proponowany tekst ma błędy składni; diagnostyki podają wiersz i kolumnę
invalid-model422Zmiana dodaje do modelu diagnostyki błędów; są one wymienione
not-printable422Zmiany nie da się zapisać jako tekstu SysML
invalid422Nie udało się zastosować zmiany do modelu
no-change400Tekst nie zmienia modelu
too-large413Tekst jest dłuższy niż 1 000 000 znaków lub propozycja jest większa niż 8 MB
too-many413 lub 409Więcej niż 100 edycji w jednym wywołaniu (413) lub propozycja zawiera już 200 zmian (409)
stale409Wcześniejsza zmiana tekstu w propozycji nie daje się już zastosować do modelu
not-found404Nie ma takiego projektu, elementu, gałęzi ani commita (Systems Modeling API udostępnia tylko czoła gałęzi)
not-writable405Tagi, scalenia, zmiana nazwy lub usunięcie projektu przez Systems Modeling API; wykonaj to w Holarch
main-protected405Usunięcie main; zamiast tego usuń gałąź wniosku o zmianę
stale-head409Gałąź przesunęła się od previousCommit; odczytaj jej head i wykonaj commit ponownie
branch-base409Nowa gałąź musi zaczynać się od czoła main
branch-review-off409Projekt nie używa przeglądu gałęzi; właściciel włącza go w Wnioski o zmianę → Ustawienia
cr-not-draft409Wniosek o zmianę został przesłany lub zamknięty; można go zapisywać tylko w stanie Draft lub Rejected
cr-full409Wniosek o zmianę zawiera 5000 zmienionych elementów lub projekt ma 20 MB wersji roboczych wniosków o zmianę
plan-limit403Zapisy do wniosków o zmianę wymagają planu Team
orphan422Nowy element nie ma właściciela; wyślij jego członkostwo właścicielskie lub owner
unknown-metaclass422@type ładunku nie jest metaklasą SysML v2
idempotency-key-reused422Idempotency-Key został użyty z inną treścią; wyślij nowy klucz
token-projects403Token ograniczony do listy projektów nie może utworzyć projektu
bad-request400Brakująca lub błędna wartość, np. root, który nie jest pakietem najwyższego poziomu, nieznany op lub nowy element bez nazwy

Limity

CoLimit
Elementy, wymagania lub połączenia na stronę500
Składowe wymienione z elementem200
Diagnostyki na odpowiedź500
Wiersze tekstu SysML na odpowiedź5000 i najwyżej 400 000 bajtów (obcięte na granicy wiersza)
Tekst doc4000 znaków na listach, 20 000 dla jednego elementu
Własny tekst SysML elementu16 000 znaków
Tekst w jednym wywołaniu propose_sysml1 000 000 znaków
Edycje w jednym wywołaniu100
Elementy wymienione jako dodane, zmienione lub usunięte w jednej zmianiePo 300
Zmiany w jednej propozycji200 i 8 MB
Strona Systems Modeling API1000 elementów (domyślnie 100)
Obiekty DataVersion w jednym commicie5,000
Zmienione elementy w jednym wniosku o zmianę5,000
Treść commita32 MB

Limity żądań, rozmiar żądań i zasady tokenów są takie jak na stronie API i MCP.

SysML® i OMG® są zastrzeżonymi znakami towarowymi Object Management Group, Inc. w Stanach Zjednoczonych i innych krajach.