# Diagrams and Elements Spec

This program creates diagrams that strive for compatibility to

- UML 2.5

- SysML 1.5

- MOF 1.4.1

In some cases, it deviates from these standards for several reasons:

- Reduce complexity to be able to handle such models in a small open source project

- Reduce feature-set to improve understandability of diagrams even to non-software-architects

- Reduce feature-set to enhance usability of the program

This section gives an overview on standards and implementation-status of crystal-facet-uml. It may be incomplete.

## Classifiers

Classifiers are the nodes in the model-graph.

The table shows the classifier types introduced by different specifications and a comment stating how this is implemented in crystal-facet-uml.

| Spec/Context | Comment
Block | SysML | Limitations: Compartment Order is "properties, operations" instead of "constraints, operations, receptions, parts, (bound) references, values, properties, stereotype-tagged-values, behavior, namespace, structure" Limitations: No labeled compartments Limitations: no Multiplicities of Block-Instances.
Constraint Block | SysML / Parametric | Limitations: Only the rounded-rect symbol is supported.
Node | UML / Deployment |
Subsystem/Boundary | UML / Use Case | A subsystem is a component with stereotype subsystem
Component | UML |
Part | UML |
Interface | UML |
Package | UML, SysML |
Class | UML | Limitations: No active classes
Object | UML |
Artifact | UML |
Comment | UML, SysML |
Image | UML, SysML | This element shows the image of its stereotype. It exists since version 1.48.0; cannot be used in version 1.47.0 and older. The description field is reserved. Use an additional comment if needed.
Stereotype | UML, SysML | This element declares a stereotype. It exists since version 1.47.0; cannot be used in version 1.46.0 and older. The description field is reserved for icon and template data. Use an additional comment to describe the stereotype. An image can be specified by stating lines and curves according to the SVG-path spec version 2.0. `<path fill="#e0e0e0" stroke="#0088cc" d="M 2,2 10,2 8,8, 0,8 Z"/>` See examples at stereotype_examples
Requirement | SysML |
Actor | UML, SysML / Use Case, Sequence |
Use Case | UML, SysML / Use Case | Limitations: No SysML extension points
Interaction Use | UML / Interaction Overview | Hint: To easily find the referenced diagram, name the interaction use identical to the diagram. XMI-Export: For xmi export, this object may only occur in interaction diagrams: interaction overview, communication, sequence and timing.
Activity/Action | UML 2.5 (ch15.2) / Activity |
Interruptable Region | UML / Activity | XMI-Export: For xmi export, all regions belonging to the same set of activities need an outer, enclosing activity.
Fork | UML, SysML / Activity | XMI-Export: For xmi export, all activity-nodes belonging to the same set of activities need an outer, enclosing activity.
Join | UML, SysML / Activity | XMI-Export: For xmi export, all activity-nodes belonging to the same set of activities need an outer, enclosing activity.
Accept Event | UML, SysML / Activity | XMI-Export: For xmi export, all activity-nodes belonging to the same set of activities need an outer, enclosing activity.
Accept Time Event | UML, SysML / Activity | XMI-Export: For xmi export, all activity-nodes belonging to the same set of activities need an outer, enclosing activity.
Send Signal | UML, SysML / Activity | XMI-Export: For xmi export, all activity-nodes belonging to the same set of activities need an outer, enclosing activity.
Decision/Choice | UML 2.5 (ch14.2.4,15.3), SysML / Activity, State | In activity diagrams, this is called decision, in statesmachines it is called choice. XMI-Export/State-context: For xmi export, all states belonging to the same statemachine need an outer, enclosing state. XMI-Export/Activity-context: For xmi export, all activity-nodes belonging to the same set of activities need an outer, enclosing activity.
Initial Node | UML 2.5 (ch14.2.4), SysML / Activity, State | Limitations: There is no distinction in ActivityInitial and FlowInitial. XMI-Export/State-context: For xmi export, all states belonging to the same statemachine need an outer, enclosing state. XMI-Export/Activity-context: For xmi export, all activity-nodes belonging to the same set of activities need an outer, enclosing activity.
Final Node | UML 2.5 (ch14.2.4), SysML / Activity, State | Limitations: There is no distinction in ActivityFinal and FlowFinal. Limitations: There is no separate terminate state-type. XMI-Export/State-context: For xmi export, all states belonging to the same statemachine need an outer, enclosing state. XMI-Export/Activity-context: For xmi export, all activity-nodes belonging to the same set of activities need an outer, enclosing activity.
State | UML 2.5 (ch14.2), SysML / State, Timing | Limitations: No symbol for hidden decompositions, no regions (swimlanes) in composite states. Limitations: entry/exit/do list. XMI-Export: For xmi export, all states belonging to the same statemachine need an outer, enclosing state.
Shallow History | UML 2.5 (ch14.2.4), SysML / State | XMI-Export: For xmi export, all states belonging to the same statemachine need an outer, enclosing state.
Deep History | UML 2.5 (ch14.2.4), SysML / State | XMI-Export: For xmi export, all states belonging to the same statemachine need an outer, enclosing state.
Value Type | SysML | not supported. Limitations: Compartment Order of Classifiers is "properties, operations" instead of "operations, properties, stereotype-tagged-values"
Enumeration | UML, SysML | not supported. Note: Use a class instead.
ActivityParameterNode | SysML | not supported.
MergeNode/Junction | UML 2.5 (ch15.3), SysML / Activity, State | In activity diagrams, it is called merge, in state diagrams junction node. This is not supported. Note: You may directly connect the arrows to the target activity/state.
ActivityPartition | UML, SysML / Activity | not supported. Note: Use a parent activity instead.

An InstanceSpecification (UML) denotes an instantiation of a classifier. crystal-facet-uml allows any classifier to appear in different diagrams as classifier, as anonymous InstanceSpecification or as named InstanceSpecification. (Rationale: If a classifier is an instance may depend on the context: An M1-class may be an instance if shown in an M2-meta-class diagram, an XML-parser-class may be an instance if shown in the context of stream processors.)

## Features

Features are elements attached to one classifier.

The table shows the feature types introduced by different specifications, if they are visible in any diagram or just once, and a comment stating how this is implemented in crystal-facet-uml.

| Spec | Comment
Property | UML, SysML | Limitations: no SysML Flow-Properties refinement.
Operation | UML, SysML |
Provided Interface | UML, SysML |
Required Interface | UML, SysML |
Port | UML, SysML | Limitations: no SysML-compartment Notation supported. Limitations: no SysML-nested-ports, SysML-proxy-port, SysML full-ports supported. Limitations: no flow property, no compartment notation, no port-compartments. Limitations: no UML behavior ports.
Input Port/Pin | UML, SysML |
Output Port/Pin | UML, SysML |
State Entry | UML, SysML |
State Exit | UML, SysML |
Tagged Value | UML, SysML | Exists since version 1.47.0; cannot be used in version 1.46.0 and older.
Lifeline | UML 2.5 (ch17.2), SysML | Lifelines are managed automatically, one cannot create, modify or delete them. Limitations: One lifeline is visible only in one diagram. Limitations: Lifelines start and end only at diagram border.

## Relationships

Relationships are the edges of the model-graph.

The table shows the relationship types introduced by different specifications, a classification in which diagram type to use them preferably, and a comment stating how this is implemented in crystal-facet-uml.

| Spec/Context | Comment
Dependency | UML, SysML |
Containment | UML, SysML / Deployment, Package, Internal Block, Composite Structure, Activity, State |
Deploy | UML / Deployment |
Manifest | UML / Deployment |
Communication Path | UML, SysML / Component, Composite Structure, Block, Internal Block |
Association | UML, SysML / Class, Use Case | Note: SysML calls this ReferenceAssociation Limitations: no AssociationClass(SysML: ParticipantProperty) exists. Limitations: no AssociationEnd Classes exist, no multiplicities, no roles, no ownership (dot notation). Limitations: no ternary associations (only two ends supported). Limitations: no non-navigateable ends (crosses) suported yet - see todo.txt.
Aggregation | UML, SysML / Class | Note: SysML calls this SharedAssociation
Composition | UML, SysML / Class | Note: SysML calls this PartAssociation
Generalization | UML, SysML / Class | Limitations: no Generalization-Sets supported
Realization | UML / Class |
Trace | SysML / Requirement |
Refine | SysML / Requirement |
Extend | UML, SysML / Use Case | Limitations: no SysML-condition-notes can be attched to this relationship
Include | UML, SysML / Use Case |
Control Flow/Transition | UML, SysML / Activity, State | In activity diagrams, this is called control flow, in statesmachines it is called transition.
Object Flow | UML, SysML / Activity |
Async. Call | UML, SysML (?) / Sequence, Timing, Communication, Interaction overview |
Sync. Call | UML, SysML (?) / Sequence, Timing, Communication, Interaction overview |
Return Call | UML, SysML (?) / Sequence, Timing, Communication, Interaction overview | In sequence diagrams, an activation bar (execution specification) is shown above return calls
Connector | UML, SysML / Internal Block | not supported. Limitations: No Bi-directional Connectors Note: SysML calls this BindingConnector Note: Use a Communication Path instead.
Item Flow | SysML / Block Definition | not supported. Note: Use an Object Flow instead.
Exception Flow | UML 2.5 (ch15.5) / Block Definition | Use a stereotype, e.g. a flow_exception as proposed in stereotype_examples

## Diagrams

Diagrams are views on the model-graph. They select classifiers and may filter their features and relationships.

The table shows the diagram types introduced by different specifications and a comment stating how this is implemented in crystal-facet-uml.

| Spec | Comment
List Diagram | - | This is an overview diagram showing only classifiers as a list. This diagram hides any feature and any relationship.
Box Overview Diagram | - | This is an overview diagram showing only 2-dimension-layouted classifiers. This diagram hides any feature and any relationship.
Block Definition Diagram | SysML |
Internal Block Diagram | SysML |
Parametric Diagram | SysML |
Deployment Diagram | UML |
Component Diagram | UML |
Composite Structure Diagram | UML |
Package Diagram | UML, SysML |
Class Diagram | UML |
Profile Diagram | UML |
Requirements Diagram | SysML |
Use Case Diagram | UML, SysML |
Interaction Overview Diagram | UML | Limitations: There is no link from Diagram-References to referenced Diagrams Containments cannot be shown in this diagram type This diagram hides any feature This diagram hides relationships except the messages of the shown scenario
Activity Diagram | UML 2.5 (ch15.2), SysML | Limitations: Swimlanes not supported
State Machine Diagram | UML, SysML |
Communication Diagram | UML | Containments cannot be shown in this diagram type This diagram hides any feature This diagram hides relationships except the messages of the shown scenario
Sequence Diagram | UML, SysML | This diagram hides any feature This diagram hides relationships except the messages of the shown scenario
Timing Diagram | UML | This diagram hides any feature This diagram hides relationships except the messages of the shown scenario

## Example stereotype images

For use as stereotype images, this section shows some generated svg-paths, licensed under Apache-2.0 or Public Domain at your choice.

Copy these xml-fragments to the description field of a stereotype-classifier in order to show these images next to all elements implemening the respective stereotype.

## Maximum stringlengths

All strings (names, descriptions, stereotypes) have a maximum length.

Ascii characters require one, most other characters two or three bytes. Current sizes in bytes are:

Classifiers:

- DATA_CLASSIFIER_MAX_NAME_LENGTH = 47,

- DATA_CLASSIFIER_MAX_STEREOTYPE_LENGTH = 47,

- DATA_CLASSIFIER_MAX_DESCRIPTION_LENGTH = 4095,

Features:

- DATA_FEATURE_MAX_KEY_LENGTH = 47, (name)

- DATA_FEATURE_MAX_VALUE_LENGTH = 255, (type)

- DATA_FEATURE_MAX_DESCRIPTION_LENGTH = 1023,

Relationships:

- DATA_RELATIONSHIP_MAX_NAME_LENGTH = 47,

- DATA_RELATIONSHIP_MAX_STEREOTYPE_LENGTH = 47,

- DATA_RELATIONSHIP_MAX_DESCRIPTION_LENGTH = 1023,

Diagrams:

- DATA_DIAGRAM_MAX_NAME_LENGTH = 47,

- DATA_DIAGRAM_MAX_STEREOTYPE_LENGTH = 47,

- DATA_DIAGRAM_MAX_DESCRIPTION_LENGTH = 8191,

In case the text your entered exceeds the string limit, you are warned that the string is truncated. Consider attaching a comment or a requirement element and move parts of the text there.