Guideline: Extending the Reusable Asset Specification
This guideline explains how to extend the Reusable Asset Specification (RAS) by creating profiles.
Relationships
Main Description

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.

  1. Define the Profile [required step]
  2. Create a UML Logical Model [optional step]
  3. Create a UML Physical Model [optional step]
  4. Create the XML Schema [required step]
  5. 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:

  1. Create a new package in the model to hold the profile.
  2. Create the model elements to describe the profile.
  3. 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:

  1. Copy the XML Schema of the ancestor profile and name it with the name of your profile.
  2. The asset node has an annotation that must be updated with the new profile information.
    1. The <xsd:appinfo xmlns:rasprofile ...> attribute should be updated with the declared namespace for the schema.
    2. The <rasprofile:profile name...> attribute should be updated with the new profile name.
    3. 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>

    4. The <rasprofile:profile version-major and version-minor...> attributes should be updated with the version information for the profile.
    5. The <rasprofile:profile parent...> attribute should be updated with a description of the profile.
    6. The <rasprofile:related-profile ...> attributes should be updated to point to the direct parent profile of your new profile. See the example above.
  3. Translate the UML Physical Model, if any, to the XML Schema document.
    1. 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.
    2. 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).