SysML v1 vs v2: how the two languages differ

At a glance

Readers who know SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v1 will recognize most concepts in SysML v2. What changed is how they are built and how precisely they are defined. The table sums up the comparison; each row has its own section below.

Foundation: a UML profile against KerML

SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v1 is defined as a profile of UMLUnified Modeling Language A standard graphical language for modeling software and systems. SysML is built on it. 2. It takes a subset of UML and adds stereotypes: a block is a UML class with the «block» stereotype, a requirement is a class with «requirement», a flow property is a property with «flowProperty». This made SysML v1 quick to adopt, because UML tools could host it, but it also meant that systems concepts were bent to fit software concepts, and that the meaning of many constructs came from UML's semantics, which were written for software.

SysML v2 drops the UML base. It is built on the Kernel Modeling Language (KerML), a smaller language whose core is given precise meaning in a library of KerML models. SysML v2 adds the systems engineering concepts on top: parts, ports, actions, states, requirements, cases and views. Every SysML v2 construct is defined as a specialization of something in that library. In practice this means:

• Structure and behavior share one foundation. Parts and actions are both occurrences that exist over time, so a part can perform an action or exhibit a state without a separate allocation layer.
• Tools agree more closely on what a model means, because the meaning is in the specification and its libraries rather than in each tool's interpretation.
• Stereotypes are no longer the extension mechanism. SysML v2 uses metadata definitions for tool-specific or domain-specific annotations.

Definitions and usages instead of blocks and properties

In SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v1 the block is the central element: a block definition diagram defines blocks, and an internal block diagram shows the parts of one block. A part property is typed by a block; a value property is typed by a value type. Giving one part a value different from its block's default, for example a heavier pump in one product variant, needs a workaround: a specialized block that redefines the property, a property-specific type, or an instance specification.

SysML v2 generalizes this into one pattern for every element: a definition says what a kind of thing is, a usage is such a thing in a context. Usages nest, and a nested usage can redefine what it inherits with its own value. The same pattern holds for attributes, ports, actions, states, requirements and views.

package CoolingLoop {
  doc /* The engine cooling loop of a small generator set. */

  private import ScalarValues::*;
  private import ISQ::*;
  private import SI::*;

  part def Pump {
    attribute mass : MassValue;
    attribute shaftPower : PowerValue;
  }

  part def ElectricPump :> Pump {
    attribute supplyVoltage : ElectricPotentialValue;
  }

  part def Radiator {
    attribute mass : MassValue;
    attribute heatRejection : PowerValue;
  }

  part def CoolingSystem {
    part pump : ElectricPump {
      attribute redefines mass = 2.4 [kg];
      attribute redefines shaftPower = 150 [W];
      attribute redefines supplyVoltage = 24 [V];
    }
    part radiator : Radiator {
      :>> mass = 6.5 [kg];
      :>> heatRejection = 18 [kW];
    }
    attribute totalMass : MassValue = pump.mass + radiator.mass;
  }
}

:>> is the short form of redefines. Reference properties in v1, which point to a part owned elsewhere, become ref usages in v2.

A standard textual notation

SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v1 has no standard text form for a whole model. The model lives in the tool's repository, people work in diagrams, and files move between tools as XMIXML Metadata Interchange An OMG XML format for exchanging UML and SysML models between tools., which is meant for machines, not for reading. Text appears only in places: constraint expressions, opaque behaviors, and action languages in some tools.

SysML v2 has a textual notation that covers the whole language, alongside a graphical notation. Both show the same model. Every listing on this page is that textual notation; the SysML v2 tutorial builds a complete model in it step by step. Text changes the way a team can work:

• A model can be reviewed line by line, compared with a diff, and kept under version control with the rest of the engineering data.
• Engineers can type a model quickly, copy patterns between models, and generate parts of it with scripts.
• A model can be checked like source code: unresolved names, wrong units and mismatched ports are reported where they occur.

The textual notation does not replace diagrams. It makes the model the primary artifact, and diagrams become views of it, as described below.

Standard library, quantities and units

SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v1 types a value property by a value type, which can carry a unit and a quantity kind. The specification includes a model for quantities and units, and model libraries for common units, but tools differ in which libraries they ship and how far they check units in expressions.

SysML v2 ships a standard library as part of the language. It includes the International System of Quantities (ISQ), SIInternational System of Units The metric system of units: meter, kilogram, second, ampere, kelvin, mole and candela, plus derived units. units (SI), US customary units, scalar types, collections and the standard view definitions. In the listing above:

• attribute mass : MassValue says the attribute is a mass, not a number.
• 6.5 [kg] is a quantity value: a number with a unit, written inline.
• pump.mass + radiator.mass adds two masses. A tool that evaluates units can reject an expression that adds a mass to a power, or a mass given in volts.

Ports, interfaces and connections

Ports in SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v1 went through several designs. Early versions had standard ports and flow ports; later versions replaced them with full ports, proxy ports and interface blocks with flow properties. A flow property has a direction (in, out or inout), a port can be conjugated to reverse the directions, and item flows on connectors say what moves. Many existing v1 models still mix the older and newer port kinds.

SysML v2 keeps the ideas and makes them uniform. A port definition lists directed features, the receiving side uses the conjugate ~ of the same definition, and an interface definition describes a kind of connection with typed ends.

package CoolantInterfaces {
  private import ISQ::*;

  item def Coolant {
    attribute temperature : ThermodynamicTemperatureValue;
  }

  port def CoolantPort {
    out item coolant : Coolant;
  }

  interface def Hose {
    end supply : CoolantPort;
    end ret : ~CoolantPort;
  }

  part def Pump {
    port outlet : CoolantPort;
  }

  part def Radiator {
    port inlet : ~CoolantPort;
  }

  part def Loop {
    part pump : Pump;
    part radiator : Radiator;
    interface hose : Hose connect pump.outlet to radiator.inlet;
  }
}

Because the directions are part of the definitions, a checker can warn when both ends of a connection send the same feature and neither receives it.

Behavior: actions and states

SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v1 borrows its behavior from UMLUnified Modeling Language A standard graphical language for modeling software and systems. SysML is built on it.: activities with token-flow semantics, state machines, and interactions for sequence diagrams. A behavior is linked to the structure that carries it out through allocation, often with activity partitions (swim lanes) or «allocate» relationships.

In SysML v2, actions and states are occurrences, like parts. An action definition has input and output parameters; successions (first … then …) give the order and flows say what passes between steps. A state definition has states and transitions with triggers, guards and effects. A part performs an action and exhibits a state, so the link to structure is part of the language rather than an added relationship.

package PumpBehavior {
  private import ISQ::*;

  item def StartCommand;
  item def StopCommand;
  item def Coolant;

  action def Circulate {
    in item cold : Coolant;
    out item warm : Coolant;
  }

  action def CoolEngine {
    action pumpCoolant : Circulate;
    action rejectHeat : Circulate;
    flow pumpCoolant.warm to rejectHeat.cold;
    first start then pumpCoolant;
    first pumpCoolant then rejectHeat;
    first rejectHeat then done;
  }

  state def PumpModes {
    entry; then off;
    state off;
    state running;
    transition first off accept StartCommand then running;
    transition first running accept StopCommand then off;
  }

  part def Pump {
    exhibit state modes : PumpModes;
  }
}

Requirements and verification cases

A SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v1 requirement is a stereotyped class with two strings: an id and a text. Relationships connect it to the rest of the model: satisfy, verify, derive, refine, trace and copy. A test case is a behavior marked «testCase». Checking a requirement with numbers needs a separate constraint block in a parametric diagram, and nothing in the language ties that constraint to the requirement's text.

In SysML v2 a requirement definition is a kind of constraint definition. It has a subject (what the requirement is about), may have attributes such as a limit, and contains the condition that must hold. The doc text and the condition sit in one element. A verification case states the requirement it verifies in its objective and returns a verdict.

package CoolingRequirements {
  private import ScalarValues::*;
  private import ISQ::*;
  private import SI::*;

  part def CoolingSystem {
    attribute heatRejection : PowerValue;
  }

  part cooling : CoolingSystem {
    attribute redefines heatRejection = 18 [kW];
  }

  requirement def <'CR-1'> HeatRejection {
    doc /* The cooling system shall reject at least the engine's waste heat at full load. */
    subject system : CoolingSystem;
    attribute wasteHeat : PowerValue;
    require constraint { system.heatRejection >= wasteHeat }
  }

  requirement coolingSpec : HeatRejection {
    subject system : CoolingSystem;
    attribute redefines wasteHeat = 15 [kW];
  }

  satisfy coolingSpec by cooling;

  verification def <'VC-1'> HeatRunTest {
    doc /* Run the engine at full load on a test stand and measure the heat the radiator rejects. */
    subject system : CoolingSystem;
    objective {
      verify coolingSpec;
    }
    return verdict : Boolean = system.heatRejection >= coolingSpec.wasteHeat;
  }

  verification heatRun : HeatRunTest {
    subject system = cooling;
  }
}

• <'CR-1'> is a short name, the v2 home of the v1 requirement id.
• require constraint is the checkable form of the text. With 18 kW against 15 kW, a tool that evaluates constraints reports the requirement as met.
• satisfy and verify keep their v1 meaning. Derive, refine and trace map to dependencies or to requirement usages nested in other requirements; teams decide how to model them.
• SysML v2 adds assumptions (assume constraint), stakeholders and concerns to requirements, and use cases and analysis cases next to verification cases.

Views instead of drawn diagrams

A SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v1 diagram is a drawing owned by the tool: someone chooses which elements appear and where. Two diagrams of the same block can disagree about what it contains, and diagram layouts seldom survive an exchange between tools. Later v1 versions added views and viewpoints, but they are mostly used for documents, not for the diagrams engineers draw every day.

In SysML v2 a view is an element of the model. It names what to show with expose, which kinds of element to include with filter, and which standard view definition to render it as. The layout is left to the tool; what the view contains is in the model and can be read in the text.

package CoolingViews {
  private import StandardViewDefinitions::*;

  part def Pump;
  part def Radiator;

  part def Loop {
    part pump : Pump;
    part radiator : Radiator;
    connect pump to radiator;
  }

  view loopConnections : InterconnectionView {
    expose Loop;
  }

  view structure : GeneralView {
    filter @SysML::PartDefinition;
    expose CoolingViews::*;
  }
}

The Systems Modeling API and JSON interchange

SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v1 models move between tools as XMIXML Metadata Interchange An OMG XML format for exchanging UML and SysML models between tools.. XMI is a standard, but each tool writes its own variant, stereotypes and diagram data, so an exchange usually needs testing per tool pair, and there is no standard way for a program to query a model held in another tool.

SysML v2 comes with the Systems Modeling API and Services specification. It defines services for projects, branches, commits, elements and queries, and a REST/HTTP binding in which each element is a JSON object with an @id and an @type. The consequences:

• A script, a dashboard or another tool can read and query a model through one documented interface instead of a vendor-specific one.
• Element ids travel with the model, so links between tools can survive an exchange.
• Models are versioned as commits on branches, much like source code.

Text files and JSON complement each other: text is for people to read, review and diff; JSON keeps the ids that tools rely on.

Migrating a model from SysML v1 to v2

Moving a v1 model to v2 is a translation between languages, not a file upgrade, and the target tool decides how much of it is automated: what to check in a SysML v2 tool covers v1 import among the other checks. Much of a typical model maps directly, and some of it is better rebuilt in the v2 way than translated literally.

What maps cleanly

• Packages and their nesting.
• Blocks to part definitions, part properties to part usages, reference properties to ref usages, generalizations to specializations.
• Value properties to attributes, with quantities and units when the v1 value types had units.
• Interface blocks with flow properties to port definitions; proxy and full ports to port usages; connectors to connections or interfaces.
• Requirement ids and text to short names and doc; satisfy and verify relationships.
• State machines to state definitions; well-structured activities to action definitions with successions and flows.

What needs rethinking

• Context-specific values. Property-specific types, instance specifications and redefinitions made only to set a value become plain redefinitions on usages. A literal translation keeps the workaround.
• Text-only requirements. v2 allows them, but the gain comes from adding the condition. Decide which requirements get a require constraint.
• Constraint blocks and parametric diagrams. They become constraint and calculation definitions, often written as expressions directly on attributes, as totalMass is above.
• Allocation. Activity partitions and «allocate» relationships from behavior to structure become perform and exhibit where the meaning is "this part does this".
• Older port kinds. Standard and flow ports from early v1 models need the most work, since v2 has one port concept.
• Profiles and stereotypes. Custom stereotypes and tagged values become metadata definitions; their meaning has to be designed again.
• Diagrams. Layouts do not carry over. Each diagram that matters becomes a view, and its content is restated with expose and filter.
• Opaque behaviors and tool scripts. Code in an action language or in a tool's scripting does not translate; it has to be rewritten or kept outside the model.

Plan a migration like any model change: convert a representative package first, review it with the people who use the model, settle the modeling patterns for the points above, then convert the rest. Keep the v1 model as the reference until the v2 model has been reviewed.

How the listings were checked

Every listing on this page was parsed and checked with the Holarch Language Engine, the engine behind Holarch's SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 Editor, with the SysML v2 standard library loaded, and gives no errors and no warnings. For which SysML v2 constructs the engine supports and its known gaps, see SysML v2 language coverage. For a longer worked model, see the SysML v2 tutorial.

Try it in Holarch

Holarch has SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 projects, where the textual notation and the views edit one model, and LMLLifecycle Modeling Language An open modeling language with a small set of classes and relationships that covers a system's whole lifecycle. Holarch models are LML models. projects. To read the listings above as a model:

1. Create a SysML v2 project. See getting started with SysML v2 projects.
2. In Model → Editor, click + New Package and paste a listing. Text that parses is applied after a short pause, and problems are marked in place. See the Editor.
3. Open the Diagrams list to see the views. See the views reference.

SysML v1 models. Holarch imports SysML 1.x models as XMIXML Metadata Interchange An OMG XML format for exchanging UML and SysML models between tools. (from Cameo Systems Modeler or MagicDraw, Enterprise Architect, Rhapsody or Papyrus) into LML projects; see import a UML/SysML model. It does not translate a SysML v1 model into SysML v2 directly. An LML project can be copied into a new SysML v2 project with Make a SysML v2 Copy…, which lists what converts and what does not (see converting between LML and SysML v2), but that route passes through LML: generalizations, operations and diagram layouts from the v1 model are not imported, so treat the result as a starting point for the rethinking described above, not as a finished migration.

Where to go next

• SysML v2 tutorial: build a small system step by step in the textual notation.
• SysML v2 tools: what to check before you choose one: a checklist and a test model for any candidate tool.
• SysML v2 projects in Holarch: text, views and engineering pages on one model.
• SysML v2 language coverage: what the engine supports and its known gaps.
• Exchanging SysML v2 models: text, JSON and Systems Modeling API repositories.