Holarch

SysML v2

La API y MCP en proyectos SysML v2

Lea, busque y compruebe modelos SysML v2 desde scripts y herramientas de IA con un token de acceso personal, proponga cambios que usted revisa y aplica en Holarch, y lea y confirme cambios a través de la Systems Modeling API, donde las ramas son solicitudes de cambio.

Cómo usarlo →

En esta página
  1. Resumen
  2. Conceptos
  3. Cómo usarlo
    1. Leer un proyecto SysML v2 con curl
    2. Comprobar texto SysML antes de proponerlo
    3. Proponer un cambio y aplicarlo
    4. Conectar una herramienta de IA a un proyecto SysML v2
    5. Ejemplo práctico: la demostración Hybrid Car
    6. Consejos
  4. Rutas REST para proyectos SysML v2
    1. Valores
  5. Herramientas MCP para proyectos SysML v2
    1. Ediciones de elementos
    2. Texto propuesto
  6. Propuestas en proyectos SysML v2
    1. Revisar una propuesta SysML v2
  7. Systems Modeling API
    1. Confirmar cambios
  8. Mensajes
  9. Límites
  10. Páginas relacionadas

Resumen

Los proyectos SysML v2 funcionan con la misma API REST, el mismo endpoint MCP y los mismos tokens de acceso personal que los proyectos LML. Los scripts y las herramientas de IA leen el modelo como elementos y texto SysML, comprueban el texto antes de cambiar nada y proponen cambios. Nada del modelo cambia hasta que una persona revisa la propuesta en Holarch y la aplica.

Tres vías de acceso:

  • API REST: https://app.holarch.app/api/v1/projects/<project>/… para scripts y paneles. Lee elementos, requisitos, diagnósticos y texto SysML, y añade cambios a una propuesta.
  • MCP: https://app.holarch.app/mcp para herramientas de IA como Claude. Las herramientas SysML v2 leen, buscan y comprueban el modelo y proponen cambios.
  • Systems Modeling API: https://app.holarch.app/api/v1/sysml/…, con las formas de la OMG Systems Modeling API para otras herramientas SysML v2. La rama main es el modelo activo y es de solo lectura; cualquier otra rama es una solicitud de cambio, y las confirmaciones van a ella. El modelo activo solo cambia cuando un aprobador aplica la solicitud de cambio en Holarch.

Los tokens, los ámbitos, las listas de proyectos, el cambio de organización, los límites de frecuencia y la conexión de Claude son iguales que para los proyectos LML. Consulte API y MCP para crear un token y conectar una herramienta de IA. Las llamadas del Mapa del programa (GET /api/v1/program-map, GET /api/v1/projects/<project>/items/<item>/trace, y las herramientas MCP program_map y trace_chain) incluyen los proyectos SysML v2 y sus elementos.

Conceptos

  • Elemento: un componente del modelo SysML v2, como una definición de parte, un puerto o un requisito. Cada elemento tiene un id (un UUID). Siempre que una ruta o herramienta pida un id, también sirve un nombre calificado como Vehicles::Car::powertrain.
  • Resumen: la forma breve de un elemento en las listas: id, type (la metaclase, como PartUsage), name, shortName, qualifiedName y owner.
  • Paquete de nivel superior: un paquete que no está dentro de otro elemento. El texto SysML de un proyecto es un texto por paquete de nivel superior, más un texto para los elementos fuera de paquetes.
  • Diagnóstico: un problema que encuentra el núcleo del lenguaje, con code, severity (error o warning), elementId, element y args. Los diagnósticos de sintaxis dan line y col en lugar de un elemento.
  • Propuesta: los cambios que un cliente de la API o una herramienta de IA reúne para su revisión. Hay una propuesta abierta por token y proyecto. El cliente la envía a revisión con un título y un resumen.
  • Respuestas paginadas: las listas llegan en páginas (limit, offset). El texto SysML largo llega en páginas de líneas (line, lines). Una respuesta que omitió algo indica truncated: true.

Cómo usarlo

Use la API cuando un script o una herramienta de IA necesite el modelo: para informar de requisitos sin elementos que los satisfagan o verifiquen, para comprobar el texto SysML de un equipo frente al modelo o para que una herramienta de IA redacte cambios del modelo que luego revisa un ingeniero.

Leer un proyecto SysML v2 con curl

  1. Cree un token en Ajustes de la cuenta → Tokens de API (consulte API y MCP).
  2. Liste sus proyectos:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects

Los proyectos SysML v2 tienen "language": "sysml2".

  1. Obtenga el resumen del modelo:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects/<project>/model

Verá los recuentos de elementos por metaclase, los paquetes de nivel superior y el número de errores y advertencias.

  1. Busque elementos, por ejemplo todas las definiciones de parte:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/elements?type=part%20def&limit=100"
  1. Lea el texto SysML de un paquete:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/sysml?root=Vehicles"

Un texto largo termina con "truncated": true y "next": la línea que debe pedirse a continuación con line.

Comprobar texto SysML antes de proponerlo

  1. Envíe el nuevo texto de un paquete a la ruta de comprobación:
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. Lea la respuesta. ok es true cuando el texto no tiene errores de sintaxis. diagnostics enumera los errores de sintaxis con line y col, y los errores que el texto añadiría al modelo. changes es el número de cambios en el modelo que produce el texto.

La comprobación no cambia nada. Solo necesita un token de lectura.

Proponer un cambio y aplicarlo

Un token de escritura añade cambios a la propuesta abierta del token. Después, el cliente envía la propuesta a revisión.

  1. Añada un cambio. Envíe el texto nuevo completo de un paquete o ediciones 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

Recibirá 201 con la propuesta, el resumen del cambio y los elementos que añade, cambia y quita. Un cambio que añade diagnósticos de error se rechaza (consulte Propuestas en proyectos SysML v2).

  1. Añada más cambios de la misma forma. Cada cambio se comprueba frente al modelo con los cambios anteriores de la propuesta aplicados.
  2. Envíe la propuesta a revisión:
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. En Holarch, abra el proyecto y luego ✦ IA ▾ → Revisar «Add range attribute»… (o la notificación bajo la campana).
  2. Compruebe las filas y haga clic en Aplicar seleccionados.

    Los cambios marcados se aplican con su nombre en el historial, y un solo Deshacer lo revierte todo.

Conectar una herramienta de IA a un proyecto SysML v2

  1. Conecte la herramienta de IA a https://app.holarch.app/mcp con un token o con inicio de sesión (consulte API y MCP).
  2. Pregunte sobre el modelo, por ejemplo «Resume el modelo Hybrid Car en Holarch» o «¿Qué requisitos del proyecto Hybrid Car no están verificados?».

    La herramienta de IA usa model_summary, list_elements, list_requirements y las demás herramientas de lectura.

  3. Pida un cambio, por ejemplo «Propón un atributo range en Car».

    La herramienta de IA lee el paquete con get_sysml, propone texto o ediciones de elementos y corrige los diagnósticos que devuelva la comprobación.

  4. Revise la propuesta en Holarch y haga clic en Aplicar seleccionados.

Ejemplo práctico: la demostración Hybrid Car

Cree la demostración con Gestionar proyectos → Archivos de proyecto ▾ → Nuevo proyecto de demostración → Hybrid Car (SysML v2) y cree un token de lectura y escritura para ella.

  1. GET /api/v1/projects/<project>/model enumera los paquetes de nivel superior, entre ellos Vehicles, HybridCarArchitecture y VehicleBehavior.
  2. GET /api/v1/projects/<project>/elements?query=Engine&type=part%20def encuentra Vehicles::Engine.
  3. GET /api/v1/projects/<project>/elements/Vehicles::Engine devuelve la definición de parte con su texto SysML, sus miembros (displacement, cylinders, maxPower, los puertos fuelIn, output y ecu) y los usos tipificados por ella.
  4. GET /api/v1/projects/<project>/elements/Vehicles::Car/connections muestra la interfaz driveShaft de powertrain.output a frontAxle.input.
  5. GET /api/v1/projects/<project>/requirements?status=unverified enumera los requisitos que ningún caso de verificación verifica, con sus ids como VR-4.1.
  6. POST /api/v1/projects/<project>/proposal/changes con {"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]} añade el cambio a la propuesta. POST /api/v1/projects/<project>/proposal con un título la envía.
  7. En Holarch, ✦ IA ▾ → Revisar «…» muestra Cambiado: con la definición de parte y el campo doc, y la diferencia de texto de Vehicles. Aplicar seleccionados la aplica.

Consejos

  • Lea un paquete con get_sysml (o GET …/sysml?root=) antes de proponer texto nuevo para él. Los elementos que no figuren en el texto propuesto se quitan.
  • Prefiera las ediciones de elementos para cambios pequeños. Solo cambian los elementos nombrados y dejan el resto del texto del paquete como está.
  • Compruebe primero el texto con check_sysml (o POST …/sysml/check). Devuelve los mismos diagnósticos con los que se rechazaría una propuesta.
  • En los scripts, nombre los elementos por su nombre calificado. Los ids no cambian cuando se cambia el nombre de un elemento; los nombres calificados, sí.
  • Dé a una herramienta de IA un token de solo lectura cuando solo responda preguntas sobre el modelo.

Rutas REST para proyectos SysML v2

Dirección base: https://app.holarch.app/api/v1. Las respuestas son JSON. /api/v1/openapi.json (OpenAPI 3.1) describe estas rutas junto con las demás.

Método y rutaQué hace
GET /projects/<project>/modelRecuentos de elementos por metaclase, los paquetes de nivel superior con sus recuentos de elementos y el número de errores y advertencias
GET /projects/<project>/elementsBúsqueda: query (o q; texto en el nombre, el nombre corto, el nombre calificado o la documentación), type, owner, limit (1–500, 50 de forma predeterminada), offset; ordenado por nombre calificado
GET /projects/<project>/elements/<id>Un elemento con sus campos, documentación, texto SysML, miembros y los usos tipificados por él; members (0–200, 100 de forma predeterminada)
GET /projects/<project>/elements/<id>/connectionsConexiones, interfaces, enlaces, flujos (con el ítem), sucesiones, transiciones, asignaciones y dependencias en el elemento o en sus características, y las que posee en su interior; limit (100 de forma predeterminada)
GET /projects/<project>/requirementsRequisitos con su id, enunciado (doc), satisfiedBy y verifiedBy; owner, status (unsatisfied o unverified), limit (100 de forma predeterminada), offset
GET /projects/<project>/diagnosticsLos diagnósticos del modelo, primero los errores; ids (separados por comas: solo esos elementos y sus miembros), limit (200 de forma predeterminada, 500 como máximo)
GET /projects/<project>/sysmlTexto SysML de un paquete de nivel superior (root), de los elementos fuera de paquetes (sin root) o de un elemento (element); line (primera línea, desde 1), lines (2000 de forma predeterminada, 5000 como máximo)
POST /projects/<project>/sysml/checkComprobar text como nuevo texto de root (o de los elementos fuera de paquetes); no cambia nada
POST /projects/<project>/proposal/changesAñadir un cambio a la propuesta abierta: {text, root} o {edits}
GET /projects/<project>/proposalLa propuesta abierta, o una por su id de proposal, con su estado y sus cambios
POST /projects/<project>/proposalEnviar la propuesta abierta a revisión: title, summary
DELETE /projects/<project>/proposalDescartar la propuesta abierta antes de enviarla

GET /projects y GET /projects/<project> también funcionan para proyectos SysML v2. Dan "language": "sysml2", y la respuesta del proyecto añade elements y types (recuentos de elementos por metaclase).

Las rutas de entidades LML (/entities, /relationships, /schema, Comprobaciones del modelo y la comprobación de calidad) responden 409 wrong-project-type en un proyecto SysML v2. Las rutas SysML v2 responden lo mismo en un proyecto LML.

Valores

  • type: una metaclase como PartUsage o RequirementDefinition, o una palabra clave tal como se escribe en el texto SysML: part, part def, attribute, port, requirement, action, package y las demás palabras clave de elementos.
  • owner, id, element, root: un id o un nombre calificado. root también admite el nombre de un paquete de nivel superior. root debe ser un paquete de nivel superior; para leer el texto de un elemento, use element.
  • Valores largos: una documentación en una lista se corta a los 4,000 caracteres, la documentación de un solo elemento a los 20,000, y el texto SysML propio de un elemento a los 16,000 caracteres.

Herramientas MCP para proyectos SysML v2

El endpoint MCP enumera estas herramientas junto a las herramientas LML. Una herramienta de IA encuentra los proyectos SysML v2 con list_projects (language: sysml2). Todas las herramientas admiten project.

Las herramientas de lectura también admiten un change_request opcional (CR-12 o su id) para leer el modelo tal como lo dejaría esa solicitud de cambio; propose_sysml y propose_element_changes admiten uno para calcular el cambio frente al modelo de la solicitud y aplicarlo a ese borrador tras la revisión. Consulte Solicitudes de cambio para conocer las reglas.

HerramientaAccesoQué hace
model_summaryLecturaRecuentos de elementos por metaclase, los paquetes de nivel superior y el número de diagnósticos
list_elementsLecturaBuscar elementos por texto (query), type y owner; paginado con limit y offset
get_elementLecturaUn elemento (id) con sus tipos, especializaciones, multiplicidad, valor, extremos, documentación, texto SysML, miembros (members, 200 como máximo) y los usos tipificados por él
get_connectionsLecturaLas conexiones, interfaces, enlaces, flujos, sucesiones, transiciones, asignaciones y dependencias de un elemento (id, limit)
list_requirementsLecturaRequisitos con su id, enunciado, satisfy y verify; owner, status (unsatisfied, unverified), limit, offset
get_sysmlLecturaTexto SysML de un paquete de nivel superior (root), de los elementos fuera de paquetes o de un elemento (element); line, lines (5000 como máximo); la respuesta da next
get_sysml_textLecturaTexto SysML de todo el modelo (cada paquete de nivel superior y luego los elementos fuera de paquetes) o de un package, hasta 200,000 caracteres por respuesta; la respuesta nombra los paquetes omitidos
check_sysmlLecturaSin text: los diagnósticos del modelo (ids, limit). Con text (y root): errores de sintaxis con línea y columna, y los errores que el texto añadiría. No cambia nada
propose_sysmlLectura y escrituraProponer el text nuevo completo de un paquete de nivel superior (root) o de los elementos fuera de paquetes (sin root; también donde va un paquete nuevo)
propose_element_changesLectura y escrituraProponer edits (100 como máximo) sin reescribir texto: crear, actualizar, mover o quitar

list_diagrams, get_diagram y get_matrix también funcionan en proyectos SysML v2: list_diagrams enumera las vistas (con su tipo, como InterconnectionView) y los diagramas de análisis guardados bajo un elemento; get_diagram da los elementos que expone una vista después de sus filtros (por id de elemento o nombre calificado); get_matrix da cada requisito con lo que lo satisface y lo verifica.

Las herramientas de propuestas de los proyectos LML funcionan aquí de la misma forma: propose_changes envía la propuesta con un título y un resumen, discard_proposal la descarta, y get_proposal y list_proposals muestran su estado. Un token de solo lectura enumera solo las herramientas de lectura.

Los errores de las herramientas vuelven como resultado de la herramienta con el mensaje y los diagnósticos, para que la herramienta de IA pueda corregir su texto e intentarlo de nuevo.

Ediciones de elementos

Cada edición de edits (MCP) o {"edits": […]} (REST) es un objeto con op:

opCampos
createkind (una palabra clave como part, part def, attribute, port, requirement, action, package) o type (una metaclase); owner (si se omite: nivel superior); name (obligatorio); opcionales shortName, typedBy, specializes, subsets, redefines, multiplicity, value, doc, direction (in, out, inout)
updateid y los campos que se van a cambiar, como en create; null o "" vacía un campo
moveid y el nuevo owner
removeid; quita el elemento con sus miembros
  • typedBy, specializes, subsets y redefines son listas de hasta 20 nombres: ids, nombres calificados o nombres tal como se escriben en el texto (funcionan nombres de biblioteca como MassValue).
  • Las ediciones posteriores pueden nombrar los elementos creados antes en la misma llamada como new:1, new:2 … en el orden en que se crearon, por ejemplo como owner. La respuesta los enumera en created con sus nuevos ids.
  • Cambiar el nombre de un elemento también actualiza las referencias que lo nombraban por su nombre anterior.

Texto propuesto

  • propose_sysml sustituye todo el texto del paquete. Los elementos conservan sus ids donde el texto todavía los declara. Los elementos que no figuran en el texto se quitan.
  • El texto debe analizarse sin errores y sin que quede nada sin aplicar. El texto que no cambia el modelo se rechaza (no-change).

Propuestas en proyectos SysML v2

El núcleo del lenguaje comprueba cada cambio propuesto antes de que se una a la propuesta:

  • El texto se analiza sin errores de sintaxis, y las ediciones de elementos se aplican.
  • Los paquetes cambiados todavía se imprimen como texto SysML y se vuelven a analizar.
  • El cambio no añade diagnósticos de error al modelo, como nombres sin resolver o errores de tipo. Los errores que el modelo ya tenía no cuentan.

Un cambio que falla se rechaza con los diagnósticos (hasta 50) que hay que corregir. No se guarda nada. Las advertencias no rechazan un cambio.

Proponer requiere un token de lectura y escritura y el rol de editor o propietario en el proyecto. Una propuesta contiene como máximo 200 cambios y 8 MB.

Revisar una propuesta SysML v2

Abra el proyecto y luego ✦ IA ▾ → Revisar «<title>»…. Cada cambio es una fila con una casilla:

  • Añadido, Cambiado y Quitado enumeran los elementos, con los campos cambiados (los 20 primeros de cada uno; «y n más» para el resto).
  • Una diferencia de texto, etiquetada con el paquete, muestra el texto SysML antes y después.
  • Un cambio que quita elementos se señala y empieza desmarcado.
  • Abra el modelo SysML v2 para aplicar este cambio. El modelo no está cargado; abra una página SysML v2 del proyecto.
  • El paquete ya no está en el modelo; omitido. El paquete se quitó después de proponer el cambio.

Aplicar seleccionados vuelve a sincronizar cada cambio de texto con el modelo actual y conserva las ediciones cuyos elementos aún existen. Comprueba todo el conjunto y lo aplica como un paso de deshacer. Los cambios que ya no encajan se omiten y se nombran en un aviso. Rechazar y Más tarde funcionan como en las propuestas LML, al igual que los roles, la caducidad (7 días) y la conservación (consulte Propuestas de clientes de IA).

Systems Modeling API

Otras herramientas SysML v2 leen y cambian modelos de Holarch mediante rutas con las formas de la OMG Systems Modeling API (REST/HTTP). La dirección base es https://app.holarch.app/api/v1/sysml. Usa los mismos tokens; cualquier rol del proyecto puede leer, y los editores y propietarios pueden confirmar cambios.

  • Proyectos: solo se enumeran los proyectos SysML v2. El @id de un proyecto es un UUID que le asigna esta API; el id de proyecto de Holarch también funciona. La respuesta incluye holarchId y url.
  • Ramas: main es el modelo activo y no se puede cambiar mediante la API. Cualquier otra rama es una solicitud de cambio en curso, llamada «CR-12 Título» y con holarchChangeRequest (id, label, status, url). Las solicitudes de cambio implementadas o retiradas en los últimos 30 días siguen apareciendo, con deleted establecido.
  • Confirmaciones: una confirmación escribe cambios en la rama de una solicitud de cambio. Solo se sirven los heads de las ramas: el head de main es el modelo activo; el head de la rama de una solicitud de cambio es el modelo activo con los cambios de la solicitud. Los ids de confirmaciones anteriores responden 404; obtenga el head actual a partir de la rama.
  • Elementos: cada elemento tiene todas las propiedades de su metaclase en el esquema JSON de OMG, incluidas las derivadas (owner, ownedElement, qualifiedName, feature, type y similares). Los elementos de la biblioteca estándar se referencian por sus ids estándar, los mismos ids que usan otras herramientas SysML v2 para el mismo elemento de biblioteca.
  • Etiquetas y consultas guardadas: ninguna; sus listas están vacías.
Método y rutaQué hace
GET /sysml/projectsSus proyectos SysML v2
POST /sysml/projectsCrear un proyecto SysML v2 vacío (name, description)
GET /sysml/projects/<projectId>Un proyecto, con su rama predeterminada
GET /sysml/projects/<projectId>/branchesmain y las ramas de solicitudes de cambio
POST /sysml/projects/<projectId>/branchesCrear una rama: una nueva solicitud de cambio en borrador (name es su título, description su motivo)
GET /sysml/projects/<projectId>/branches/<branchId>La rama (su @id o main), con head
DELETE /sysml/projects/<projectId>/branches/<branchId>Retirar la solicitud de cambio
GET /sysml/projects/<projectId>/commitsLos heads y las confirmaciones enviadas a las ramas, de la más reciente a la más antigua
POST /sysml/projects/<projectId>/commits?branchId=<branchId>Confirmar cambios en una rama (véase más abajo)
GET /sysml/projects/<projectId>/commits/<commitId>Una confirmación head
GET /sysml/projects/<projectId>/commits/<commitId>/changesLo que la rama cambia frente al modelo activo: un DataVersion por elemento
GET /sysml/projects/<projectId>/commits/<commitId>/elementsTodos los elementos de la confirmación, paginados
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>Un elemento
GET /sysml/projects/<projectId>/commits/<commitId>/rootsLos elementos de nivel superior, paginados
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>/relationshipsLas relaciones que tienen el elemento como origen o destino; direction es in, out o both (predeterminado), paginadas
POST /sysml/projects/<projectId>/query-resultsLos elementos que coinciden con una consulta (cuerpo más abajo), paginados; commitId debe ser un head
GET /sysml/projects/<projectId>/tags, /queries, /commits/<commitId>/elements/<elementId>/projectUsagesListas vacías

Las respuestas de lista son arrays JSON. Las listas se paginan con page[size] (100 de forma predeterminada, 1000 como máximo) y page[after] (el @id del último elemento de la página anterior) o page[before] (el @id del primer elemento de la página siguiente). La cabecera Link da la página siguiente con rel="next" y la anterior con rel="prev".

Una consulta es un objeto JSON con un where opcional (un PrimitiveConstraint con property, operator (=, in, <, <=, >, >= o instanceOf), value e inverse, o un CompositeConstraint con operator and u or y constraint), scope (ids de elementos: la búsqueda los abarca a ellos y lo que poseen) y select (las propiedades que se devuelven; @id y @type siempre se devuelven):

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

Leer los elementos de un 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"

Confirmar cambios

Escribir requiere un token con acceso de lectura y escritura, el rol de editor o propietario, el plan Team (también para cuentas académicas y de clase) y la revisión de ramas activada en el proyecto (Solicitudes de cambio → Ajustes). Un aprobador revisa y aplica la solicitud de cambio en Holarch; los tokens nunca votan ni aplican.

  1. Cree una rama: POST /branches con {"@type": "Branch", "name": "Cabin heater"}. La respuesta es la rama con su holarchChangeRequest.
  2. Lea el head de la rama y sus elementos.
  3. POST /commits?branchId=<branch @id> con una lista de DataVersion:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  "https://app.holarch.app/api/v1/sysml/projects/<projectId>/commits?branchId=<branch id>" \
  -d '{"@type": "Commit", "description": "Add the heater",
       "previousCommit": {"@id": "<head id>"},
       "change": [{"@type": "DataVersion", "identity": {"@id": "<new uuid>"},
                   "payload": {"@type": "PartDefinition", "declaredName": "CabinHeater", "owner": {"@id": "<package id>"}}}]}'
  • Cambiar un elemento: envíe el elemento tal como lo leyó, con las propiedades cambiadas. Solo cuentan las propiedades propias (declaredName, ownedRelationship, isAbstract y similares); las derivadas se ignoran, de modo que devolver lo que leyó no cambia nada. Una propiedad que omita conserva su valor; envíe null o [] para vaciarla.
  • Elementos nuevos: dé al elemento un UUID nuevo y su membresía propietaria (enviada en la misma confirmación) o owner, que crea la membresía por usted.
  • Quitar un elemento: payload: null lo quita con todo lo que posee.
  • Comprobaciones: cada paquete que toca la confirmación debe imprimirse y analizarse de nuevo, y la confirmación no debe añadir diagnósticos de error; de lo contrario, 422 con los diagnostics que hay que corregir.
  • previousCommit: el head sobre el que se hizo su cambio. Si la rama ha avanzado desde entonces, la respuesta es 409 stale-head con el head actual; lea de nuevo y confirme sobre él.
  • Reintentos: envíe una cabecera Idempotency-Key. Un reintento con la misma clave y el mismo cuerpo en un plazo de 24 horas recibe de nuevo la primera respuesta.
  • Confirmaciones en main: una confirmación sin branchId, o con main, va a la solicitud de cambio en borrador propia de su token («API changes from <token name>»), creada con la primera confirmación de este tipo. La respuesta indica cuál en holarchChangeRequest y en una cabecera Warning.
  • Proyectos nuevos: un proyecto creado con POST /sysml/projects tiene la revisión de ramas activada. Su primera confirmación en main, mientras usted sea su único miembro, se escribe directamente en el modelo, una vez; las confirmaciones posteriores pasan por solicitudes de cambio.

Envíe la solicitud de cambio a revisión con POST /api/v1/projects/<project>/change-requests/<CR-12>/submit (API y MCP). Las etiquetas, las fusiones y el cambio de nombre o la eliminación de un proyecto responden 405 con lo que hay que hacer en su lugar. Los errores llevan @type Error y una description, tal como los define la API de OMG.

Mensajes

Se aplican los códigos de API y MCP. Las rutas y herramientas SysML v2 añaden:

CódigoEstadoSignificado
wrong-project-type409Una operación LML en un proyecto SysML v2, o una operación SysML v2 en un proyecto LML
syntax422El texto propuesto tiene errores de sintaxis; los diagnósticos dan la línea y la columna
invalid-model422El cambio añade diagnósticos de error al modelo; se enumeran
not-printable422El cambio no se puede escribir como texto SysML
invalid422No se pudo aplicar el cambio al modelo
no-change400El texto no cambia el modelo
too-large413El texto supera los 1,000,000 caracteres, o la propuesta supera los 8 MB
too-many413 o 409Más de 100 ediciones en una llamada (413), o la propuesta ya contiene 200 cambios (409)
stale409Un cambio de texto anterior de la propuesta ya no se aplica al modelo
not-found404No existe ese proyecto, elemento, rama o confirmación (la Systems Modeling API solo sirve los heads de las ramas)
not-writable405Etiquetas, fusiones, cambio de nombre o eliminación de un proyecto mediante la Systems Modeling API; hágalo en Holarch
main-protected405Eliminar main; elimine en su lugar una rama de solicitud de cambio
stale-head409La rama ha avanzado desde previousCommit; lea su head y confirme de nuevo
branch-base409Una rama nueva debe partir del head de main
branch-review-off409El proyecto no usa la revisión de ramas; un propietario la activa en Solicitudes de cambio → Ajustes
cr-not-draft409La solicitud de cambio está enviada o cerrada; solo se puede escribir mientras está en Borrador o Rechazada
cr-full409La solicitud de cambio contiene 5,000 elementos cambiados, o el proyecto 20 MB de borradores de solicitudes de cambio
plan-limit403Las escrituras en solicitudes de cambio requieren el plan Team
orphan422Un elemento nuevo no tiene propietario; envíe su membresía propietaria u owner
unknown-metaclass422El @type de un payload no es una metaclase de SysML v2
idempotency-key-reused422La Idempotency-Key se usó con otro cuerpo; envíe una clave nueva
token-projects403Un token limitado a una lista de proyectos no puede crear un proyecto
bad-request400Un valor que falta o es incorrecto, como un root que no es un paquete de nivel superior, una op desconocida o un elemento nuevo sin nombre

Límites

QuéLímite
Elementos, requisitos o conexiones por página500
Miembros enumerados con un elemento200
Diagnósticos por respuesta500
Líneas de texto SysML por respuesta5,000, y como máximo 400,000 bytes (cortado en una línea)
Texto de documentación4,000 caracteres en listas, 20,000 para un elemento
El texto SysML propio de un elemento16,000 caracteres
Texto en una llamada a propose_sysml1,000,000 caracteres
Ediciones en una llamada100
Elementos enumerados como añadidos, cambiados o quitados en un cambio300 de cada uno
Cambios en una propuesta200, y 8 MB
Página de la Systems Modeling API1,000 elementos (100 de forma predeterminada)
DataVersions en una confirmación5,000
Elementos cambiados en una solicitud de cambio5,000
Cuerpo de la confirmación32 MB

Los límites de frecuencia, el tamaño de las solicitudes y las reglas de los tokens son los de API y MCP.

SysML® y OMG® son marcas registradas de Object Management Group, Inc. en los Estados Unidos y otros países.