System Context and Use Cases with Claude & Syside (Part 2)

SysML v2 and AI are a surprisingly good fit. It is a coincidence that a modeling language with a formal textual notation emerged almost simultaneously with LLMs, an AI technology that is exceptionally adept at handling text. However, many systems engineers are currently taking advantage of this fortunate circumstance and experimenting with both technologies.

Although the textual notation is formal, it is still „only“ another view of the model. The graphical view continues to have its place, and the actual model also contains information that does not appear in the textual notation by default.

In this section, we model the context of our system and define the most important actors and use cases. We’ll build on the SYSMOD library and examine how Syside represents the model both textually and graphically.

Step 2 in the development process: Flesh out the idea

In the first step The discussion centered on the stakeholder problem, which we described in an almost excessively solution-neutral way. Here are three implementation strategies that all solve the stakeholder problem but differ drastically from one another:

• Air conditioning for the building
• Personal Table Fan
• Water bucket for your feet

Before we can move forward, we need to decide on a specific idea to pursue. The process for doing this is outlined in the „System Idea“ step:

Even though it’s already clear where this is headed (a table fan), the purpose here is to show how we systematically make this decision. First, we define our idea. The idea is doc-element part of DeskCoolingSystem, which, in turn, is in context:

System Concept: model/DeskCoolingSystemIdea.sysml

#systemContext part def DeskCoolingSystemIdeaContext {
    part def DeskCoolingSystem {
 doc
 /* System idea: a tabletop fan for a single workstation.
 *
 * The device sits on the desk next to the person it serves and cools
         * them by directing a stream of the surrounding room air at them, rather
 * than by lowering the room temperature. It draws its power from
 * a USB port on equipment already on the desk, so it requires no
 * installation, no dedicated power outlet, and no maintenance.
 *
         * This is a commitment to a type of solution, not a design. How the
 * airflow is produced, directed, and controlled is determined in
 * Activity 5. */
 port powerPort {
 doc
 /* Port through which the system receives electrical power. */
 }
    }
}

Actors, Decisions, Assumptions

We’re getting a little ahead of ourselves here, since the definition of the system context doesn’t actually come until Step 3. That’s why the context shown here is still incomplete. To flesh out our idea, we need to identify the following:

• Actuators: Who interacts with the system? These are not (necessarily) the stakeholders and can also include things like the energy supply
• Decisions: Which alternatives—that limit the range of possible solutions—did we deliberately choose?
• Assumptions: What does our system rely on? Essentially, these are the framework conditions—both for the system's operation and for its development.

To represent this in SysML, we need the appropriate data structures. To do this, we use SysML v2 metadata, which also allows us to define the attributes. The following file contains both the metadata and the decisions and assumptions:

Here are two examples:

• Decision D-03: The system is powered by a USB port on the equipment already on the desk. This allows the device to be used at a typical workstation without any preparation: no need for a free power outlet, no installation, and no charging routine.
• Assumption A-02: Circulating untreated room air over a person alleviates the feeling of being too warm at the temperatures typically found in a standard workplace.

A visualization as a SysML diagram isn't very helpful here. The situation is similar to that of the user needs in the first part. We could create a tabular view, but I'll skip that here since the SysML v2 code is easy to read.

Traceability

To ensure that our decisions and assumptions aren't made in a vacuum, we can explicitly establish traceability here. Here is an example for D-03.

System Concept: model/DeskCoolingDecisions.sysml

dependency d03MotivatedBy from d03 to FitsOrdinaryWorkplaces, ComfortWithoutAttention {
    doc
    /* D-03 is designed for use in an ordinary workplace without any preparation, and
 without a charging routine that the desk worker needs to maintain. */
}

Step 3: System Context

Even though we’ve already given some thought to the actuators during the ideation phase, they are part of the system context. Here, we should take a pragmatic approach and model only what is truly relevant. For example, we had the OfficeNeighbor identified, which we'll omit because it plays a minor role.

That said, not every stakeholder is also an actor, and not every actor is a stakeholder.

For our example project, we now have three actuators, as shown in the context diagram below.

Unfortunately, the graphical visualization using Syside—which is based on TomSawyer—is already reaching its limits here. The default layout was quite wide—too wide to embed in a blog post. So I adjusted the model manually, which caused one of the connectors to be crooked (I couldn’t find a feature to straighten it).

This is a simple diagram showing one system and three actuators. At least in its current form, it is not scalable and is also unreasonable to expect many stakeholders to understand. Therefore, my clear recommendation here would be to map out the context on a whiteboard with the relevant stakeholders. The only important thing then is to keep track of changes properly and delete outdated descriptions.

Use cases

Another outcome of Step 3 is the use cases. For this simple model, we will start by working with three of them:

• PutIntoService: The system is being put into operation.
• ProvideRelief: The system is operating normally.
• AdjustRelief: The user adapts the system to changing conditions.

This is where the model starts to become a bit confusing and (unnecessarily?) complex. More on that in a moment. For now, here are both the textual and graphical models for the third use case:

AdjustRelief: model/DeskCoolingSystemContext.sysml

#systemUseCase use case def AdjustRelief {
    doc
    /* The desk worker changes the amount of relief the system provides. */
    subject deskCoolingSystem : DeskCoolingSystem;
    actor deskWorker;
    objective {
 doc
 /* The desk worker adjusts the amount of relief to their
 current preference—including none at all—without having to stop
 working to do so. */
        frame concern simpleUseAndControl : SimpleUseAndControl;
    }
    attribute ucMotivation :>> ucMotivation = "The desk worker’s preferences change throughout the day, depending on the room, their clothing, and their current activities. Relief that cannot be adjusted is usually either too little or too much.";
    attribute ucTrigger :>> ucTrigger = "The desk worker asks the system for a different level of relief.";
    attribute ucResult :>> ucResult = "The relief provided by the system corresponds to what the desk worker requested.";
    constraint precondition :>> precondition {
 doc
        /* The system is operational at the workplace. */
    }
    constraint postcondition :>> postcondition {
 doc
 /* The system provides relief at the level the desk worker requested,
 and the desk worker did not have to interrupt their work
 to achieve it. Stopping the system occurs when that
 level is none. */
    }
    action acceptReliefSetting :> deskCoolingSystem.acceptReliefSetting;
    action deliverRelief :> deskCoolingSystem.deliverRelief;
    action indicateService :> deskCoolingSystem.indicateService;
    first start then acceptReliefSetting;
    first acceptReliefSetting then deliverRelief;
    first deliverRelief then indicateService;
    first indicateService then done;
}

The graphical representation isn't really useful. On the other hand, the text version is extremely easy to read and useful.

Parts, Part Definitions, and Inheritance Relationships

At this point, at the latest, a characteristic of SysML v2 becomes apparent that results in a steep learning curve: The model consists not only of the visible elements, but also of a relatively large number of references to definitions, more general elements, and inherited elements. This enables reuse and very precise semantics. However, when reading the model, you often have to follow multiple levels.

An important starting point is the difference between part def and part. A Definition of describes a class of things. A Usage describes how such a thing occurs in a specific context. The analogy to types and variables serves as a first approximation, even though the SysML v2 semantics go beyond that. The SysML v2 specification explicitly describes a usage as the application of a definition in a specific context.

Our system therefore first appears as a definition:

part def DeskCoolingSystem {
    port deskWorkerPort;
    port powerPort;
    port environmentPort;
}

In the system context, there is then a specific part that is typed by this definition:

#System part deskCoolingSystem : DeskCoolingSystem :>> soi;

DeskCoolingSystem So it says, What kind of system? We model. deskCoolingSystem says, what role this system plays in this context.

But that's not the end of the process. In Step 3, we refine the definition from the system concept:

part def DeskCoolingSystem :> DCD_IDEA::DeskCoolingSystem {
    port :>> deskWorkerPort {
 out item coolingEffect : CoolingEffect;
 out item serviceIndication : ServiceIndication;
 in item reliefSetting : ReliefSetting;
    }
    // ...
}

This means there are two definitions with the same simple name in different packages. DCD_CONTEXT::DeskCoolingSystem specialized DCD_IDEA::DeskCoolingSystem. The first definition essentially states: We are developing a USB-powered desk fan with these interfaces. The second definition retains this statement and specifies what is exchanged via the interfaces and what black-box behavior the system exhibits.

The same principle applies to the context:

#systemContext part def DeskCoolingSystemContext
    :> DCD_IDEA::DeskCoolingSystemIdeaContext {
    #System part deskCoolingSystem
 :>> DCD_IDEA::DeskCoolingSystemIdeaContext::deskCoolingSystem
 : DeskCoolingSystem;
    // Use Cases ...
}

The DeskCoolingSystemContext So, based on Step 3, the DeskCoolingSystemIdeaContext from Step 2. At the same time, the value inherited from it deskCoolingSystem redefined and supplemented with the more detailed DeskCoolingSystem-Typed definition.

This creates a chain of refinement:

System Idea
    DeskCoolingSystemIdeaContext
 deskCoolingSystem : DCD_IDEA::DeskCoolingSystem
 ↓
Specification Context
    DeskCoolingSystemContext
 deskCoolingSystem : DCD_CONTEXT::DeskCoolingSystem

This prevents duplication. The specification context does not need to redefine the three actuators and the basic interfaces. It inherits them from the system concept context and only adds the information that is included in this development step.

SYSMOD adds another layer to the mix

Added to that is the SYSMOD Library. Among other things, it provides generic concepts such as Project, SystemContext, actors, soi, useCases, systemIdeaContext and specificationContext. The keywords, too, #project, #SystemContext and # System Use Case come from this library.

This allows us, for example, to write:

#User part deskWorker :> actors;
#ExternalSystem part usbPowerSource :> actors;

actors does not need to be defined in our model. It is already part of the generic SYSMOD system context. Likewise, soithat System of Interest, from this library. SYSMOD also already defines a collection useCases for the use cases of a system context. (GitHub)

At the project level, reuse becomes even more apparent:

part deskCoolingIdeaContext
    :>> systemIdeaContext
    : DCD_IDEA::DeskCoolingSystemIdeaContext;
part deskCoolingContext
    :>> specificationContext
    : DCD_CONTEXT::DeskCoolingSystemContext
    :> deskCoolingIdeaContext;

Here, the generic SYSMOD project is customized for our product. deskCoolingIdeaContext replaces or refines the one provided by SYSMOD systemIdeaContext. deskCoolingContext do the same with specificationContext and is also related to the preceding one deskCoolingIdeaContext.

That is the major advantage of a library like SYSMOD: project structure, methodological roles, and many recurring modeling patterns do not have to be reinvented for every product. SYSMOD itself models a chain that extends from the brownfield context through the system idea and specification context to subsequent architectures. Our tailored process skips the Brownfield Context but continues to utilize the rest of the structure.

The price for this is indirectness. For example, anyone who deskCoolingContext To understand this, you may need to examine its definition, the system-idea context, the inherited elements, and the corresponding SYSMOD elements. Even in a small example, the meaning of an element is thus spread across multiple files and levels.

:, :>, :>>, and #

SysML v2 expresses a large portion of these relationships using three very similar operators:

This can be confusing, especially for beginners, but it's important. The same operator :> has a different specific name depending on the element type. In a definition, this is called specialization:

part def DeskCoolingSystem
    :> DCD_IDEA::DeskCoolingSystem;

With SysML v2, you can also spell that out:

part def DeskCoolingSystem
    specializes DCD_IDEA::DeskCoolingSystem;

"Usage" means :> on the other hand subsets. Our actuators are a good example:

#User part deskWorker :> actors;

deskWorker replaced actors No. It is a more specific component of the generally defined set of actors. We use the same principle in the use cases:

action deliverRelief :> deskCoolingSystem.deliverRelief;

The action in the use case is a specific application of the black-box behavior already defined in the system.

:>> is stronger. It is used when an inherited usage, in the new context, redefined will. This happens here, for example:

port :>> deskWorkerPort {
    out item coolingEffect : CoolingEffect;
    out item serviceIndication : ServiceIndication;
    in item reliefSetting : ReliefSetting;
}

The port is already part of the system design. In the next development phase, there are no plans to create a second port alongside it. Instead, this existing port will be refined. That is why :>>.

A practical rule of thumb is therefore:

• : answers the question „Which definition is used to type this element?“.
• :> answered „Which more general definition or usage am I specializing or subsetting?“.
• :>> answered „Which inherited convention am I refining at this very point?“.

The SysML v2 specification explicitly uses the following terms for this purpose: defined by, specializes or subsets and redefines; Redefinition itself is a special form of subsetting.

By the way, the keywords listed are valid SysML v2 syntax. From

part deskCoolingSystem : DeskCoolingSystem :>> soi;

So, mentally (and also in writing), one can

part deskCoolingSystem
    defined by DeskCoolingSystem
    redefines soi;

...especially when you're just getting started, this longer version is much easier to read.

Finally, we also #, which is a Metadata Annotation indicates:

#User part deskWorker :> actors;

#User Additionally classifies the following model element as User. User In our case, this is a metadata definition provided by SYSMOD.

This means:

• #User: semantic labeling as user/actor
• part-time desk worker: the actual part usage
• :> actors: deskWorker is a subset of the more general actors-Usage

The # It is therefore neither part of the name nor a comment or preprocessor symbol. It attaches additional, machine-readable meaning to the element.

One metadata def It can also contain its own attributes. When applying the annotation, we can assign values to these attributes.

The extensive reuse of definitions, subsets, and redefinitions is one of SysML v2’s strengths. It prevents the same information from being duplicated in multiple places. At the same time, this creates a high navigation burden. Even a small model therefore requires an understanding of definitions and usages, namespaces, specialization, subsetting, redefinition, and the libraries used. The syntax is compact, but the underlying semantics are not.

What's in it for me?

The example is very small in scope. Nevertheless, a surprisingly deep model structure is already emerging. This is due in part to the fact that we consistently use the mechanisms of SysML v2 and SYSMOD: definition and usage, specialization, subsetting, redefinition, and the step-by-step refinement of SYSMOD contexts. These mechanisms prevent duplication and create precise semantics. The trade-off is a significant burden in terms of navigation and learning.

Therefore, I wouldn't do anything significant for this project flatten. Precisely because the Repo SysML v2 is intended to demonstrate the method, the resulting complexity is itself a relevant outcome. If, on the other hand, I were to build a „Learn SysML v2 in 30 Minutes“ demonstrator that was as simple as possible, I would omit several of these levels.

What do we get in return for all this effort?

• Errors become apparent sooner. Syside validates the model as you type and checks not only syntax but also numerous semantic rules. An invalid type, an incorrect reference, or an invalid model relationship is thus immediately visible in the editor. While this goes beyond a simple syntax check, it only detects inconsistencies for which a formal rule exists. For example, the fact that a decision cannot be traced back to a stakeholder need is not automatically a SysML error. For that, we need a separate modeling rule. Syside Automator supports such project-specific checks via Python.
• Reuse without copying. That is exactly why definitions and usages work together. A definition such as DeskCoolingSystem Alternatively, a SYSMOD concept is modeled once and can be used in various contexts and refined as needed. This eliminates the need to keep changes synchronized across multiple copies. The SysML v2 specification explicitly cites reuse in different contexts as the purpose of the definition/usage concept.
• The consequences of changes can be analyzed. Explicit relationships turn a change into a starting point for impact analysis. For example, if a stakeholder need changes, I can navigate from there to decisions, requirements, architecture, and later verification—provided we have modeled these relationships. Looking at it the other way around, we can ask: Why does this element exist? Syside already supports „Find References“ at the base level across the entire model and can update all semantically related references when renaming. The actual technical impact analysis goes beyond this, but is based on precisely this network of relationships.

• Gaps can be systematically identified. As soon as relationships are not just described in text but are part of the model, gap analysis becomes possible. For example, we can check: Is there a decision without an underlying need? A #User No stakeholders? A requirement with no origin? A requirement that won't be verified later? Questions like these can be automated using the model and formulated as project-specific validation rules. Syside Automator supports programmatic model access and custom validation rules for this purpose.
• Traceability is gaining semantic meaning. A link in SysML distinguishes between typing, specialization, subsetting, redefinition, satisfaction, verification, and other relationships. This makes it possible not only to determine, that not that the two elements are related, but rather like. SysML v2 was specifically designed to ensure consistency and traceability among requirements, behavior, structure, analysis, and verification.
• Changes become versionable and verifiable. In this case, the model is in text form, so we can use standard version control. A Git diff shows which model lines have been changed, changes can be reviewed via branches and pull requests, and the history is preserved. Sensmetry explicitly cites the traceability of changes via Git as an advantage of the „System as Code“ approach. The SysML v2 API also supports versioning and serves as an alternative to the text-based approach, which we will also examine in more detail shortly.
• The model will be machine-readable. Diagrams, tables, documentation, quality checks, or custom analyses can be generated from the same model structure. Syside now clearly separates these functions: The Editor supports modeling and validation, the Modeler generates views and diagrams, and Automator enables Python-based analyses and reports. It is precisely the precise relationships—which make the model more complex to read—that provide the necessary structure for this.

This also shifts how we assess complexity. A long chain of definition, usage, specialization, and redefinition is initially harder to read than a table or a diagram with a few boxes. On the other hand, the significance of this chain for a tool is clear.

Whether this effort is worthwhile depends heavily on how much value our stakeholders derive from the model—and how quickly that value reaches them.

In the next section, we'll take a look at requirements and architecture using SYSMOD and SysML v2.