Holarch

SysML v2

A API e o MCP em projetos SysML v2

Leia, pesquise e cheque modelos SysML v2 a partir de scripts e ferramentas de IA com um token de acesso pessoal, proponha mudanças que você revisa e aplica no Holarch, e leia e faça commits pela Systems Modeling API, na qual os branches são solicitações de mudança.

Como usá-lo →

Nesta página
  1. Visão geral
  2. Conceitos
  3. Como usá-lo
    1. Ler um projeto SysML v2 com curl
    2. Checar texto SysML antes de propô-lo
    3. Propor uma mudança e aplicá-la
    4. Conectar uma ferramenta de IA a um projeto SysML v2
    5. Exemplo prático: a demonstração Hybrid Car
    6. Dicas
  4. Rotas REST para projetos SysML v2
    1. Valores
  5. Ferramentas MCP para projetos SysML v2
    1. Edições de elementos
    2. Texto proposto
  6. Propostas em projetos SysML v2
    1. Revisar uma proposta SysML v2
  7. Systems Modeling API
    1. Fazer commit de mudanças
  8. Mensagens
  9. Limites
  10. Páginas relacionadas

Visão geral

Os projetos SysML v2 funcionam com a mesma REST API, o mesmo endpoint MCP e os mesmos tokens de acesso pessoal que os projetos LML. Scripts e ferramentas de IA leem o modelo como elementos e texto SysML, checam o texto antes de alterar qualquer coisa e propõem mudanças. Nada no modelo muda até que uma pessoa revise a proposta no Holarch e a aplique.

Três formas de acesso:

  • REST API: https://app.holarch.app/api/v1/projects/<project>/… para scripts e painéis. Ela lê elementos, requisitos, diagnósticos e texto SysML, e adiciona mudanças a uma proposta.
  • MCP: https://app.holarch.app/mcp para ferramentas de IA como o Claude. As ferramentas SysML v2 leem, pesquisam e checam o modelo e propõem mudanças.
  • Systems Modeling API: https://app.holarch.app/api/v1/sysml/…, nos formatos da OMG Systems Modeling API, para outras ferramentas SysML v2. O branch main é o modelo ativo e é somente leitura; todo outro branch é uma solicitação de mudança, e os commits vão para ele. O modelo ativo só muda quando um aprovador aplica a solicitação de mudança no Holarch.

Tokens, escopos, listas de projetos, a chave da organização, limites de taxa e a conexão do Claude são os mesmos dos projetos LML. Consulte API e MCP para criar um token e conectar uma ferramenta de IA. As chamadas do Mapa do programa (GET /api/v1/program-map, GET /api/v1/projects/<project>/items/<item>/trace e as ferramentas MCP program_map e trace_chain) incluem projetos SysML v2 e seus elementos.

Conceitos

  • Elemento: um item do modelo SysML v2, como uma definição de part, uma port ou um requisito. Cada elemento tem um id (um UUID). Onde uma rota ou ferramenta pede um id, um nome qualificado como Vehicles::Car::powertrain também funciona.
  • Resumo: a forma curta de um elemento em listas: id, type (a metaclasse, como PartUsage), name, shortName, qualifiedName e owner.
  • Pacote de nível superior: um pacote que não está dentro de outro elemento. O texto SysML de um projeto é um texto por pacote de nível superior, mais um texto para os elementos fora de pacotes.
  • Diagnóstico: um problema que o núcleo da linguagem encontra, com code, severity (error ou warning), elementId, element e args. Diagnósticos de sintaxe dão line e col em vez de um elemento.
  • Proposta: as mudanças que um cliente da API ou uma ferramenta de IA reúne para revisão. Há uma proposta aberta por token e projeto. O cliente a envia para revisão com um título e um resumo.
  • Respostas paginadas: as listas vêm em páginas (limit, offset). Textos SysML longos vêm em páginas de linhas (line, lines). Uma resposta que deixou algo de fora diz truncated: true.

Como usá-lo

Use a API quando um script ou uma ferramenta de IA precisar do modelo: para relatar requisitos sem elementos que os satisfaçam ou verifiquem, para checar o texto SysML de uma equipe em relação ao modelo, ou para deixar uma ferramenta de IA rascunhar mudanças no modelo que um engenheiro depois revisa.

Ler um projeto SysML v2 com curl

  1. Crie um token em Ajustes da conta → Tokens de API (consulte API e MCP).
  2. Liste seus projetos:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects

Os projetos SysML v2 têm "language": "sysml2".

  1. Obtenha o resumo do modelo:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects/<project>/model

Você vê as contagens de elementos por metaclasse, os pacotes de nível superior e o número de erros e avisos.

  1. Encontre elementos, por exemplo todas as definições de part:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/elements?type=part%20def&limit=100"
  1. Leia o texto SysML de um pacote:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/sysml?root=Vehicles"

Um texto longo termina com "truncated": true e "next": a linha a pedir em seguida com line.

Checar texto SysML antes de propô-lo

  1. Envie o novo texto de um pacote para a rota de checagem:
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. Leia a resposta. ok é true quando o texto não tem erros de sintaxe. diagnostics lista os erros de sintaxe com line e col, e os erros que o texto acrescentaria ao modelo. changes é o número de mudanças no modelo que o texto faz.

A checagem não altera nada. Ela precisa apenas de um token de leitura.

Propor uma mudança e aplicá-la

Um token de escrita adiciona mudanças à proposta aberta do token. O cliente então envia a proposta para revisão.

  1. Adicione uma mudança. Envie o texto novo completo de um pacote ou edições de elementos:
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

Você recebe 201 com a proposta, o resumo da mudança e os elementos que ela adiciona, altera e remove. Uma mudança que acrescenta diagnósticos de erro é recusada (consulte Propostas em projetos SysML v2).

  1. Adicione mais mudanças da mesma forma. Cada mudança é checada em relação ao modelo com as mudanças anteriores da proposta aplicadas.
  2. Envie a proposta para revisão:
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. No Holarch, abra o projeto e depois ✦ IA ▾ → Revisar “Add range attribute”… (ou a notificação no sino).
  2. Confira as linhas e clique em Aplicar selecionados.

    As mudanças marcadas são aplicadas com seu nome no histórico, e um único Desfazer reverte tudo.

Conectar uma ferramenta de IA a um projeto SysML v2

  1. Conecte a ferramenta de IA a https://app.holarch.app/mcp com um token ou com login (consulte API e MCP).
  2. Pergunte sobre o modelo, por exemplo “Resuma o modelo Hybrid Car no Holarch” ou “Quais requisitos do projeto Hybrid Car não estão verificados?”.

    A ferramenta de IA usa model_summary, list_elements, list_requirements e as outras ferramentas de leitura.

  3. Peça uma mudança, por exemplo “Proponha um atributo range em Car”.

    A ferramenta de IA lê o pacote com get_sysml, propõe texto ou edições de elementos e corrige os diagnósticos que a checagem devolver.

  4. Revise a proposta no Holarch e clique em Aplicar selecionados.

Exemplo prático: a demonstração Hybrid Car

Crie a demonstração com Gerenciar projetos → Arquivos do projeto ▾ → Novo projeto de demonstração → Hybrid Car (SysML v2) e depois crie um token de leitura e escrita para ela.

  1. GET /api/v1/projects/<project>/model lista os pacotes de nível superior, entre eles Vehicles, HybridCarArchitecture e VehicleBehavior.
  2. GET /api/v1/projects/<project>/elements?query=Engine&type=part%20def encontra Vehicles::Engine.
  3. GET /api/v1/projects/<project>/elements/Vehicles::Engine devolve a definição de part com seu texto SysML, seus membros (displacement, cylinders, maxPower, as ports fuelIn, output e ecu) e os usos tipados por ela.
  4. GET /api/v1/projects/<project>/elements/Vehicles::Car/connections lista a interface driveShaft de powertrain.output para frontAxle.input.
  5. GET /api/v1/projects/<project>/requirements?status=unverified lista os requisitos que nenhum caso de verificação verifica, com seus ids, como VR-4.1.
  6. POST /api/v1/projects/<project>/proposal/changes com {"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]} adiciona a mudança à proposta. POST /api/v1/projects/<project>/proposal com um título a envia.
  7. No Holarch, ✦ IA ▾ → Revisar “…” mostra Alterado: com a definição de part e o campo doc, e o diff de texto de Vehicles. Aplicar selecionados a aplica.

Dicas

  • Leia um pacote com get_sysml (ou GET …/sysml?root=) antes de propor um texto novo para ele. Elementos deixados de fora do texto proposto são removidos.
  • Prefira edições de elementos para mudanças pequenas. Elas alteram apenas os elementos nomeados e mantêm o resto do texto do pacote como está.
  • Cheque o texto com check_sysml (ou POST …/sysml/check) primeiro. Ele devolve os mesmos diagnósticos com que uma proposta seria recusada.
  • Nomeie os elementos pelo nome qualificado em scripts. Os ids permanecem iguais quando um elemento é renomeado; os nomes qualificados não.
  • Dê a uma ferramenta de IA um token somente leitura quando ela só responde perguntas sobre o modelo.

Rotas REST para projetos SysML v2

Endereço base: https://app.holarch.app/api/v1. As respostas são JSON. /api/v1/openapi.json (OpenAPI 3.1) descreve estas rotas junto com as outras.

Método e caminhoO que ele faz
GET /projects/<project>/modelContagens de elementos por metaclasse, os pacotes de nível superior com suas contagens de elementos e o número de erros e avisos
GET /projects/<project>/elementsPesquisa: query (ou q; texto no nome, nome curto, nome qualificado ou doc), type, owner, limit (1–500, padrão 50), offset; ordenado pelo nome qualificado
GET /projects/<project>/elements/<id>Um elemento com seus campos, doc, texto SysML, membros e os usos tipados por ele; members (0–200, padrão 100)
GET /projects/<project>/elements/<id>/connectionsConnections, interfaces, bindings, fluxos (com o item), sucessões, transições, alocações e dependências no elemento ou nas suas features, e as que ele possui internamente; limit (padrão 100)
GET /projects/<project>/requirementsRequisitos com seu id, declaração (doc), satisfiedBy e verifiedBy; owner, status (unsatisfied ou unverified), limit (padrão 100), offset
GET /projects/<project>/diagnosticsOs diagnósticos do modelo, erros primeiro; ids (separados por vírgula: apenas esses elementos e seus membros), limit (padrão 200, no máximo 500)
GET /projects/<project>/sysmlTexto SysML de um pacote de nível superior (root), dos elementos fora de pacotes (sem root) ou de um elemento (element); line (primeira linha, a partir de 1), lines (padrão 2000, no máximo 5000)
POST /projects/<project>/sysml/checkCheca text como o novo texto de root (ou dos elementos fora de pacotes); não altera nada
POST /projects/<project>/proposal/changesAdiciona uma mudança à proposta aberta: {text, root} ou {edits}
GET /projects/<project>/proposalA proposta aberta, ou uma pelo id de proposal, com seu status e suas mudanças
POST /projects/<project>/proposalEnvia a proposta aberta para revisão: title, summary
DELETE /projects/<project>/proposalDescarta a proposta aberta antes de ela ser enviada

GET /projects e GET /projects/<project> também funcionam para projetos SysML v2. Eles dão "language": "sysml2", e a resposta do projeto acrescenta elements e types (contagens de elementos por metaclasse).

As rotas de entidades LML (/entities, /relationships, /schema, Checagens do modelo e a checagem de qualidade) respondem 409 wrong-project-type em um projeto SysML v2. As rotas SysML v2 respondem o mesmo em um projeto LML.

Valores

  • type: uma metaclasse como PartUsage ou RequirementDefinition, ou uma palavra-chave como escrita no texto SysML: part, part def, attribute, port, requirement, action, package e as outras palavras-chave de elementos.
  • owner, id, element, root: um id ou um nome qualificado. root também aceita o nome de um pacote de nível superior. root deve ser um pacote de nível superior; para ler o texto de um elemento, use element.
  • Valores longos: um doc em uma lista é cortado em 4.000 caracteres, o doc de um único elemento em 20.000, e o próprio texto SysML de um elemento em 16.000 caracteres.

Ferramentas MCP para projetos SysML v2

O endpoint MCP lista estas ferramentas ao lado das ferramentas LML. Uma ferramenta de IA encontra projetos SysML v2 com list_projects (language: sysml2). Toda ferramenta aceita project.

As ferramentas de leitura também aceitam um change_request opcional (CR-12 ou seu id) para ler o modelo como essa solicitação de mudança o deixaria; propose_sysml e propose_element_changes aceitam um para calcular a mudança em relação ao modelo da solicitação e aplicá-la nesse rascunho após a revisão. Consulte Solicitações de mudança para as regras.

FerramentaAcessoO que ele faz
model_summaryLeituraContagens de elementos por metaclasse, os pacotes de nível superior e o número de diagnósticos
list_elementsLeituraEncontra elementos por texto (query), type e owner; paginado com limit e offset
get_elementLeituraUm elemento (id) com seus tipos, especializações, multiplicidade, valor, extremidades, doc, texto SysML, membros (members, no máximo 200) e os usos tipados por ele
get_connectionsLeituraAs connections, interfaces, bindings, fluxos, sucessões, transições, alocações e dependências de um elemento (id, limit)
list_requirementsLeituraRequisitos com seu id, declaração, satisfy e verify; owner, status (unsatisfied, unverified), limit, offset
get_sysmlLeituraTexto SysML de um pacote de nível superior (root), dos elementos fora de pacotes ou de um elemento (element); line, lines (no máximo 5000); a resposta dá next
get_sysml_textLeituraTexto SysML do modelo inteiro (todo pacote de nível superior e depois os elementos fora de pacotes) ou de um package, até 200.000 caracteres por resposta; a resposta nomeia os pacotes deixados de fora
check_sysmlLeituraSem text: os diagnósticos do modelo (ids, limit). Com text (e root): erros de sintaxe com linha e coluna, e os erros que o texto acrescentaria. Não altera nada
propose_sysmlLeitura e escritaPropõe o novo text completo de um pacote de nível superior (root) ou dos elementos fora de pacotes (sem root; também onde entra um pacote novo)
propose_element_changesLeitura e escritaPropõe edits (no máximo 100) sem reescrever texto: create, update, move ou remove

list_diagrams, get_diagram e get_matrix também funcionam em projetos SysML v2: list_diagrams lista as vistas (com seu tipo, como InterconnectionView) e os diagramas de análise guardados sob um elemento; get_diagram dá os elementos que uma vista expõe após seus filtros (por id de elemento ou nome qualificado); get_matrix dá cada requisito com o que o satisfaz e o verifica.

As ferramentas de proposta dos projetos LML funcionam da mesma forma aqui: propose_changes envia a proposta com um título e um resumo, discard_proposal a descarta, e get_proposal e list_proposals mostram seu status. Um token somente leitura lista apenas as ferramentas de leitura.

Os erros das ferramentas voltam como resultado da ferramenta, com a mensagem e os diagnósticos, para que a ferramenta de IA possa corrigir seu texto e tentar de novo.

Edições de elementos

Cada edição em edits (MCP) ou {"edits": […]} (REST) é um objeto com op:

opCampos
createkind (uma palavra-chave como part, part def, attribute, port, requirement, action, package) ou type (uma metaclasse); owner (omitido: nível superior); name (obrigatório); opcionais shortName, typedBy, specializes, subsets, redefines, multiplicity, value, doc, direction (in, out, inout)
updateid e os campos a alterar, como em create; null ou "" limpa um campo
moveid e o novo owner
removeid; remove o elemento com seus membros
  • typedBy, specializes, subsets e redefines são listas de até 20 nomes: ids, nomes qualificados ou nomes como escritos no texto (nomes de biblioteca como MassValue funcionam).
  • Edições posteriores podem nomear elementos criados antes na mesma chamada como new:1, new:2 … na ordem em que foram criados, por exemplo como owner. A resposta os lista em created com seus novos ids.
  • Renomear um elemento também atualiza as referências que o nomeavam pelo nome antigo.

Texto proposto

  • propose_sysml substitui o texto inteiro do pacote. Os elementos mantêm seus ids onde o texto ainda os declara. Elementos deixados de fora do texto são removidos.
  • O texto deve ser analisável sem deixar nada sem aplicar. Um texto que não altera o modelo é recusado (no-change).

Propostas em projetos SysML v2

Cada mudança proposta é checada pelo núcleo da linguagem antes de entrar na proposta:

  • O texto é analisável sem erros de sintaxe, e as edições de elementos se aplicam.
  • Os pacotes alterados ainda podem ser impressos como texto SysML e analisados de novo.
  • A mudança não acrescenta diagnósticos de erro ao modelo, como nomes não resolvidos ou erros de tipo. Os erros que o modelo já tinha não contam.

Uma mudança que falha é recusada com os diagnósticos (até 50) a corrigir. Nada é guardado. Avisos não recusam uma mudança.

Propor exige um token de leitura e escrita e o papel de editor ou proprietário no projeto. Uma proposta contém no máximo 200 mudanças e 8 MB.

Revisar uma proposta SysML v2

Abra o projeto e depois ✦ IA ▾ → Revisar “<título>”…. Cada mudança é uma linha com uma caixa de seleção:

  • Adicionado, Alterado e Removido listam os elementos, com os campos alterados (os 20 primeiros de cada; “e mais n” para o restante).
  • Um diff de texto, rotulado com o pacote, mostra o texto SysML antes e depois.
  • Uma mudança que remove elementos é sinalizada e começa desmarcada.
  • Abra o modelo SysML v2 para aplicar esta alteração. O modelo não está carregado; abra uma página SysML v2 do projeto.
  • O pacote não está mais no modelo; ignorado. O pacote foi removido depois de a mudança ser proposta.

Aplicar selecionados sincroniza de novo cada mudança de texto com o modelo atual e mantém as edições cujos elementos ainda existem. Ele checa o conjunto inteiro e o aplica como uma etapa de desfazer. Mudanças que não se encaixam mais são ignoradas e nomeadas em uma notificação. Rejeitar e Mais tarde funcionam como nas propostas LML, assim como os papéis, a expiração (7 dias) e a retenção (consulte Propostas de clientes de IA).

Systems Modeling API

Outras ferramentas SysML v2 leem e alteram modelos do Holarch por rotas nos formatos da OMG Systems Modeling API (REST/HTTP). O endereço base é https://app.holarch.app/api/v1/sysml. Ela usa os mesmos tokens; qualquer papel no projeto pode ler, e editores e proprietários podem fazer commits.

  • Projetos: só os projetos SysML v2 são listados. O @id de um projeto é um UUID que esta API lhe dá; o id do projeto no Holarch também funciona. A resposta inclui holarchId e url.
  • Branches: main é o modelo ativo e não pode ser alterado pela API. Todo outro branch é uma solicitação de mudança em andamento, chamada "CR-12 Título" e com holarchChangeRequest (id, label, status, url). Solicitações de mudança implementadas ou retiradas nos últimos 30 dias ainda são listadas, com deleted definido.
  • Commits: um commit grava mudanças no branch de uma solicitação de mudança. Só as cabeças dos branches são servidas: a cabeça de main é o modelo ativo, a cabeça do branch de uma solicitação de mudança é o modelo ativo com as mudanças da solicitação. Ids de commits mais antigos respondem 404; obtenha a cabeça atual a partir do branch.
  • Elementos: cada elemento tem todas as propriedades da sua metaclasse no esquema JSON da OMG, incluindo as derivadas (owner, ownedElement, qualifiedName, feature, type e semelhantes). Os elementos da biblioteca padrão são referenciados pelos seus ids padrão, os ids que outras ferramentas SysML v2 usam para o mesmo elemento de biblioteca.
  • Tags e consultas salvas: nenhuma; suas listas estão vazias.
Método e caminhoO que ele faz
GET /sysml/projectsSeus projetos SysML v2
POST /sysml/projectsCria um projeto SysML v2 vazio (name, description)
GET /sysml/projects/<projectId>Um projeto, com seu branch padrão
GET /sysml/projects/<projectId>/branchesmain e os branches das solicitações de mudança
POST /sysml/projects/<projectId>/branchesCria um branch: uma nova solicitação de mudança em rascunho (name é seu título, description seu motivo)
GET /sysml/projects/<projectId>/branches/<branchId>O branch (seu @id ou main), com head
DELETE /sysml/projects/<projectId>/branches/<branchId>Retira a solicitação de mudança
GET /sysml/projects/<projectId>/commitsAs cabeças e os commits enviados aos branches, os mais novos primeiro
POST /sysml/projects/<projectId>/commits?branchId=<branchId>Faz commit de mudanças em um branch (abaixo)
GET /sysml/projects/<projectId>/commits/<commitId>Um commit de cabeça
GET /sysml/projects/<projectId>/commits/<commitId>/changesO que o branch muda em relação ao modelo ativo: um DataVersion por elemento
GET /sysml/projects/<projectId>/commits/<commitId>/elementsTodos os elementos do commit, paginados
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>Um elemento
GET /sysml/projects/<projectId>/commits/<commitId>/rootsOs elementos de nível superior, paginados
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>/relationshipsOs relacionamentos que têm o elemento como origem ou destino; direction é in, out ou both (padrão), paginados
POST /sysml/projects/<projectId>/query-resultsOs elementos que correspondem a uma consulta (corpo abaixo), paginados; commitId deve ser uma cabeça
GET /sysml/projects/<projectId>/tags, /queries, /commits/<commitId>/elements/<elementId>/projectUsagesListas vazias

As respostas de lista são arrays JSON. As listas são paginadas com page[size] (padrão 100, no máximo 1000) e page[after] (o @id do último item da página anterior) ou page[before] (o @id do primeiro item da página seguinte). O cabeçalho Link dá a próxima página com rel="next" e a anterior com rel="prev".

Uma consulta é um objeto JSON com um where opcional (um PrimitiveConstraint com property, operator (=, in, <, <=, >, >= ou instanceOf), value e inverse, ou um CompositeConstraint com operator and ou or e constraint), scope (ids de elementos: a pesquisa os abrange, junto com o que eles possuem) e select (as propriedades a devolver; @id e @type sempre voltam):

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

Leia os elementos de um modelo:

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"

Fazer commit de mudanças

Escrever exige um token com acesso de leitura e escrita, o papel de editor ou proprietário, o plano Team (também para contas acadêmicas e de turma) e a revisão de branch ativada no projeto (Solicitações de mudança → Ajustes). Um aprovador revisa e aplica a solicitação de mudança no Holarch; tokens nunca votam nem aplicam.

  1. Crie um branch: POST /branches com {"@type": "Branch", "name": "Cabin heater"}. A resposta é o branch com seu holarchChangeRequest.
  2. Leia a cabeça do branch e seus elementos.
  3. POST /commits?branchId=<branch @id> com uma lista de DataVersions:
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>"}}}]}'
  • Alterar um elemento: envie o elemento como você o leu, com as propriedades alteradas. Só as propriedades próprias contam (declaredName, ownedRelationship, isAbstract e semelhantes); as derivadas são ignoradas, então devolver o que você leu não altera nada. Uma propriedade que você omite mantém seu valor; envie null ou [] para limpá-la.
  • Elementos novos: dê ao elemento um novo UUID e sua membership proprietária (enviada no mesmo commit) ou owner, que cria a membership por você.
  • Remover um elemento: payload: null o remove com tudo o que ele possui.
  • Checagens: cada pacote que o commit afeta deve poder ser impresso e analisado de novo, e o commit não pode acrescentar diagnósticos de erro; caso contrário, 422 com os diagnostics a corrigir.
  • previousCommit: a cabeça sobre a qual sua mudança foi feita. Se o branch avançou desde então, a resposta é 409 stale-head com a head atual; leia de novo e faça o commit sobre ela.
  • Novas tentativas: envie um cabeçalho Idempotency-Key. Uma nova tentativa com a mesma chave e o mesmo corpo em até 24 horas recebe de novo a primeira resposta.
  • Commits em main: um commit sem branchId, ou com main, vai para a solicitação de mudança em rascunho do seu próprio token ("API changes from <token name>"), criada no primeiro desses commits. A resposta diz qual em holarchChangeRequest e em um cabeçalho Warning.
  • Projetos novos: um projeto criado com POST /sysml/projects tem a revisão de branch ativada. Seu primeiro commit em main, enquanto você é o único membro, é gravado diretamente no modelo, uma vez; os commits posteriores passam por solicitações de mudança.

Envie a solicitação de mudança para revisão com POST /api/v1/projects/<project>/change-requests/<CR-12>/submit (API e MCP). Tags, merges e renomear ou excluir um projeto respondem 405 com o que fazer em vez disso. Os erros trazem @type Error e uma description, como a API da OMG os define.

Mensagens

Os códigos de API e MCP se aplicam. As rotas e ferramentas SysML v2 acrescentam:

CódigoStatusSignificado
wrong-project-type409Uma operação LML em um projeto SysML v2, ou uma operação SysML v2 em um projeto LML
syntax422O texto proposto tem erros de sintaxe; os diagnósticos dão linha e coluna
invalid-model422A mudança acrescenta diagnósticos de erro ao modelo; eles são listados
not-printable422A mudança não pode ser escrita como texto SysML
invalid422Não foi possível aplicar a mudança ao modelo
no-change400O texto não altera o modelo
too-large413O texto tem mais de 1.000.000 caracteres, ou a proposta tem mais de 8 MB
too-many413 ou 409Mais de 100 edições em uma chamada (413), ou a proposta já contém 200 mudanças (409)
stale409Uma mudança de texto anterior da proposta não se aplica mais ao modelo
not-found404Projeto, elemento, branch ou commit inexistente (a Systems Modeling API serve apenas as cabeças dos branches)
not-writable405Tags, merges, renomear ou excluir um projeto pela Systems Modeling API; faça isso no Holarch
main-protected405Excluir main; exclua o branch de uma solicitação de mudança em vez disso
stale-head409O branch avançou desde previousCommit; leia sua head e faça o commit de novo
branch-base409Um branch novo deve começar na cabeça de main
branch-review-off409O projeto não usa revisão de branch; um proprietário a ativa em Solicitações de mudança → Ajustes
cr-not-draft409A solicitação de mudança foi enviada ou fechada; ela só pode ser gravada em Rascunho ou Rejeitada
cr-full409A solicitação de mudança contém 5.000 itens alterados, ou o projeto 20 MB de rascunhos de solicitações de mudança
plan-limit403Gravações em solicitações de mudança exigem o plano Team
orphan422Um elemento novo não tem dono; envie sua membership proprietária ou owner
unknown-metaclass422O @type de um payload não é uma metaclasse SysML v2
idempotency-key-reused422O Idempotency-Key foi usado com outro corpo; envie uma chave nova
token-projects403Um token limitado a uma lista de projetos não pode criar um projeto
bad-request400Um valor ausente ou errado, como um root que não é um pacote de nível superior, um op desconhecido ou um elemento novo sem nome

Limites

O quêLimite
Elementos, requisitos ou conexões por página500
Membros listados com um elemento200
Diagnósticos por resposta500
Linhas de texto SysML por resposta5.000, e no máximo 400.000 bytes (cortado em uma linha)
Texto doc4.000 caracteres em listas, 20.000 para um elemento
O próprio texto SysML de um elemento16.000 caracteres
Texto em uma chamada propose_sysml1.000.000 caracteres
Edições em uma chamada100
Elementos listados como adicionados, alterados ou removidos em uma mudança300 de cada
Mudanças em uma proposta200, e 8 MB
Página da Systems Modeling API1.000 elementos (padrão 100)
DataVersions em um commit5,000
Itens alterados em uma solicitação de mudança5,000
Corpo do commit32 MB

Os limites de taxa, o tamanho das solicitações e as regras de tokens são os de API e MCP.

SysML® e OMG® são marcas registradas da Object Management Group, Inc. nos Estados Unidos e em outros países.