Issue 6927: UML 2 Super / Interactions / Ambiguous diagram tags (uml2-rtf) Source: Simula Research Laboratory (Mr. Bran Selic, selic(at)acm.org) Nature: Uncategorized Issue Severity: Summary: Diagrams have a frame and a tag that describes the kind of diagram. Most diagrams correspond to a portion of the metamodel, and in most cases there is a one-to-one correspondence between metamodel chapters and diagram types, although variants are allowed for special cases (such as 'package'). There are four kinds of diagrams showing interactions, each with its own unique contents and syntax: sequence diagrams, communications diagrams, interaction overview diagrams, and timing diagrams. Unlike the difference between class diagrams and package diagrams, for example, each of these is very different in appearance and content from the others, even though they allegedly all map to the same interaction model (which might be dubious in practice, given the very different content, but that's another matter). However, the examples all use the same tag, 'sd', for all of the kinds of interaction diagram. Clearly 'sd' is an abreviation for 'sequence diagram' and it is inappropriate for the other types. (The fact that it is an English-language abreviation is another problem that we will let pass for now.) It would seem that each kind of diagram should have its own tag, given that they have different syntax and usage. For example, we could use 'sd', 'cd', 'iod', and 'td' if we wish to keep the same abbreviated format. But in any case the tags should be different and they should be descriptive of the diagram, not the underlying modeling chapter. (The official tag for interaction diagrams as a group is 'interaction', not 'sd' (page 589), so 'sd' is already descriptive of just one variant.) If the argument is that you can tell apart the different variants of interaction diagram by looking at them, that argument would apply with even more force to the diagrams for different kinds of models, such as class diagrams, state machine diagrams, etc., so we wouldn't need tags at all. (Which may be true, and users will probably not bother most of the time, but let's at least get it right in the standard.) Resolution: Disposition: Deferred to UML 2.4 RTF Revised Text: Actions taken: January 23, 2004: received issue Discussion: While this is possibly a reasonable suggestion, it does not represent either a consistency fix or a clarification and is more appropriately resolved in some future revision. This is an overall discussion and not only for Interactions. The question is about two different aspects: 1. What should the tab keyword indicate? a. the type of diagram b. the object defined by the diagram c. irrelevant, the tab is only for naming End of Annotations:===== ubject: UML 2 Super / Interactions / Ambiguous diagram tags X-Mailer: Lotus Notes Release 6.0.2CF1 June 9, 2003 From: Branislav Selic Date: Fri, 23 Jan 2004 08:52:29 -0500 X-MIMETrack: Serialize by Router on D25ML05/25/M/IBM(Release 6.0.2CF1|June 9, 2003) at 01/23/2004 08:52:31, Serialize complete at 01/23/2004 08:52:31 Diagrams have a frame and a tag that describes the kind of diagram. Most diagrams correspond to a portion of the metamodel, and in most cases there is a one-to-one correspondence between metamodel chapters and diagram types, although variants are allowed for special cases (such as 'package'). There are four kinds of diagrams showing interactions, each with its own unique contents and syntax: sequence diagrams, communications diagrams, interaction overview diagrams, and timing diagrams. Unlike the difference between class diagrams and package diagrams, for example, each of these is very different in appearance and content from the others, even though they allegedly all map to the same interaction model (which might be dubious in practice, given the very different content, but that's another matter). However, the examples all use the same tag, 'sd', for all of the kinds of interaction diagram. Clearly 'sd' is an abreviation for 'sequence diagram' and it is inappropriate for the other types. (The fact that it is an English-language abreviation is another problem that we will let pass for now.) It would seem that each kind of diagram should have its own tag, given that they have different syntax and usage. For example, we could use 'sd', 'cd', 'iod', and 'td' if we wish to keep the same abbreviated format. But in any case the tags should be different and they should be descriptive of the diagram, not the underlying modeling chapter. (The official tag for interaction diagrams as a group is 'interaction', not 'sd' (page 589), so 'sd' is already descriptive of just one variant.) If the argument is that you can tell apart the different variants of interaction diagram by looking at them, that argument would apply with even more force to the diagrams for different kinds of models, such as class diagrams, state machine diagrams, etc., so we wouldn't need tags at all. (Which may be true, and users will probably not bother most of the time, but let's at least get it right in the standard.) Bran Selic Distinguished Engineer IBM Rational Software Subject: RE: ,gi, Discussion on issue 6927 - Ambiguous diagram tags Date: Fri, 12 Mar 2004 17:47:41 -0500 X-MS-Has-Attach: X-MS-TNEF-Correlator: Thread-Topic: Latest issues assignments and status spreadsheet Thread-Index: AcQG92rABoZlXPTRRF27wctiift3kQAAAjcgAGKbxgA= From: "Nikolai Mansurov" To: "Branislav Selic (E-mail)" , Hello all, I want to have a discussion on issue 6927 on diagram tags. Although the issue is originally raised on Interactions, there are similar inconsistencies throughout the spec. 6927 (attached below) is a request to add specific tags (diagram kinds) for Timing Diagram, Communication Diagram and Interaction Overview Diagram, in order to differenciate them from Sequence diagrams. I have investigated other Behavior chapters from this perspective, and found several inconsistencies across the board. Depending on the general feeling, issue 6927 can be solved in a more generic scope, i.e. aligning the "look and feel" of the graphicals notations for all 13 UML 2 diagrams; or can be solved in isolation, just within Interactions, in which case it will be easier to simply omit the tags altogether, as it is done elsewhere. Here are more detailed considerations, after that there is a proposal. There is an Appendix A. "Diagrams" that describes the common "look and feel" of UML 2 diagrams. It includes an optional rectangular frame, and a heading. The frame is used when the diagrammed element has "graphical border elements" (page 587). Frame is optional. If the frame is omitted, so is the heading. The heading is a string, contained in a name tag (rectangle with cutoff corner) in the upper topmost corner of the rectangle, with the following syntax: [] [] On page 589, it is said, that (by the way, there is a typo and an extra period before the colon): "UML diagrams may have the following kinds >>frame names<< as part of the heading.:" - activity - class - component - interaction - package - state machine - use case Then the text says: "Note - Short forms of these names should be also defined, e.g. pkg for package." When looking at the way different Behavior diagram notations are described in their corresponding sections, I've noticed the following INCONSISTENCIES: 1. Activities do not have an explicit definition of a diagram or a frame. There is activity notation for element Activity (page 289), also table 13 (graphical elements for containment) that includes a border (a rectangle with ROUNDED corners) and the name of the activity in the top left corner, but no kind, or little frame around the name. Activity has border elements (parameters), but the description does not mention how this is related to "frame" in Appendix A. The possibility of using a kind "activity" or a short form ("ad" ?) are not mentioned. This is inconsistent with appendix A. 2. State machines do not have an explicit definition of a diagram or a frame. There is notation for element State Machine (table 20), that refers to substate machines. Otherwise, there is no description for the notation of the behavioral state machine. There is however a paragraph of protocol state machines with an example of a diagram with a frame (rectangle with straight corners), the name of the state machine in the top left corner, and a little frame around the name. State machine diagram example are consistent with Appendix A, but they do not use a diagram kind name "state machine", or suggest a short form ("sm" ?). 3. Interactions do define an explicit graphical element called frame. Interactions always have an explicit tag "sd" in front of the name. Issue 6927 is about the same tag "sd" being used for Sequence Diagrams, Interaction Overview Diagrams, Timing Diagrams, and Communication Diagrams. Interactions are therefore consistent with Appendix A. "sd" kind is a short form of the full kind "interaction", I suppose. 4. Use cases do not define a graphical element for frame. Example on page 526 shows a Use Case Diagram at the center of which is a rectangle symbol and the name in top RIGHT corner, without a tag of a little frame around the name. The actor figures are outside. The notation is therefore inconsistent with Appendix A. ( I did not check structure diagrams. ) There is another issue - Appendix A says that the "taxonomy (Figure 464) provides a logical organization for the various major kinds of diagrams. However it does not preclude the mixing different kinds of diagram types, as one might do when one combines structural and behavioral elements (e.g. showing a state machine nested inside an internal structure). Consequently, the boundaries between different kinds of diagram types are not strictly enforced". The issue here is that a mixture of elements from different diagram kinds may soon loose its unambiguous meaning. Here is my proposal : 1. update Appendix A to mention all diagram names (include Composite Structure Diagram, Object Diagram, Deployment Diagram, Communication Diagram, Timing Diagram and Interaction Overview Diagram to the list at page 589 to align it with Figure 464). 2. change the text "may have the following kind name in the heading" to: "in case a full kind name is used in the heading, it should be one of the following" 3. change the "Note" sentence in Appendix A (remove word "should", and provide complete list of kinds, see below) 4. update the list of full as well as short kind names to include all leaf diagrams in Figure 464: full kind short kind diagram ---------------------------------------------------------------------------------- activity ad activity diagram sequence sd sequence diagram timing td timing diagram communication com communication diagram interaction overview iod interaction overview diagram state machine sm state machine use case ucd use case diagram class cd class diagram component cmp component diagram object obj object diagram package pkg package diagram deployment depl deployment diagram composite cs composite structure diagram As you see, there is a certain challenge in short kinds for diagrams, starting with a "c": communcation, class, component, composite structure. Another challenge here is to have a consistent rule for such short name. 5. make the major 13 major diagrams type kinds MANDATORY, with an explicit kind. It would be good to make it a COMPLIANCY POINT , actually. Mixing of elements from diagrams of different kinds can be allowed, but the standard diagram kind should not be used. It will become such "mixed" diagrams visually distinguishable. 6. It would be good to go through all chapters and unify the way diagrams are described, maybe tweaking the graphical notation, if necessary. -- activity diagrams (alignment with Appendix A) -- interaction diagrams (reference to Appendix A) -- state machines (reference to Appendix A) -- use cases (alignment with Appendix A) Any comments? Cheers, Nick ------------------------------------------------------------------------------------------------------------------------------------------ This is issue # 6927 UML 2 Super / Interactions / Ambiguous diagram tags Diagrams have a frame and a tag that describes the kind of diagram. Most diagrams correspond to a portion of the metamodel, and in most cases there is a one-to-one correspondence between metamodel chapters and diagram types, although variants are allowed for special cases (such as 'package'). There are four kinds of diagrams showing interactions, each with its own unique contents and syntax: sequence diagrams, communications diagrams, interaction overview diagrams, and timing diagrams. Unlike the difference between class diagrams and package diagrams, for example, each of these is very different in appearance and content from the others, even though they allegedly all map to the same interaction model (which might be dubious in practice, given the very different content, but that's another matter). However, the examples all use the same tag, 'sd', for all of the kinds of interaction diagram. Clearly 'sd' is an abreviation for 'sequence diagram' and it is inappropriate for the other types. (The fact that it is an English-language abreviation is another problem that we will let pass for now.) It would seem that each kind of diagram should have its own tag, given that they have different syntax and usage. For example, we could use 'sd', 'cd', 'iod', and 'td' if we wish to keep the same abbreviated format. But in any case the tags should be different and they should be descriptive of the diagram, not the underlying modeling chapter. (The official tag for interaction diagrams as a group is 'interaction', not 'sd' (page 589), so 'sd' is already descriptive of just one variant.) If the argument is that you can tell apart the different variants of interaction diagram by looking at them, that argument would apply with even more force to the diagrams for different kinds of models, such as class diagrams, state machine diagrams, etc., so we wouldn't need tags at all. (Which may be true, and users will probably not bother most of the time, but let's at least get it right in the standard.) Subject: RE: RE: ,gi, Discussion on issue 6927 - Ambiguous diagram tags Date: Fri, 12 Mar 2004 19:49:04 -0500 X-MS-Has-Attach: X-MS-TNEF-Correlator: Thread-Topic: RE: ,gi, Discussion on issue 6927 - Ambiguous diagram tags Thread-Index: AcQG92rABoZlXPTRRF27wctiift3kQAAAjcgAGKbxgAAA29nwA== From: "Pete Rivett" To: "Nikolai Mansurov" , "Branislav Selic (E-mail)" , Thanks for taking the time to share the analysis, Nick! However after a doubletake I have reached quite opposite conclusions. Despite appearances I think that the key point is that the kind in the diagram heading is the kind (in effect the metaclass) of the namespace depicted NOT the kind of the diagram. The list on p589 is a list of potential namespaces not a list of diagram types. This is explicit in the penultimate paragraph of p587: The heading of a diagram represents the kind, name and parameters of the namespace enclosing or the model element owning elements that are represented by symbols in the contents area. This is enforced by several of the figures e.g in figure 363, the caption says that on the left is a 'class diagram' but the kind in the frame says 'package'. And that the diagram on the right is a 'composite structure diagram' but the kind in the frame is 'class'. Thus the Issue is wrong in its first sentence when it says "Diagrams have a frame and a tag that describes the kind of diagram" and this seems to have influenced your analysis. So the interactions chapter is wrong/inconsistent with Appendix A in having 'sd' as the kind: it should have the metaclass of the element i.e. 'Interaction' or 'intcn'. Based on your analysis it is the only chapter to be inconsistent in this way. It would not necessarily be a bad idea to indicate the diagram type in the title. However that would require far more extensive rewriting of Appendix A. BTW I don't quite understand your proposed item 5. - what does it mean to "make the major 13 major diagrams type kinds MANDATORY, with an explicit kind". Does it mean that a compliant tool must support all 13 diagram types. And that moreover a compliant tool must support labeling of diagrams with their kind? Or does it mean that compliant tools must ensure all diagrams must have an explicit kind? Regards Pete PS While reading I spotted the following typos (not sure if they have been raised): p587 para 2 line 2 "UML diagrams contains graphical elements" (should be "contain") p587 para 5 line 1 "symbols defines the type" (should be "define") p587 last para "C1 and C1" (should be "C1 and C2") p588 para 1 line 2 "a graphical symbols" (should remove "a") p588 para 1 line 4 "assocition" Pete Rivett (mailto:pete.rivett@adaptive.com) Consulting Architect, Adaptive Inc. Dean Park House, 8-10 Dean Park Crescent, Bournemouth, BH1 1HL, UK Tel: +44 (0)1202 449419 Fax: +44 (0)1202 449448 http://www.adaptive.com -------------------------------------------------------------------------------- From: Nikolai Mansurov [mailto:nikolai@klocwork.com] Sent: Friday, March 12, 2004 10:48 PM To: Branislav Selic (E-mail); uml2-superstructure-ftf@omg.org Subject: RE: ,gi, Discussion on issue 6927 - Ambiguous diagram tags Hello all, I want to have a discussion on issue 6927 on diagram tags. Although the issue is originally raised on Interactions, there are similar inconsistencies throughout the spec. 6927 (attached below) is a request to add specific tags (diagram kinds) for Timing Diagram, Communication Diagram and Interaction Overview Diagram, in order to differenciate them from Sequence diagrams. I have investigated other Behavior chapters from this perspective, and found several inconsistencies across the board. Depending on the general feeling, issue 6927 can be solved in a more generic scope, i.e. aligning the "look and feel" of the graphicals notations for all 13 UML 2 diagrams; or can be solved in isolation, just within Interactions, in which case it will be easier to simply omit the tags altogether, as it is done elsewhere. Here are more detailed considerations, after that there is a proposal. There is an Appendix A. "Diagrams" that describes the common "look and feel" of UML 2 diagrams. It includes an optional rectangular frame, and a heading. The frame is used when the diagrammed element has "graphical border elements" (page 587). Frame is optional. If the frame is omitted, so is the heading. The heading is a string, contained in a name tag (rectangle with cutoff corner) in the upper topmost corner of the rectangle, with the following syntax: [] [] On page 589, it is said, that (by the way, there is a typo and an extra period before the colon): "UML diagrams may have the following kinds >>frame names<< as part of the heading.:" - activity - class - component - interaction - package - state machine - use case Then the text says: "Note - Short forms of these names should be also defined, e.g. pkg for package." When looking at the way different Behavior diagram notations are described in their corresponding sections, I've noticed the following INCONSISTENCIES: 1. Activities do not have an explicit definition of a diagram or a frame. There is activity notation for element Activity (page 289), also table 13 (graphical elements for containment) that includes a border (a rectangle with ROUNDED corners) and the name of the activity in the top left corner, but no kind, or little frame around the name. Activity has border elements (parameters), but the description does not mention how this is related to "frame" in Appendix A. The possibility of using a kind "activity" or a short form ("ad" ?) are not mentioned. This is inconsistent with appendix A. 2. State machines do not have an explicit definition of a diagram or a frame. There is notation for element State Machine (table 20), that refers to substate machines. Otherwise, there is no description for the notation of the behavioral state machine. There is however a paragraph of protocol state machines with an example of a diagram with a frame (rectangle with straight corners), the name of the state machine in the top left corner, and a little frame around the name. State machine diagram example are consistent with Appendix A, but they do not use a diagram kind name "state machine", or suggest a short form ("sm" ?). 3. Interactions do define an explicit graphical element called frame. Interactions always have an explicit tag "sd" in front of the name. Issue 6927 is about the same tag "sd" being used for Sequence Diagrams, Interaction Overview Diagrams, Timing Diagrams, and Communication Diagrams. Interactions are therefore consistent with Appendix A. "sd" kind is a short form of the full kind "interaction", I suppose. 4. Use cases do not define a graphical element for frame. Example on page 526 shows a Use Case Diagram at the center of which is a rectangle symbol and the name in top RIGHT corner, without a tag of a little frame around the name. The actor figures are outside. The notation is therefore inconsistent with Appendix A. ( I did not check structure diagrams. ) There is another issue - Appendix A says that the "taxonomy (Figure 464) provides a logical organization for the various major kinds of diagrams. However it does not preclude the mixing different kinds of diagram types, as one might do when one combines structural and behavioral elements (e.g. showing a state machine nested inside an internal structure). Consequently, the boundaries between different kinds of diagram types are not strictly enforced". The issue here is that a mixture of elements from different diagram kinds may soon loose its unambiguous meaning. Here is my proposal : 1. update Appendix A to mention all diagram names (include Composite Structure Diagram, Object Diagram, Deployment Diagram, Communication Diagram, Timing Diagram and Interaction Overview Diagram to the list at page 589 to align it with Figure 464). 2. change the text "may have the following kind name in the heading" to: "in case a full kind name is used in the heading, it should be one of the following" 3. change the "Note" sentence in Appendix A (remove word "should", and provide complete list of kinds, see below) 4. update the list of full as well as short kind names to include all leaf diagrams in Figure 464: full kind short kind diagram ---------------------------------------------------------------------------------- activity ad activity diagram sequence sd sequence diagram timing td timing diagram communication com communication diagram interaction overview iod interaction overview diagram state machine sm state machine use case ucd use case diagram class cd class diagram component cmp component diagram object obj object diagram package pkg package diagram deployment depl deployment diagram composite cs composite structure diagram As you see, there is a certain challenge in short kinds for diagrams, starting with a "c": communcation, class, component, composite structure. Another challenge here is to have a consistent rule for such short name. 5. make the major 13 major diagrams type kinds MANDATORY, with an explicit kind. It would be good to make it a COMPLIANCY POINT , actually. Mixing of elements from diagrams of different kinds can be allowed, but the standard diagram kind should not be used. It will become such "mixed" diagrams visually distinguishable. 6. It would be good to go through all chapters and unify the way diagrams are described, maybe tweaking the graphical notation, if necessary. -- activity diagrams (alignment with Appendix A) -- interaction diagrams (reference to Appendix A) -- state machines (reference to Appendix A) -- use cases (alignment with Appendix A) Any comments? Cheers, Nick ------------------------------------------------------------------------------------------------------------------------------------------ This is issue # 6927 UML 2 Super / Interactions / Ambiguous diagram tags Diagrams have a frame and a tag that describes the kind of diagram. Most diagrams correspond to a portion of the metamodel, and in most cases there is a one-to-one correspondence between metamodel chapters and diagram types, although variants are allowed for special cases (such as 'package'). There are four kinds of diagrams showing interactions, each with its own unique contents and syntax: sequence diagrams, communications diagrams, interaction overview diagrams, and timing diagrams. Unlike the difference between class diagrams and package diagrams, for example, each of these is very different in appearance and content from the others, even though they allegedly all map to the same interaction model (which might be dubious in practice, given the very different content, but that's another matter). However, the examples all use the same tag, 'sd', for all of the kinds of interaction diagram. Clearly 'sd' is an abreviation for 'sequence diagram' and it is inappropriate for the other types. (The fact that it is an English-language abreviation is another problem that we will let pass for now.) It would seem that each kind of diagram should have its own tag, given that they have different syntax and usage. For example, we could use 'sd', 'cd', 'iod', and 'td' if we wish to keep the same abbreviated format. But in any case the tags should be different and they should be descriptive of the diagram, not the underlying modeling chapter. (The official tag for interaction diagrams as a group is 'interaction', not 'sd' (page 589), so 'sd' is already descriptive of just one variant.) If the argument is that you can tell apart the different variants of interaction diagram by looking at them, that argument would apply with even more force to the diagrams for different kinds of models, such as class diagrams, state machine diagrams, etc., so we wouldn't need tags at all. (Which may be true, and users will probably not bother most of the time, but let's at least get it right in the standard.) To: "Pete Rivett" Cc: "Branislav Selic (E-mail)" , "Nikolai Mansurov" , uml2-superstructure-ftf@omg.org Subject: RE: RE: ,gi, Discussion on issue 6927 - Ambiguous diagram tags X-Mailer: Lotus Notes Release 6.0.2CF1 June 9, 2003 From: James E Rumbaugh Date: Fri, 12 Mar 2004 17:44:51 -0800 X-MIMETrack: Serialize by Router on D03NM118/03/M/IBM(Release 6.0.2CF2|July 23, 2003) at 03/12/2004 18:44:57, Serialize complete at 03/12/2004 18:44:57 I think it woud be better if the tag identified the type of diagram, not the type of the underlying model content. If you know the diagram type, the content type follows automatically, but not the reverse. A diagram is by nature a visual thing so we need to establish which kind of diagram we have so we can understand the visual syntax. For example, a timing diagram has very different syntax from an ordinary sequence diagram, and labeling them both interactions doesn't help much. In any case, labeling all interaction diagrams "sd" is clearly a bad idea. If it means "sequence diagram", then it should apply only to sequence diagram syntax, if it describes the underlying content then it should be "int" or something like that (because clearly most of the interaction diagrams are not sequence diagrams, so the "sd" abbreviation doesn't work). But I think users will be a lot happier if you name the diagram type, not the metamodel content. - Jim Rumbaugh "Pete Rivett" 03/12/2004 04:49 PM To "Nikolai Mansurov" , "Branislav Selic (E-mail)" , cc Subject RE: RE: ,gi, Discussion on issue 6927 - Ambiguous diagram tags Thanks for taking the time to share the analysis, Nick! However after a doubletake I have reached quite opposite conclusions. Despite appearances I think that the key point is that the kind in the diagram heading is the kind (in effect the metaclass) of the namespace depicted NOT the kind of the diagram. The list on p589 is a list of potential namespaces not a list of diagram types. This is explicit in the penultimate paragraph of p587: The heading of a diagram represents the kind, name and parameters of the namespace enclosing or the model element owning elements that are represented by symbols in the contents area. This is enforced by several of the figures e.g in figure 363, the caption says that on the left is a 'class diagram' but the kind in the frame says 'package'. And that the diagram on the right is a 'composite structure diagram' but the kind in the frame is 'class'. Thus the Issue is wrong in its first sentence when it says "Diagrams have a frame and a tag that describes the kind of diagram" and this seems to have influenced your analysis. So the interactions chapter is wrong/inconsistent with Appendix A in having 'sd' as the kind: it should have the metaclass of the element i.e. 'Interaction' or 'intcn'. Based on your analysis it is the only chapter to be inconsistent in this way. It would not necessarily be a bad idea to indicate the diagram type in the title. However that would require far more extensive rewriting of Appendix A. BTW I don't quite understand your proposed item 5. - what does it mean to "make the major 13 major diagrams type kinds MANDATORY, with an explicit kind". Does it mean that a compliant tool must support all 13 diagram types. And that moreover a compliant tool must support labeling of diagrams with their kind? Or does it mean that compliant tools must ensure all diagrams must have an explicit kind? Regards Pete PS While reading I spotted the following typos (not sure if they have been raised): p587 para 2 line 2 "UML diagrams contains graphical elements" (should be "contain") p587 para 5 line 1 "symbols defines the type" (should be "define") p587 last para "C1 and C1" (should be "C1 and C2") p588 para 1 line 2 "a graphical symbols" (should remove "a") p588 para 1 line 4 "assocition" Pete Rivett (mailto:pete.rivett@adaptive.com) Consulting Architect, Adaptive Inc. Dean Park House, 8-10 Dean Park Crescent, Bournemouth, BH1 1HL, UK Tel: +44 (0)1202 449419 Fax: +44 (0)1202 449448 http://www.adaptive.com -------------------------------------------------------------------------------- From: Nikolai Mansurov [mailto:nikolai@klocwork.com] Sent: Friday, March 12, 2004 10:48 PM To: Branislav Selic (E-mail); uml2-superstructure-ftf@omg.org Subject: RE: ,gi, Discussion on issue 6927 - Ambiguous diagram tags Hello all, I want to have a discussion on issue 6927 on diagram tags. Although the issue is originally raised on Interactions, there are similar inconsistencies throughout the spec. 6927 (attached below) is a request to add specific tags (diagram kinds) for Timing Diagram, Communication Diagram and Interaction Overview Diagram, in order to differenciate them from Sequence diagrams. I have investigated other Behavior chapters from this perspective, and found several inconsistencies across the board. Depending on the general feeling, issue 6927 can be solved in a more generic scope, i.e. aligning the "look and feel" of the graphicals notations for all 13 UML 2 diagrams; or can be solved in isolation, just within Interactions, in which case it will be easier to simply omit the tags altogether, as it is done elsewhere. Here are more detailed considerations, after that there is a proposal. There is an Appendix A. "Diagrams" that describes the common "look and feel" of UML 2 diagrams. It includes an optional rectangular frame, and a heading. The frame is used when the diagrammed element has "graphical border elements" (page 587). Frame is optional. If the frame is omitted, so is the heading. The heading is a string, contained in a name tag (rectangle with cutoff corner) in the upper topmost corner of the rectangle, with the following syntax: [] [] On page 589, it is said, that (by the way, there is a typo and an extra period before the colon): "UML diagrams may have the following kinds >>frame names<< as part of the heading.:" - activity - class - component - interaction - package - state machine - use case Then the text says: "Note - Short forms of these names should be also defined, e.g. pkg for package." When looking at the way different Behavior diagram notations are described in their corresponding sections, I've noticed the following INCONSISTENCIES: 1. Activities do not have an explicit definition of a diagram or a frame. There is activity notation for element Activity (page 289), also table 13 (graphical elements for containment) that includes a border (a rectangle with ROUNDED corners) and the name of the activity in the top left corner, but no kind, or little frame around the name. Activity has border elements (parameters), but the description does not mention how this is related to "frame" in Appendix A. The possibility of using a kind "activity" or a short form ("ad" ?) are not mentioned. This is inconsistent with appendix A. 2. State machines do not have an explicit definition of a diagram or a frame. There is notation for element State Machine (table 20), that refers to substate machines. Otherwise, there is no description for the notation of the behavioral state machine. There is however a paragraph of protocol state machines with an example of a diagram with a frame (rectangle with straight corners), the name of the state machine in the top left corner, and a little frame around the name. State machine diagram example are consistent with Appendix A, but they do not use a diagram kind name "state machine", or suggest a short form ("sm" ?). 3. Interactions do define an explicit graphical element called frame. Interactions always have an explicit tag "sd" in front of the name. Issue 6927 is about the same tag "sd" being used for Sequence Diagrams, Interaction Overview Diagrams, Timing Diagrams, and Communication Diagrams. Interactions are therefore consistent with Appendix A. "sd" kind is a short form of the full kind "interaction", I suppose. 4. Use cases do not define a graphical element for frame. Example on page 526 shows a Use Case Diagram at the center of which is a rectangle symbol and the name in top RIGHT corner, without a tag of a little frame around the name. The actor figures are outside. The notation is therefore inconsistent with Appendix A. ( I did not check structure diagrams. ) There is another issue - Appendix A says that the "taxonomy (Figure 464) provides a logical organization for the various major kinds of diagrams. However it does not preclude the mixing different kinds of diagram types, as one might do when one combines structural and behavioral elements (e.g. showing a state machine nested inside an internal structure). Consequently, the boundaries between different kinds of diagram types are not strictly enforced". The issue here is that a mixture of elements from different diagram kinds may soon loose its unambiguous meaning. Here is my proposal : 1. update Appendix A to mention all diagram names (include Composite Structure Diagram, Object Diagram, Deployment Diagram, Communication Diagram, Timing Diagram and Interaction Overview Diagram to the list at page 589 to align it with Figure 464). 2. change the text "may have the following kind name in the heading" to: "in case a full kind name is used in the heading, it should be one of the following" 3. change the "Note" sentence in Appendix A (remove word "should", and provide complete list of kinds, see below) 4. update the list of full as well as short kind names to include all leaf diagrams in Figure 464: full kind short kind diagram ---------------------------------------------------------------------------------- activity ad activity diagram sequence sd sequence diagram timing td timing diagram communication com communication diagram interaction overview iod interaction overview diagram state machine sm state machine use case ucd use case diagram class cd class diagram component cmp component diagram object obj object diagram package pkg package diagram deployment depl deployment diagram composite cs composite structure diagram As you see, there is a certain challenge in short kinds for diagrams, starting with a "c": communcation, class, component, composite structure. Another challenge here is to have a consistent rule for such short name. 5. make the major 13 major diagrams type kinds MANDATORY, with an explicit kind. It would be good to make it a COMPLIANCY POINT , actually. Mixing of elements from diagrams of different kinds can be allowed, but the standard diagram kind should not be used. It will become such "mixed" diagrams visually distinguishable. 6. It would be good to go through all chapters and unify the way diagrams are described, maybe tweaking the graphical notation, if necessary. -- activity diagrams (alignment with Appendix A) -- interaction diagrams (reference to Appendix A) -- state machines (reference to Appendix A) -- use cases (alignment with Appendix A) Any comments? Cheers, Nick ------------------------------------------------------------------------------------------------------------------------------------------ This is issue # 6927 UML 2 Super / Interactions / Ambiguous diagram tags Diagrams have a frame and a tag that describes the kind of diagram. Most diagrams correspond to a portion of the metamodel, and in most cases there is a one-to-one correspondence between metamodel chapters and diagram types, although variants are allowed for special cases (such as 'package'). There are four kinds of diagrams showing interactions, each with its own unique contents and syntax: sequence diagrams, communications diagrams, interaction overview diagrams, and timing diagrams. Unlike the difference between class diagrams and package diagrams, for example, each of these is very different in appearance and content from the others, even though they allegedly all map to the same interaction model (which might be dubious in practice, given the very different content, but that's another matter). However, the examples all use the same tag, 'sd', for all of the kinds of interaction diagram. Clearly 'sd' is an abreviation for 'sequence diagram' and it is inappropriate for the other types. (The fact that it is an English-language abreviation is another problem that we will let pass for now.) It would seem that each kind of diagram should have its own tag, given that they have different syntax and usage. For example, we could use 'sd', 'cd', 'iod', and 'td' if we wish to keep the same abbreviated format. But in any case the tags should be different and they should be descriptive of the diagram, not the underlying modeling chapter. (The official tag for interaction diagrams as a group is 'interaction', not 'sd' (page 589), so 'sd' is already descriptive of just one variant.) If the argument is that you can tell apart the different variants of interaction diagram by looking at them, that argument would apply with even more force to the diagrams for different kinds of models, such as class diagrams, state machine diagrams, etc., so we wouldn't need tags at all. (Which may be true, and users will probably not bother most of the time, but let's at least get it right in the standard.) Date: Mon, 15 Mar 2004 13:45:46 +0100 From: Oystein Haugen User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.4) Gecko/20030624 Netscape/7.1 (ax) X-Accept-Language: en-us, en To: James E Rumbaugh CC: Pete Rivett , "Branislav Selic (E-mail)" , Nikolai Mansurov , uml2-superstructure-ftf@omg.org Subject: Re: ,gi, Discussion on issue 6927 - Ambiguous diagram tags X-MailScanner-Information: This message has been scanned for viruses/spam. Contact postmaster@uio.no if you have questions about this scanning X-UiO-MailScanner: No virus found X-UiO-Spam-info: not spam, SpamAssassin (score=1.219, required 12, HTML_20_30 0.47, HTML_FONTCOLOR_UNKNOWN 0.10, HTML_MESSAGE 0.00, HTML_TAG_EXISTS_TBODY 0.10, HTML_TITLE_EMPTY 0.54) X-UiO-Spam-score: s Jim, Nick, Bran, etc. I basically agree with Jim, but want to add a few comments. Historically we experiemented with both styles (tagging each individual diagram type, or tagging the metamodel content). The reasons for only using "sd" for Interaction diagrams are as follows: 1. Sequence Diagram is the dominant one of the interaction diagrams (all features of all other interaction diagrams can be expressed in the sequence diagram) 2. References (Interaction Use) in sequence diagrams or interaction overview diagrams or timing diagrams may refer to any interaction diagram, but not to other kinds of diagrams. 3. It was not simple to find a good abbreviation for "Interaction diagram" because "int" gives the wrong connotation for many people (associating 'int' with 'integer') I would prefer that all diagrams types were tagged, and that it was clear what symbols could go into each diagram. (I am a little uncertain how normative the selection of symbols given in the Diagrams sections are) Every diagram type should have the possibility to have a frame with the name given in a uniform manner. I have no strong feelings for the "sd" keyword even though I have to change many slides if it is changed (:-) Thanks, Oystein James E Rumbaugh wrote: I think it woud be better if the tag identified the type of diagram, not the type of the underlying model content. If you know the diagram type, the content type follows automatically, but not the reverse. A diagram is by nature a visual thing so we need to establish which kind of diagram we have so we can understand the visual syntax. For example, a timing diagram has very different syntax from an ordinary sequence diagram, and labeling them both interactions doesn't help much. In any case, labeling all interaction diagrams "sd" is clearly a bad idea. If it means "sequence diagram", then it should apply only to sequence diagram syntax, if it describes the underlying content then it should be "int" or something like that (because clearly most of the interaction diagrams are not sequence diagrams, so the "sd" abbreviation doesn't work). But I think users will be a lot happier if you name the diagram type, not the metamodel content. - Jim Rumbaugh "Pete Rivett" 03/12/2004 04:49 PM To "Nikolai Mansurov" , "Branislav Selic (E-mail)" , cc Subject RE: RE: ,gi, Discussion on issue 6927 - Ambiguous diagram tags Thanks for taking the time to share the analysis, Nick! However after a doubletake I have reached quite opposite conclusions. Despite appearances I think that the key point is that the kind in the diagram heading is the kind (in effect the metaclass) of the namespace depicted NOT the kind of the diagram. The list on p589 is a list of potential namespaces not a list of diagram types. This is explicit in the penultimate paragraph of p587: The heading of a diagram represents the kind, name and parameters of the namespace enclosing or the model element owning elements that are represented by symbols in the contents area. This is enforced by several of the figures e.g in figure 363, the caption says that on the left is a 'class diagram' but the kind in the frame says 'package'. And that the diagram on the right is a 'composite structure diagram' but the kind in the frame is 'class'. Thus the Issue is wrong in its first sentence when it says "Diagrams have a frame and a tag that describes the kind of diagram" and this seems to have influenced your analysis. So the interactions chapter is wrong/inconsistent with Appendix A in having 'sd' as the kind: it should have the metaclass of the element i.e. 'Interaction' or 'intcn'. Based on your analysis it is the only chapter to be inconsistent in this way. It would not necessarily be a bad idea to indicate the diagram type in the title. However that would require far more extensive rewriting of Appendix A. BTW I don't quite understand your proposed item 5. - what does it mean to "make the major 13 major diagrams type kinds MANDATORY, with an explicit kind". Does it mean that a compliant tool must support all 13 diagram types. And that moreover a compliant tool must support labeling of diagrams with their kind? Or does it mean that compliant tools must ensure all diagrams must have an explicit kind? Regards Pete PS While reading I spotted the following typos (not sure if they have been raised): p587 para 2 line 2 "UML diagrams contains graphical elements" (should be "contain") p587 para 5 line 1 "symbols defines the type" (should be "define") p587 last para "C1 and C1" (should be "C1 and C2") p588 para 1 line 2 "a graphical symbols" (should remove "a") p588 para 1 line 4 "assocition" Pete Rivett (mailto:pete.rivett@adaptive.com) Consulting Architect, Adaptive Inc. Dean Park House, 8-10 Dean Park Crescent, Bournemouth, BH1 1HL, UK Tel: +44 (0)1202 449419 Fax: +44 (0)1202 449448 http://www.adaptive.com -------------------------------------------------------------------------------- From: Nikolai Mansurov [mailto:nikolai@klocwork.com] Sent: Friday, March 12, 2004 10:48 PM To: Branislav Selic (E-mail); uml2-superstructure-ftf@omg.org Subject: RE: ,gi, Discussion on issue 6927 - Ambiguous diagram tags Hello all, I want to have a discussion on issue 6927 on diagram tags. Although the issue is originally raised on Interactions, there are similar inconsistencies throughout the spec. 6927 (attached below) is a request to add specific tags (diagram kinds) for Timing Diagram, Communication Diagram and Interaction Overview Diagram, in order to differenciate them from Sequence diagrams. I have investigated other Behavior chapters from this perspective, and found several inconsistencies across the board. Depending on the general feeling, issue 6927 can be solved in a more generic scope, i.e. aligning the "look and feel" of the graphicals notations for all 13 UML 2 diagrams; or can be solved in isolation, just within Interactions, in which case it will be easier to simply omit the tags altogether, as it is done elsewhere. Here are more detailed considerations, after that there is a proposal. There is an Appendix A. "Diagrams" that describes the common "look and feel" of UML 2 diagrams. It includes an optional rectangular frame, and a heading. The frame is used when the diagrammed element has "graphical border elements" (page 587). Frame is optional. If the frame is omitted, so is the heading. The heading is a string, contained in a name tag (rectangle with cutoff corner) in the upper topmost corner of the rectangle, with the following syntax: [] [] On page 589, it is said, that (by the way, there is a typo and an extra period before the colon): "UML diagrams may have the following kinds >>frame names<< as part of the heading.:" - activity - class - component - interaction - package - state machine - use case Then the text says: "Note - Short forms of these names should be also defined, e.g. pkg for package." When looking at the way different Behavior diagram notations are described in their corresponding sections, I've noticed the following INCONSISTENCIES: 1. Activities do not have an explicit definition of a diagram or a frame. There is activity notation for element Activity (page 289), also table 13 (graphical elements for containment) that includes a border (a rectangle with ROUNDED corners) and the name of the activity in the top left corner, but no kind, or little frame around the name. Activity has border elements (parameters), but the description does not mention how this is related to "frame" in Appendix A. The possibility of using a kind "activity" or a short form ("ad" ?) are not mentioned. This is inconsistent with appendix A. 2. State machines do not have an explicit definition of a diagram or a frame. There is notation for element State Machine (table 20), that refers to substate machines. Otherwise, there is no description for the notation of the behavioral state machine. There is however a paragraph of protocol state machines with an example of a diagram with a frame (rectangle with straight corners), the name of the state machine in the top left corner, and a little frame around the name. State machine diagram example are consistent with Appendix A, but they do not use a diagram kind name "state machine", or suggest a short form ("sm" ?). 3. Interactions do define an explicit graphical element called frame. Interactions always have an explicit tag "sd" in front of the name. Issue 6927 is about the same tag "sd" being used for Sequence Diagrams, Interaction Overview Diagrams, Timing Diagrams, and Communication Diagrams. Interactions are therefore consistent with Appendix A. "sd" kind is a short form of the full kind "interaction", I suppose. 4. Use cases do not define a graphical element for frame. Example on page 526 shows a Use Case Diagram at the center of which is a rectangle symbol and the name in top RIGHT corner, without a tag of a little frame around the name. The actor figures are outside. The notation is therefore inconsistent with Appendix A. ( I did not check structure diagrams. ) There is another issue - Appendix A says that the "taxonomy (Figure 464) provides a logical organization for the various major kinds of diagrams. However it does not preclude the mixing different kinds of diagram types, as one might do when one combines structural and behavioral elements (e.g. showing a state machine nested inside an internal structure). Consequently, the boundaries between different kinds of diagram types are not strictly enforced". The issue here is that a mixture of elements from different diagram kinds may soon loose its unambiguous meaning. Here is my proposal : 1. update Appendix A to mention all diagram names (include Composite Structure Diagram, Object Diagram, Deployment Diagram, Communication Diagram, Timing Diagram and Interaction Overview Diagram to the list at page 589 to align it with Figure 464). 2. change the text "may have the following kind name in the heading" to: "in case a full kind name is used in the heading, it should be one of the following" 3. change the "Note" sentence in Appendix A (remove word "should", and provide complete list of kinds, see below) 4. update the list of full as well as short kind names to include all leaf diagrams in Figure 464: full kind short kind diagram ---------------------------------------------------------------------------------- activity ad activity diagram sequence sd sequence diagram timing td timing diagram communication com communication diagram interaction overview iod interaction overview diagram state machine sm state machine use case ucd use case diagram class cd class diagram component cmp component diagram object obj object diagram package pkg package diagram deployment depl deployment diagram composite cs composite structure diagram As you see, there is a certain challenge in short kinds for diagrams, starting with a "c": communcation, class, component, composite structure. Another challenge here is to have a consistent rule for such short name. 5. make the major 13 major diagrams type kinds MANDATORY, with an explicit kind. It would be good to make it a COMPLIANCY POINT , actually. Mixing of elements from diagrams of different kinds can be allowed, but the standard diagram kind should not be used. It will become such "mixed" diagrams visually distinguishable. 6. It would be good to go through all chapters and unify the way diagrams are described, maybe tweaking the graphical notation, if necessary. -- activity diagrams (alignment with Appendix A) -- interaction diagrams (reference to Appendix A) -- state machines (reference to Appendix A) -- use cases (alignment with Appendix A) Any comments? Cheers, Nick ------------------------------------------------------------------------------------------------------------------------------------------ This is issue # 6927 UML 2 Super / Interactions / Ambiguous diagram tags Diagrams have a frame and a tag that describes the kind of diagram. Most diagrams correspond to a portion of the metamodel, and in most cases there is a one-to-one correspondence between metamodel chapters and diagram types, although variants are allowed for special cases (such as 'package'). There are four kinds of diagrams showing interactions, each with its own unique contents and syntax: sequence diagrams, communications diagrams, interaction overview diagrams, and timing diagrams. Unlike the difference between class diagrams and package diagrams, for example, each of these is very different in appearance and content from the others, even though they allegedly all map to the same interaction model (which might be dubious in practice, given the very different content, but that's another matter). However, the examples all use the same tag, 'sd', for all of the kinds of interaction diagram. Clearly 'sd' is an abreviation for 'sequence diagram' and it is inappropriate for the other types. (The fact that it is an English-language abreviation is another problem that we will let pass for now.) It would seem that each kind of diagram should have its own tag, given that they have different syntax and usage. For example, we could use 'sd', 'cd', 'iod', and 'td' if we wish to keep the same abbreviated format. But in any case the tags should be different and they should be descriptive of the diagram, not the underlying modeling chapter. (The official tag for interaction diagrams as a group is 'interaction', not 'sd' (page 589), so 'sd' is already descriptive of just one variant.) If the argument is that you can tell apart the different variants of interaction diagram by looking at them, that argument would apply with even more force to the diagrams for different kinds of models, such as class diagrams, state machine diagrams, etc., so we wouldn't need tags at all. (Which may be true, and users will probably not bother most of the time, but let's at least get it right in the standard.) -- Dr. Oystein Haugen Associate Professor Department of Informatics, University of Oslo P.O. Box 1080 Blindern N-0316 Oslo Norway Tel: +47 22 85 27 37 (office) Tel: +47 913 90 914 (mobile) http://folk.uio.no/oysteinh OMG Issue No: 6927 Title: UML 2 Super / Interactions / Ambiguous diagram tags Source: International Business Machines (Mr. Bran Selic, bselic@ca.ibm.com) Summary: Diagrams have a frame and a tag that describes the kind of diagram. Most diagrams correspond to a portion of the metamodel, and in most cases there is a one-to-one correspondence between metamodel chapters and diagram types, although variants are allowed for special cases (such as 'package'). There are four kinds of diagrams showing interactions, each with its own unique contents and syntax: sequence diagrams, communications diagrams, interaction overview diagrams, and timing diagrams. Unlike the difference between class diagrams and package diagrams, for example, each of these is very different in appearance and content from the others, even though they allegedly all map to the same interaction model (which might be dubious in practice, given the very different content, but that's another matter). However, the examples all use the same tag, 'sd', for all of the kinds of interaction diagram. Clearly 'sd' is an abreviation for 'sequence diagram' and it is inappropriate for the other types. (The fact that it is an English-language abreviation is another problem that we will let pass for now.) It would seem that each kind of diagram should have its own tag, given that they have different syntax and usage. For example, we could use 'sd', 'cd', 'iod', and 'td' if we wish to keep the same abbreviated format. But in any case the tags should be different and they should be descriptive of the diagram, not the underlying modeling chapter. (The official tag for interaction diagrams as a group is 'interaction', not 'sd' (page 589), so 'sd' is already descriptive of just one variant.) If the argument is that you can tell apart the different variants of interaction diagram by looking at them, that argument would apply with even more force to the diagrams for different kinds of models, such as class diagrams, state machine diagrams, etc., so we wouldn't need tags at all. (Which may be true, and users will probably not bother most of the time, but let's at least get it right in the standard.) Discussion: While this is possibly a reasonable suggestion, it does not represent either a consistency fix or a clarification and is more appropriately resolved in some future revision. Disposition: Defer