Introduction
As discussed in Concept: Reusable Asset Specification, the RAS Default profile can be used to
represent a spectrum of assets. This profile has been used to specify assets such as reference applications,
mechanisms, components, and documents. However, this flexibility can also mitigate some reuse benefits as certain asset
types require a rigor that could be missing. For instance, the specification of a component should always have a
description of the interface(s) that it implements, but the Default profile does not require an interface
specification and, therefore, leaves this to the asset producer (i.e., asset artifact developer or asset packager) to
provide.
What is needed is a more rigorous representation for significant types of assets, such as components and Web services.
This improves reusability through consistent organization and specification. As mentioned earlier, an asset is a
logical grouping of asset artifacts that provide a solution to a problem for a context. You use profiles to
describe certain kinds of assets and to identify specific asset artifacts that must be in an asset.
In this guideline, we describe how RAS is represented using models, as well as the steps for creating a RAS profile
using these models. Style guidelines that should be followed when developing a RAS profile are also described.
RAS Models
RAS is described from several perspectives by various models. One model is the UML Logical Model, which describes the
asset domain. Another model is the UML Physical Model, which describes the asset as it will be rendered in the XML
Schema.
The XML Schema defines the organization of the XML document, which serves as the asset's manifest or table of contents.
These models and schemas are manipulated when creating a new profile.
Steps To Create a RAS Profile
The following steps describe how to create a RAS profile. These steps do not describe the use of specific tools that
might exist to automate the process.
The XML Schemas and UML Models have been implemented with a certain style. As you extend these you should be aware of
the style and follow it where possible. Refer to the XML Schema Style and UML Model Style sections below.
-
Define the Profile [required step]
-
Create a UML Logical Model [optional step]
-
Create a UML Physical Model [optional step]
-
Create the XML Schema [required step]
-
Test the XML Schema [required step]
1. Define the Profile
This step is required. When you define the profile you also describe the core semantics of the asset type. This
includes defining the following:
-
The name of the profile.
-
The ancestry of the profile; this is the profile from which the new profile will be derived, such as the Default
profile.
-
The scope and intended audience of the profile.
-
A description of what is new/modified for each of the RAS sections.
-
Any classification scheme elements
-
The types of asset artifacts that the solution section should contain
-
Any specific usage rules
The outputs from this task are typically used to create documentation for future producers and consumers of the new
profile.
2. Create a UML Logical Model
This step is optional. The purpose of the step is to provide clarity of the domain of the asset type that is
being captured. At this point we express the new profile as a UML model. This model describes the domain of the profile
or, in other words, it is the domain model of the asset type.
This includes doing the following in the RAS UML model:
-
Create a new package in the model to hold the profile.
-
Create the model elements to describe the profile.
-
Identify the points where the new profile's ancestor profile should be extended and perform the extension.
The outputs from this task are typically used as input to the Create UML Physical
Model step.
3. Create a UML Physical Model
This step is optional. This model is a UML view of how the XML Schema will look. XML Schema does not support
inheritance relationships. The Logical Model is transposed into a collection of classes representing the
nodes that will appear in the XML Schema. The aggregation relationship is used to describe the containment of
nodes.
4. Create the XML Schema
This step is required. In this step you create the XML Schema file. Skipping the previous two steps skips
relevant analysis and design tasks on the profile.
A critical rule to follow in this step is: the semantics of the new profile's ancestry cannot be made more
constrained. This means, that if you are creating profile X and it derives from the RAS Default Profile, then profile X
cannot be more constrained than the RAS Default Profile. If this is needed then you create a profile that extends the
Core RAS.
To create the XML Schema for the new profile consider the following tasks:
-
Copy the XML Schema of the ancestor profile and name it with the name of your profile.
-
The asset node has an annotation that must be updated with the new profile information.
-
The <xsd:appinfo xmlns:rasprofile ...> attribute should be updated with the declared namespace for
the schema.
-
The <rasprofile:profile name...> attribute should be updated with the new profile name.
-
The <rasprofile:profile id...> attribute should be updated with the new id for the profile. This is a
new GUID that is concatenated to the parent GUIDs. See the example below:
<xsd:appinfo xmlns:rasprofile="http://www.rational.com/ras/rasdefaultprofile2_0"
source="profile-history">
<rasprofile:profile name="Default"
id="F1C842AD-CE85-4261-ACA7-178C457018A1::31E5BFBF-B16E-4253-8037-98D70D07F35F" version-major="2"
version-minor="0" parent="F1C842AD-CE85-4261-ACA7-178C457018A1">
<rasprofile:description>This is the second major version of the default profile. This profile can
be accepted by XDE release 2 and later.</rasprofile:description>
<rasprofile:related-profile name="Core" id="F1C842AD-CE85-4261-ACA7-178C457018A1" version-major="1"
version-minor="0" parent="">The original base of Core RAS.</rasprofile:related-profile>
</rasprofile:profile>
-
The <rasprofile:profile version-major and version-minor...> attributes should be updated with the
version information for the profile.
-
The <rasprofile:profile parent...> attribute should be updated with a description of the profile.
-
The <rasprofile:related-profile ...> attributes should be updated to point to the direct parent
profile of your new profile. See the example above.
-
Translate the UML Physical Model, if any, to the XML Schema document.
-
When creating a schema for a profile, the existing profile elements must be preserved. They cannot be
deleted or altered. This step involves adding new nodes and attributes or modifying existing items that are
not part of the Default profile.
-
Provide a description on each node in the schema. If you create a new node called test-script then you
should create a short description in the schema on that node.
It is useful to create a description of the new profile.
5. Test the XML Schema
The schema should be instantiated and a sample XML document should be created and completed to validate the structure.
If possible, the document should be tested in a RAS-aware tool.
RAS Profile Style Guidelines
The RAS UML Models and the XML Schema, specifically the Default profile, have been developed with a particular style.
This section, which describes the style, should be followed when creating these models and schemas.
UML Model Style
-
Extend the Default profile using inheritance.
-
You may want to create a formal UML profile as well.
XML Schema Style
-
XML document IDs are captured in xsd:string attributes. This provides flexibility for using both document-only IDs
as well as external IDs, such as those from a particular tool that may be implementing RAS.
-
When creating the schema you must consider which nodes need to be global in the document. For instance, in the
Default profile the artifact node is a global node because it is used in many places throughout the schema.
-
When adding or modifying a node in the schema, add documentation to the node.
-
For each attribute in a node identify attribute name, type, and use (i.e., multiplicity).
|