Hello and welcome back to the Advent of SysML v2 – a daily, hands-on mini-course designed to bring you up to speed with the new SysML v2 standard and the modern Syside tooling that makes you productive from day one.

By the end of this lesson, you will:

• Learn about definitions and usages in SysML v2
• Discover how to refactor your models with Syside

If you want to dive deeper into the world of SysML v2, check out The SysML v2 Book, where this topic is also discussed in more detail.

What Are Definitions and Usages?

Definitions and usages are fundamental concepts in SysML v2. They are both types, classifying things in the universe we model. However, it is crucial to understand the difference and learn which one to use in a particular situation.

Technically, definition elements are types that classify individual things in the universe. Cars, Marriages, Integers, Procedures – these are all definitions because they capture something on their own.

In contrast, usage elements represent relationships: the use of something in a specific context, typically to specify another type. A car owned by someone, someone’s first marriage, age, subroutines – these are all usages because they can be interpreted in a context. Can you tell the context in each of the previous cases?

To sum up, definitions specify the inherent properties of things, independent of their context, while usages specify their properties within a specific context.

Almost everything in SysML is either a definition or a usage. The figure below provides some intuition of when to use which.

Consistent Terminology in SysML v2

One of the big steps in SysML v2 compared to v1 is the harmonization of terminology. Almost every element has a definition and a usage variant. SysML v1 also had concepts equivalent to definitions and usages, but they were never explicitly labeled as such. The following table shows the correspondence between SysML v1 and v2 elements.

SysML v1	SysML v2
block / part property	part def / part
value type / value property	attribute def / attribute
interface block / proxy port	port def / port
association block / connector	connection def / connection
activity / action	action def / action
state machine / state	state def / state
constraint block / constraint property	constraint def / constraint

Actually, properties always map to usages, but there are also some other concepts. Block Definition Diagrams had definition in their name for a good reason, too. Most things modeled on a BDD were actually definitions. Internal Block Diagrams and compartments, on the other hand, hosted usages.

Some of these are still good markers. If you would put something in a package or on an empty diagram, it is most likely a definition. If you nest it under some other type (definition or usage), or display it in a compartment, it is most likely a usage.

In later episodes, we will cover most of the concepts in the table.

How to Model With Definitions and Usages?

Let us see all this in action. The model below is an extract from the model of Santa’s sleigh, demonstrating definitions and usages. As usual, you can find it in Syside Cloud (get access by registering for Advent of SysML v2).

In line 2, we immediately see a definition element, namely a part definition. This represents the “blueprint” of Santa’s sleigh, or more accurately, SantaSleigh, our patented new design, ready to be mass-produced once we complete its engineering. Our design does not need a context to be interpreted, so it is indeed a definition element. If it were a usage, we would always need to say “the Santa’s sleigh of what?”. This doesn’t add up, even in English.

Inside the specification of Santa’s sleigh, we find a usage element in line 3. This is a part usage that we use to define what Santa’s sleigh is. In other words, a feature of Santa’s sleigh. The usage is called “dashboard”, and after the colon, we can see the definition that is being used to create or procure this part: “NaughtyNiceDashboard” (defined in line 9). This means that in every instance of Santa’s sleigh, there will always be an instance of a naughty-nice dashboard. 

The usage is not an instance, though! It is still a type, a more specific version of naughty-nice dashboards. It is more specific because every instance of it will be built into an instance of Santa’s sleigh. We will learn about a related concept, specializations, in the next lesson.

Looking at the definition and the usage elements in lines 2 and 3, you can also spot that the names of definitions are conventionally written with an upper-case letter, while usages start with a lower-case letter. Together with the different highlighting, this can help you navigate the model more easily.

In line 4, “cockpit” is another usage element, but without a type this time. This is also possible in SysML – the type of this usage will automatically be the most general part called “Part” from the Semantic Library. The definition “Part” is rather boring and way too general to be useful for us, but we can also elaborate usages locally with nested usages, adding interesting features to our very generic part.

You can see this in line 5. The referential item usage “driver” is a feature of another usage, “cockpit”. This means that in the context of Santa’s sleigh, the general “Part” blueprint defining “cockpit” will be extended with a new feature “driver”. In other words, we did not have a blueprint for a cockpit, so we are making one up right here, without creating a definition element.

This is called usage-focused modeling. It can be very efficient in drafting models, but be sure to always start with a definition element. After all, we are not designing the something of something, we are designing the something itself.

If you start with a usage that also has meaning, literally, everything may have that feature. So if Santa’s sleigh is a package-level usage, it means everything may have a Santa’s sleigh – even Santa’s sleigh itself. And cockpits. And Christmas trees. And even numbers. They don’t have to, but still, this is probably not what you wanted.

Refactoring SysML v2 Models With Syside

One of the most underappreciated advantages of SysML v2’s textual syntax is that it unlocks genuine refactoring, the kind software developers have relied on for decades. In traditional graphical SysML tools, “refactoring” often meant hours of dragging boxes, re-wiring connectors, and hoping the layout engine wouldn’t destroy your carefully arranged diagram. With a textual foundation, refactoring becomes fast, predictable, and fully automated.

Let’s explore how Syside supports this workflow.

Auto-formatting your models

Consistent formatting isn’t just aesthetic. It makes models easier to read, review, and maintain across a team. Syside’s language server can automatically format your model files.

To enable format on save:

1. Open settings with Ctrl/Cmd+Comma
2. Search for “Editor: Format On Save” and enable it. Alternatively, use the "editor.formatOnSave": true configuration option.

You can also format a specific selection by right-clicking and choosing “Format Selection.” The formatter handles indentation, spacing, and alignment while respecting your intentional formatting choices.

This may seem like a small convenience, but consider what it means in practice: you can write quickly without worrying about alignment, paste code from documentation or colleagues, and trust that saving will normalize everything. The cognitive overhead disappears.

Refactoring models with AI assistance

Let’s look at a practical example. Suppose you drafted a model quickly using usage-focused modeling and ended up with something like this:

This works, but there’s obvious repetition. Every reindeer has the same structure, and if you wanted to add a new attribute to all of them, you’d need to change nine places. The model is missing a definition.

You can ask an AI assistant to extract the common pattern into a definition. The result:

The AI recognized the repeated pattern, created a Reindeer definition with the common energyLevel attribute, typed each usage to that definition, and handled Rudolph’s special case using a redefinition.

This is exactly the kind of evolution we discussed earlier: start with usage-focused modeling for speed, then extract definitions as the model matures. The textual syntax makes this workflow possible. The same applies to other refactoring tasks you might face: applying a design pattern across an entire model, reorganizing namespaces after a project restructure, or adding metadata annotations to hundreds of elements. What used to take hours of manual edits becomes a conversation with an AI assistant.

Challenge for Tomorrow

Your challenge after this lesson is to add some more definitions and usages to Santa’s sleigh. Go to Syside Cloud and extend either your first model or the one we provided in Lesson 2 with the following concepts. Use parts for component-like concepts, items for payload-like concepts, and attributes for attribute-like concepts.

• A magical cargo bay that can hold an arbitrary number of gifts (these are three new elements!)
• Weight of the cockpit and the cargo bay
• The color of Santa’s sleigh

Be sure to get definitions and usages right!

Once you are done, open “L03_SantaWorkshop_Challenge.sysml”. This model does not meet Santa’s standards, so if we don’t want to get on the naughty list, we need to clean it up.

First, format the model by running the auto-format feature. Tweak the result if necessary. Then, refactor the model such that common features of elves are moved into a base definition. Can we do this with all the elves? Consider pros and cons.

Summary

In this episode, you learned about definitions and usages, a core concept in SysML v2. You should now know when to use which and what happens if you mix them up. You also saw how you can refactor models in Syside manually and automatically. If you haven’t yet done so, it is now time to go to Syside Cloud to do the challenge. Don’t forget to come back tomorrow for another episode of the Advent of SysML v2!