IBM Rational Architecture Management Software model structure guidelines

22 January 2008 (First published 09 June 2005)

The way you organize the content of your models and the way you structure the storage of your models can be two of the biggest determinants of success for a modeling practice. In Part 1 of this series of articles, you will learn the terminology, concepts, principles, and best practices related to these concerns as they apply to the IBM® Rational® Eclipse-based UML modeling products. Subsequent articles in the series will provide suggestions for model content and organization corresponding to several modeling approaches, such as classic IBM® Rational Unified Process®, business-driven development for service-oriented architecture (SOA), and Model Driven Systems Development.

About this series

These model structure guidelines include four articles:

  • Part 1 covers basic information that is not specific to any one modeling style, and it also focuses on considerations of structuring models to support team modeling efforts.
  • Part 2 provides guidance specifically for a classic IBM® Rational Unified Process® modeling style.
  • Part 3 (not yet published) provides guidance specifically for a Business-Driven Architecture for SOA (service-oriented architecture) modeling style, which is sometimes referred to in this series as BDD4SOA
  • Part 4 (not yet published) provides guidance specifically for a Model Driven Systems Development (MDSD) modeling style.

Intended audience

These model structure guidelines are directed primarily to users of IBM® Rational® products that support Unified Modeling Language 2.0 (UML 2) modeling. At the time of this publication those products include IBM® Rational® Software Architect, IBM® Rational® Systems Developer, and IBM® Rational® Software Modeler. Within these guidelines, we will refer to such products collectively as "the products under discussion" or simply "the software." The guidelines focus primarily on concerns that are associated with creating a new set of models or with refactoring an existing set of models.

A secondary audience is those who use IBM® Rational® Rose or IBM® Rational® XDE and plan to migrate those models to the products under discussion. This audience may find the guidance helpful in restructuring imported models or in restructuring the Rational Rose or Rational XDE models before importing them.

If you use Rational Software Modeler, you will find this article useful, but some sections reflect capabilities available only in Rational Software Architect and Rational Systems Developer.

Scope and purpose

This guidance in this series explains general considerations for how to organize conceptual UML Model artifacts and content. It also offers specific guidelines for the internal organizational structures of those artifacts and covers these three basic modeling approaches:

  • Classic IBM® Rational Unified Process®
  • Business-Driven Development for SOA (service-oriented architecture), which we sometimes refer to as BDD4SOA
  • Model Driven Systems Development (MDSD)

The guidelines in this series are not meant to limit your thinking. They are meant to help you understand how to use the capabilities of the software to facilitate a process that seems best to you. The model structures described in this articles are guidelines, not imperatives. For instance, whether or not you decide to follow the classic Rational Unified Process modeling style, the BDD4SOA style, or another style is something that you must decide. More narrowly, whether or not you choose to model a particular construct within any of those approaches should also be a consideration of your own development process. These can (and possibly should) be project-specific decisions, as opposed to enterprise-wide decisions. Also, please recognize that Rational Unified Process itself is not a rigid set of process rules. It is a process framework within which you can formulate process definitions, which can range from very formal, or "heavy," to very flexible, or "lightweight."

Your choices of how to use UML Modeling can also range from very formal to very informal. You might choose to treat your models as formal architectural drawings that are to be strictly followed during construction. Or you might treat your models as sketches that suggest the broad outlines of a design, but are considered disposable when the project moves into implementation. The products under discussion can support you at either end of these process and modeling continuums. They also make it possible to use models not just as blueprints, but as specifications from which significant portions of an implementation can be automatically generated. This Patterns-Based Engineering (PBE) approach involves using model-to-model and model-to-code transformations. PBE can introduce special concerns regarding model structures.

Transformations are often designed with the expectation that the UML Models that serve as inputs conform to a particular UML syntax or "grammar." Such grammar might be enforced by the use of UML profiles and custom constraints, -- in effect, using a UML-based Domain Specific Language -- but it might also be no more than a set of stylistic conventions that you publish internally. If you will be using models and transformations to practice PBE, look for Rational PBE-specific resources in the Rational Architecture area of IBM® developerWorks® using search terms such as patterns and transformations.

Finally, this series is a guide to model organization, not a guide to developing the detailed content of models. For information on tool-specific techniques for developing the content of Rational models, see these other resources:

  • Product documentation (tutorials, samples, included Help)
  • Tool mentors in the Rational Unified Process configurations
  • Rational-related resources on IBM developerWorks

Prerequisite knowledge

Part 1 strives to nurture those who are quite new to modeling concepts. Some passages assume that you are familiar with the concepts and issues of team development in general. Other passages assume familiarity with specific software configuration management (SCM) solutions, but, again, the discussions strive to nurture those who do not already have such knowledge.

Parts 2, 3, and 4 assume that you have some knowledge of Unified Modeling Language (UML). If you are familiar with the elements of UML 2 that are listed in Table 1, you should have no difficulty understanding those parts, either. These parts also assume that you are familiar with some of the fundamental operational concepts of the products under discussion. If you are not, you can gain sufficient background by reading the portions of the "Overview" contents in the "Welcome" pages of those products, in particular the Welcome brochure titled "Different modeling approaches for different process philosophies." If you are coming from a Rational Rose or Rational XDE background, it may also help to read the developerWorks article called "The New IBM Rational Design and Construction Products for Rational Rose and Rational XDE Users" (see Resources).

Table 1. UML 2 elements
Diagram typesSemantic elements commonly associated with this type of diagram
Use caseActor, use case
ClassClass, interface, collaboration
ComponentComponent, subsystem, port, the concepts of provided and required interfaces
ActivityActivity, partition, control flow, object flow, action nodes (Initial, Final, Action, Accept Event), control nodes (Fork, Merge, Decision), object nodes (Central Buffer, Object, Data Store), and pins (Input, Output, Value)
Sequence, communication
DeploymentNode, artifact, communication path
Composite structurePart, port, connector
State machineNo detailed knowledge required
VariousAssociation, dependency, generalization, Role

Typographic conventions

Discussions that are likely to be of interest to readers who are migrating from IBM® Rational® Rose or IBM® Rational® XDE are highlighted in sidebars.

The articles strive to consistently capitalize the names of element types defined by the UML metamodel (for instance, Package, Component, or Class) to distinguish them from any of the various common meanings of those terms.

Note: For Version 6 users of Rational Software Architect, the corresponding earlier V6 paper (in English and other languages) is available for download. If you are a user of Rational Software Modeler V6, you will also find the paper useful but should be aware that some sections reflect capabilities available only in Rational Software Architect and not in Rational Software Modeler.


English (V7)ArchtMgt_SW_series_Part1.pdf318 KB
English (V7)ArchtMgt_SW_series_Part2.pdf3233KB
English (V6)rsa_model_structure_guidelines_eng.pdf2048 KB
Brazilian Portuguese (V6)rsa_model_structure_guidelines_braz.pdf1159 KB
French (V6)rsa_model_structure_guidelines_fra.pdf1224 KB
Japanese (V6)rsa_model_structure_guidelines_ja.pdf1258 KB
Korean (V6)rsa_model_structure_guidelines_ko.pdf4584 KB
Simplified Chinese (V6)rsa_model_structure_guidelines_chi.pdf1914 KB


SummaryTitle=IBM Rational Architecture Management Software model structure guidelines