Holarch

SysML v2

API і MCP у проєктах SysML v2

Читайте, шукайте та перевіряйте моделі SysML v2 зі скриптів та інструментів ШІ за допомогою персонального токена доступу, пропонуйте зміни, які ви переглядаєте та застосовуєте в Holarch, і читайте та фіксуйте зміни через Systems Modeling API, де гілки є запитами на зміну.

Як цим користуватися →

На цій сторінці
  1. Огляд
  2. Поняття
  3. Як користуватися
    1. Читання проєкту SysML v2 за допомогою curl
    2. Перевірка тексту SysML перед пропозицією
    3. Пропозиція зміни та її застосування
    4. Під’єднання інструмента ШІ до проєкту SysML v2
    5. Приклад: демопроєкт Hybrid Car
    6. Поради
  4. Маршрути REST для проєктів SysML v2
    1. Значення
  5. Інструменти MCP для проєктів SysML v2
    1. Зміни елементів
    2. Запропонований текст
  6. Пропозиції в проєктах SysML v2
    1. Рецензування пропозиції SysML v2
  7. Systems Modeling API
    1. Коміт змін
  8. Повідомлення
  9. Обмеження
  10. Пов’язані сторінки

Огляд

Проєкти SysML v2 працюють з тим самим REST API, кінцевою точкою MCP і персональними токенами доступу, що й проєкти LML. Скрипти й інструменти ШІ читають модель як елементи й текст SysML, перевіряють текст, перш ніж щось змінити, і пропонують зміни. Нічого в моделі не змінюється, доки людина не прорецензує пропозицію в Holarch і не застосує її.

Три способи доступу:

  • REST API: https://app.holarch.app/api/v1/projects/<project>/… для скриптів і панелей моніторингу. Він читає елементи, вимоги, діагностику й текст SysML і додає зміни до пропозиції.
  • MCP: https://app.holarch.app/mcp для інструментів ШІ, як-от Claude. Інструменти SysML v2 читають, шукають і перевіряють модель та пропонують зміни.
  • Systems Modeling API: https://app.holarch.app/api/v1/sysml/…, у формах OMG Systems Modeling API для інших інструментів SysML v2. Гілка main — це жива модель, доступна лише для читання; кожна інша гілка — запит на зміну, і коміти йдуть у неї. Жива модель змінюється лише тоді, коли затверджувач застосовує запит на зміну в Holarch.

Токени, області доступу, списки проєктів, перемикач організації, обмеження частоти й під’єднання Claude такі самі, як для проєктів LML. Як створити токен і під’єднати інструмент ШІ, див. API і MCP. Виклики Карта програми (GET /api/v1/program-map, GET /api/v1/projects/<project>/items/<item>/trace та інструменти MCP program_map і trace_chain) охоплюють проєкти SysML v2 та їхні елементи.

Поняття

  • Елемент: один складник моделі SysML v2, як-от визначення частини, порт або вимога. Кожен елемент має id (UUID). Скрізь, де маршрут чи інструмент просить id, працює також кваліфікована назва, як-от Vehicles::Car::powertrain.
  • Стисла форма: коротка форма елемента в списках: id, type (метаклас, як-от PartUsage), name, shortName, qualifiedName і owner.
  • Пакет верхнього рівня: пакет, що не міститься в іншому елементі. Текст SysML проєкту — це по одному тексту на пакет верхнього рівня плюс один текст для елементів поза пакетами.
  • Діагностика: проблема, яку знаходить ядро мови, з code, severity (error або warning), elementId, element і args. Синтаксична діагностика замість елемента дає line і col.
  • Пропозиція: зміни, які клієнт API чи інструмент ШІ збирає для рецензування. Для кожного токена й проєкту відкрита одна пропозиція. Клієнт надсилає її на рецензування з заголовком і підсумком.
  • Посторінкові відповіді: списки надходять сторінками (limit, offset). Довгий текст SysML надходить сторінками рядків (line, lines). Відповідь, у якій щось пропущено, містить truncated: true.

Як користуватися

Використовуйте API, коли скрипту чи інструменту ШІ потрібна модель: щоб звітувати про вимоги без елементів, що їх задовольняють або верифікують, щоб перевірити текст SysML команди щодо моделі або щоб дозволити інструменту ШІ підготувати чернетки змін моделі, які потім рецензує інженер.

Читання проєкту SysML v2 за допомогою curl

  1. Створіть токен у Налаштування облікового запису → Токени API (див. API і MCP).
  2. Перелічіть свої проєкти:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects

Проєкти SysML v2 мають "language": "sysml2".

  1. Отримайте зведення моделі:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects/<project>/model

Ви бачите кількість елементів за метакласами, пакети верхнього рівня й кількість помилок і попереджень.

  1. Знайдіть елементи, наприклад кожне визначення частини:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/elements?type=part%20def&limit=100"
  1. Прочитайте текст SysML пакета:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/sysml?root=Vehicles"

Довгий текст закінчується "truncated": true і "next": рядком, який слід запросити далі через line.

Перевірка тексту SysML перед пропозицією

  1. Надішліть новий текст пакета на маршрут перевірки:
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. Прочитайте відповідь. ok дорівнює true, коли текст не має синтаксичних помилок. diagnostics перелічує синтаксичні помилки з line і col, а також помилки, які текст додав би до моделі. changes — кількість змін моделі, які вносить текст.

Перевірка нічого не змінює. Їй потрібен лише токен читання.

Пропозиція зміни та її застосування

Токен запису додає зміни до відкритої пропозиції токена. Потім клієнт надсилає пропозицію на рецензування.

  1. Додайте зміну. Надішліть або повний новий текст пакета, або зміни елементів:
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

Ви отримуєте 201 з пропозицією, підсумком зміни та елементами, які вона додає, змінює й вилучає. Зміна, що додає діагностику помилок, відхиляється (див. Пропозиції в проєктах SysML v2).

  1. Додавайте інші зміни так само. Кожна зміна перевіряється щодо моделі із застосованими попередніми змінами пропозиції.
  2. Надішліть пропозицію на рецензування:
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. У Holarch відкрийте проєкт, потім відкрийте ✦ ШІ ▾ → Переглянути “Add range attribute”… (або сповіщення під дзвіночком).
  2. Перевірте рядки й натисніть Застосувати вибране.

    Позначені зміни застосовуються з вашим іменем в історії, і одне натискання “Відмінити” повертає все назад.

Під’єднання інструмента ШІ до проєкту SysML v2

  1. Під’єднайте інструмент ШІ до https://app.holarch.app/mcp за допомогою токена або входу (див. API і MCP).
  2. Запитайте про модель, наприклад “Підсумуй модель Hybrid Car у Holarch” або “Які вимоги в проєкті Hybrid Car не верифіковано?”.

    Інструмент ШІ використовує model_summary, list_elements, list_requirements та інші інструменти читання.

  3. Попросіть зміну, наприклад “Запропонуй атрибут range для Car”.

    Інструмент ШІ читає пакет через get_sysml, пропонує текст або зміни елементів і виправляє діагностику, яку повертає перевірка.

  4. Прорецензуйте пропозицію в Holarch і натисніть Застосувати вибране.

Приклад: демопроєкт Hybrid Car

Створіть демопроєкт через Керування проєктами → Файли проєктів ▾ → Новий демопроєкт → Hybrid Car (SysML v2), потім створіть для нього токен читання й запису.

  1. GET /api/v1/projects/<project>/model перелічує пакети верхнього рівня, серед них Vehicles, HybridCarArchitecture і VehicleBehavior.
  2. GET /api/v1/projects/<project>/elements?query=Engine&type=part%20def знаходить Vehicles::Engine.
  3. GET /api/v1/projects/<project>/elements/Vehicles::Engine повертає визначення частини з його текстом SysML, членами (displacement, cylinders, maxPower, порти fuelIn, output і ecu) і використаннями, типізованими ним.
  4. GET /api/v1/projects/<project>/elements/Vehicles::Car/connections перелічує інтерфейс driveShaft від powertrain.output до frontAxle.input.
  5. GET /api/v1/projects/<project>/requirements?status=unverified перелічує вимоги, які не верифікує жоден випадок верифікації, з їхніми ідентифікаторами, як-от VR-4.1.
  6. POST /api/v1/projects/<project>/proposal/changes з {"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]} додає зміну до пропозиції. POST /api/v1/projects/<project>/proposal із заголовком надсилає її.
  7. У Holarch ✦ ШІ ▾ → Переглянути “…” показує Змінено: з визначенням частини й полем doc, а також текстову різницю Vehicles. Застосувати вибране застосовує її.

Поради

  • Прочитайте пакет через get_sysml (або GET …/sysml?root=), перш ніж пропонувати для нього новий текст. Елементи, пропущені в запропонованому тексті, вилучаються.
  • Для невеликих змін надавайте перевагу змінам елементів. Вони змінюють лише названі елементи й залишають решту тексту пакета як є.
  • Спершу перевірте текст через check_sysml (або POST …/sysml/check). Він повертає ту саму діагностику, з якою було б відхилено пропозицію.
  • У скриптах називайте елементи кваліфікованою назвою. Ідентифікатори не змінюються, коли елемент перейменовують; кваліфіковані назви змінюються.
  • Давайте інструменту ШІ токен лише для читання, коли він тільки відповідає на запитання про модель.

Маршрути REST для проєктів SysML v2

Базова адреса: https://app.holarch.app/api/v1. Відповіді — у JSON. /api/v1/openapi.json (OpenAPI 3.1) описує ці маршрути разом з іншими.

Метод і шляхЩо він робить
GET /projects/<project>/modelКількість елементів за метакласами, пакети верхнього рівня з кількістю їхніх елементів, а також кількість помилок і попереджень
GET /projects/<project>/elementsПошук: query (або q; текст у назві, короткому імені, кваліфікованій назві чи doc), type, owner, limit (1–500, за замовчуванням 50), offset; сортування за кваліфікованою назвою
GET /projects/<project>/elements/<id>Один елемент з його полями, doc, текстом SysML, членами й використаннями, типізованими ним; members (0–200, за замовчуванням 100)
GET /projects/<project>/elements/<id>/connectionsЗ’єднання, інтерфейси, зв’язування, потоки (з предметом), послідовності, переходи, розподіли й залежності на елементі або його ознаках, а також ті, що належать до нього; limit (за замовчуванням 100)
GET /projects/<project>/requirementsВимоги з їхнім ідентифікатором, формулюванням (doc), satisfiedBy і verifiedBy; owner, status (unsatisfied або unverified), limit (за замовчуванням 100), offset
GET /projects/<project>/diagnosticsДіагностика моделі, спершу помилки; ids (через кому: лише ці елементи та їхні члени), limit (за замовчуванням 200, не більше 500)
GET /projects/<project>/sysmlТекст SysML пакета верхнього рівня (root), елементів поза пакетами (без root) або одного елемента (element); line (перший рядок, від 1), lines (за замовчуванням 2000, не більше 5000)
POST /projects/<project>/sysml/checkПеревірити text як новий текст root (або елементів поза пакетами); нічого не змінює
POST /projects/<project>/proposal/changesДодати зміну до відкритої пропозиції: {text, root} або {edits}
GET /projects/<project>/proposalВідкрита пропозиція або пропозиція за ідентифікатором proposal, з її статусом і змінами
POST /projects/<project>/proposalНадіслати відкриту пропозицію на рецензування: title, summary
DELETE /projects/<project>/proposalВідкинути відкриту пропозицію до надсилання

GET /projects і GET /projects/<project> також працюють для проєктів SysML v2. Вони дають "language": "sysml2", а відповідь про проєкт додає elements і types (кількість елементів за метакласами).

Маршрути сутностей LML (/entities, /relationships, /schema, Перевірки моделі та перевірка якості) у проєкті SysML v2 відповідають 409 wrong-project-type. Маршрути SysML v2 відповідають так само в проєкті LML.

Значення

  • type: метаклас, як-от PartUsage чи RequirementDefinition, або ключове слово, як його записано в тексті SysML: part, part def, attribute, port, requirement, action, package та інші ключові слова елементів.
  • owner, id, element, root: ідентифікатор або кваліфікована назва. root також приймає назву пакета верхнього рівня. root має бути пакетом верхнього рівня; щоб прочитати текст одного елемента, використовуйте element.
  • Довгі значення: doc у списку обрізається до 4,000 символів, doc окремого елемента — до 20,000, а власний текст SysML елемента — до 16,000 символів.

Інструменти MCP для проєктів SysML v2

Кінцева точка MCP перелічує ці інструменти поруч з інструментами LML. Інструмент ШІ знаходить проєкти SysML v2 через list_projects (language: sysml2). Кожен інструмент приймає project.

Інструменти читання також приймають необов’язковий change_request (CR-12 або його ідентифікатор), щоб читати модель такою, якою її зробив би цей запит на зміну; propose_sysml і propose_element_changes приймають його, щоб обчислити зміну щодо моделі запиту й після рецензування застосувати її в цю чернетку. Правила див. у Запити на зміну.

ІнструментДоступЩо він робить
model_summaryЧитанняКількість елементів за метакласами, пакети верхнього рівня й кількість діагностик
list_elementsЧитанняПошук елементів за текстом (query), type і owner; посторінково через limit і offset
get_elementЧитанняОдин елемент (id) з його типами, спеціалізаціями, кратністю, значенням, кінцями, doc, текстом SysML, членами (members, не більше 200) і використаннями, типізованими ним
get_connectionsЧитанняЗ’єднання, інтерфейси, зв’язування, потоки, послідовності, переходи, розподіли й залежності елемента (id, limit)
list_requirementsЧитанняВимоги з їхнім ідентифікатором, формулюванням, satisfy і verify; owner, status (unsatisfied, unverified), limit, offset
get_sysmlЧитанняТекст SysML пакета верхнього рівня (root), елементів поза пакетами або одного елемента (element); line, lines (не більше 5000); відповідь дає next
get_sysml_textЧитанняТекст SysML усієї моделі (кожен пакет верхнього рівня, потім елементи поза пакетами) або одного package, до 200,000 символів на відповідь; відповідь називає пропущені пакети
check_sysmlЧитанняБез text: діагностика моделі (ids, limit). З text (і root): синтаксичні помилки з рядком і стовпцем, а також помилки, які додав би текст. Нічого не змінює
propose_sysmlЧитання й записЗапропонувати повний новий text пакета верхнього рівня (root) або елементів поза пакетами (без root; також туди, де з’являється новий пакет)
propose_element_changesЧитання й записЗапропонувати edits (не більше 100) без переписування тексту: створити, оновити, перемістити або вилучити

list_diagrams, get_diagram і get_matrix працюють і в проєктах SysML v2: list_diagrams перелічує подання (з їхнім видом, як-от InterconnectionView) і діаграми аналізу, що зберігаються під елементом; get_diagram дає елементи, які подання показує після своїх фільтрів (за ідентифікатором елемента або кваліфікованою назвою); get_matrix дає кожну вимогу з тим, що її задовольняє й верифікує.

Інструменти пропозицій проєктів LML тут працюють так само: propose_changes надсилає пропозицію з заголовком і підсумком, discard_proposal відкидає її, а get_proposal і list_proposals показують її статус. Токен лише для читання перелічує тільки інструменти читання.

Помилки інструментів повертаються як результат інструмента з повідомленням і діагностикою, тож інструмент ШІ може виправити свій текст і спробувати знову.

Зміни елементів

Кожна зміна в edits (MCP) або {"edits": […]} (REST) — це об’єкт з op:

opПоля
createkind (ключове слово, як-от part, part def, attribute, port, requirement, action, package) або type (метаклас); owner (якщо пропущено: верхній рівень); name (обов’язково); необов’язкові shortName, typedBy, specializes, subsets, redefines, multiplicity, value, doc, direction (in, out, inout)
updateid і поля для зміни, як для create; null або "" очищує поле
moveid і новий owner
removeid; вилучає елемент з його членами
  • typedBy, specializes, subsets і redefines — списки до 20 імен: ідентифікаторів, кваліфікованих назв або імен, як їх записано в тексті (бібліотечні імена, як-от MassValue, працюють).
  • Пізніші зміни можуть називати елементи, створені раніше в тому самому виклику, як new:1, new:2 … у порядку створення, наприклад як owner. Відповідь перелічує їх у created з їхніми новими ідентифікаторами.
  • Перейменування елемента також оновлює посилання, які називали його старим іменем.

Запропонований текст

  • propose_sysml замінює весь текст пакета. Елементи зберігають свої ідентифікатори там, де текст і далі їх оголошує. Елементи, пропущені в тексті, вилучаються.
  • Текст має розбиратися повністю, без незастосованих залишків. Текст, що не змінює модель, відхиляється (no-change).

Пропозиції в проєктах SysML v2

Кожну запропоновану зміну перевіряє ядро мови, перш ніж вона потрапить до пропозиції:

  • Текст розбирається без синтаксичних помилок, а зміни елементів застосовуються.
  • Змінені пакети й далі друкуються як текст SysML і знову розбираються.
  • Зміна не додає до моделі діагностики помилок, як-от нерозв’язаних імен чи помилок типів. Помилки, які модель уже мала, не враховуються.

Зміна, що не проходить перевірку, відхиляється з діагностикою (до 50) для виправлення. Нічого не зберігається. Попередження не спричиняють відхилення зміни.

Для пропозицій потрібні токен читання й запису та роль редактора або власника в проєкті. Одна пропозиція містить не більше 200 змін і 8 MB.

Рецензування пропозиції SysML v2

Відкрийте проєкт, потім ✦ ШІ ▾ → Переглянути “<title>”…. Кожна зміна — це рядок із прапорцем:

  • Додано, Змінено і Вилучено перелічують елементи зі зміненими полями (перші 20 кожного виду; “і ще n” для решти).
  • Текстова різниця з позначкою пакета показує текст SysML до й після.
  • Зміна, що вилучає елементи, позначається й спочатку не позначена прапорцем.
  • Відкрийте модель SysML v2, щоб застосувати цю зміну. Модель не завантажено; відкрийте сторінку SysML v2 проєкту.
  • Пакета більше немає в моделі; пропущено. Пакет вилучили після того, як зміну було запропоновано.

Застосувати вибране знову синхронізує кожну текстову зміну з поточною моделлю й зберігає зміни, елементи яких ще існують. Воно перевіряє весь набір і застосовує його як один крок відміни. Зміни, які більше не підходять, пропускаються й називаються у сповіщенні. Відхилити і Пізніше працюють як для пропозицій LML, так само як ролі, термін дії (7 днів) і зберігання (див. Пропозиції від клієнтів ШІ).

Systems Modeling API

Інші інструменти SysML v2 читають і змінюють моделі Holarch через маршрути у формах OMG Systems Modeling API (REST/HTTP). Базова адреса — https://app.holarch.app/api/v1/sysml. Використовуються ті самі токени; читати може будь-яка роль у проєкті, а комітити — редактори й власники.

  • Проєкти: перелічуються лише проєкти SysML v2. @id проєкту — це UUID, який надає цей API; ідентифікатор проєкту Holarch також працює. Відповідь містить holarchId і url.
  • Гілки: main — це жива модель, і її не можна змінити через API. Кожна інша гілка — це запит на зміну в роботі з назвою "CR-12 Title", що несе holarchChangeRequest (id, label, status, url). Запити на зміну, реалізовані або відкликані за останні 30 днів, ще перелічуються з установленим deleted.
  • Коміти: коміт записує зміни в гілку запиту на зміну. Надаються лише вершини гілок: вершина main — це жива модель, вершина гілки запиту на зміну — жива модель зі змінами запиту. Старіші ідентифікатори комітів відповідають 404; отримайте поточну вершину з гілки.
  • Елементи: кожен елемент має всі властивості свого метакласу зі схеми OMG JSON, включно з похідними (owner, ownedElement, qualifiedName, feature, type тощо). На елементи стандартної бібліотеки посилаються за їхніми стандартними ідентифікаторами — тими, що їх інші інструменти SysML v2 використовують для того самого бібліотечного елемента.
  • Теги й збережені запити: немає; їхні списки порожні.
Метод і шляхЩо він робить
GET /sysml/projectsВаші проєкти SysML v2
POST /sysml/projectsСтворити порожній проєкт SysML v2 (name, description)
GET /sysml/projects/<projectId>Один проєкт з його гілкою за замовчуванням
GET /sysml/projects/<projectId>/branchesmain і гілки запитів на зміну
POST /sysml/projects/<projectId>/branchesСтворити гілку: новий запит на зміну в стані Чернетка (name — його заголовок, description — його причина)
GET /sysml/projects/<projectId>/branches/<branchId>Гілка (її @id або main) з head
DELETE /sysml/projects/<projectId>/branches/<branchId>Відкликати запит на зміну
GET /sysml/projects/<projectId>/commitsВершини й коміти, надіслані в гілки, спершу найновіші
POST /sysml/projects/<projectId>/commits?branchId=<branchId>Закомітити зміни в гілку (нижче)
GET /sysml/projects/<projectId>/commits/<commitId>Коміт-вершина
GET /sysml/projects/<projectId>/commits/<commitId>/changesЩо гілка змінює порівняно з живою моделлю: по одному DataVersion на елемент
GET /sysml/projects/<projectId>/commits/<commitId>/elementsУсі елементи коміту, посторінково
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>Один елемент
GET /sysml/projects/<projectId>/commits/<commitId>/rootsЕлементи верхнього рівня, посторінково
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>/relationshipsЗв’язки, у яких елемент є джерелом або ціллю; direction — in, out або both (за замовчуванням), посторінково
POST /sysml/projects/<projectId>/query-resultsЕлементи, що відповідають запиту (тіло нижче), посторінково; commitId має бути вершиною
GET /sysml/projects/<projectId>/tags, /queries, /commits/<commitId>/elements/<elementId>/projectUsagesПорожні списки

Відповіді-списки — це масиви JSON. Списки розбиваються на сторінки через page[size] (за замовчуванням 100, не більше 1000) і page[after] (@id останнього елемента попередньої сторінки) або page[before] (@id першого елемента наступної сторінки). Заголовок Link дає наступну сторінку з rel="next" і попередню з rel="prev".

Запит — це об’єкт JSON з необов’язковими where (PrimitiveConstraint з property, operator (=, in, <, <=, >, >= або instanceOf), value та inverse, або CompositeConstraint з operator and чи or та constraint), scope (ідентифікатори елементів: пошук охоплює їх і те, чим вони володіють) і select (властивості, які слід повернути; @id і @type повертаються завжди):

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

Читання елементів моделі:

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"

Коміт змін

Для запису потрібні токен з доступом на читання й запис, роль редактора або власника, тариф Team (також для академічних і навчальних облікових записів) і ввімкнене для проєкту рецензування гілок (Запити на зміну → Налаштування). Затверджувач рецензує й застосовує запит на зміну в Holarch; токени ніколи не голосують і не застосовують.

  1. Створіть гілку: POST /branches з {"@type": "Branch", "name": "Cabin heater"}. Відповідь — гілка з її holarchChangeRequest.
  2. Прочитайте вершину гілки та її елементи.
  3. POST /commits?branchId=<branch @id> зі списком 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>"}}}]}'
  • Зміна елемента: надішліть елемент таким, яким ви його прочитали, зі зміненими властивостями. Враховуються лише власні властивості (declaredName, ownedRelationship, isAbstract тощо); похідні ігноруються, тож надсилання назад прочитаного нічого не змінює. Властивість, яку ви пропустили, зберігає своє значення; надішліть null або [], щоб її очистити.
  • Нові елементи: дайте елементу новий UUID і або його членство-власника (надіслане в тому самому коміті), або owner, що створює членство за вас.
  • Вилучення елемента: payload: null вилучає його разом з усім, чим він володіє.
  • Перевірки: кожен пакет, якого торкається коміт, має знову друкуватися й розбиратися, і коміт не має додавати діагностики помилок; інакше 422 з diagnostics для виправлення.
  • previousCommit: вершина, на якій зроблено вашу зміну. Якщо гілка відтоді змістилася, відповідь — 409 stale-head з поточною head; прочитайте знову й закомітьте поверх неї.
  • Повтори: надсилайте заголовок Idempotency-Key. Повтор з тим самим ключем і тілом протягом 24 годин знову отримує першу відповідь.
  • Коміти в main: коміт без branchId або з main потрапляє до власного чернеткового запиту на зміну вашого токена ("API changes from <token name>"), створеного під час першого такого коміту. Відповідь вказує, якого саме, у holarchChangeRequest і в заголовку Warning.
  • Нові проєкти: проєкт, створений через POST /sysml/projects, має ввімкнене рецензування гілок. Його перший коміт у main, поки ви єдиний учасник, записується в модель напряму, один раз; пізніші коміти проходять через запити на зміну.

Надішліть запит на зміну на рецензування через POST /api/v1/projects/<project>/change-requests/<CR-12>/submit (API і MCP). Теги, об’єднання та перейменування чи видалення проєкту відповідають 405 з тим, що зробити натомість. Помилки несуть @type Error і description, як їх визначає OMG API.

Повідомлення

Діють коди з API і MCP. Маршрути й інструменти SysML v2 додають:

КодСтатусЗначення
wrong-project-type409Операція LML у проєкті SysML v2 або операція SysML v2 у проєкті LML
syntax422Запропонований текст має синтаксичні помилки; діагностика вказує рядок і стовпець
invalid-model422Зміна додає до моделі діагностику помилок; її перелічено
not-printable422Зміну не можна записати як текст SysML
invalid422Зміну не вдалося застосувати до моделі
no-change400Текст не змінює модель
too-large413Текст довший за 1,000,000 символів, або пропозиція більша за 8 MB
too-many413 або 409Понад 100 змін в одному виклику (413), або пропозиція вже містить 200 змін (409)
stale409Попередня текстова зміна пропозиції більше не застосовується до моделі
not-found404Немає такого проєкту, елемента, гілки чи коміту (Systems Modeling API надає лише вершини гілок)
not-writable405Теги, об’єднання, перейменування чи видалення проєкту через Systems Modeling API; зробіть це в Holarch
main-protected405Видалення main; видаліть натомість гілку запиту на зміну
stale-head409Гілка змістилася з часу previousCommit; прочитайте її head і закомітьте знову
branch-base409Нова гілка має починатися з вершини main
branch-review-off409Проєкт не використовує рецензування гілок; власник вмикає його в Запити на зміну → Налаштування
cr-not-draft409Запит на зміну надіслано або закрито; записувати в нього можна лише в стані Чернетка або Відхилено
cr-full409Запит на зміну містить 5,000 змінених елементів, або проєкт — 20 MB чернеток запитів на зміну
plan-limit403Запис у запити на зміну потребує тарифу Team
orphan422Новий елемент не має власника; надішліть його членство-власника або owner
unknown-metaclass422@type корисного навантаження не є метакласом SysML v2
idempotency-key-reused422Idempotency-Key уже використано з іншим тілом; надішліть новий ключ
token-projects403Токен, обмежений списком проєктів, не може створити проєкт
bad-request400Відсутнє або неправильне значення, як-от root, що не є пакетом верхнього рівня, невідомий op або новий елемент без назви

Обмеження

ЩоОбмеження
Елементів, вимог або з’єднань на сторінку500
Членів, перелічених з елементом200
Діагностик на відповідь500
Рядків тексту SysML на відповідь5,000, і не більше 400,000 байтів (обрізається по рядку)
Текст doc4,000 символів у списках, 20,000 для одного елемента
Власний текст SysML елемента16,000 символів
Текст в одному виклику propose_sysml1,000,000 символів
Змін в одному виклику100
Елементів, перелічених як додані, змінені або вилучені в одній змініпо 300
Змін в одній пропозиції200 і 8 MB
Сторінка Systems Modeling API1,000 елементів (за замовчуванням 100)
DataVersion в одному коміті5,000
Змінених елементів в одному запиті на зміну5,000
Тіло коміту32 MB

Обмеження частоти, розміру запиту й правила токенів — ті самі, що в API і MCP.

SysML® і OMG® — зареєстровані торговельні марки Object Management Group, Inc. у США та інших країнах.