Guide · SysML v2
Moving a SysML v1 model to SysML v2: a step-by-step migration
A SysML v1 model can be converted to SysML v2 automatically, but a migration is more than a file conversion: someone has to decide what the converted model should look like and check that it still says what the v1 model said. This guide walks through a migration in eight steps, from taking stock of the v1 model to switching over, with a small model converted and read line by line.
On this page
- Before you start: a translation, not an upgrade
- 1. Take stock of the v1 model
- 2. Export the model from the SysML v1 tool
- 3. Convert a pilot package
- 4. Read the conversion report
- A worked example: a small rover model
- 5. Rework what was approximated or left out
- 6. Rebuild the views that matter
- 7. Check and review the v2 model
- 8. Convert the rest and switch over
- Migration checklist
- Where to go next
Before you start: a translation, not an upgrade
SysML v2 is a new language, not a new version of the SysML v1 file format. Blocks become part definitions, ports are typed by port definitions, requirements carry conditions, and diagrams become views that the model defines. SysML v1 vs v2 explains the differences one by one.
A converter does the mechanical part: every element that has a SysML v2 counterpart is written in SysML v2, and the rest is reported. What a converter cannot do is decide how your team wants to use the new language. Plan the migration as a modeling task with an owner, a review and a point where the v2 model becomes the reference.
This guide uses Holarch's converter, which imports a SysML 1.x model into a SysML v2 project and reports every element as converted, approximated or left out. The planning steps apply whichever converter you use.
1. Take stock of the v1 model
Before you export anything, find out what the model holds and who depends on it. A short inventory saves rework later.
- Packages and owners. List the top-level packages, who maintains each, and which ones other models or documents refer to. Packages are the unit you will convert and review.
- Diagrams that matter. Note the diagrams people actually use in reviews and documents. Diagram layouts do not carry over to SysML v2, so these become views you rebuild.
- Profiles and stereotypes. List your own stereotypes and their tagged values. They become metadata definitions, and their meaning in the new model has to be agreed again.
- Behavior written as code. Opaque behaviors, guards and constraints in OCL, an action language or a tool's scripting are kept as text in their original language; they are not translated.
- Unnamed elements. Relationships that point to elements without a name cannot be written in SysML v2 text, which refers to elements by name. Name the elements you trace to now, in the v1 tool.
- Size. Holarch converts one file of up to 64 MB and 250,000 elements at a time. Larger models are exported one package at a time.
2. Export the model from the SysML v1 tool
The converter reads the model from XMI, the exchange format SysML v1 tools write. Each tool exports it a little differently:
| Tool | What to import |
|---|---|
| Cameo Systems Modeler, MagicDraw | The .mdzip project file, or File → Export To → Eclipse UML2 (v5.x) XMI File and the .xmi file |
| Enterprise Architect | Select the package, Publish → Export XML, choose XMI 2.1, and import the .xml file. Project files (.eap, .qea) are not read directly. |
| IBM Rhapsody | An XMI 2.x export from the XMI toolkit |
| Eclipse Papyrus | The model's .uml file |
Keep the exported file with the migration records: it is the exact v1 input your review refers to.
3. Convert a pilot package
Start with one package that is representative but not the largest: a subsystem with structure, interfaces, some behavior and its requirements. The pilot shows what your model's conversion looks like before you commit the whole team to it.
- Create a SysML v2 project, or open the one the converted model should go into, and click Model → Import and Export.
- Under Import, choose Into a new SysML v2 project for a pilot, so nothing else is touched.
- Drop the exported file on the box. A progress card shows the stages: reading the XMI file, converting to SysML v2, checking the result.
Nothing is imported yet. The next screen is the preview with the conversion report.
4. Read the conversion report
Conversion from SysML v1 at the top of the preview gives the number of elements converted, approximated and left out, and whether the SysML v2 text checks without problems. Every element of the v1 model has one result:
- Converted: the element has a direct SysML v2 counterpart, such as a block that becomes a
part def. - Approximated: the element is kept in a changed form, for example a transition through a choice that becomes one transition per path. These are the places where the meaning may differ from the v1 model.
- Left out: SysML v2 has no counterpart, or the element points to something that is not in the file.
Use Show to list the approximated and left-out elements. Each row gives the element, its SysML v1 kind, what it became with its SysML v2 name, and why. Open Show the SysML v2 text to read the result, and click Download Report to keep the report as a CSV file. The CSV is the worklist for step 5: sort it by reason and give each group an owner.
A worked example: a small rover model
A small SysML v1 model of a planetary rover's power path, in three packages:
| Package | SysML v1 elements |
|---|---|
| Types | A value type Power with the unit W; a block Charge; an interface block Power Interface with two outgoing flow properties, charge (a Charge) and voltage (a Real) |
| Structure | An encapsulated block Rover with part properties battery and computer, a value property power budget of 120 W, a connector power bus between their ports and an item flow power flow of Charge on it. A block Battery with a proxy port out; a block Computer with a conjugated proxy port in and a full port raw. Both carry a user stereotype «Hardware» with tagged values. An association whose end is owned by the association. |
| Requirements | Requirements R-1 Mission and R-2 Power Margin; R-2 derived from R-1; R-2 satisfied by the battery part; a trace from Computer to Battery |
Converted, it reads like this. The listing is the converter's output, unchanged:
package 'Rover Model' {
package Types {
attribute def Power :> ISQ::PowerValue;
part def Charge;
port def 'Power Interface' {
out item charge : Charge;
out attribute voltage : ScalarValues::Real;
}
}
package Structure {
part def Rover {
doc /* Six-wheeled science rover. */
@SysMLv1Library::BlockData { isEncapsulated = true; }
part battery : Battery;
part computer : Computer;
attribute 'power budget' : Types::Power = 120 [SI::W];
connection 'power bus' connect battery.'out' to computer.'in';
satisfy Requirements::'Power Margin' by battery;
flow 'power flow' of Types::Charge from battery.'out' to computer.'in';
}
part def Battery {
@'SysML v1 Profiles'::rov::Hardware { qualified = "true"; vendor = "Acme Cells"; }
port 'out' : Types::'Power Interface';
attribute capacity : Types::Power;
}
part def Computer {
@'SysML v1 Profiles'::rov::Hardware { vendor = "Orbital Logic"; }
port 'in' : ~Types::'Power Interface';
part raw : Types::Charge {
@SysMLv1Library::PortData { isFullPort = true; }
}
}
}
package Requirements {
requirement <'R-1'> Mission {
doc /* The rover shall explore the landing site. */
}
requirement <'R-2'> 'Power Margin' {
doc /* Keep a 50 % power margin. */
}
connection : DerivationConnections::Derivation connect 'Power Margin' to Mission;
dependency from Structure::Computer to Structure::Battery {
@SysMLv1Library::TraceData { isTrace = true; }
}
}
}
package 'SysML v1 Profiles' {
package rov {
metadata def Hardware {
attribute qualified : ScalarValues::String;
attribute vendor : ScalarValues::String;
}
}
}
What happened to each part of the v1 model:
- Value type with a unit. Power in watts specializes the standard library's
ISQ::PowerValue, and the default value is written with its unit:120 [SI::W]. A value type whose unit is not a mapped SI unit stays a real number, with the unit in its documentation, and is reported as approximated. - Blocks and properties. Blocks become
part defs and part properties becomeparts. The block's isEncapsulated has no SysML v2 keyword, so it is kept asSysMLv1Library::BlockDatametadata. - Interface block and ports. The interface block becomes a
port defwhose flow properties are directed features:out itemfor the block-typed one,out attributefor the value. The conjugated proxy port is typed~Types::'Power Interface'. The full port becomes a part withSysMLv1Library::PortDatametadata, because a SysML v2 port is typed by a port definition. - Connector and item flow. The connector becomes a
connectionbetween the two ports, and the item flow on it aflowof Charge between the same ports. - Requirements. Each requirement keeps its id as a short name,
<'R-1'>, and its text asdoc. The satisfy relationship sits in the block that owns the satisfying part; the derive relationship becomes a derivation connection; the trace becomes a dependency withSysMLv1Library::TraceData. - The user stereotype. «Hardware» becomes a
metadata defin a package'SysML v1 Profiles', applied to each block with its tagged values. Its two applications are reported as approximated: tag values became text attributes, whatever their type was in the profile. - The association. An association without a class has no SysML v2 counterpart here, and its end owned by the association is not converted either. Both are reported as left out; the properties on the blocks carry the structure.
The report for this model: 31 elements, 27 converted, 2 approximated, 2 left out, and the text checks with no errors and no warnings. Names that are not plain identifiers, such as 'power budget' or 'out' (a SysML v2 keyword), are quoted so they keep their v1 spelling.
5. Rework what was approximated or left out
Go through the report's approximated and left-out rows by reason. Most reasons call for one of a few decisions:
| What the report says | What to decide |
|---|---|
| A port is typed by a block that is not an interface block; it became a port without a type | Define a port definition with the features that cross the boundary, and type the port with it. |
| Transitions through a choice, junction, fork or join; each path became one transition | Check that the joined guards still say what the v1 diagram meant; simplify where the paths are now easier to read. |
| A trigger is kept as documentation | Rewrite change and time triggers as SysML v2 triggers where the meaning is clear, such as accept after a duration. |
| A unit is not an SI unit Holarch maps; the value type is a real number | Decide whether a standard quantity fits, or keep the real number and the documented unit. |
| An action kind other than a call, opaque or accept action became a plain action | Rewrite sends and other specific actions with the SysML v2 action that does the same. |
| Activity partitions are not converted | Say which part does what with perform in the part, instead of a swimlane. |
| It points to an element without a name | Name the target in the v1 tool and convert again, or add the relationship in the v2 model. |
| Its name is used twice in the same place; renamed with a suffix | Give each element a name that says what it is. |
| Tagged values became text attributes of the metadata | Give the metadata attributes the types they need, and agree what each stereotype means now. |
Two kinds of text need a look even when they converted cleanly. Opaque bodies are kept as textual representations in their original language, such as language "OCL" /* … */; Holarch checks only bodies written in SysML or KerML, so rewrite a guard or constraint as a SysML expression where the model should evaluate it. And literal translations keep v1 workarounds, such as property-specific types made only to set a value: in SysML v2 these are plain redefinitions on usages. What needs rethinking lists the common ones.
6. Rebuild the views that matter
Diagrams and their layout are not converted. Take the list of diagrams from step 1 and create a view for each one that is still needed: a general view for structure and requirements, an interconnection view for parts and connections, an action flow view for activities, a state transition view for state machines. Rebuild only what people use; the model holds everything else either way. See the views reference.
7. Check and review the v2 model
- The text checks clean. The import shows the check of the converted text before anything changes; after your rework, the Editor marks any new problems as you type.
- Counts match. Compare a few numbers between the v1 model and the v2 model: requirements, parts, ports, connections, verification relationships. A difference you cannot explain from the report is worth a look.
- The people who use the model review it. Walk through the pilot package with its owners, starting with the approximated elements and the rebuilt views.
- Record the decisions. Write down the modeling patterns you settled on for ports, triggers, units and stereotypes, so the rest of the migration follows them.
8. Convert the rest and switch over
Convert the remaining packages one at a time, into the same SysML v2 project. Each import shows the same preview: a package already in the project shows as Changed or Unchanged, a new one as New, and you choose which packages to import. Each import is one undo step.
Keep the v1 model as the reference until the v2 model has been reviewed, then freeze it and make the SysML v2 project the model of record. From that point, changes go into the v2 model only.
Migration checklist
- Packages, owners and the diagrams that matter are listed.
- Elements that relationships point to have names.
- The exported XMI file is kept with the migration records.
- A pilot package is converted, its report downloaded, and every approximated and left-out row has a decision.
- Modeling patterns for ports, triggers, units and stereotypes are written down.
- Needed views are rebuilt; the text checks clean.
- The model's users have reviewed the pilot.
- The remaining packages are converted the same way, and the v1 model is frozen.
Where to go next
- SysML v1 to SysML v2 in Holarch: what the converter reads and writes, and the CubeSat EO-1 example.
- Importing SysML v1 models: every step, mapping, limit and message in the Docs.
- SysML v1 vs v2: how the two languages differ.
- SysML v2 tutorial: build a model in the textual notation.
- SysML v2 language coverage: what SysML v2 projects support and the known gaps.
Cameo Systems Modeler, MagicDraw, Enterprise Architect, Rhapsody and Eclipse Papyrus are trademarks of their respective owners. Holarch is not affiliated with or endorsed by them.