Defining URIs for artifact types, attributes, and other resources

Kathryn Fryer, IBM 
Last updated: July 2020
Build basis: IBM Engineering Lifecycle Management 6.x, 7.x

In many articles and best practice guidelines for IBM Engineering Lifecycle Management (ELM), we recommend defining URIs for artifact types, attributes, enumeration values, and so on. This becomes even more important when you use Lifecycle Query Engine (LQE) for reporting, and especially for applications like IBM DOORS Next Generation (DOORS Next) where types can vary greatly across project areas and configurations. In this article, we explore in more depth what it means to define URIs, what a URI consists of, and best practices in defining your own URI vocabularies, expanding upon the OASIS Open Services for Lifecycle Collaboration (OSLC) guidelines.

What is a URI anyways?

A “uniform resource identifier” (URI) identifies a particular resource unambiguously. In fact, a URL (like the address of this web page) is a type of URI. In this case, the “resources” in question are the artifact types, attributes, enumerations, relationships, and so on that describe your type system.

Two resources that have the same URI are considered to be the same. So for example, if you have Business Requirement artifacts in different project areas and they all use the same URI for that artifact type, the system considers those types to be the same – even if the project areas use different labels to describe the type (which is not recommended – ideally labels should be consistent too). Conversely, if one project area used a different URI or no URI at all, the system would consider the Business Requirement type in that project area to be a different resource type. Note: When no URI is specified, the system defines a unique value internally; leaving URI fields blank does not make them equivalent.

Inconsistent URI usage has impacts when you want to report across project areas: if each Business Requirement type has a unique URI, the system treats those as different artifact types. Report Builder would display multiple instances of Business Requirement, which makes it very challenging to select, set conditions, and filter by project area or component. The screen capture below shows an example where the Stability and Status attributes have been defined in different components with inconsistent URIs:

Report Builder showing attributes with conflicting URIs

The system also uses URIs when enforcing link constraints in DOORS Next. It becomes even more necessary to have consistent URIs when you enable configuration management and introduce the potential for multiple versions of the same types across components, configurations, and project areas.

Note: Where possible, keep labels consistent as well. If you use common URIs across components and project areas, but the labels differ (for example, one uses SW Requirement and another Software Requirement), Report Builder will choose one of the labels to display. You can’t currently control that choice.  If you are using configuration management, there are options as of version 7.0.1 to use a type system specific to a configuration; see the IBM Knowledge Centre for more details.

What does a URI look like?

When you specify a URI for a type resource, the syntax is similar to that of a URL:

http://domain-name.suffix/ns/path#identifier

where:

• domain-name.suffix/ns/path (everything that comes before the # sign) is the namespace. A namespace is a grouping for a set of related URIs, also known as a vocabulary.
  • domain-name is the domain that owns or defines the namespace, such as your company domain.
  • /ns/ is a convention that indicates a namespace.
  • path is one or more identifiers separated by / that characterize or describe the namespace.
• identifier is the string that identifies the specific resource. The collection of identifiers defined in a namespace is often called a vocabulary.

Note: While OSLC recommends using # to separate the identifier, some vocabularies use the / instead.

Here are some examples of URIs:

• http://open-services.net/ns/rm#Requirement
  • The domain name is open-services.net, which comes from the OASIS OSLC standards group; OSLC defines multiple namespaces in the open-services.net domain.
  • The path is rm, indicating the rm (requirements management) namespace.
  • The identifier is Requirement, identifying the Requirement artifact type or Class.
• http://jazz.net/ns/rm#Module
  • The domain name is jazz.net; ELM defines multiple vocabularies in this domain.
  • The path is rm, indicating the rm (requirements management) namespace. While the path segment is the same as the OSLC URI above, these are two different namespaces because the domain differs.
  • The identifier is Module, another artifact type.

These examples both use lifecycle discipline (requirements management) to group URI vocabularies. That is only one of many possible organizations for a namespace or vocabulary; you might choose to use organization, process, or some other logical grouping. For example, ELM recently introduced vocabularies that define terms that span the development lifecycle and the ELM suite, including software and systems engineering, enterprise agile, and automotive compliance. The LQE server has an index of vocabularies that it uses to establish resource shapes; you can find them on your own LQE server at http://server:port/lqe/web/admin/vocabularies.

How do you define URIs?

Defining URIs requires some understanding of your type system and the artifact types, attributes, and so on that you require. As described in other Jazz.net articles like Maintaining your DOORS Next type system, it’s important to be consistent and manage evolution across the organization.

Where possible, use existing URIs from published vocabularies like those defined by OSLC and jazz.net. These vocabularies are public to encourage reuse for semantically equivalent type resources. For new terms or extensions to existing definitions, you will define your own vocabularies with your own namespace and URIs. 

For example, if you have an enumeration for Risk Impact with values of Minor, Major, and Catastrophic, you could use URIs from the jazz.net/ns/ccm vocabulary: the enumeration URI would be http://jazz.net/ns/ccm#Impact, with values http://jazz.net/ns/ccm#ImpactMajor, http://jazz.net/ns/ccm#ImpactMinor, and because that vocabulary does not include a Catastrophic value, you would define your own such as http://myorg.com/ns/mynamespace#ImpactCatastrophic.

It doesn’t matter that you are mixing different namespaces, as long as you use the URIs themselves consistently across resources. You could use those same enum URIs and values for different attributes, such as Risk Impact and Actual Impact. You can even use the same URI in different applications or domains, for example, a single URI to represent a Priority attribute for both requirements and work items, or a single enum value for Unassigned that you use across multiple enumeration values. The following screen capture shows an example of defining a Rating scale enumeration type, with values defined by OSLC and jazz.net, that can be used for multiple attributes.

Example of defining enumeration with URIs in DOORS Next

For simplicity and ease of management, minimize the number of namespaces you define; you might need more than one, depending on the size and scope of your unique type resources. Use meaningful namespace identifiers. Avoid using specific tool or application names that could change over time or suggest restricted use.

There are a number of conventions typically used when defining URI vocabularies, to indicate semantics:

• Use camelCase for identifier names, where each new word is capitalized, without spaces and ideally without underscores.
• Artifact types, data types, and enumeration types usually start with an uppercase letter, as they are considered classes of objects. For example, http://jazz.net/ns/enterprise_agile#Epic or http://jazz.net/ns/ccm#Impact
• Enumeration values also start with an uppercase letter. Some vocabularies describe enum values as RDF individuals. As a good practice, consider making the enumeration values a variant of the enumeration identifier. For example, http://jazz.net/ns/ccm#ImpactMajor, http://jazz.net/ns/ccm#ImpactMinor.
• Attributes or properties start with a lowercase letter. For example, http://jazz.net/ns/process#isAccessPublic.
• Link types are also a kind of property and start with a lowercase letter. For example, http://open-services.net/ns/qm#implementsRequirement.

Where do we define URIs?

There are two aspects to consider: where you associate the URIs with the types in the ELM applications, and where you document your vocabularies so administrators know which URIs to specify where.

Other than Rhapsody Model Manager, which does not support user-defined types, each of the main ELM applications provides settings where an administrator can modify the type system, including specifying URIs:

In the settings related to types and attributes, you will find fields to enter the associated URI. The system or template might have populated some fields already. Remember if you leave a field blank, the system will generate a unique internal identifier that will likely differ from one generated in a different project area or component.

Specify URIs as soon as possible when you create new project areas or components. If you use project or component templates, include the URIs in the templates. That ensures they are always specified for the standard types and attributes you use and reduces opportunities for manual error. Teams who extend or customize the type system once instantiated will need to manually add URIs for the additions. In the GCM application, you can also export properties with URIs to import into a different project area, and DOORS Next supports importing type system properties from existing project areas or components.

Export and import type definitions in GCM application

Import properties (types) in DOORS Next application

Document your URI vocabulary with the semantics of how to apply the identifiers and namespaces. The OSLC and jazz.net vocabularies were formally documented based on the OASIS OSLC Guidelines and Best Practice: Publish RDF vocabularies. That vocabulary format includes syntax to reference other vocabularies or terms to provide semantic context. The guidelines also describe how to publish HTML pages to enable URIs to act like URLs; if you enter an OSLC or jazz.net URI in your browser address field, it resolves to an informational page specific to that vocabulary or namespace. For example, entering http://open-services.net/ns/rm#Requirement opens the following page:

OSLC HTML documentation for rm vocabulary

You can follow the same OSLC approach or provide something simpler like a text file or document. The important thing is to document your URIs and share them across your organization so that teams use them consistently.

Note: If you do formally define your vocabularies to resolve to a web page, make sure your URIs reflect your security model (http or https) and domain name so they resolve correctly.

You do not need to import your vocabulary into LQE. Once you add URIs to the type definitions in the ELM applications, the applications include the URIs in the Tracked Resource Set (TRS) feeds that LQE consumes.

You should also define any extension points for teams to extend your vocabulary, along with the process for further extending and evolving the vocabulary over time. Ideally, changes will be additive. While you want to reuse URIs for resources that are essentially the same, you should never repurpose an existing URI for a different resource. Similarly, changing the label associated with a URI can impact reporting.

Summary of best practices

In summary, using consistent URIs across type system resources is important for cross-project reporting as well as some linking scenarios. To promote consistency, follow the practices described in this article including:

• Define URIs for your type system elements in the ELM applications as early in adoption as possible.
• Reuse terms from existing vocabularies where possible, creating your own when needed.
• Keep labels consistent as much as possible.
• Document your vocabulary terms, including extension points, and ensure your teams use and adopt them.
• Incorporate URIs into your project area and component templates.
• Define processes for extending and evolving your vocabularies.

If you have issues with maintaining your type system, contact IBM Support or your IBM representative.

For more information

• OASIS OSLC Guidelines for defining URIs
• Managing project or component properties in requirements projects in the IBM Knowledge Centre
• Managing type definitions for the GCM application in the IBM Knowledge Centre
• Managing project properties in ETM in the IBM Knowledge Centre
• Maintaining the DOORS Next Generation type system in a configuration-management-enabled environment on Jazz.net

About the author

Kathryn Fryer is a Senior Solution Architect focused on the IBM Engineering Lifecycle Management solution, particularly around global configuration management. Drawing on 30 years at IBM in software development, management, and user experience, Kathryn works closely with clients and internal development and offering teams to develop usage models, aid adoption, and improve product offerings. She can be contacted at fryerk@ca.ibm.com.

© Copyright IBM Corporation 2020