Copyright © 2008 International Business Machines Corp.



UML2 3.0 Migration Guide



This guide looks at the changes between UML 2.1.2 and UML 2.2 as defined by the OMG™.  The changes in the versions of UML® correspond to versions UML2 2.2.x and UML2 3.0.0 in the UML2 API.


By James Bruck, IBM
September 26, 2008



A few terms will be used throughout this document.



UML2 3.0.0

Latest version of the UML2 API.

UML2 2.2.x

Previous version of the UML2 API.

UML 2.2

This refers to the latest version of the UML specification defined by OMG available at:



Two important points to keep in mind:

·    The namespace URI for the UML metamodel in UML2 3.0.0  has changed to ( and corresponding updates to

·    API breaking changes have been made in this latest version so the major version number of the API has been increased to 3.0.0.

Summary of the changes

The following tables summarize the changes affecting the UML metamodel from versions 2.1.2 to 2.2.







·          StartObjectBehaviorAction 








·        ClearStructuralFeatureAction::result : OutputPin[0..1]

·        DecisionNode::decisionInputFlow : ObjectFlow[0..1]

·        WriteStructuralFeatureAction::result : OutputPin[0..1]





·        ClassifierTemplateParameter::defaultClassifier



             Default changed


·        Generalization::isSubstitutable



               Type Changed


·        TimeEvent::getWhen -> ValueSpecification  to TimeExpression   







               Made contained


·        Duration::expr

·       TimeExpression::expr



                   List  to Scalar



              Scalar to List


·        TemplateParameterSubstitution::actual[1..*]->[1]   

·        TemplateParameterSubstitution::ownedActual[0..*]->[0..1]   



·        ClassifierTemplateParameter::constrainingClassifier [0..1]->[0..*]

·        ComponentRealization::realizingClassifier[1] -> [1..*]





Default Values:



·          CallAction.isSynchronous = true








·          ClassifierTemplateParameter::getDefaultClassifier()

·          ClassifierTemplateParameter::setDefaultClassifier()





·          ActivityEdge::getWeight()    

·          Component::getRequireds()    



           Constraint added


·         ActivityParameterNode::validateMaximumOneParameterNode()

·         ActivityParameterNode::validateMaximumTwoParameterNodes()

·         ClearStructuralFeatureAction::validateTypeOfResult()

·         ClearStructuralFeatureAction::validateMultiplicityOfResult()

·         DecisionNode::validateDecisionInputFlowIncoming()

·         DecisionNode::validateIncomingControlOneInputParameter()

·         DecisionNode::validateIncomingOutgoingEdges()

·         DecisionNode::validateparameters()

·         DecisionNode::validateTwoInputParameters()

·         DecisionNode::validateZeroInputParameters()



 Constraint removed


·         DecisionNode::validateOneIncomingEdge()

·         DecisionNode::validateInputParameter()

·         MultiplicityElement::validateupperGt0



 Constraint changed


·        Behavior::getSpecification()

·        DecisionNode::validateEdges()

·        Transition::validateOutgoingPseudostates()









·          CallConcurrencyKind::GUARDED









·          Property no longer specializes TemplateableElement




Opening up older models

Models created using the older 2.2.x version of the API will seamlessly open up in the latest version of the UML editor.   The in-memory representation will comply with the latest metamodel changes.  If these models are subsequently saved, the updated in-memory representation will be persisted with an updated namespace URI.

 To update older models, simply open them using the UML editor and then save them.  Profiles and models should be opened and closed/saved so that the UML namespace URI will be updated. 


Model migration summary

Model migration involves mapping constructs from the older version of the metamodel to the newer.   There are several cases to consider for this particular mapping:


·   Features whose multiplicity have changed from lists to scalar

o  In such cases, the resource handler will take the last item out of the list.  The only instances concern situations where having more than one item didn’t make sense in the first place, therefore, dropping remaining items would be acceptable.

§   TemplateParameterSubstitution::actual

§   TemplateParameterSubstitution::ownedActual

·   Features whose multiplicities have changed  from scalar to list

o  Simply move the singular item to the new list.  

·   Features removed altogether:

o  In this case we map defaultClassifier to default from TemplateParameter if default was not previously set.  If default was set previously, we save the default classifier to a new stereotype.

§   ClassifierTemplateParameter::defaultClassifier. 

·   Losing features due to change of inheritance:

o  A profile will be created to capture the missing information. 

§   Property no longer inherits from TemplateableElement.


UML2 profile for unmapped features

A specialized profile is used to capture information that would otherwise be dropped since no direct mapping from the old metamodel to the new exists.

The profile in question resides in org.eclipse.uml2.uml.resources\profiles\UML2.profile.uml


3 new stereotypes with properties have been introduced:

·   A stereotype with metaclass extension to TimeEvent with:

o   when” meta-attribute : aggregation = composition.

·   A stereotype with metaclass extension to Property with:

o  tempateBinding” meta-attribute : aggregation = composition.

o  ownedTemplateSignature” meta-attribute : aggregation = composition.

·   A stereotype with metaclass extension to ClassifierTemplateParameter with:

o  “defaultClassifier” meta-attribute : aggregation = none.


Client code sweep

The following is a list of API modifications causing breakage.


·   Property no longer inherits from TemplateableElement

o  We lose:

§   createOwnedTemplateSignature()

§   createTemplateBinding()

§   getOwnedTemplateSignature()

§   getTemplateBindings()

§   isTemplate()

§   parameterableElements()

§   setOwnedTemplateSignature()

o  Migration path:

§   The functionality is removed and there is no direct API migration path.   The ability to use Property as a TemplateableElement is obscure however, and did not have much practical use in the past.

·   ClassifierTemplateParameter::defaultClassifier removed

o  We lose:

§   ClassifierTemplateParameter::getDefaultClassifier()

§   ClassifierTemplateParameter::setDefaultClassifier()

o  Migration path:

§   Should simply call ClassifierTemplateParamter::getDefault() or setDefault() inherited from TemplateParameter.

·   Multiplicities changing from list to scalar

o  Changed:

§   TemplateParameterSubstitution::actual

§   TemplateParameterSubstitution::ownedActual

o  Migration path:

§   Having multiple ‘actual’ or ‘ownedActual’ didn’t make sense in the past.  The collections should have been used with one item in all cases.

·   Mulitplicities changing from scalar to list

o  Changed:

§   ClassifierTemplateParameter::constrainingClassifier

§   ComponentRealization::realizingClassifier

o  MigrationPath:

§   Simply move the one item to the list.

·   Constraints removed

o  DecisionNode::validateOneIncomingEdge()

o  MultiplicityElement::validateUppperGT0()

o  DecisionNode::validateInputParameter()

o  Migration path:

§   Simply clean up removed functionality and references.




Constraint migration details


The details of constraint migration will have to be examined on a case-by-case basis and will not be addressed in detail by this document.   The following is a list of constraints that have been added, changed or removed:

·   Added

o  ActivityParameterNode::validateMaximumOneParameterNode()

o  ActivityParameterNode::validateMaximumTwoParameterNodes()

o  ClearStructuralFeatureAction::validateTypeOfResult()

o  ClearStructuralFeatureAction::validateMultiplicityOfResult()

o  DecisionNode::validateDecisionInputFlowIncoming()

o  DecisionNode::validateIncomingControlOneInputParameter()

o  DecisionNode::validateIncomingOutgoingEdges()

o  DecisionNode::validateparameters()

o  DecisionNode::validateTwoInputParameters()

o  DecisionNode::validateZeroInputParameters()

·   Changed

o  Behavior::getSpecification()

o  DecisionNode::validateEdges()

o  Transition::validateOutgoingPseudostates()

·   Removed

o  DecisionNode::validateOneIncomingEdge()

o  DecisionNode::validateInputParameter()

o  MultiplicityElement::validateupperGt0


Detailed Summary


The  following table indicates the changes to the UML metamodel in more detail.


OMG Issue







Remove constraint on MultiplicityElement that limited upper bound to be > 0. Now have ability to set the upper bound of a MultiplicityElement to 0.



  • Update constraint on MultiplicityElement.
  • deleted InfrastructureLibrary::Core::Abstractions::Multiplicities::MultiplicityElement::upper_gt_0

·         deleted InfrastructureLibrary::Core::Basic::MultiplicityElement::upper_gt_0

·         deleted InfrastructureLibrary::Core::Constructs::MultiplicityElement::upper_gt_0

·         deleted UML::Classes::Kernel::MultiplicityElement::upper_gt_0






The notation of operation has changed.  Multiplicity should now be part of the visual representation.


  • Labels for Operations should be looked at.






The meaning of redefinition has been clarified.  Explicitly states conformance of types.  Defines ‘explicit’ and ‘implicit’ redefinition.


  • Probably no impact but we should double check that we follow the guidelines.






Multiplicity of ComponentRealization::realizingClassifier has changed to [1..*] from [1]

updated documentation for UML::Components::BasicComponents::ComponentRealization::realizingClassifier


  • Changes to property sheets. 
  • Possible compare-merge impact.






The OCL constraint indicating how required and provided interfaces should be calculated has been updated.

Inherited ports also are taken into account. 


  • The OCL expression as shown in the spec. should follow the current UML implementation but a thorough review of the constraint would be needed.
  • This *may* impact the opensource UML component.

·         updated body constraint for UML::Components::BasicComponents::Component::provided()

·         updated body constraint for UML::Components::BasicComponents::Component::required()







These are the changes that were introduced to make certain properties derived (Vertex/Transition etc.)


  • We already have the implementation in place but the packages would have to be restructured and made part of the core implementation.

·         added UML::compositeStructures::InternalStructures::ConnectableElement::end() (10536)

·         added UML::StateMachines::BasicStateMachines::Vertex::outgoing() (10537)

·         added UML::StateMachines::BasicStateMachines::Vertex::incoming() (10537)

·         UML.uml will be changing as a consequence.






Added new feature for ClearStructuralFeatureAction.


Added WriteStructuralFeatureAction::result


  • Changes to open-source UML (meta-model)
  • Several new constraints to be implemented.

·         added documentation for UML::Actions::IntermediateActions::ClearStructuralFeatureAction::result

·         added UML::Actions::IntermediateActions::ClearStructuralFeatureAction::type_of_result

·         added UML::Actions::IntermediateActions::ClearStructuralFeatureAction::multiplicity_of_result

·         added documentation and new feature for UML::Actions::IntermediateActions::WriteStructuralFeatureAction::result

·         added UML::Actions::IntermediateActions::WriteStructuralFeatureAction::type_of_result

·         added UML::Actions::IntermediateActions::WriteStructuralFeatureAction::multiplicity_of_result






New metatype StartObjectBehaviorAction added.


  • Add new type for Activity Diagram palette.

·         lower bound of UML::Actions::CompleteActions::StartObjectBehaviorAction::object to 1

·         added documentation for UML::Actions::CompleteActions::StartObjectBehaviorAction

·         added documentation for UML::Actions::CompleteActions::StartObjectBehaviorAction::object

·         added UML::Actions::CompleteActions::StartObjectBehaviorAction::type_of_object

·         added UML::Actions::CompleteActions::StartObjectBehaviorAction::multiplicity_of_object

·         added UML::Actions::CompleteActions::StartObjectBehaviorAction::number_order_arguments

·         added UML::Actions::CompleteActions::StartObjectBehaviorAction::number_order_results

·         added UML::Actions::CompleteActions::StartObjectBehaviorAction::type_ordering_multiplicity_match







2 new constraints added to ActivityParameterNode


  • New constraints to be implemented.
  • added UML::Activities::BasicActivities::ActivityParameterNode::maximum_one_parameter_node
  • added UML::Activities::BasicActivities::ActivityParameterNode::maximum_two_parameter_nodes





9398 11240 11243 11400

Multiplicity on several template related features has been changed.


  • Affects templates

·         changed upper bound of UML::AuxiliaryConstructs::Templates::TemplateParameterSubstitution::ownedActual to 1 and updated  documentation (9398)

·         changed upper bound of UML::AuxiliaryConstructs::Templates::TemplateParameterSubstitution::actual to 1 and updated documentation (938)

·         updated documentation for UML::AuxiliaryConstructs::Templates::TemplateParameterSubstitution (9398)

·         updated documentation for UML::AuxiliaryConstructs::Templates::ClassifierTemplateParameter::constrainingClassifier (11243)

·         changed upper bound of ClassifierTemplateParameter::constrainingClassifier from 1 to *

·         ClassifierTemplateParameter::defaultClassifier was removed






New definition of DecisionNode.


  • New feature added.  
  • 8 new constraints added.

·         deleted UML::Activities::IntermediateActivities::DecisionNode::one_incoming_edge

·         deleted UML::Activities::IntermediateActivities::DecisionNode::input_parameter

·         updated specification of UML::Activities::IntermediateActivities::DecisionNode::edges

·          added UML::Activities::IntermediateActivities::DecisionNode::incoming_outgoing_edges

·         added UML::Activities::IntermediateActivities::DecisionNode::decision_input_flow_incoming

·         added UML::Activities::IntermediateActivities::DecisionNode::parameters

·         added UML::Activities::IntermediateActivities::DecisionNode::zero_input_parameters

·         added UML::Activities::IntermediateActivities::DecisionNode::incoming_object_one_input_parameter

·         added UML::Activities::IntermediateActivities::DecisionNode::incoming_control_one_input_parameter

  • added UML::Activities::IntermediateActivities::DecisionNode::two_input_parameters






One constraint on Transitions was changed.


  • Disallow junctions and joins to have triggers.
  • Constraint change.

·         updated specification for UML::StateMachines::BehaviorStateMachines::Transition::outgoing_pseudostates






Changed namespace URI’s for root packages of Lx models to ''







updated documentation for UML::CommonBehaviors::Communications::CallConcurrencyKind::concurrent

  • Opensource UML would have to update documentation on API.





updated documentation for UML::Activities::CompleteActivities::ActivityEdge::weight

  • Opensource UML would have to update documentation on API.





added default value for UML::Classes::Kernel::Generalization::isSubstitutable

  • Generalization::isSubstitutable should no longer be unsettable now that it has a default value.





updated documentation for UML::CommonBehaviors::BasicBahaviors::Behavior::specification

  • Opensource UML would have to update documentation.





TimeExpression::expr and Duration::expr are now composite.

  • This might require changes to tools an item providers





TimeEvent::when changed from ValueSpecification to TimeExpression

  • This will have migration impact





Property no longer specializes TemplateableElement

  • This results in API breaking changes since we are removing inherited features.
  • Was missed in a previous version of UML but corrected in this version.




For the most part, the migration from UML 2.1.2 to 2.2.0 should be straight forward.   Keep in mind that changes have been made to the API and the namespace URI in the serialized models has been updated.

 For more information on UML2, visit the home page or join the newsgroup.


 [1] Unified Modeling Language: Superstructure, version 2.2; formal/2008-05-05. OMG.


Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.