Holarch

SysML v2

SysML v2 projelerinde API ve MCP

SysML v2 modellerini kişisel erişim belirteciyle betiklerden ve YZ araçlarından okuyun, arayın ve denetleyin; Holarch'ta inceleyip uyguladığınız değişiklikler önerin ve dalların değişiklik talepleri olduğu Systems Modeling API üzerinden okuyup commit edin.

Nasıl kullanılır →

Bu sayfada
  1. Genel bakış
  2. Kavramlar
  3. Nasıl kullanılır
    1. curl ile bir SysML v2 projesini okuma
    2. SysML metnini önermeden önce denetleme
    3. Bir değişiklik önerme ve uygulama
    4. Bir YZ aracını bir SysML v2 projesine bağlama
    5. Çalışılmış örnek: Hybrid Car demosu
    6. İpuçları
  4. SysML v2 projeleri için REST rotaları
    1. Değerler
  5. SysML v2 projeleri için MCP araçları
    1. Öğe düzenlemeleri
    2. Önerilen metin
  6. SysML v2 projelerinde öneriler
    1. Bir SysML v2 önerisini inceleme
  7. Systems Modeling API
    1. Değişiklikleri commit etme
  8. İletiler
  9. Sınırlar
  10. İlgili sayfalar

Genel bakış

SysML v2 projeleri, LML projeleriyle aynı REST API, MCP uç noktası ve kişisel erişim belirteçleriyle çalışır. Betikler ve YZ araçları modeli öğeler ve SysML metni olarak okur, herhangi bir şeyi değiştirmeden önce metni denetler ve değişiklik önerir. Bir kişi öneriyi Holarch'ta inceleyip uygulayana kadar modelde hiçbir şey değişmez.

Üç giriş yolu:

  • REST API: betikler ve panolar için https://app.holarch.app/api/v1/projects/<project>/…. Öğeleri, gereksinimleri, tanılamaları ve SysML metnini okur ve bir öneriye değişiklik ekler.
  • MCP: Claude gibi YZ araçları için https://app.holarch.app/mcp. SysML v2 araçları modeli okur, arar, denetler ve değişiklik önerir.
  • Systems Modeling API: diğer SysML v2 araçları için OMG Systems Modeling API biçimlerinde https://app.holarch.app/api/v1/sysml/…. main dalı canlı modeldir ve salt okunurdur; diğer her dal bir değişiklik talebidir ve commit'ler ona gider. Canlı model yalnızca bir onaylayıcı değişiklik talebini Holarch'ta uyguladığında değişir.

Belirteçler, kapsamlar, proje listeleri, kuruluş değiştirme, hız sınırları ve Claude'u bağlama LML projelerindekiyle aynıdır. Belirteç oluşturma ve bir YZ aracını bağlama için bkz. API ve MCP. Program Haritası çağrıları (GET /api/v1/program-map, GET /api/v1/projects/<project>/items/<item>/trace ve program_map ile trace_chain MCP araçları) SysML v2 projelerini ve öğelerini içerir.

Kavramlar

  • Öğe: SysML v2 modelinin bir öğesi; örneğin bir part definition, bir port veya bir gereksinim. Her öğenin bir kimliği (UUID) vardır. Bir rota veya araç kimlik istediğinde Vehicles::Car::powertrain gibi bir nitelikli ad da çalışır.
  • Özet: listelerde bir öğenin kısa biçimi: id, type (PartUsage gibi metasınıf), name, shortName, qualifiedName ve owner.
  • En üst düzey paket: başka bir öğenin içinde olmayan bir paket. Bir projenin SysML metni, her en üst düzey paket için bir metin ve paketlerin dışındaki öğeler için bir metinden oluşur.
  • Tanılama: dil çekirdeğinin bulduğu bir sorun; code, severity (error veya warning), elementId, element ve args içerir. Sözdizimi tanılamaları bir öğe yerine line ve col verir.
  • Öneri: bir API istemcisinin veya YZ aracının inceleme için topladığı değişiklikler. Her belirteç ve proje için bir öneri açıktır. İstemci onu bir başlık ve özetle incelemeye gönderir.
  • Sayfalı yanıtlar: listeler sayfalar hâlinde gelir (limit, offset). Uzun SysML metni satır sayfaları hâlinde gelir (line, lines). Bir şeyi dışarıda bırakan yanıt truncated: true belirtir.

Nasıl kullanılır

Bir betiğin veya YZ aracının modele ihtiyacı olduğunda API'yi kullanın: karşılayan veya doğrulayan öğesi olmayan gereksinimleri raporlamak, bir ekibin SysML metnini modele göre denetlemek veya bir YZ aracının daha sonra bir mühendisin incelediği model değişikliklerini taslak olarak hazırlamasını sağlamak için.

curl ile bir SysML v2 projesini okuma

  1. Hesap ayarları → API belirteçleri altında bir belirteç oluşturun (bkz. API ve MCP).
  2. Projelerinizi listeleyin:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects

SysML v2 projelerinde "language": "sysml2" bulunur.

  1. Model özetini alın:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects/<project>/model

Metasınıf başına öğe sayılarını, en üst düzey paketleri ve hata ile uyarı sayısını görürsünüz.

  1. Öğeleri bulun, örneğin tüm part definition'ları:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/elements?type=part%20def&limit=100"
  1. Bir paketin SysML metnini okuyun:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/sysml?root=Vehicles"

Uzun bir metin "truncated": true ve "next" ile biter: sonraki istekte line ile istenecek satır.

SysML metnini önermeden önce denetleme

  1. Bir paketin yeni metnini denetleme rotasına gönderin:
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. Yanıtı okuyun. Metinde sözdizimi hatası olmadığında ok değeri true olur. diagnostics, sözdizimi hatalarını line ve col ile ve metnin modele ekleyeceği hataları listeler. changes, metnin yaptığı model değişikliklerinin sayısıdır.

Denetleme hiçbir şeyi değiştirmez. Yalnızca bir okuma belirteci gerektirir.

Bir değişiklik önerme ve uygulama

Bir yazma belirteci, belirtecin açık önerisine değişiklik ekler. İstemci ardından öneriyi incelemeye gönderir.

  1. Bir değişiklik ekleyin. Bir paketin tam yeni metnini veya öğe düzenlemelerini gönderin:
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

Öneri, değişikliğin özeti ve değişikliğin eklediği, değiştirdiği ve kaldırdığı öğelerle birlikte 201 alırsınız. Hata tanılamaları ekleyen bir değişiklik reddedilir (bkz. SysML v2 projelerinde öneriler).

  1. Daha fazla değişikliği aynı şekilde ekleyin. Her değişiklik, önerinin önceki değişiklikleri uygulanmış modele göre denetlenir.
  2. Öneriyi incelemeye gönderin:
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'ta projeyi açın, ardından ✦ YZ ▾ → “Add range attribute” incele… seçeneğini (veya zilin altındaki bildirimi) açın.
  2. Satırları denetleyin ve Seçilenleri uygula düğmesine tıklayın.

    İşaretli değişiklikler geçmişte adınızla birlikte uygulanır ve tek bir Geri al ile hepsi geri alınır.

Bir YZ aracını bir SysML v2 projesine bağlama

  1. YZ aracını bir belirteçle veya oturum açarak https://app.holarch.app/mcp adresine bağlayın (bkz. API ve MCP).
  2. Model hakkında soru sorun, örneğin “Holarch'taki Hybrid Car modelini özetle” veya “Hybrid Car projesindeki hangi gereksinimler doğrulanmadı?”.

    YZ aracı model_summary, list_elements, list_requirements ve diğer okuma araçlarını kullanır.

  3. Bir değişiklik isteyin, örneğin “Car üzerinde bir range özniteliği öner”.

    YZ aracı paketi get_sysml ile okur, metin veya öğe düzenlemeleri önerir ve denetlemenin döndürdüğü tanılamaları düzeltir.

  4. Öneriyi Holarch'ta inceleyin ve Seçilenleri uygula düğmesine tıklayın.

Çalışılmış örnek: Hybrid Car demosu

Demoyu Projeleri yönet → Proje dosyaları ▾ → Yeni demo proje → Hybrid Car (SysML v2) ile oluşturun, ardından onun için okuma ve yazma belirteci oluşturun.

  1. GET /api/v1/projects/<project>/model, aralarında Vehicles, HybridCarArchitecture ve VehicleBehavior bulunan en üst düzey paketleri listeler.
  2. GET /api/v1/projects/<project>/elements?query=Engine&type=part%20def, Vehicles::Engine öğesini bulur.
  3. GET /api/v1/projects/<project>/elements/Vehicles::Engine, part definition'ı SysML metni, üyeleri (displacement, cylinders, maxPower, fuelIn, output ve ecu port'ları) ve onunla türlenen usage'larla birlikte döndürür.
  4. GET /api/v1/projects/<project>/elements/Vehicles::Car/connections, powertrain.output ile frontAxle.input arasındaki driveShaft interface'ini listeler.
  5. GET /api/v1/projects/<project>/requirements?status=unverified, hiçbir verification case'in doğrulamadığı gereksinimleri VR-4.1 gibi kimlikleriyle listeler.
  6. {"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]} ile POST /api/v1/projects/<project>/proposal/changes değişikliği öneriye ekler. Bir başlıkla POST /api/v1/projects/<project>/proposal öneriyi gönderir.
  7. Holarch'ta ✦ YZ ▾ → “…” incele, part definition ve doc alanıyla Değiştirildi: bölümünü ve Vehicles paketinin metin farkını gösterir. Seçilenleri uygula değişikliği uygular.

İpuçları

  • Bir paket için yeni metin önermeden önce onu get_sysml (veya GET …/sysml?root=) ile okuyun. Önerilen metinde yer almayan öğeler kaldırılır.
  • Küçük değişiklikler için öğe düzenlemelerini tercih edin. Bunlar yalnızca adı verilen öğeleri değiştirir ve paket metninin geri kalanını olduğu gibi bırakır.
  • Metni önce check_sysml (veya POST …/sysml/check) ile denetleyin. Bir önerinin reddedileceği tanılamaların aynısını döndürür.
  • Betiklerde öğeleri nitelikli adla adlandırın. Bir öğe yeniden adlandırıldığında kimlikler aynı kalır; nitelikli adlar kalmaz.
  • Bir YZ aracı yalnızca model hakkındaki soruları yanıtlıyorsa ona salt okunur bir belirteç verin.

SysML v2 projeleri için REST rotaları

Temel adres: https://app.holarch.app/api/v1. Yanıtlar JSON'dur. /api/v1/openapi.json (OpenAPI 3.1) bu rotaları diğerleriyle birlikte tanımlar.

Yöntem ve yolNe yapar
GET /projects/<project>/modelMetasınıf başına öğe sayıları, öğe sayılarıyla en üst düzey paketler ve hata ile uyarı sayısı
GET /projects/<project>/elementsArama: query (veya q; ad, kısa ad, nitelikli ad veya doc içindeki metin), type, owner, limit (1–500, varsayılan 50), offset; nitelikli ada göre sıralanır
GET /projects/<project>/elements/<id>Alanları, doc'u, SysML metni, üyeleri ve onunla türlenen usage'larla tek bir öğe; members (0–200, varsayılan 100)
GET /projects/<project>/elements/<id>/connectionsÖğede veya özelliklerindeki connection'lar, interface'ler, binding'ler, flow'lar (item ile), succession'lar, transition'lar, allocation'lar ve dependency'ler ile öğenin içinde sahip olunanlar; limit (varsayılan 100)
GET /projects/<project>/requirementsKimlik, ifade (doc), satisfiedBy ve verifiedBy ile gereksinimler; owner, status (unsatisfied veya unverified), limit (varsayılan 100), offset
GET /projects/<project>/diagnosticsModelin tanılamaları, önce hatalar; ids (virgülle ayrılmış: yalnızca bu öğeler ve üyeleri), limit (varsayılan 200, en fazla 500)
GET /projects/<project>/sysmlBir en üst düzey paketin (root), paketlerin dışındaki öğelerin (root olmadan) veya tek bir öğenin (element) SysML metni; line (ilk satır, 1'den), lines (varsayılan 2000, en fazla 5000)
POST /projects/<project>/sysml/checktext değerini root (veya paketlerin dışındaki öğeler) için yeni metin olarak denetler; hiçbir şeyi değiştirmez
POST /projects/<project>/proposal/changesAçık öneriye bir değişiklik ekler: {text, root} veya {edits}
GET /projects/<project>/proposalAçık öneri veya proposal kimliğiyle belirtilen bir öneri, durumu ve değişiklikleriyle
POST /projects/<project>/proposalAçık öneriyi incelemeye gönderir: title, summary
DELETE /projects/<project>/proposalAçık öneriyi gönderilmeden önce atar

GET /projects ve GET /projects/<project> SysML v2 projelerinde de çalışır. "language": "sysml2" verirler ve proje yanıtı elements ile types (metasınıf başına öğe sayıları) ekler.

LML nesne rotaları (/entities, /relationships, /schema, Model denetimleri ve kalite denetimi) bir SysML v2 projesinde 409 wrong-project-type yanıtı verir. SysML v2 rotaları da bir LML projesinde aynı yanıtı verir.

Değerler

  • type: PartUsage veya RequirementDefinition gibi bir metasınıf ya da SysML metninde yazıldığı biçimiyle bir anahtar sözcük: part, part def, attribute, port, requirement, action, package ve diğer öğe anahtar sözcükleri.
  • owner, id, element, root: bir kimlik veya nitelikli ad. root bir en üst düzey paketin adını da kabul eder. root bir en üst düzey paket olmalıdır; tek bir öğenin metnini okumak için element kullanın.
  • Uzun değerler: bir listedeki doc 4,000 karakterde, tek bir öğenin doc'u 20,000 karakterde ve bir öğenin kendi SysML metni 16,000 karakterde kesilir.

SysML v2 projeleri için MCP araçları

MCP uç noktası bu araçları LML araçlarının yanında listeler. Bir YZ aracı SysML v2 projelerini list_projects (language: sysml2) ile bulur. Her araç project alır.

Okuma araçları ayrıca, modeli o değişiklik talebinin oluşturacağı hâliyle okumak için isteğe bağlı bir change_request (CR-12 veya kimliği) alır; propose_sysml ve propose_element_changes değişikliği talebin modeline göre hesaplamak ve incelemeden sonra o taslağa uygulamak için bir değişiklik talebi alır. Kurallar için bkz. Değişiklik talepleri.

AraçErişimNe yapar
model_summaryOkumaMetasınıf başına öğe sayıları, en üst düzey paketler ve tanılama sayısı
list_elementsOkumaÖğeleri metne (query), type ve owner değerine göre bulur; limit ve offset ile sayfalanır
get_elementOkumaTürleri, özelleştirmeleri, çokluğu, değeri, uçları, doc'u, SysML metni, üyeleri (members, en fazla 200) ve onunla türlenen usage'larla tek bir öğe (id)
get_connectionsOkumaBir öğenin connection'ları, interface'leri, binding'leri, flow'ları, succession'ları, transition'ları, allocation'ları ve dependency'leri (id, limit)
list_requirementsOkumaKimlik, ifade, satisfy ve verify ile gereksinimler; owner, status (unsatisfied, unverified), limit, offset
get_sysmlOkumaBir en üst düzey paketin (root), paketlerin dışındaki öğelerin veya tek bir öğenin (element) SysML metni; line, lines (en fazla 5000); yanıt next verir
get_sysml_textOkumaTüm modelin (her en üst düzey paket, ardından paketlerin dışındaki öğeler) veya tek bir package değerinin SysML metni, yanıt başına en fazla 200,000 karakter; yanıt dışarıda bırakılan paketleri adlandırır
check_sysmlOkumatext olmadan: modelin tanılamaları (ids, limit). text (ve root) ile: satır ve sütunla sözdizimi hataları ve metnin ekleyeceği hatalar. Hiçbir şeyi değiştirmez
propose_sysmlOkuma ve yazmaBir en üst düzey paketin (root) veya paketlerin dışındaki öğelerin (root olmadan; yeni bir paket de buraya gider) tam yeni text değerini önerir
propose_element_changesOkuma ve yazmaMetni yeniden yazmadan edits (en fazla 100) önerir: oluşturma, güncelleme, taşıma veya kaldırma

list_diagrams, get_diagram ve get_matrix SysML v2 projelerinde de çalışır: list_diagrams görünümleri (InterconnectionView gibi türleriyle) ve bir öğenin altında tutulan analiz diyagramlarını listeler; get_diagram bir görünümün filtrelerinden sonra gösterdiği öğeleri (öğe kimliğine veya nitelikli ada göre) verir; get_matrix her gereksinimi onu karşılayan ve doğrulayan öğelerle verir.

LML projelerinin öneri araçları burada da aynı şekilde çalışır: propose_changes öneriyi bir başlık ve özetle gönderir, discard_proposal onu atar, get_proposal ve list_proposals durumunu gösterir. Salt okunur bir belirteç yalnızca okuma araçlarını listeler.

Araç hataları, ileti ve tanılamalarla birlikte bir araç sonucu olarak döner; böylece YZ aracı metnini düzeltip yeniden deneyebilir.

Öğe düzenlemeleri

edits (MCP) veya {"edits": […]} (REST) içindeki her düzenleme op içeren bir nesnedir:

opAlanlar
createkind (part, part def, attribute, port, requirement, action, package gibi bir anahtar sözcük) veya type (bir metasınıf); owner (atlanırsa: en üst düzey); name (zorunlu); isteğe bağlı shortName, typedBy, specializes, subsets, redefines, multiplicity, value, doc, direction (in, out, inout)
updateid ve oluşturmadaki gibi değiştirilecek alanlar; null veya "" bir alanı temizler
moveid ve yeni owner
removeid; öğeyi üyeleriyle birlikte kaldırır
  • typedBy, specializes, subsets ve redefines en fazla 20 adlık listelerdir: kimlikler, nitelikli adlar veya metinde yazıldığı biçimiyle adlar (MassValue gibi kitaplık adları çalışır).
  • Sonraki düzenlemeler, aynı çağrıda daha önce oluşturulan öğeleri oluşturulma sırasına göre new:1, new:2 … olarak adlandırabilir; örneğin owner olarak. Yanıt bunları yeni kimlikleriyle created altında listeler.
  • Bir öğeyi yeniden adlandırmak, onu eski adıyla anan başvuruları da günceller.

Önerilen metin

  • propose_sysml paketin tüm metnini değiştirir. Öğeler, metnin onları hâlâ bildirdiği yerlerde kimliklerini korur. Metinde yer almayan öğeler kaldırılır.
  • Metin, uygulanmadan kalan hiçbir şey olmadan ayrıştırılmalıdır. Modeli değiştirmeyen metin reddedilir (no-change).

SysML v2 projelerinde öneriler

Önerilen her değişiklik, öneriye katılmadan önce dil çekirdeği tarafından denetlenir:

  • Metin sözdizimi hatası olmadan ayrıştırılır ve öğe düzenlemeleri uygulanır.
  • Değiştirilen paketler hâlâ SysML metni olarak yazdırılır ve yeniden ayrıştırılır.
  • Değişiklik modele çözümlenmemiş adlar veya tür hataları gibi hata tanılamaları eklemez. Modelde zaten olan hatalar sayılmaz.

Başarısız olan bir değişiklik, düzeltilecek tanılamalarla (en fazla 50) reddedilir. Hiçbir şey saklanmaz. Uyarılar bir değişikliği reddettirmez.

Öneride bulunmak, okuma ve yazma belirteci ile projede düzenleyici veya sahip rolü gerektirir. Bir öneri en fazla 200 değişiklik ve 8 MB içerir.

Bir SysML v2 önerisini inceleme

Projeyi açın, ardından ✦ YZ ▾ → “<title>” incele…. Her değişiklik onay kutusu olan bir satırdır:

  • Eklendi, Değiştirildi ve Kaldırıldı, öğeleri değişen alanlarla listeler (her birinin ilk 20'si; geri kalanı için “ve n tane daha”).
  • Paketle etiketlenen bir metin farkı, SysML metninin önceki ve sonraki hâlini gösterir.
  • Öğe kaldıran bir değişiklik işaretlenir ve işaretsiz başlar.
  • Bu değişikliği uygulamak için SysML v2 modelini açın. Model yüklenmedi; projenin bir SysML v2 sayfasını açın.
  • Paket artık modelde değil; atlandı. Paket, değişiklik önerildikten sonra kaldırıldı.

Seçilenleri uygula, her metin değişikliğini mevcut modele göre yeniden eşitler ve öğeleri hâlâ var olan düzenlemeleri korur. Tüm kümeyi denetler ve tek bir geri alma adımı olarak uygular. Artık uymayan değişiklikler atlanır ve bir bildirimde adlandırılır. Reddet ve Daha sonra, LML önerilerindeki gibi çalışır; roller, süre sonu (7 gün) ve saklama da öyle (bkz. YZ istemcilerinden gelen öneriler).

Systems Modeling API

Diğer SysML v2 araçları Holarch modellerini OMG Systems Modeling API (REST/HTTP) biçimlerindeki rotalar üzerinden okur ve değiştirir. Temel adres https://app.holarch.app/api/v1/sysml'dir. Aynı belirteçleri kullanır; her proje rolü okuyabilir, düzenleyiciler ve sahipler commit edebilir.

  • Projeler: yalnızca SysML v2 projeleri listelenir. Bir projenin @id değeri bu API'nin ona verdiği bir UUID'dir; Holarch proje kimliği de çalışır. Yanıt holarchId ve url içerir.
  • Dallar: main canlı modeldir ve API üzerinden değiştirilemez. Diğer her dal, “CR-12 Title” biçiminde adlandırılan ve holarchChangeRequest (id, label, status, url) taşıyan, devam eden bir değişiklik talebidir. Son 30 günde uygulanan veya geri çekilen değişiklik talepleri deleted ayarlı olarak listelenmeye devam eder.
  • Commit'ler: bir commit, değişiklikleri bir değişiklik talebinin dalına yazar. Yalnızca dal başları sunulur: main dalının başı canlı modeldir, bir değişiklik talebi dalının başı talebin değişiklikleriyle birlikte canlı modeldir. Daha eski commit kimlikleri 404 yanıtı verir; geçerli başı daldan alın.
  • Öğeler: her öğe, türetilenler dahil (owner, ownedElement, qualifiedName, feature, type ve benzerleri) OMG JSON şemasındaki metasınıfının her özelliğine sahiptir. Standart kitaplık öğelerine standart kimlikleriyle, yani diğer SysML v2 araçlarının aynı kitaplık öğesi için kullandığı kimliklerle başvurulur.
  • Etiketler ve kayıtlı sorgular: yok; listeleri boştur.
Yöntem ve yolNe yapar
GET /sysml/projectsSysML v2 projeleriniz
POST /sysml/projectsBoş bir SysML v2 projesi oluşturur (name, description)
GET /sysml/projects/<projectId>Varsayılan dalıyla tek bir proje
GET /sysml/projects/<projectId>/branchesmain ve değişiklik talebi dalları
POST /sysml/projects/<projectId>/branchesBir dal oluşturur: yeni bir Taslak değişiklik talebi (name başlığı, description gerekçesidir)
GET /sysml/projects/<projectId>/branches/<branchId>head ile dal (@id değeri veya main)
DELETE /sysml/projects/<projectId>/branches/<branchId>Değişiklik talebini geri çeker
GET /sysml/projects/<projectId>/commitsBaşlar ve dallara gönderilen commit'ler, en yenisi önce
POST /sysml/projects/<projectId>/commits?branchId=<branchId>Değişiklikleri bir dala commit eder (aşağıda)
GET /sysml/projects/<projectId>/commits/<commitId>Bir baş commit
GET /sysml/projects/<projectId>/commits/<commitId>/changesDalın canlı modele göre değiştirdikleri: her öğe için bir DataVersion
GET /sysml/projects/<projectId>/commits/<commitId>/elementsCommit'in tüm öğeleri, sayfalı
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>Tek bir öğe
GET /sysml/projects/<projectId>/commits/<commitId>/rootsEn üst düzey öğeler, sayfalı
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>/relationshipsÖğenin kaynak veya hedef olduğu ilişkiler; direction değeri in, out veya both (varsayılan), sayfalı
POST /sysml/projects/<projectId>/query-resultsBir sorguyla eşleşen öğeler (gövde aşağıda), sayfalı; commitId bir baş olmalıdır
GET /sysml/projects/<projectId>/tags, /queries, /commits/<commitId>/elements/<elementId>/projectUsagesBoş listeler

Liste yanıtları JSON dizileridir. Listeler page[size] (varsayılan 100, en fazla 1000) ve page[after] (önceki sayfanın son öğesinin @id değeri) veya page[before] (sonraki sayfanın ilk öğesinin @id değeri) ile sayfalanır. Link üst bilgisi sonraki sayfayı rel="next" ile, öncekini rel="prev" ile verir.

Sorgu; isteğe bağlı bir where (property, operator (=, in, <, <=, >, >= veya instanceOf), value ve inverse içeren bir PrimitiveConstraint ya da and veya or operator değeri ve constraint içeren bir CompositeConstraint), scope (öğe kimlikleri: arama onları ve sahip olduklarını kapsar) ve select (döndürülecek özellikler; @id ve @type her zaman döner) içeren bir JSON nesnesidir:

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

Bir modelin öğelerini okuyun:

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"

Değişiklikleri commit etme

Yazma; okuma ve yazma erişimli bir belirteç, düzenleyici veya sahip rolü, Team planı (akademik ve sınıf hesapları için de) ve proje için açık dal incelemesi (Değişiklik talepleri → Ayarlar) gerektirir. Bir onaylayıcı değişiklik talebini Holarch'ta inceler ve uygular; belirteçler hiçbir zaman oy vermez veya uygulamaz.

  1. Bir dal oluşturun: {"@type": "Branch", "name": "Cabin heater"} ile POST /branches. Yanıt, holarchChangeRequest ile birlikte daldır.
  2. Dalın başını ve öğelerini okuyun.
  3. Bir DataVersion listesiyle POST /commits?branchId=<branch @id>:
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>"}}}]}'
  • Bir öğeyi değiştirme: öğeyi okuduğunuz gibi, özellikleri değiştirilmiş olarak gönderin. Yalnızca sahip olunan özellikler sayılır (declaredName, ownedRelationship, isAbstract ve benzerleri); türetilenler yok sayılır, bu nedenle okuduğunuzu geri göndermek hiçbir şeyi değiştirmez. Dışarıda bıraktığınız bir özellik değerini korur; temizlemek için null veya [] gönderin.
  • Yeni öğeler: öğeye yeni bir UUID ve sahiplik üyeliğini (aynı commit'te gönderilir) ya da üyeliği sizin için oluşturan owner değerini verin.
  • Bir öğeyi kaldırma: payload: null öğeyi sahip olduğu her şeyle birlikte kaldırır.
  • Denetimler: commit'in dokunduğu her paket yeniden yazdırılıp ayrıştırılabilmeli ve commit hata tanılamaları eklememelidir; aksi takdirde düzeltilecek diagnostics ile 422 döner.
  • previousCommit: değişikliğinizin yapıldığı baş. Dal o zamandan beri ilerlediyse yanıt geçerli head ile 409 stale-head olur; yeniden okuyun ve onun üzerine commit edin.
  • Yeniden denemeler: bir Idempotency-Key üst bilgisi gönderin. 24 saat içinde aynı anahtar ve gövdeyle yapılan bir yeniden deneme ilk yanıtı yeniden alır.
  • main dalına commit'ler: branchId olmadan veya main ile yapılan bir commit, belirtecinizin kendi taslak değişiklik talebine (“API changes from <token name>”) gider; bu talep ilk böyle commit'te oluşturulur. Yanıt hangisi olduğunu holarchChangeRequest içinde ve bir Warning üst bilgisinde belirtir.
  • Yeni projeler: POST /sysml/projects ile oluşturulan bir projede dal incelemesi açıktır. Projenin tek üyesi sizken main dalına yapılan ilk commit bir kez doğrudan modele yazılır; sonraki commit'ler değişiklik taleplerinden geçer.

Değişiklik talebini POST /api/v1/projects/<project>/change-requests/<CR-12>/submit ile incelemeye gönderin (API ve MCP). Etiketler, birleştirmeler ve bir projeyi yeniden adlandırma veya silme, bunun yerine ne yapılacağını belirten 405 yanıtı verir. Hatalar, OMG API'nin tanımladığı gibi @type Error ve bir description taşır.

İletiler

API ve MCP kodları geçerlidir. SysML v2 rotaları ve araçları şunları ekler:

KodDurumAnlamı
wrong-project-type409Bir SysML v2 projesinde LML işlemi veya bir LML projesinde SysML v2 işlemi
syntax422Önerilen metinde sözdizimi hataları var; tanılamalar satır ve sütun verir
invalid-model422Değişiklik modele hata tanılamaları ekliyor; bunlar listelenir
not-printable422Değişiklik SysML metni olarak yazılamıyor
invalid422Değişiklik modele uygulanamadı
no-change400Metin modeli değiştirmiyor
too-large413Metin 1,000,000 karakterden uzun veya öneri 8 MB'tan büyük
too-many413 veya 409Tek bir çağrıda 100'den fazla düzenleme (413) veya öneride zaten 200 değişiklik var (409)
stale409Önerinin önceki bir metin değişikliği artık modele uygulanmıyor
not-found404Böyle bir proje, öğe, dal veya commit yok (Systems Modeling API yalnızca dal başlarını sunar)
not-writable405Systems Modeling API üzerinden etiketler, birleştirmeler, bir projeyi yeniden adlandırma veya silme; bunu Holarch'ta yapın
main-protected405main dalını silme; bunun yerine bir değişiklik talebi dalını silin
stale-head409Dal previousCommit değerinden bu yana ilerledi; head değerini okuyun ve yeniden commit edin
branch-base409Yeni bir dal main dalının başından başlamalıdır
branch-review-off409Proje dal incelemesi kullanmıyor; bir sahip bunu Değişiklik talepleri → Ayarlar içinde açar
cr-not-draft409Değişiklik talebi gönderilmiş veya kapatılmış; yalnızca Taslak veya Reddedildi durumundayken yazılabilir
cr-full409Değişiklik talebi 5,000 değişmiş öğe içeriyor veya projede 20 MB değişiklik talebi taslağı var
plan-limit403Değişiklik taleplerine yazma Team planını gerektirir
orphan422Yeni bir öğenin sahibi yok; sahiplik üyeliğini veya owner değerini gönderin
unknown-metaclass422Bir payload'ın @type değeri bir SysML v2 metasınıfı değil
idempotency-key-reused422Idempotency-Key başka bir gövdeyle kullanıldı; yeni bir anahtar gönderin
token-projects403Bir proje listesiyle sınırlı bir belirteç proje oluşturamaz
bad-request400Eksik veya yanlış bir değer; örneğin en üst düzey paket olmayan bir root, bilinmeyen bir op veya adı olmayan yeni bir öğe

Sınırlar

NeSınır
Sayfa başına öğe, gereksinim veya connection500
Bir öğeyle listelenen üyeler200
Yanıt başına tanılama500
Yanıt başına SysML metni satırı5,000 ve en fazla 400,000 bayt (bir satırda kesilir)
Doc metniListelerde 4,000 karakter, tek bir öğe için 20,000
Bir öğenin kendi SysML metni16,000 karakter
Tek bir propose_sysml çağrısındaki metin1,000,000 karakter
Tek bir çağrıdaki düzenlemeler100
Tek bir değişiklikte eklendi, değiştirildi veya kaldırıldı olarak listelenen öğelerHer biri 300
Tek bir önerideki değişiklikler200 ve 8 MB
Systems Modeling API sayfası1,000 öğe (varsayılan 100)
Tek bir commit'teki DataVersion'lar5,000
Tek bir değişiklik talebindeki değişmiş öğeler5,000
Commit gövdesi32 MB

Hız sınırları, istek boyutu ve belirteç kuralları API ve MCP sayfasındakilerle aynıdır.

SysML® ve OMG®, Object Management Group, Inc.'in Amerika Birleşik Devletleri'nde ve diğer ülkelerde tescilli ticari markalarıdır.