SysML v2
SysML v2 프로젝트의 API 및 MCP
개인 액세스 토큰으로 스크립트와 AI 도구에서 SysML v2 모델을 읽고 검색하고 검사하며, Holarch에서 검토하고 적용할 변경을 제안하고, 브랜치가 변경 요청인 Systems Modeling API를 통해 읽고 커밋합니다.
이 페이지의 내용
개요
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 프로젝트 읽기
- 계정 설정 → API 토큰에서 토큰을 만듭니다(API와 MCP 참조).
- 프로젝트 목록을 봅니다.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
SysML v2 프로젝트에는 "language": "sysml2"이(가) 있습니다.
- 모델 요약을 가져옵니다.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects/<project>/model
메타클래스별 요소 수, 최상위 패키지, 오류와 경고의 수가 표시됩니다.
- 요소를 찾습니다. 예를 들어 모든 part definition:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/elements?type=part%20def&limit=100"
- 패키지의 SysML 텍스트를 읽습니다.
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/sysml?root=Vehicles"
긴 텍스트는 "truncated": true와 "next"(다음에 line으로 요청할 줄)로 끝납니다.
제안하기 전에 SysML 텍스트 검사하기
- 패키지의 새 텍스트를 검사 경로로 보냅니다.
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
- 응답을 읽습니다. 텍스트에 구문 오류가 없으면
ok는true입니다.diagnostics는line과col이 있는 구문 오류와, 텍스트가 모델에 추가할 오류를 나열합니다.changes는 텍스트가 만드는 모델 변경의 수입니다.
검사는 아무것도 변경하지 않으며, 읽기 토큰만 필요합니다.
변경 제안 및 적용하기
쓰기 토큰은 토큰의 열린 제안에 변경을 추가합니다. 그런 다음 클라이언트가 검토를 위해 제안을 보냅니다.
- 변경을 추가합니다. 패키지의 완전한 새 텍스트 또는 요소 편집 중 하나를 보냅니다.
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 프로젝트의 제안 참조).
- 같은 방식으로 변경을 더 추가합니다. 각 변경은 제안의 이전 변경이 적용된 모델과 대조해 검사됩니다.
- 검토를 위해 제안을 보냅니다.
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
- Holarch에서 프로젝트를 연 후 ✦ AI ▾ → “Add range attribute” 검토…(또는 종 아래의 알림)를 엽니다.
- 행을 확인하고 선택 항목 적용을 클릭합니다.
체크된 변경이 기록에 사용자의 이름과 함께 적용되며, 실행 취소 한 번으로 모두 되돌립니다.
AI 도구를 SysML v2 프로젝트에 연결하기
- 토큰 또는 로그인으로 AI 도구를
https://app.holarch.app/mcp에 연결합니다(API와 MCP 참조). - 모델에 대해 질문합니다. 예: “Holarch의 Hybrid Car 모델을 요약해 줘” 또는 “Hybrid Car 프로젝트에서 검증되지 않은 요구사항은 무엇이야?”
AI 도구는
model_summary,list_elements,list_requirements및 기타 읽기 도구를 사용합니다. - 변경을 요청합니다. 예: “
Car에range속성을 제안해 줘”.AI 도구는
get_sysml로 패키지를 읽고, 텍스트 또는 요소 편집을 제안하고, 검사가 반환하는 진단을 고칩니다. - Holarch에서 제안을 검토하고 선택 항목 적용을 클릭합니다.
작업 예제: Hybrid Car 데모
프로젝트 관리 → 프로젝트 파일 ▾ → 새 데모 프로젝트 → Hybrid Car (SysML v2)로 데모를 만든 후, 그 프로젝트의 읽기 및 쓰기 토큰을 만듭니다.
GET /api/v1/projects/<project>/model은 최상위 패키지를 나열하며, 그중에Vehicles,HybridCarArchitecture,VehicleBehavior가 있습니다.GET /api/v1/projects/<project>/elements?query=Engine&type=part%20def는Vehicles::Engine을 찾습니다.GET /api/v1/projects/<project>/elements/Vehicles::Engine은 part definition을 그 SysML 텍스트, 멤버(displacement,cylinders,maxPower, 포트fuelIn,output,ecu), 그리고 이 정의로 타입 지정된 usage와 함께 반환합니다.GET /api/v1/projects/<project>/elements/Vehicles::Car/connections는powertrain.output에서frontAxle.input으로 가는 interfacedriveShaft를 나열합니다.GET /api/v1/projects/<project>/requirements?status=unverified는 어떤 검증 케이스도 검증하지 않는 요구사항을VR-4.1같은 id와 함께 나열합니다.{"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을(를) 보내면 제안이 전송됩니다.- 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>/requirements | id, 진술(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/check | text를 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 | 필드 |
|---|---|
create | kind(part, part def, attribute, port, requirement, action, package 같은 키워드) 또는 type(메타클래스). owner(생략 시 최상위). name(필수). 선택 사항 shortName, typedBy, specializes, subsets, redefines, multiplicity, value, doc, direction(in, out, inout) |
update | id와 변경할 필드(create와 동일). null 또는 ""은(는) 필드를 지움 |
move | id와 새 owner |
remove | id. 요소를 그 멤버와 함께 제거 |
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>/branches | main과 변경 요청 브랜치 |
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에서 변경 요청을 검토하고 적용하며, 토큰은 투표하거나 적용하지 않습니다.
- 브랜치 만들기:
{"@type": "Branch", "name": "Cabin heater"}와 함께 POST/branches. 응답은holarchChangeRequest가 포함된 브랜치입니다. - 브랜치의 헤드와 그 요소를 읽습니다.
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와 함께409stale-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-type | 409 | SysML v2 프로젝트에서의 LML 작업, 또는 LML 프로젝트에서의 SysML v2 작업 |
syntax | 422 | 제안된 텍스트에 구문 오류가 있습니다. 진단에 줄과 열이 표시됩니다 |
invalid-model | 422 | 변경이 모델에 오류 진단을 추가합니다. 진단이 나열됩니다 |
not-printable | 422 | 변경을 SysML 텍스트로 기록할 수 없습니다 |
invalid | 422 | 변경을 모델에 적용할 수 없었습니다 |
no-change | 400 | 텍스트가 모델을 바꾸지 않습니다 |
too-large | 413 | 텍스트가 1,000,000자보다 길거나 제안이 8 MB보다 큽니다 |
too-many | 413 또는 409 | 한 호출에 편집이 100개를 넘거나(413), 제안에 이미 변경이 200개 있습니다(409) |
stale | 409 | 제안의 이전 텍스트 변경이 더 이상 모델에 적용되지 않습니다 |
not-found | 404 | 해당 프로젝트, 요소, 브랜치 또는 커밋이 없습니다(Systems Modeling API는 브랜치 헤드만 제공) |
not-writable | 405 | Systems Modeling API를 통한 태그, 병합, 프로젝트 이름 바꾸기 또는 삭제. Holarch에서 수행합니다 |
main-protected | 405 | main 삭제. 대신 변경 요청 브랜치를 삭제합니다 |
stale-head | 409 | previousCommit 이후 브랜치가 이동했습니다. 그 head를 읽고 다시 커밋합니다 |
branch-base | 409 | 새 브랜치는 main의 헤드에서 시작해야 합니다 |
branch-review-off | 409 | 프로젝트가 브랜치 검토를 사용하지 않습니다. 소유자가 변경 요청 → 설정에서 켭니다 |
cr-not-draft | 409 | 변경 요청이 제출되었거나 종료되었습니다. Draft 또는 Rejected 상태일 때만 기록할 수 있습니다 |
cr-full | 409 | 변경 요청에 변경된 항목이 5,000개 있거나, 프로젝트에 변경 요청 초안이 20 MB 있습니다 |
plan-limit | 403 | 변경 요청에 쓰려면 Team 요금제가 필요합니다 |
orphan | 422 | 새 요소에 소유자가 없습니다. 소유 멤버십 또는 owner를 보냅니다 |
unknown-metaclass | 422 | 페이로드의 @type이(가) SysML v2 메타클래스가 아닙니다 |
idempotency-key-reused | 422 | Idempotency-Key가 다른 본문과 함께 사용되었습니다. 새 키를 보냅니다 |
token-projects | 403 | 프로젝트 목록으로 제한된 토큰은 프로젝트를 만들 수 없습니다 |
bad-request | 400 | 최상위 패키지가 아닌 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) |
| 커밋 하나의 DataVersion | 5,000 |
| 변경 요청 하나의 변경된 항목 | 5,000 |
| 커밋 본문 | 32 MB |
속도 제한, 요청 크기, 토큰 규칙은 API와 MCP의 규칙을 따릅니다.
관련 페이지
SysML® 및 OMG®는 미국 및 기타 국가에서 Object Management Group, Inc.의 등록 상표입니다.