Appendix A: Legend for UML Modelling OMG UML General This annex explains the UML elements used in this specification. For more information, please refer to the comprehensive literature available for UML. The formal specification can be found in [35]. Figure 1 shows a class with name "Class1" and an attribute with name "attr" of type Class2. Attributes are owned by the class. Some of these attributes may represent the end of binary associations, see also Figure 8. In this case, the instance of Class2 is navigable via the instance of the owning class Class1.[1] Figure 1. Class Figure 2 shows that Class4 inherits all member elements from Class3. Or in other word, Class3 is a generalization of Class4, Class4 is a specialization of Class3. This means that each instance of Class4 is also an instance of Class3. An instance of Class4 has the attributes attr1 and attr2, whereas instances of Class3 only have the attribute attr1. Figure 2. Inheritance/Generalization Figure 3 defines the required and allowed multiplicity/cardinality within an association between instances of Class1 and Class2. In this example, an instance of Class2 is always related to exactly one instance of Class1. An instance of Class1 is either related to none, one, or more (unlimited, i.e. no constraint on the upper bound) instances of Class2. The relationship can change over time. Multiplicity constraints can also be added to attributes and aggregations. The notation of multiplicity is as follows: <lower-bound>.. <upper-bound> where <lower-bound> is a value specification of type Integer - i.e. 0, 1, 2, … - and <upper-bound> is a value specification of type UnlimitedNatural. The star character (*) is used to denote an unlimited upper bound. The default is 1 for lower-bound and upper-bound. Figure 3. Multiplicity A multiplicity element represents a collection of values. The default is a set, i.e. it is not ordered and the elements within the collection are unique and contain no duplicates. Figure 4 shows an ordered collection: the instances of Class2 related to an instance of Class1. The stereotype <<ordered>> is used to denote that the relationship is ordered. Figure 4. Ordered Multiplicity Figure 5 shows that the member ends of an association can be named as well, i.e. an instance of Class1 can be in relationship "relation" to an instance of Class2. Vice versa, the instance of Class2 is in relationship "reverseRelation" to the instance of Class1. Figure 5. Association Figure 6 shows a composition, also called a composite aggregation. A composition is a binary association, grouping a set of instances. The individuals in the set are typed as specified by Class2. The multiplicity of instances of Class2 to Class1 is always 1 (i.e. upper-bound and lower-bound have value "1"). One instance of Class2 belongs to exactly one instance of Class1. There is no instance of Class2 without a relationship to an instance of Class1. Figure 6 shows the composition using an association relationship with a filled diamond as composition adornment. Figure 6. Composition (Composite Aggregation) Figure 7 shows an aggregation. An aggregation is a binary association. In contrast to a composition, an instance of Class2 can be shared by several instances of Class1. Figure 7 shows the shared aggregation using an association relationship with a hallow diamond as aggregation adornment. Figure 7. Aggregation Figure 8 illustrates that the attribute notation can be used for an association end owned by a class. In this example, the attribute name is "attr" and the elements of this attribute are typed with Class2. The multiplicity, here "0..*", is added in square brackets. If the aggregation is ordered, it is added in curly brackets like in this example. Figure 8. Navigable Attribute Notation for Associations Figure 9 shows a class with three attributes with primitive types and default values. When a property with a default value is instantiated in the absence of a specific setting for the property, the default value is evaluated to provide the initial values of the property. Figure 9. Default Value Figure 10 shows that there is a dependency relationship between Class1 and Class2. In this case, the dependency means that Class1 depends on Class2 because the type of attribute attr depends on the specification of class Class2. A dependency is depicted as dashed arrow between two model elements. Figure 10. Dependency Figure 11 shows an abstract class. It uses the stereotype <<abstract>>. There are no instances of abstract classes. They are typically used for specific member elements that are inherited by non-abstract classes. Figure 11. Abstract Class Figure 12 shows a package named "Package2". A package is a namespace for its members. In this example, the member belonging to Package2 is class Class2. Figure 12. Package Figure 13 shows that all elements in Package2 are imported into the namespace defined by Package1. This is a special dependency relationship between the two packages with stereotype <<import>>. Figure 13. Imported Package Figure 14 shows an enumeration with the name "Enumeration1". An enumeration is a data type with its values enumerated as literals. It contains two literal values, "a" and "b". It is a class with stereotype <<enumeration>>. The literals owned by the enumeration are ordered. Figure 14. Enumeration[2] Figure 15 shows how a note can be attached to an element, in this example to class "Class1". Figure 15. Note Figure 16 shows how a constraint is attached to an element, in this example to class "Class1". Figure 16. Constraint UML Naming Rules The following rules are used for naming of classes, attributes etc.: all names use CamelCase; for exceptions see rules for Enumeration values, class names always start with a capital letter, attribute names always start with a small letter, primitive types start with a capital letter; exception: predefined types of XSD like string, enumerations start with a capital letter, names of member ends of an association start with a capital letter, all stereotypes specific to the Asset Administration Shell specification start with a capital letter, e.g. "<<Deprecated>>"; predefined stereotypes in UML start with a small letter, e.g. "<<abstract>>" or "<<enumeration>>". In UML, the convention is to name associations and aggregations in singular form. The multiplicity is to be taken into account to decide on whether there are none, a single, or several elements in the corresponding association or aggregation. Note: a plural form of the name of attributes with cardinality >=1 may be needed in some serializations (e.g. in JSON). In this case, it is recommended to add an "s". In case of resulting incorrect English (e.g. isCaseOf isCaseOfs), it must be decided whether to support such exceptions. Templates, Inheritance, Qualifiers, and Categories At first glance, there seems to be some overlapping within the concepts of data specification templates, extensions, inheritance, qualifiers, and categories introduced in the metamodel. This clause explains the commonalities and differences and gives hints for good practices. In general, an extension of the metamodel by inheritance is foreseen. Templates might also be used as alternatives. Extensions can be used to add proprietary and/or temporary information to an element. Extensions do not support interoperability. They can be used as work-around for missing properties in the standard. In this case, the same extensions are attached to all elements of a specific class (e.g. to properties). However, in general, extensions can be attached in a quite arbitrary way. Properties are defined in a predefined way as key values pairs (in this case keys named "name"). In contrast to extensions, templates aim at enabling interoperability between the partners that agree on the template. A template defines a set of attributes, each of them with clear semantics. This set of attributes corresponds to a (sub-)schema. Templates should only be used if different instances of the class follow different schemas and the templates for the schemas are not known at design time of the metamodel. Templates might also be used if the overall metamodel is not yet stable enough or a tool supports templates but not (yet) the complete metamodel. Typically, all instances of a specific class with the same category provide the same attribute values conformant to the template. In contrast to extensions, the attributes in the template have speaking names. Note: categories are deprecated and should no longer be used. However, when using non-standardized proprietary data specification templates, interoperability cannot be ensured and thus should be avoided whenever possible. In case all instances of a class follow the same schema, inheritance and/or categories should be used. Categories can be used if all instances of a class follow the same schema but have different constraints depending on their category. Such a constraint might specify that an optional attribute is mandatory for this category (like the unit that is mandatory for properties representing physical values). Realizing the same via inheritance would lead to multiple inheritance – a state that is to be avoided[3]. Note: categories are deprecated and should no longer be used. Qualifiers are used if the structure and the semantics of the element is the same independent of its qualifiers. Only the quality or the meaning of the value for the element differs. Value qualifiers are used if only the quantity but not the semantics of the value changes. Depending on the application, either both value and qualifier define the "real" semantics together, or the qualifier is not really relevant and is ignored by the application. Example: the actual temperature might be good enough for non-critical visualization of trends, independent of whether the temperature is measured or just estimated (qualifier would denote: measured or estimated). Concept qualifiers are used to avoid multiplying existing semantically clearly defined concepts with the corresponding qualifier information, e.g. life cycle. Template qualifiers are used to guide the creation and validation of element instances. Notes to Graphical UML Representation Specific graphical modelling rules, which are used in this specification but not included in this form, are explained below [35]. Figure 17 shows different graphical representations of a composition (composite aggregation). In Variant A, a relationship with a filled aggregation diamond is used. In Variant B, an attribute with the same semantics is defined. And in Variant C, the implicitly assumed default name of the attribute in Variant A is explicitly stated. This document uses notation B. It is assumed that only the end member of the association is navigable per default, i.e. it is possible to navigate from an instance of Class1 to the owned instance of Class2 but not vice versa. If there is no name for the end member of the association given, it is assumed that the name is identical to the class name but starting with a small letter – compared to Variant C. Class2 instance only exists if the parent object of type Class1 exists. Figure 17. Graphical Representations of Composite Aggregation/Composition Figure 18 shows different representations of a shared aggregation: a Class2 instance can exist independently of a Class1 instance; it only references the instances of Class2. Now an attribute with the same semantics is defined In Variant B. The reference is denoted by a star added after the type of the attribute. It is assumed that only the end member of the aggregation association is navigable per default, i.e. it is possible to navigate from an instance of Class1 to the owned instance of Class2 but not vice versa. Otherwise, variant B would not be identical to Variant A. Figure 18. Graphical Representation of Shared Aggregation A specialty in Figure 18 is that the aggregated instances are referables in the sense of the Asset Administration Shell metamodel (i.e. they inherit from the predefined abstract class "Referable"). This is why Variant B is identical to Variant A. This would not be the case for non-referable elements in the metamodel. The structure of a reference to a model element of the Asset Administration Shell is explicitly defined. A model reference consists of an ordered list of keys. The last key in the key chain shall reference an instance of type Class2 (i.e. Reference. Figure 19 show different graphical representations of generalization. Variant A is the classical graphical representation as defined in [35]. Variant B is a short form, if Class1 is not on the same diagram. The name of the class that Class3 is inheriting from is depicted in the upper right corner. Variant C not only shows which class Class3 instances are inheriting from, but also what they are inheriting. This is depicted by the class name it is inheriting from, followed by "::" and then the list of all inherited elements – here attribute class2. Typically, the inherited elements are not shown. Figure 19. Graphical Representation of Generalization/Inheritance Figure 20 depicts different graphical notations for enumerations in combination with inheritance. On the left side "Enumeration1" additionally contains the literals as defined by "Enumeration2". Note 1: the direction of inheritance is opposite to the one for class inheritance. This can be seen on the right side of Figure 20 that defines the same enumeration but without inheritance. Figure 20. Graphical Representation for Enumeration with Inheritance Note 2: in this specification all elements of an enumeration are ordered alphabetically. Figure 21 shows an experimental class, marked by the stereotype "Experimental”. Figure 21. Graphical Representation for Experimental Classes Figure 22 depicts a deprecated class, which is marked by the stereotype "Deprecated". Figure 22. Graphical Representation for Deprecated Elements Figure 23 shows a class representing a template. It is marked by the stereotype "Template". Figure 23. Graphical Representation of a Template Class 1. „Navigability notation was often used in the past according to an informal convention, whereby non-navigable ends were assumed to be owned by the Association whereas navigable ends were assumed to be owned by the Classifier at the opposite end. This convention is now deprecated. Aggregation type, navigability, and end ownership are separate concepts, each with their own explicit notation. Association ends owned by classes are always navigable, while those owned by associations may be navigable or not. [35]” 2. In Enterprise Architect, the single enumeration values also have a stereotype <<enum>> each. 3. Exception: multiple inheritance is used in this specification, but only in case of inheriting from abstract classes.