SysML v2 API and CI/CD Integration

A Practitioner’s View on the SysML v2 API

Speaker: Andrew Sarvanos, SysML v2 Implementation Leader at Dassault Systèmes
Event: Presentation at an OMG (Object Management Group) event, discussing SysML v2 and its implementation.

Overview of Key Themes

Andrew Sarvanos provided a detailed, practical examination of the SysML v2 API, moving beyond its basic functions to highlight areas for improvement and demonstrate powerful extensions. The presentation focused on demystifying the API for a broad audience, explaining its dual-layered structure (PIM and PSM) and current limitations, particularly in querying capabilities. A significant portion of the talk was dedicated to showcasing Dassault Systèmes’ extended API functionalities within their MagicDraw/Cameo platform, including advanced validation, textual, and diagrammatic services. The ultimate theme was the integration of these APIs into a full Continuous Integration/Continuous Deployment (CI/CD) workflow, illustrating how robust APIs can automate model validation, artifact generation, and cross-tool integration in a real-world engineering environment.

Key Points of the Presentation

Understanding the SysML v2 API Structure:
- The specification defines a two-level API:
  - PIM (Platform Independent Model): A high-level, technology-agnostic description of what the API should do (e.g., get elements, create a project).
  - PSM (Platform Specific Model): A concrete implementation for a specific technology. Currently, the spec officially defines a full RESTful API and a partial OSLC implementation.
- Conformance is not a simple “yes or no.” A tool can be conformant at the PIM level, the more specific PSM level (e.g., implementing the exact REST endpoints), or conformant to specific services (e.g., project creation but not model querying).
Limitations of the Standard API:
- Querying: The standard RESTful API query language is described as “pretty primitive.” It primarily allows for filtering elements by basic properties like name and type using simple AND logic. It lacks the power for complex, graph-based queries.
- Digital Thread & External Linking: To link a SysML element to an external artifact (like a requirement in another system), you must make a specific API call to create an “external relationship.” This link is not stored in the SysML model itself but managed via the API.
- Efficiency Concerns: This API-based linking method can be inefficient. For example, to build a traceability matrix for 1,000 elements, you might need to make 1,000 separate API calls to retrieve their external links.
Proposed and Implemented API Extensions:
- To overcome standard limitations, the speaker’s team implemented several custom, yet powerful, API extensions:
  - Evaluation Service: Allows running complex queries written in the standard SysML v2 expression language directly against the model via a single API endpoint. This is far more powerful and intuitive than the standard query service.
  - Textual Service: An endpoint that returns the complete textual (KerML) representation for a given model element (e.g., a namespace), which is crucial for version control (like Git) and text-based analysis tools.
  - Diagrammatic Service: A service that renders a view or view usage as a diagram (in SVG format) and returns it through an API call. This enables embedding live, auto-updating diagrams in external platforms like Confluence.
Practical Application in a CI/CD Pipeline:
- A full CI/CD workflow was demonstrated using the open-source tool Jenkins.
- A commit to the model repository automatically triggers a pipeline that uses the extended APIs to:
  1. Validate the model for errors.
  2. Extract requirement differences.
  3. Push the model’s textual representation to a Git repository.
  4. Extract and push updated diagrams to a Confluence page.
  5. Regenerate and compile source code.
- This demonstrates a fully automated, end-to-end digital engineering ecosystem where the model is the single source of truth and all downstream artifacts are updated automatically.

Key Quotes

“Robert asked me to talk about the system auditor API and how boring that is, right? … So I made a decision maybe I should you know talk about things that Not many people realize about APIs, about the tool.”
“API is at the high level, any kind of API system only should support operation called get elements… and there are two limitations. One is RESTful… And there is a way to do that in OSC.”
“Conformance is not just true or false.”
“What kind of querying you can do using RESTful API? It’s pretty primitive, honestly.”
“You can establish these relationships, But let’s imagine you’ve got the tree stability matrix… it means you would need to call the stressful API one thousand times to retrieve, you know, this connected telegraphs. Is that efficient? I don’t think so, but that’s what we have.”
“These APIs they don’t need to be painful. They need to be simple to use, right?”

Action Points for the Audience

Learn SysML v2 Hands-On: Take advantage of the newly launched, free MagicDraw/Cameo SysML v2 Community Edition to learn and experiment with the language and its 100% compliant standard implementation.
Look Beyond Basic API Conformance: When evaluating tools, understand that “API support” is nuanced. Ask vendors specifically about which services they support, the power of their query capabilities, and whether they offer extensions for practical needs like textual and diagrammatic retrieval.
Advocate for Better Standards: Recognize the current limitations of the standard API. Consider contributing feedback to the OMG working groups to help standardize more powerful and efficient services, such as advanced querying and textual representation endpoints.
Embrace Automation with APIs: Think of the SysML model repository not as a silo, but as the central hub of a digital engineering ecosystem. Explore using APIs to build automated CI/CD pipelines (using tools like Jenkins) to validate models, manage versions in Git, and publish documentation to platforms like Confluence, thereby increasing efficiency a