SysML v2 for Visual Studio Code

Edit SysML v2 and KerML models in Visual Studio Code, then inspect and change them through live diagrams. The extension includes language support, editable graphical views, and the OMG standard library. It works locally without Java, PlantUML, or a separate library download.

This project is under active development. If you find a model that does not parse or draw correctly, please report it with a small example.

Getting started

1. Install the extension and wait for the status bar to show SysML: ready.
2. Run SysML: New Model…, or open a .sysml or .kerml file.
3. Use completion (Ctrl+Space) or type a snippet prefix such as sysml-part-def.
4. Open the diagram editor (3 options)
   • Right click on a file and select Show SysML Diagrams
   • Open a SysML file and click on the Show diagram inline hint above supported elements.
   • Run SysML: Show Diagram from the command palette or editor title bar.
5. Right-click the diagram or Browser View to add elements. Diagram edits are written back to the model text.

Use Ctrl+Alt+D to move the diagram between a side panel and a full editor tab.

Use the diagram toolbar Save button (after Redo) or File > Save All to save source and diagram JSON together, or enable File > Auto Save. Diagram edits update the JSON buffer live. Undo and Redo stay in the diagram and share the source history. Saving does not clear undo history.

Editing models

The language service provides:

• syntax highlighting for SysML v2 and KerML;
• type-aware completion for definition slots, feature chains, collection calls, and units, plus snippets, signature help, and inline suggestions;
• hover information for types, multiplicities, relationships, documentation, and library symbols;
• diagnostics for syntax, name resolution, semantics, style, units, type and relationship conformance, and common SysML v1 constructs;
• quick fixes, formatting, find references, cross-file rename, and go-to-definition;
• document and workspace symbols;
• optional auto-import on save;
• CodeLens actions for diagrams, references, and verification cases.

The bundled standard library resolves packages such as Parts, Ports, ISQ, SI, Requirements, and States. Library definitions open as read-only source when you navigate to them.

Diagrams

Diagrams use SysML v2 graphical notation and are generated directly from the model. They do not require PlantUML or an image server.

Modeled comment annotations follow their graph element or port in every graphical view, including inherited members from workspace and library files. Comments are read-only in the diagram. On a writable graph element or port, use Properties or Add note or Edit note in the context menu to add, edit, or clear its modeled doc text. Relationship edges are not note targets.

You can build a model from an empty package. Right-click a blank surface or an existing element to see the additions valid for that location. Drag between compatible elements to create the view's usual relationship, or choose a different relationship from the source element's menu.

Action Flow keeps ownership and performance visually distinct: solid action/owning-part boundaries contain owner-local dashed, port-free «performer» lanes, with one combined lane for an exact performer set. Start/done stay outside the lanes. Action pins connect to pins; structural ports are used only by explicit send/accept endpoints. An action before if/while/loop/for is a solid, always-open «action» frame with compartments and pins; an inline control is dashed, has no title separator, remains draggable, and starts with an editable one-line «keyword» clause. Right-click creation inside actions/action definitions starts from valid selected defaults; selected controls can add a missing else/while/until clause or promote an anonymous control with an action name. Named diagram edges write succession current then next;; their control-transition routes are dotted, while item flows remain continuous. Targeting an anonymous control moves its block below the source action as lexical then. Targeted terminate actions retain their target, and succession flow has a separate sequencing mark.

State Transition draws an exhibiting part as a boundary around the exact state it exhibits, not as a detached box and «exhibit» edge. On a package canvas, create state def or state; parts appear there only through their exhibit claims.

Action Flow and State Transition automatic layout follows the chosen Top to Bottom or Left to Right direction. Control successions and transitions form clear ranks with open routing space. Data, definition, causation, exhibit, and other context links remain overlays and do not pull the main flow out of shape.

Action Flow has a remembered control for owned action definitions. Hiding them preserves their placement, routes, labels and snap points. Showing them again does not run automatic layout.

Interconnection View has separate remembered controls for owned part definitions, explicit connections and explicit interfaces. A visible definition is directly editable. Explicit relationships are low-profile blocks with one named end dot and snap point per end. Interface dots bind only to structural ports. Compact notation turns fully bound binary usages into labelled direct lines and n-ary usages into labelled circular bus hubs. Anonymous hubs match the size and outline colour of explicit connection end dots. Local unbound and partially bound usages keep their blocks and editable dots. An inherited connection appears only when a binding semantically identifies the same visible part or port occurrence. State Transition keeps a remembered state-definition control. IV, AFV and STV omit «defined by» lines entirely, with no optional filter. Types remain on elements and in Properties.

Documentation owned by an explicit connection or interface stays inside that relationship's doc compartment. A documented or annotated relationship keeps its block when compact notation is selected.

IV, AFV and STV local internals/compartment controls overlay the title while hovered or selected. GV disclosure controls follow the same rule and also appear on keyboard focus. Labels preserve model case and expose full text on hover when shortened. Ordinary GV cards size to their names within the automatic width budget; manual widths remain authoritative. Open packages and containers fit their child canvas with clear title padding. Attribute value textboxes and framed Properties fields make editing visible.

General View has two independent modes. Both begin with the selected root's immediate children closed. Closed packages list their direct members in both modes, including nested packages. Compartments lists hidden members on other closed cards. Hover over or select any element or package to show the upper-right + to reveal its explicit children as nodes. The open parent shows its title and a child canvas. Attributes, actions, items, documentation and metadata remain available even without relations. Relations start hidden and can be enabled. Tree uses the same control visibility. Packages reveal their immediate members, including nested packages and definitions. Other elements reveal only part usages. Tree keeps complete families together. Select a closed Tree usage line to edit each usage's Name and Multiplicity in framed fields. Attributes expose an editable Value textbox on the node and in Properties. Both modes offer Straight, Curved and Orthogonal. Reset Connector Routing applies the selected style while preserving node placement.

The Browser View is also an authoring surface: right-click a writable container to add children, or choose Show diagrams on a compatible element to open its focused views.

Diagram editing includes:

• add, rename, delete, move, and resize;
• create, delete, reconnect, and route relationships;
• nested package, part, action, state, and subject containers;
• editable Properties for common model fields;
• ranked automatic layout with per-view direction and connector-style controls;
• separate Select and Hand navigation tools, temporary Space panning, wheel scroll or zoom behavior, and canvas scrollbars;
• SVG export, or CSV export for Grid View;
• light, dark, and high-contrast theme support, including the bundled gray-background SysML v2 Gray theme.

Semantic edits pass through the language server's syntax guard and normal source Undo. The JSON side-car under .vscode/sysml/diagrams/ stores placement, open/closed sizes, port positions, manual and automatic connector geometry, zoom and grid. Compartments and Tree keep separate expansion and presentation settings. Hidden children keep their relative geometry, and surviving rectangles restore without global layout. Opening a Compartments container makes room through minimal local shifts of colliding neighbours and necessary parent growth. Older expansion choices migrate to element keys; incompatible automatic GV routes are refreshed without discarding compatible placement or manual waypoints. A completed drag saves one geometry operation. Pan and scroll remain transient. The JSON is a normal text document, so Undo, Redo, Save All and Auto Save apply to it, and a diagram gesture shares one history with the source editor. The headless CLI uses the same saved arrangement and mode projections.

If you are unsure which view to open, run SysML: Which Diagram?. It accepts questions and familiar SysML v1 names such as BDD, IBD, activity, state machine, sequence, requirements, use case, and parametric diagram.

Validation and diagram export in CI

The extension includes two command-line tools for desktop and CI use:

npx sysml-validate models/ --strict
npx sysml-validate models/ --format github

npx sysml-diagram export --file model.sysml --view iv --out docs/iv.svg
npx sysml-diagram export --file model.sysml --all --out-dir docs/diagrams

sysml-validate can emit text, JSON, SARIF, or GitHub workflow annotations. sysml-diagram reads project settings and committed diagram layouts; use --auto-layout when you want a fresh layout.

Run SysML: Copy Headless CLI Command to copy a command for the current model.

VS Code for the Web

The language service and editable diagrams work on vscode.dev, github.dev, and other browser-hosted VS Code environments. The bundled standard library works there as well.

The following features are desktop-only because they require local filesystem or Node.js access:

• opening and extracting .kpar archives;
• importing and exporting abstract-syntax JSON;
• revealing the standard-library folder in the operating system;
• the sysml-diagram and sysml-validate command-line tools.

Agent tools

The extension contributes VS Code language-model tools for agents that support that API. They provide model context, draft validation, standard-library search, symbol resolution, requirement traces, diagnostic explanations, and modeling guidance. Results come from the language server rather than from a separate chatbot.

The extension does not include an AI model, credentials, an MCP server, or vendor-specific agent packages.

Common settings

Open Settings → Extensions → SysML v2 for the full list.

Project-specific diagram overrides can be committed in .vscode/sysml/project.json.

Useful commands

• SysML: New Model…
• SysML: Show Diagram
• SysML: Which Diagram?
• SysML: Show Diagnostic Reference
• SysML: Show Syntax Tree
• SysML: Reload Standard Library
• SysML: Report Parse Coverage
• SysML: Open / Extract .kpar Archive (desktop)
• SysML: Open / Export Abstract Syntax JSON (desktop)

Privacy

The extension collects no telemetry and includes no analytics or usage reporting. Model files and diagram data stay in the local or browser workspace unless you choose to share them through another service.

Licenses and attribution

The extension is distributed under the repository's Freeware License.

The bundled sysml.library/ files come from the OMG SysML v2 Release, release tag 2026-04, and retain the Eclipse Public License v2.0 and notices shipped in resources/sysml.library/.

Full third-party license texts are included with the packaged dependencies.

Feedback

Report bugs and request features at github.com/voidaliot/sysml-v2-vscext-release/issues. A small model and the view name usually make diagram issues much easier to reproduce.