Install from Marketplace
Open SysML v2 on the Visual Studio Marketplace and choose Install.
1 Install
Install from the Marketplace or use a standalone VSIX. There is nothing else to install—no Java, PlantUML, diagram server, or cloud account.
Or install a VSIX
If you have a standalone package, run Extensions: Install from VSIX… from the Command Palette (Ctrl/Cmd+Shift+P).
Open a model folder
Open a folder containing .sysml, .kerml, or .kpar files.
Wait for ready
Open a .sysml file and wait until the status bar shows SysML: ready. The bundled library is pre-indexed, so this is fast.
✓
↑ Back to top
The extension runs entirely on your machine. Source text, diagram side-cars, and project config stay in your repository.
2 Open the sample workspace
Clone the public sample repository, then open the folder in VS Code:
▸
git clone https://github.com/voidaliot/sysml-v2-samples.gitcode sysml-v2-samples
Start with e-mountainbike.sysml for the broadest tour, or sdv.sysml for a larger vehicle architecture. Smaller drone, flashlight, vehicle, cruise-ship, and robocopter models let you learn one concept at a time.
Explore the text
Use hover, completion, outline, go-to-definition, references, and Problems while the status bar shows SysML: ready.
Ask which view fits
Run SysML: Which Diagram? and choose the engineering question you want to answer.
Round-trip an edit
Move a node or waypoint, then rename or add an element and inspect the resulting source and .vscode/sysml/diagrams/ layout sidecar.
3 Core editor workflow
Treat SysML and KerML files like code. Everything below is server-backed and works across your workspace and the read-only bundled standard library.
- Syntax highlighting works instantly for
.sysmland.kerml. - Completion offers keywords, snippets, visible symbols, library names, members, and units.
- Hover shows element kind, typing, multiplicity, documentation, and links to the library source.
- Diagnostics appear in Problems with stable codes such as
RES001,SEM006,UNIT003, andMIG001. - Quick fixes handle mechanical rewrites: missing imports, boolean-operator migration, missing requirement subjects, unit suggestions, and SysML v1 idiom migration.
- Formatting is AST-based and follows your VS Code indentation settings.
- Navigation: go to definition, find references, rename, document symbols, workspace symbols, document highlight, signature help, and inlay hints.
Useful commands
| Command | Purpose |
|---|---|
SysML: Show Diagram | Open the live diagram preview for the active model or element. |
SysML: Which Diagram? (view guidance) | Pick the question you want answered and open the recommended view. |
SysML: Toggle Diagram Side / Tab Mode | Switch between the side panel and a full tab (Ctrl+Alt+D). |
SysML: Show Diagnostic Reference | Open the diagnostic-code catalogue. |
SysML: Open Standard Library Folder | Browse the bundled OMG standard-library source. |
SysML: Open .kpar Archive | Open an OMG package archive as read-only extracted model files. |
SysML: Export Abstract Syntax JSON | Export the active textual model to OMG abstract-syntax JSON. |
4 Diagram views
Run SysML: Show Diagram on sdv.sysml. The extension detects which views have content and offers the relevant options. Diagrams render locally on a React Flow canvas.
| View | Shows |
|---|---|
| General | Definitions, packages, usage links, specialization, imports, requirements, metadata, variation, compartments, and quick category filters. |
| Interconnection | Nested parts, ports, connectors, bindings, interfaces, item flows, endpoint docking, and reconnectable connectors. |
| Action Flow | Actions, control nodes, send/accept nodes, item flows, final/terminate nodes, and performers. |
| State Transition | States, composite and parallel state frames, transitions, guards, effects, exhibit and causation links. |
| Sequence | Lifelines, activation bars, messages, payload labels, replies, and event occurrences. |
| Case | Use, analysis, and verification cases with actors, subjects, includes, specialization, and optional boundary-box presentation. |
| Geometry | 2D plan or isometric 3D shape layout from model-declared positions and dimensions. |
| Grid | Editable requirements table with documentation, subject, per-attribute columns, constraints, satisfy/verify links, status, and CSV export. |
| Browser | Package and membership tree panel with expand/collapse and diagram-element highlighting. |
✓
Diagram colors follow the active VS Code theme. Layout state is stored under .vscode/sysml/diagrams/ in the repository, never inside the .sysml source.
5 Edit diagrams safely
The diagram preview is not just a picture — it sends guarded workspace edits through the language server.
Common actions:
- Drag and resize nodes.
- Rename elements with F2 or the toolbar action.
- Add view-specific elements from the toolbar tools.
- Draw relationships with two clicks: connect, transition, succession, message, include, satisfy, and other view-specific links.
- Select connectors, delete them, reconnect endpoints, or adjust waypoints.
- Export graph views as SVG.
- Export Grid View as CSV.
!
↑ Back to top
The text model stays authoritative. If an edit would produce invalid SysML, the server rejects it instead of corrupting the file.
6 Standard library
The complete OMG SysML v2 release standard library is bundled and pre-indexed:
- Systems Library — Parts, Ports, Items, Actions, States, Requirements, Constraints, Cases, Views, SysML.
- Kernel Libraries — data types, functions, and semantic kernel packages.
- Domain Libraries — Quantities and Units, Geometry, Analysis, Metadata, Cause and Effect, Requirement Derivation.
sysml.standardLibraryPath can point at an external sysml.library/ source tree, a .kpar archive, or a directory of .kpar archives. Leave it empty to use the bundled library.
7 Recommended settings
Open VS Code settings and search for sysml.
| Setting | Default | Purpose |
|---|---|---|
sysml.editor.autoImportOnSave | true | Add missing cross-package imports on save. |
sysml.diagnostics.units | true | Enable quantity and unit diagnostics. |
sysml.inlayHints.dimension | false | Show physical-dimension hints. |
sysml.preview.diagrams.defaultKind | gv | Preferred primary diagram view. |
sysml.preview.diagrams.defaultMode | side | Open diagrams in side-panel or tab mode. |
sysml.preview.diagrams.update | on-save | Choose live, on-save, or manual diagram refresh. |
sysml.preview.diagrams.lineStyle | orthogonal | Default connector routing style. |
sysml.preview.diagrams.syncUsageToDef | true | Let Interconnection structural edits synchronize to typed definitions. |
sysml.validation.severities | {} | Override individual diagnostic severities. |
✓
↑ Back to top
Project teams can check in .vscode/sysml/project.json to set diagram defaults consistently across a repository.
8 Troubleshooting
| Symptom | Fix |
|---|---|
Language identifier is not SysML. | Confirm the file extension is .sysml and select the language manually from the VS Code status bar. |
| Diagnostics look stale. | Run SysML: Restart Language Server. |
| A diagram view is missing. | The active model or selected anchor probably has no content for that view. Run SysML: Which Diagram? (view guidance) to choose the right view for your question. |
| A standard-library symbol does not resolve. | Leave sysml.standardLibraryPath empty to use the bundled pre-indexed library, or verify that your external path points at a valid source tree or .kpar archive. |
9 Links
- Feature tour
- Visual Studio Marketplace
- Public sample models
- Report an issue
- Bundled library attribution: see the extension package
resources/sysml.library/licenses.