SysML v2 Deep Dive 5 min read

Lesson 12: Item Definitions (The Metamodel of the "Stuff" That Flows)

Item Definitions (The Metamodel of the "Stuff" That Flows)

In SysML v1, engineers modeled the things that flow through a system by typing a FlowProperty or an ItemFlow with a standard Block, ValueType, or Signal. While this successfully gave the payload structural properties - allowing you to specify the density or octane level of "Fuel" rather than just an anonymous flow rate - it meant using the exact same generic Block construct for a passive payload as you used for an active system component.

SysML v2 introduces greater semantic precision by providing the item def. According to the SysML v2 abstract syntax, an item definition is a specific kind of occurrence definition used for things that exist in space and time and can be acted upon, but which do not necessarily perform actions themselves.

The Concept: What is an Item

To understand items, we must observe their position in the SysML v2 Metamodel Hierarchy (which extends KerML):

 [OccurrenceDefinition]  ◄─── (Base spatial-temporal classifier)
         ▲
         │
 [ItemDefinition]        ◄─── (Specializes Systems Library 'Items::Item')
         ▲
         │
 [PartDefinition]        ◄─── (Specializes Systems Library 'Parts::Part')

In the abstract syntax:

  • ItemDefinition is a specialized subclass of OccurrenceDefinition. Because it inherits from occurrences, every item has temporal and spatial extent. It is not just a passive data type; it exists in physical space and time, possesses a distinct lifetime, and can be tracked as it is stored, consumed, or flowing.
  • The Structural Distinction (Item vs Part): A PartDefinition is a specialized subclass of ItemDefinition. Thus, all parts are items, but not all items are parts.
    • Parts (PartDefinition) represent modular, active structural units (e.g., an ECU, a pump, or an actuator) designed to perform actions and exhibit states within a system.
    • Items (ItemDefinition) represent things that are acted upon, stored, or processed by those parts, but do not necessarily perform system actions themselves (e.g., point-cloud telemetry, hydraulic oil, or electrical energy).

The Code: Intelligent Fuel & Data

Here is a package that defines physical fuel and digital payment data, then uses the fuel definition in a nozzle port.

package MaterialDefinitions {
    private import ISQ::*;          // Standard Quantities (Mass, Time, etc.)
    private import SI::*;           // Measurement units (kg, m, s, etc.)
    private import Time::*;         // Clock model and DateTime types
    private import ScalarValues::*; // Standard datatypes (Real, String, Boolean)

    // 1. Physical Matter (Fuel)
    // An item can have physical properties and internal structure.
    item def Fuel {
        attribute octaneLevel : Real;
        attribute density : MassDensityValue;

        // Items can even have constraints!
        // We ensure density is above a threshold.
        // SysML v2 enforces dimensional consistency, so we must specify the unit.
        constraint { density > 700[kg/m^3] }
    }

    // 2. Information (Data)
    // An item can be digital.
    item def PaymentData {
        attribute encryptionKey : String;
        attribute timestamp : DateTime;
    }

    // 3. Using the Item in a Port (Recap from Lesson 9)
    port def NozzlePort {
        // We flow the 'Fuel' item defined above.
        // It's not just a number; it's an object with density and octane.
        out item superUnleaded : Fuel;
    }
}

Graphical Notation

12.sysml

Additionally, SysML v2 supports both discrete and continuous domains using the exact same ItemDefinition metaclass:

  • Discrete Items: Represent countable, individual objects that pass through or interact with a system (e.g., a Person, a specific cargo container, or a discrete CAN bus frame). They are modeled with discrete multiplicities (e.g., item trackingPacket : SensorTelemetry [0..*];).
  • Continuous Items: Represent continuous flows or materials that are stored in tanks or are streamed between ports (e.g., liquid fuel, thermal energy, or electrical current). These are modeled as continuous substances by embedding quantitative attributes inside the item.

Ports, Interfaces & Directed Items

How do items actually travel? They are declared as Directed Features inside Port Definitions (port def), which are then wired via Interface Connections (interface def):

package CommunicationArchitecture {
    private import MaterialDefinitions::*;
    private import Time::*;         // Clock model and DateTime types
    private import ScalarValues::*; // Standard datatypes (Real, String, Boolean)

    // 1. Structured Data Payload Item Definition
    item def SensorTelemetry {
        attribute packetID : Integer;
        attribute payloadTimestamp : TimeValue;
        attribute sensorDataPoints : Real[1..*];
    }

    // 2. Port Definition utilizing the Item Payload
    port def TelemetryPort {
        // Declaring the item as a directed OUT feature
        out item telemetryData : SensorTelemetry;
    }

    // 3. Dual Part Architectures using Port Conjugation (tilde '~')
    part def SensorUnit {
        port telemetryOut : TelemetryPort;
    }

    part def FusionECU {
        // Conjugation '~' automatically flips 'out item' to 'in item'
        port telemetryIn : ~TelemetryPort;
    }

    // 4. Logical Interface Contract routing the Item payload
    interface def TelemetryInterface {
        end sourcePort : TelemetryPort;
        end targetPort : ~TelemetryPort;

        // Declarative flow stating exactly WHAT item flows across the line
        flow of SensorTelemetry from sourcePort.telemetryData to targetPort.telemetryData;
    }
}

Graphical Notation

12.sysml (2)

V1 vs. V2 Cheat Sheet

ConceptSysML v1SysML v2
Exchanged payloadModeled using an ItemFlow that was typed by a generic Block, ValueType, or Signal.Defined explicitly with an item def, isolating passive payloads from active structural blocks.
Port flow declarationFlow property on a port or interface construct.Directed item feature inside a port def.
Quantity/value typeValue Type, often used to stand in for the payload itself.attribute def or a KerML DataType for values; item def for the exchanged thing.
Item flowA separate Item Flow relationship.A flow usage when modeling the flow itself.

The key idea is that SysML v2 separates the thing being exchanged from the values that describe it. Fuel is the item. Its density and octane level are attributes. That separation lets the model preserve both the payload's identity and the engineering data needed to reason about it.

Next Lesson

We shift gears to Language Architecture. Before we dive into behavior, we need to understand the "Layer Cake" of SysML v2. We will look at KerML, the engine under the hood that makes all this rigorous definition possible.

SysML v2

SysModeler Team

Engineering & Product