Holarch

SysML v2

SysML v2 프로젝트의 API 및 MCP

개인 액세스 토큰으로 스크립트와 AI 도구에서 SysML v2 모델을 읽고 검색하고 검사하며, Holarch에서 검토하고 적용할 변경을 제안하고, 브랜치가 변경 요청인 Systems Modeling API를 통해 읽고 커밋합니다.

사용 방법 →

이 페이지의 내용
  1. 개요
  2. 개념
  3. 사용 방법
    1. curl로 SysML v2 프로젝트 읽기
    2. 제안하기 전에 SysML 텍스트 검사하기
    3. 변경 제안 및 적용하기
    4. AI 도구를 SysML v2 프로젝트에 연결하기
    5. 작업 예제: Hybrid Car 데모
    6. 팁
  4. SysML v2 프로젝트의 REST 경로
    1. 값
  5. SysML v2 프로젝트의 MCP 도구
    1. 요소 편집
    2. 제안된 텍스트
  6. SysML v2 프로젝트의 제안
    1. SysML v2 제안 검토하기
  7. Systems Modeling API
    1. 변경 커밋하기
  8. 메시지
  9. 제한 사항
  10. 관련 페이지

개요

SysML v2 프로젝트는 LML 프로젝트와 같은 REST API, MCP 엔드포인트, 개인 액세스 토큰으로 작동합니다. 스크립트와 AI 도구는 모델을 요소와 SysML 텍스트로 읽고, 무엇이든 바꾸기 전에 텍스트를 검사하고, 변경을 제안합니다. 사람이 Holarch에서 제안을 검토하고 적용할 때까지 모델은 바뀌지 않습니다.

세 가지 접근 방법:

  • REST API: 스크립트와 대시보드용 https://app.holarch.app/api/v1/projects/<project>/…. 요소, 요구사항, 진단, SysML 텍스트를 읽고, 제안에 변경을 추가합니다.
  • MCP: Claude 같은 AI 도구용 https://app.holarch.app/mcp. SysML v2 도구가 모델을 읽고 검색하고 검사하며 변경을 제안합니다.
  • Systems Modeling API: 다른 SysML v2 도구를 위한 OMG Systems Modeling API 형태의 https://app.holarch.app/api/v1/sysml/…. 브랜치 main은 실시간 모델이며 읽기 전용입니다. 다른 모든 브랜치는 변경 요청이며, 커밋은 그 브랜치로 들어갑니다. 실시간 모델은 승인자가 Holarch에서 변경 요청을 적용할 때만 바뀝니다.

토큰, 범위, 프로젝트 목록, 조직 전환, 속도 제한, Claude 연결은 LML 프로젝트와 같습니다. 토큰 만들기와 AI 도구 연결은 API와 MCP를 참조하십시오. 프로그램 맵 호출(GET /api/v1/program-map, GET /api/v1/projects/<project>/items/<item>/trace, MCP 도구 program_map과 trace_chain)에는 SysML v2 프로젝트와 그 요소가 포함됩니다.

개념

  • 요소: part definition, port, requirement 같은 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 클라이언트나 AI 도구가 검토를 위해 모으는 변경입니다. 토큰과 프로젝트마다 제안 하나가 열려 있습니다. 클라이언트는 제목과 요약을 붙여 검토를 위해 제안을 보냅니다.
  • 페이지 단위 응답: 목록은 페이지 단위로 옵니다(limit, offset). 긴 SysML 텍스트는 줄 단위 페이지로 옵니다(line, lines). 무언가를 생략한 응답에는 truncated: true가 표시됩니다.

사용 방법

스크립트나 AI 도구에 모델이 필요할 때 API를 사용합니다. 충족하거나 검증하는 요소가 없는 요구사항을 보고하거나, 팀의 SysML 텍스트를 모델과 대조해 검사하거나, AI 도구가 모델 변경 초안을 작성하고 엔지니어가 검토하게 할 때입니다.

curl로 SysML v2 프로젝트 읽기

  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. 요소를 찾습니다. 예를 들어 모든 part definition:
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에서 프로젝트를 연 후 ✦ AI ▾ → “Add range attribute” 검토…(또는 종 아래의 알림)를 엽니다.
  2. 행을 확인하고 선택 항목 적용을 클릭합니다.

    체크된 변경이 기록에 사용자의 이름과 함께 적용되며, 실행 취소 한 번으로 모두 되돌립니다.

AI 도구를 SysML v2 프로젝트에 연결하기

  1. 토큰 또는 로그인으로 AI 도구를 https://app.holarch.app/mcp에 연결합니다(API와 MCP 참조).
  2. 모델에 대해 질문합니다. 예: “Holarch의 Hybrid Car 모델을 요약해 줘” 또는 “Hybrid Car 프로젝트에서 검증되지 않은 요구사항은 무엇이야?”

    AI 도구는 model_summary, list_elements, list_requirements 및 기타 읽기 도구를 사용합니다.

  3. 변경을 요청합니다. 예: “Car에 range 속성을 제안해 줘”.

    AI 도구는 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은 part definition을 그 SysML 텍스트, 멤버(displacement, cylinders, maxPower, 포트 fuelIn, output, ecu), 그리고 이 정의로 타입 지정된 usage와 함께 반환합니다.
  4. GET /api/v1/projects/<project>/elements/Vehicles::Car/connections는 powertrain.output에서 frontAxle.input으로 가는 interface driveShaft를 나열합니다.
  5. GET /api/v1/projects/<project>/requirements?status=unverified는 어떤 검증 케이스도 검증하지 않는 요구사항을 VR-4.1 같은 id와 함께 나열합니다.
  6. {"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]}을(를) 사용한 POST /api/v1/projects/<project>/proposal/changes는 제안에 변경을 추가합니다. 제목과 함께 POST /api/v1/projects/<project>/proposal을(를) 보내면 제안이 전송됩니다.
  7. Holarch에서 ✦ AI ▾ → “…” 검토는 part definition과 필드 doc이 있는 변경됨:과 Vehicles의 텍스트 비교를 표시합니다. 선택 항목 적용으로 적용합니다.

팁

  • 패키지의 새 텍스트를 제안하기 전에 get_sysml(또는 GET …/sysml?root=)로 패키지를 읽습니다. 제안된 텍스트에서 빠진 요소는 제거됩니다.
  • 작은 변경에는 요소 편집을 사용하는 것이 좋습니다. 이름이 지정된 요소만 변경하고 나머지 패키지 텍스트는 그대로 둡니다.
  • 먼저 check_sysml(또는 POST …/sysml/check)로 텍스트를 검사합니다. 제안이 거부될 때와 같은 진단을 반환합니다.
  • 스크립트에서는 정규화된 이름으로 요소를 지정합니다. 요소의 이름이 바뀌면 id는 그대로지만 정규화된 이름은 바뀝니다.
  • 모델에 관한 질문에만 답하는 AI 도구에는 읽기 전용 토큰을 줍니다.

SysML v2 프로젝트의 REST 경로

기본 주소: 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 텍스트, 멤버, 이 요소로 타입 지정된 usage가 포함된 요소 하나. members(0–200, 기본값 100)
GET /projects/<project>/elements/<id>/connections요소 또는 그 기능에 있는, 그리고 그 안에 소유된 connection, interface, binding, flow(항목 포함), succession, transition, allocation, dependency. limit(기본값 100)
GET /projects/<project>/requirementsid, 진술(doc), satisfiedBy, verifiedBy가 포함된 요구사항. owner, status(unsatisfied 또는 unverified), limit(기본값 100), offset
GET /projects/<project>/diagnostics모델의 진단(오류 먼저). ids(쉼표로 구분: 해당 요소와 그 멤버만), limit(기본값 200, 최대 500)
GET /projects/<project>/sysml최상위 패키지(root), 패키지 외부 요소(root 없음), 또는 요소 하나(element)의 SysML 텍스트. line(첫 줄, 1부터), lines(기본값 2000, 최대 5000)
POST /projects/<project>/sysml/checktext를 root(또는 패키지 외부 요소)의 새 텍스트로 검사. 아무것도 변경하지 않음
POST /projects/<project>/proposal/changes열린 제안에 변경 추가: {text, root} 또는 {edits}
GET /projects/<project>/proposal열린 제안 또는 proposal id로 지정한 제안과 그 상태 및 변경
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: id 또는 정규화된 이름. root는 최상위 패키지의 이름도 받습니다. root는 최상위 패키지여야 하며, 요소 하나의 텍스트를 읽으려면 element를 사용합니다.
  • 긴 값: 목록의 doc은 4,000자에서, 단일 요소의 doc은 20,000자에서, 요소 자체의 SysML 텍스트는 16,000자에서 잘립니다.

SysML v2 프로젝트의 MCP 도구

MCP 엔드포인트는 LML 도구 옆에 이 도구들을 나열합니다. AI 도구는 list_projects(language: sysml2)로 SysML v2 프로젝트를 찾습니다. 모든 도구는 project를 받습니다.

읽기 도구는 선택 사항인 change_request(CR-12 또는 그 id)도 받아 해당 변경 요청이 만들 모델을 읽습니다. propose_sysml과 propose_element_changes는 이를 받아 요청의 모델과 대조해 변경을 계산하고, 검토 후 그 초안에 적용합니다. 규칙은 변경 요청을 참조하십시오.

도구액세스기능
model_summary읽기메타클래스별 요소 수, 최상위 패키지, 진단의 수
list_elements읽기텍스트(query), type, owner로 요소 찾기. limit와 offset으로 페이지 지정
get_element읽기유형, 특수화, 다중성, 값, 끝, doc, SysML 텍스트, 멤버(members, 최대 200), 이 요소로 타입 지정된 usage가 포함된 요소 하나(id)
get_connections읽기요소의 connection, interface, binding, flow, succession, transition, allocation, dependency(id, limit)
list_requirements읽기id, 진술, satisfy, verify가 포함된 요구사항. owner, status(unsatisfied, unverified), limit, offset
get_sysml읽기최상위 패키지(root), 패키지 외부 요소, 또는 요소 하나(element)의 SysML 텍스트. line, lines(최대 5000). 응답에 next가 포함됨
get_sysml_text읽기모델 전체(모든 최상위 패키지, 그다음 패키지 외부 요소) 또는 package 하나의 SysML 텍스트. 응답당 최대 200,000자이며, 응답에 제외된 패키지가 표시됨
check_sysml읽기text 없이: 모델의 진단(ids, limit). text(와 root)와 함께: 줄과 열이 있는 구문 오류, 그리고 텍스트가 추가할 오류. 아무것도 변경하지 않음
propose_sysml읽기 및 쓰기최상위 패키지(root) 또는 패키지 외부 요소(root 없음, 새 패키지가 들어갈 곳이기도 함)의 완전한 새 text 제안
propose_element_changes읽기 및 쓰기텍스트를 다시 쓰지 않고 edits(최대 100개) 제안: 만들기, 업데이트, 이동, 제거

list_diagrams, get_diagram, get_matrix도 SysML v2 프로젝트에서 작동합니다. list_diagrams는 뷰(InterconnectionView 같은 종류 포함)와 요소 아래에 보관된 분석 다이어그램을 나열하고, get_diagram은 필터를 적용한 후 뷰가 노출하는 요소를 제공하며(요소 id 또는 정규화된 이름으로), get_matrix는 각 요구사항과 그것을 충족하고 검증하는 것을 제공합니다.

LML 프로젝트의 제안 도구가 여기서도 같은 방식으로 작동합니다. propose_changes는 제목과 요약을 붙여 제안을 보내고, discard_proposal은 제안을 버리며, get_proposal과 list_proposals는 그 상태를 보여 줍니다. 읽기 전용 토큰에는 읽기 도구만 나열됩니다.

도구 오류는 메시지와 진단이 담긴 도구 결과로 돌아오므로, AI 도구가 텍스트를 고쳐 다시 시도할 수 있습니다.

요소 편집

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개 이름의 목록입니다. id, 정규화된 이름, 또는 텍스트에 쓰는 이름(MassValue 같은 라이브러리 이름도 가능)입니다.
  • 나중 편집은 같은 호출에서 앞서 만든 요소를 만든 순서대로 new:1, new:2 …로 지정할 수 있습니다(예: owner로). 응답은 이 요소들을 새 id와 함께 created 아래에 나열합니다.
  • 요소의 이름을 바꾸면 이전 이름으로 요소를 지정하던 참조도 업데이트됩니다.

제안된 텍스트

  • propose_sysml은 패키지의 텍스트 전체를 대체합니다. 텍스트가 여전히 선언하는 요소는 id를 유지합니다. 텍스트에서 빠진 요소는 제거됩니다.
  • 텍스트는 적용되지 않고 남는 부분 없이 구문 분석되어야 합니다. 모델을 바꾸지 않는 텍스트는 거부됩니다(no-change).

SysML v2 프로젝트의 제안

제안된 모든 변경은 제안에 합류하기 전에 언어 코어가 검사합니다.

  • 텍스트가 구문 오류 없이 구문 분석되고, 요소 편집이 적용됩니다.
  • 변경된 패키지가 여전히 SysML 텍스트로 출력되고 다시 구문 분석됩니다.
  • 변경이 확인되지 않는 이름이나 유형 오류 같은 오류 진단을 모델에 추가하지 않습니다. 모델에 이미 있던 오류는 세지 않습니다.

실패한 변경은 고칠 진단(최대 50개)과 함께 거부됩니다. 아무것도 저장되지 않습니다. 경고는 변경을 거부하지 않습니다.

제안하려면 읽기 및 쓰기 토큰과 프로젝트의 편집자 또는 소유자 역할이 필요합니다. 제안 하나에는 최대 200개 변경과 8 MB가 들어갑니다.

SysML v2 제안 검토하기

프로젝트를 연 후 ✦ AI ▾ → “<title>” 검토…를 엽니다. 각 변경은 체크 상자가 있는 행입니다.

  • 추가됨, 변경됨, 제거됨은 요소를 변경된 필드와 함께 나열합니다(각각 처음 20개, 나머지는 “외 n개”).
  • 패키지 이름이 붙은 텍스트 비교가 변경 전후의 SysML 텍스트를 보여 줍니다.
  • 요소를 제거하는 변경은 표시되며 체크 해제 상태로 시작합니다.
  • 이 변경을 적용하려면 SysML v2 모델을 여십시오. 모델이 로드되지 않았습니다. 프로젝트의 SysML v2 페이지를 엽니다.
  • 패키지가 더 이상 모델에 없어 건너뛰었습니다. 변경이 제안된 후 패키지가 제거되었습니다.

선택 항목 적용은 각 텍스트 변경을 현재 모델과 다시 동기화하고, 요소가 아직 있는 편집을 유지합니다. 전체 집합을 검사하고 실행 취소 한 단계로 적용합니다. 더 이상 맞지 않는 변경은 건너뛰고 알림에 표시됩니다. 거부와 나중에는 LML 제안과 같은 방식으로 작동하며, 역할, 만료(7일), 보존도 마찬가지입니다(AI 클라이언트의 제안 참조).

Systems Modeling API

다른 SysML v2 도구는 OMG Systems Modeling API(REST/HTTP) 형태의 경로로 Holarch 모델을 읽고 변경합니다. 기본 주소는 https://app.holarch.app/api/v1/sysml입니다. 같은 토큰을 사용하며, 모든 프로젝트 역할이 읽을 수 있고 편집자와 소유자가 커밋할 수 있습니다.

  • 프로젝트: SysML v2 프로젝트만 나열됩니다. 프로젝트의 @id는 이 API가 부여하는 UUID이며, Holarch 프로젝트 id도 사용할 수 있습니다. 응답에는 holarchId와 url이 포함됩니다.
  • 브랜치: main은 실시간 모델이며 API로 변경할 수 없습니다. 다른 모든 브랜치는 진행 중인 변경 요청으로, "CR-12 Title"처럼 이름이 붙고 holarchChangeRequest(id, label, status, url)를 가집니다. 지난 30일 안에 구현되거나 철회된 변경 요청도 deleted가 설정된 상태로 계속 나열됩니다.
  • 커밋: 커밋은 변경 요청 브랜치에 변경을 기록합니다. 브랜치 헤드만 제공됩니다. main의 헤드는 실시간 모델이고, 변경 요청 브랜치의 헤드는 요청의 변경이 적용된 실시간 모델입니다. 이전 커밋 id는 404를 응답합니다. 현재 헤드는 브랜치에서 가져옵니다.
  • 요소: 각 요소는 OMG JSON 스키마에 있는 메타클래스의 모든 속성을 가지며, 파생 속성(owner, ownedElement, qualifiedName, feature, type 등)도 포함됩니다. 표준 라이브러리 요소는 표준 id, 즉 다른 SysML v2 도구가 같은 라이브러리 요소에 사용하는 id로 참조됩니다.
  • 태그와 저장된 쿼리: 없습니다. 그 목록은 비어 있습니다.
메서드와 경로기능
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브랜치 만들기: 새 Draft 변경 요청(name은 제목, description은 사유)
GET /sysml/projects/<projectId>/branches/<branchId>head가 포함된 브랜치(그 @id 또는 main)
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"로 이전 페이지를 제공합니다.

쿼리는 선택 사항인 where(property, operator(=, in, <, <=, >, >= 또는 instanceOf), value, inverse가 있는 PrimitiveConstraint, 또는 operator and나 or와 constraint가 있는 CompositeConstraint), scope(요소 id: 검색이 이 요소와 그 소유물을 대상으로 함), select(반환할 속성. @id와 @type은 항상 반환됨)가 있는 JSON 객체입니다.

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. 브랜치 만들기: {"@type": "Branch", "name": "Cabin heater"}와 함께 POST /branches. 응답은 holarchChangeRequest가 포함된 브랜치입니다.
  2. 브랜치의 헤드와 그 요소를 읽습니다.
  3. DataVersion 목록과 함께 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>"}}}]}'
  • 요소 변경: 읽은 그대로의 요소를 속성만 바꿔 보냅니다. 소유 속성(declaredName, ownedRelationship, isAbstract 등)만 반영되고 파생 속성은 무시되므로, 읽은 것을 그대로 보내면 아무것도 바뀌지 않습니다. 생략한 속성은 값을 유지합니다. 지우려면 null 또는 []을(를) 보냅니다.
  • 새 요소: 요소에 새 UUID를 부여하고, 소유 멤버십(같은 커밋으로 보냄) 또는 멤버십을 대신 만들어 주는 owner 중 하나를 지정합니다.
  • 요소 제거: payload: null은 요소를 그 소유물 전체와 함께 제거합니다.
  • 검사: 커밋이 건드리는 각 패키지가 다시 출력되고 구문 분석되어야 하며, 커밋이 오류 진단을 추가해서는 안 됩니다. 그렇지 않으면 고칠 diagnostics와 함께 422가 반환됩니다.
  • previousCommit: 변경을 만든 기준 헤드입니다. 그 후 브랜치가 이동했다면 응답은 현재 head와 함께 409 stale-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를 응답합니다. 오류는 OMG API가 정의하는 대로 @type Error와 description을 가집니다.

메시지

API와 MCP의 코드가 적용됩니다. SysML v2 경로와 도구는 다음을 추가합니다.

코드상태의미
wrong-project-type409SysML v2 프로젝트에서의 LML 작업, 또는 LML 프로젝트에서의 SysML v2 작업
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-writable405Systems Modeling API를 통한 태그, 병합, 프로젝트 이름 바꾸기 또는 삭제. Holarch에서 수행합니다
main-protected405main 삭제. 대신 변경 요청 브랜치를 삭제합니다
stale-head409previousCommit 이후 브랜치가 이동했습니다. 그 head를 읽고 다시 커밋합니다
branch-base409새 브랜치는 main의 헤드에서 시작해야 합니다
branch-review-off409프로젝트가 브랜치 검토를 사용하지 않습니다. 소유자가 변경 요청 → 설정에서 켭니다
cr-not-draft409변경 요청이 제출되었거나 종료되었습니다. Draft 또는 Rejected 상태일 때만 기록할 수 있습니다
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바이트(줄 단위로 자름)
Doc 텍스트목록에서 4,000자, 요소 하나에 20,000자
요소 자체의 SysML 텍스트16,000자
propose_sysml 호출 한 번의 텍스트1,000,000자
호출 한 번의 편집100
변경 하나에서 추가·변경·제거로 나열되는 요소각각 300개
제안 하나의 변경200개, 8 MB
Systems Modeling API 페이지요소 1,000개(기본값 100)
커밋 하나의 DataVersion5,000
변경 요청 하나의 변경된 항목5,000
커밋 본문32 MB

속도 제한, 요청 크기, 토큰 규칙은 API와 MCP의 규칙을 따릅니다.

SysML® 및 OMG®는 미국 및 기타 국가에서 Object Management Group, Inc.의 등록 상표입니다.