10.3 Comments, Rationales, Problems, Stereotypes, Frames & Diagram Descriptions

10.3 Comments, Rationales, Problems, Stereotypes, Frames & Diagram Descriptions

Quick Reference: SysML enriches systems models through cross-cutting metadata and structural framing constructs. Comments use dog-eared note boxes connected by dashed lines without arrowheads (anchor lines). SysML standardizes two specialized comment stereotypes: «rationale» (capturing architectural justification) and «problem» (flagging unresolved defects or design issues). Stereotypes extend UML metaclasses with domain-specific semantics and tagged values. Every SysML diagram is bounded by a Diagram Frame with a standardized header (kind [type] name [diagramName]), whose perimeter can host boundary ports, parameter nodes, and interaction gates.

---

Informational Annotations: Comments and Note Anchors

In systems engineering, visual diagrams must convey both formal structural/behavioral logic and the contextual rationale that led to specific engineering decisions. In SysML, informal or human-readable textual descriptions are incorporated using Comments.

The Comment Element

• Graphical Notation: A rectangle with its upper-right corner folded over (a dog-eared note box).
• Content: Unstructured text, rich prose, hyperlinks, or mathematical expressions describing an element or diagram.
• Connection to Model Elements (The Anchor): A comment attaches to one or more annotated model elements using a dashed line without an arrowhead.

Exam Trap: On the certification exam, question distractors frequently refer to the comment connecting line as a "dependency line" or illustrate it with an open stick arrowhead. In standard SysML, the line connecting a comment to a model element is strictly an anchor line (annotatedElement reference in the metamodel) and must never have an arrowhead.

+-----------------------+
|       «block»         |
|   HydraulicPumpUnit   | - - - - - - - - - - - - - - +--------------------------+
+-----------------------+      (Dashed line,          | Standard SysML Comment:  |
| flowRate = 120 L/min  |       NO arrowhead)         | Operating envelope must  |
+-----------------------+                             | withstand 300 bar peak.  |
                                                      +--------------------------+

---

Specialized Comment Stereotypes: «rationale» and «problem»

SysML formally extends the basic UML Comment metaclass by providing two standardized, specialized stereotypes essential for systems engineering governance:

                          +-----------------------------+
                          |         UML Comment         |
                          +-----------------------------+
                                         ^
                                         |
                    +--------------------+--------------------+
                    | «stereotype»                            | «stereotype»
          +-------------------+                     +-------------------+
          |    «rationale»    |                     |     «problem»     |
          +-------------------+                     +-------------------+

1. The «rationale» Stereotype

• Purpose: Documents the underlying engineering justification, trade study results, mathematical analysis, or regulatory compliance reasoning behind a modeling choice.
• Visual Notation: A dog-eared note box displaying the stereotype keyword «rationale» at the top, followed by the explanatory justification text.
• Common Engineering Applications:
  • Justifying why a redundant dual-bus architecture was selected over a single bus.
  • Referencing a trade study report ID that determined battery chemistry.
  • Recording safety factor margins required by aerospace regulatory baselines.
• Attachment: SysML 1.2 says a rationale "can be attached to any model element including relationships," so it can sit on a «satisfy» dependency to cite the trade study behind a design decision.

2. The «problem» Stereotype

• Purpose: Flags a known design defect, unresolved technical question, anomalous behavior, safety hazard, or open issue requiring engineering remediation.
• Visual Notation: A dog-eared note box displaying the stereotype keyword «problem» at the top, followed by the issue description.
• Common Engineering Applications:
  • Documenting that thermal dissipation exceeds enclosure limits during peak processing.
  • Flagging an unverified interface protocol between two vendor-supplied subsystems.
  • Recording an unresolved test failure pending root-cause investigation.

Semantic Non-Intrusiveness

Both «rationale» and «problem» elements are non-executable informational metadata. They do not alter the behavioral execution semantics, state transitions, or token flows of the annotated elements. However, they provide rigorous traceability for systems audits and design reviews.

---

Constraints vs. Comments

Modelers must distinguish between informal explanatory notes and formal mathematical Constraints:

---

Stereotypes, Tagged Values, and SysML Profiles

SysML is itself a specialized profile of UML, created by defining stereotypes that adapt UML to systems engineering. Furthermore, systems engineering organizations routinely define their own custom Profiles to tailor SysML to specialized domains such as avionics, automotive safety (ISO 26262), medical devices, or defense systems.

1. Stereotypes

• Definition: A stereotype is a model construct that extends an existing UML or SysML metaclass (such as Block, Property, Operation, or Comment), adding domain-specific semantics.
• Visual Syntax: Rendered by placing the stereotype name enclosed within guillemets («stereotypeName») directly above or before the element's name.
• Example: In SysML, «block» is a stereotype extending the UML Class metaclass; «itemFlow» extends UML InformationFlow.

2. Tagged Values (Stereotype Properties)

• Definition: When a stereotype is defined, it can own attributes. When the stereotype is applied to a model element, these attributes are called Tagged Values.
• Visual Syntax: Displayed in one of two standardized formats:
  1. Inside curly braces beneath or beside the element name: {tag1 = value1, tag2 = value2}.
  2. Inside a dedicated compartment within the element's rectangle. SysML 1.2 allows a compartment labeled with the stereotype name in guillemets (e.g., «spaceQualified») listing that stereotype's property values.

+-------------------------------------------------------+
|                      «block»                          |
|                «radiationHardened»                    |
|                  FlightTelemetryCPU                   |
|       {radTolerance = 100kRad, safetyClass = A}       |
+-------------------------------------------------------+
| properties                                            |
|   clockFrequency : Frequency = 400 MHz                |
+-------------------------------------------------------+

---

Diagram Frames and Boundary Syntax

Every SysML diagram is encapsulated within an outer rectangular border called the Diagram Frame. The frame defines the boundary of the diagram canvas and establishes the structural or behavioral scope of the view.

The Standard Diagram Header Syntax

In the upper-left corner of the frame, a distinct header box displays a strictly structured text string:

kind [type] name [diagramName]

1. kind (Mandatory): A 2-to-3 letter lowercase mnemonic identifying the specific SysML diagram kind:
   • bdd (Block Definition Diagram)
   • ibd (Internal Block Diagram)
   • act (Activity Diagram)
   • stm (State Machine Diagram)
   • sd (Sequence Diagram)
   • req (Requirement Diagram)
   • uc (Use Case Diagram)
   • par (Parametric Diagram)
   • pkg (Package Diagram)
2. [type] (included when needed to remove ambiguity): The metaclass of the model element that encloses and owns the diagram content, enclosed in square brackets (e.g., [Block], [Activity], [StateMachine], [Interaction], [Package]).
3. name (always shown): The qualified or simple identifier of the specific model element owning the diagram (e.g., SpacecraftBus, ThermalControlActivity).
4. [diagramName] (Optional): A descriptive user-assigned title for this specific graphical view, enclosed in square brackets (e.g., [Internal Power Routing], [Nominal Telemetry Sequence]).

Boundary Elements on Diagram Frames

Crucially, the border of a diagram frame is not merely a visual border—it serves as the interface boundary of the enclosing model element. Across different diagram kinds, the frame border hosts specific boundary elements:

1. Internal Block Diagram (ibd): Boundary Ports
   • Small square port symbols drawn directly on the outer diagram frame represent ports belonging to the enclosing Block that owns the IBD.
   • Connectors inside the IBD attach to these boundary ports, routing internal signals from internal parts to external systems.
2. Activity Diagram (act): Activity Parameter Nodes
   • Rectangles drawn directly on the diagram frame border represent input and output parameters of the enclosing Activity.
   • Object flow arrows inside the activity originate from or terminate at these boundary parameter nodes.
3. Sequence Diagram (sd): Boundary Gates
   • Connection points placed on the frame border representing message endpoints that enter or exit the interaction from external contexts.
4. Frame Anchors for Annotations
   • An entire diagram can be annotated by attaching a Comment, «rationale», or «problem» dog-eared note directly to the diagram frame border via a dashed anchor line.
5. Other Border Elements
   • SysML 1.2 Annex A also lists entry and exit points on state machine frames and constraint parameters on constraint block frames.

Diagram Description and Diagram Usage

The MU100 coverage map names the diagram description alongside the header. SysML 1.2 Annex A defines it as a comment attached to the diagram frame (its Figure A.2 shows it at the top right of the frame) that can include:

The diagram description may also identify the view the diagram belongs to and the corresponding viewpoint (Section 1.2). Tools may present it in more detail.

SysML 1.2 also allows a diagram usage: a keyword such as «ContextDiagram» placed above the diagram kind in the heading to mark a specialized use of a diagram kind, for example a context diagram drawn as a uc, bdd, or ibd. Because a diagram is not a metaclass, this is a notation convention rather than a true stereotype.

---

Worked Real-World Example: Electric Vehicle Battery Management System (BMS)

Consider an Internal Block Diagram specifying the internal architecture of an EV Battery Pack:

• Diagram Header: ibd [Block] BatteryPack [Internal Cell Balancing Architecture]
• Boundary Ports on Frame:
  • pHighVoltage : HV_PowerPort positioned on the right vertical frame border.
  • pCAN : CAN_BusPort positioned on the bottom frame border.
• Stereotyped Component: The internal controller part bmsCore : BMS_Controller is stereotyped with «automotiveSafety» displaying tagged values {ASIL = ASIL_D, maxFailureRate = 10FIT}.
• Rationale Annotation: A dog-eared note labeled «rationale» is anchored via a dashed line to the cell balancing resistor circuit: "Passive cell balancing selected over active balancing based on trade study TS-BMS-04; satisfies volume, thermal envelope, and unit cost constraints."
• Problem Annotation: A dog-eared note labeled «problem» is anchored via a dashed line to the temperature sensor array: "Thermistor ADC sampling experiences severe EMI noise when inverter draws >300A; filtering capacitor revision required in Rev C."

This single diagram combines structural framing, interface boundaries, domain metadata (stereotypes and tags), and formal engineering rationale and issue tracking.

---

Summary Comparison of SysML Annotations & Stereotype Constructs

---

Diagram Frame Elements Across SysML Diagram Kinds

---

Exam Pitfalls & Misconceptions