UML Model Organization with Packages and the Package Diagram

May 21, 2013

It is no coincidence that the package element in UML is represented by a folder icon, similar to directories in a file system Graphical User Interface (GUI).  Packages are used to organize the elements of a model just as folders are used to organize files.  The contents of a package are any kind of element that is part of a model, including other packages.  Beyond that description there’s not much more information on how to use packages in the UML specification.  Since they are a general grouping thing, it is up to usage scenarios to suggest what the best practices are for using packages.  There are some practices that apply in most situations, and more that depend upon the modeling methodology or the purpose of the model.

First and foremost, use packages to organize your model, regardless of the model purpose.  Even the most trivial model quickly becomes unmanageable without some kind of organization.  There is no single correct way to organize a model.  A modeler may choose to organize around process or product or some combination of the two.   Second, use the package diagram to provide visualizations of that organization.   The model browser view below illustrates how even a simple model can begin to be confusing with no organization of the model elements.

A model with no organizing principle appliedno_org
The same model with an organizing principle appliedorg

In addition to being able to gather like items together to allow modelers to focus their attention on relevant elements and make those elements easier to find in the browser, packages provide a namespace for the elements they contain.  Namespaces allow modelers to create unambiguous named references to each of the elements in a model.  This is useful in situations such as when a modeler is evolving a system and creating an as-is and a to-be system model.   It is natural to have elements named the same in each model.  In order to disambiguate elements with the same name, they can be placed in different packages so that the fully-qualified names are different.

Packages can be placed on a UML package diagram.  The modeler might choose to do this to present a high-level view of a model or to show relationships among the packages of elements.  Three different package diagrams representing the model organization shown above are presented here.  Each of these diagrams uses the optional diagram frame, showing the diagram type (pkg) and diagram name (Use Case View).  Note that although  the diagram and the package have the same name (Use Case View) this is not required.  In the first diagram, the two high-level packages are shown.  As with many other modeling situations, only the details we need are presented, and the details of the package contents are elided.


In the second diagram, the packages contained in the Actors package are shown.  The labels on the Human and Non-Human package describe the namespace of the containing package.  The containment relationship also serves to describe the namespace.  In this example, the fully qualified name of the Actor Operator is Use Case View::Actors::Human::Operator.


In the third diagram, the contents of the packages are shown embedded in the package elements.  This representation is the third presentation option found in the UML specification.


Your package diagrams will in all likelihood be some combination of each of these styles, as will your choice of organizing principles.  Choose the one that is appropriate for its intended use.

If you want to print this article there is a PDF attachment on the Sparx Community site –

Model Organization with Packages


Adapting SW Requirements Visualization to MBSE

October 25, 2011

I recently finished a nine-month assignment as a Product Manager working with Seilevel to define business requirements for several software projects.  Seilevel has an interesting approach to requirements visualization that they call the Requirements Modeling Language (RML®).  As I worked with their methodology I started to consider how the role of Product Manager or Business Analyst differed from the role of Requirements Engineer in the systems engineering world.  My initial conclusion is that they are very similar.  So similar in fact that I have begun to explore a mapping between the RML® diagrams and Unified Modeling Language (UML)/Systems Modeling Language (SysML) diagrams.  I will be presenting a tutorial on this topic at the INCOSE San Diego Chapter Mini-Conference on Nov. 18.  Here are some of my initial observations:

Advantages of RML®

  • The approach is inherently agile.  There are many types of diagrams but the descriptions include suggestions for when the requirements modeler should use each of the different diagram types and when they should not.
  • Requirements Visualization helps to eliminate ambiguity.  A picture is worth a thousand words, especially when the requirements modeler augments the picture with a few words of explanation.
  • RML® is not constrained to a requirements modeling language or tool, so it is very flexible.

Disadvantages of RML® in Model Based Systems Engineering (MBSE)

  • It is not constrained to a modeling language or tool, so the reader may misunderstand the semantics of the visualization.
  • Requirements Traceability is a separate model that can not take advantage of modeling tool capabilities.

Every system architecture or development methodology that I am familiar with (e.g. VAP, OOSEM, INCONIX) all have requirements as an initial input.  One of the often stated advantages of SysML was the ability to use models for developing those requirements, but most of the tutorial material seems to emphasize the interface between the modeling tools and the requirements management tools.  RML® seems to offer a proven methodology for using models to fulfill the vision of those developing SysML.  Future posts will include my thoughts as I work through how to adapt it to MBSE.