SysML v2 Naming Conventions
One of the great strengths of our SysML community in the learning club is how much we learn together. Every session reveals fresh insights, as we collectively explore better ways to structure and express models. From recurring patterns to subtle pitfalls, these shared experiences shape how we practice systems modeling in real-world settings.
A perfect example of this collaborative refinement is our evolving approach to naming conventions in SysML v2. Consistent, meaningful names make a huge difference in understanding complex models. Below are the guidelines we’ve adopted through thoughtful discussions in the club.
Naming in SysML v2 is more than just a stylistic concern—it’s fundamental for ensuring clarity, maintainability, and semantic precision in system models. Here are some key conventions to follow when naming elements in SysML v2:
1. Differentiate Between Definitions and Usages
A central concept in SysML v2 is the distinction between definitions and usages. This distinction should be reflected in naming:
- Definitions begin with an uppercase letter:
Example:Battery - Usages begin with a lowercase letter:
Example:battery : Battery
This immediately signals the role each element plays in the model.
2. Use Descriptive Usage Names
If the usage context adds clarity, name the usage after its function or purpose rather than copying the definition name:
- Good:
backupBattery : Battery - Avoid:
battery : Battery(if multiple batteries or roles exist)
Use names that explain why this element is here, not just what it is.
3. Ports: Use “Port” as a Postfix
When naming ports, always append the suffix Port to make the role explicit:
- Good:
PowerPort,FuelInPort,DataOutPort - Avoid:
Power,FuelIn,DataOut
This avoids ambiguity, especially since otherwise the name often represents only the things that flow, for example, Power.
4. Do Not Shorten Names Arbitrarily
Maintain full descriptive names for clarity:
- Prefer:
engineTemperatureSensor - Avoid:
engTempSens
If names get too long, define a short name that makes it convenient to use in textual notation or layout in graphical notation.
5. Do Not Skip Names
Every element, including usages, should be named—even if its role seems obvious. Unnamed elements can hinder understanding and traceability.
By following these naming conventions, your SysML v2 models will not only be syntactically correct but also easier to read, understand, and maintain. Consistent naming is especially crucial when collaborating across teams or domains.
These conventions are just a starting point—and they evolve with practice. What naming patterns have worked well in your models? Share your own conventions or ideas with the club—we’d love to learn from you too! Write a comment below or discuss your proposals with us in the learning club community, if you are a member.
