Best Practice: Enable Users to Specify URIs for Custom Attributes, Types, and Values

State: Approved

Contact: Arthur Ryman

Scope

Most Rational development tools allow administrative users to define custom properties, link types, enumerated values, and other similar data elements. These user-defined data elements are normally scoped to some context within the tools, e.g. to project areas within Rational Team Concert (RTC). Although this capability is very valuable to users, it leads to complexity when users need to query data that comes from multiple tools or multiple contexts within a tool.

For example, suppose the concept of priority is not built-in to a tool and that users at a company, Acme, have added it to two contexts as "Priority" in one and "Urgency" in the other. Furthermore, suppose the allowed values for this property are "High", "Medium" and "Low" in one context, and "P1", "P2", "P3", and "P4". A query such as "find all the high priority items in all contexts" now becomes problematic since the query author needs to know what each context means by high priority. Furthermore, when a new context is added, it might use yet another set of terms and so the query would need to be updated. This problem will become acute for Lifecycle Query Engine (LQE) since it combines data from multiple contexts.

The purpose of this recommendation is define a best practice for representing these user-defined data elements in RDF so that cross-context queries are easier to author and maintain.

This Best Practice is closely related to Best Practice: Use URIs to Represent Enumerated Values which discusses how to define enumerated values in RDF vocabularies.

Recommendation

Enable Users to Optionally Specify an External URI for Each Custom Name

Whenever a tool allows the addition of user-defined data elements, it MUST allow the user to optionally specify an HTTP URI for that data element, and the specified URI MUST be used in the RDF representation of all resources that contain the data element. The specified URI MAY be part of an industry standard such as Dublin Core (DC), Friend of a Friend (FOAF), or Open Services for Lifecycle Collaboration (OSLC), or it MAY be defined by the user's organization. If the URI is defined by the user's organization, then the user's organization SHOULD make it dereferencable via HTTP GET as per the W3C Best Practice Recipes for Publishing RDF Vocabularies.

Generate and Publish Default URIs When No External URI Is Specified

If the user does not specify the optional URI, then the tool MUST use a default generated HTTP URI. The generated URI SHOULD be as human-readable as possible. One method for achieving human-readability is to apply a human-friendly name mangling algorithm to the user-defined label for the data element. The tool MUST make the generated URI dereferencable via HTTP GET as per the W3C Best Practices for Publishing RDF Vocabularies. The published RDF vocabulary SHOULD include any relevant descriptive information provided the user as part of the data element definition, e.g. the label and description.

Example

Suppose Acme has defined a company-wide Application Lifecycle Management (ALM) RDF vocabulary that includes the following terms:

With this standard vocabulary, the desired SPARQL query for all high priority items is:

   SELECT ?item 
   WHERE {
      ?item <http://acme.example.com/ns/alm#priority> <http://acme.com/ns/alm#P1>
   }

The adminstrator of context 1 uses Priorty. The administrator of context 2 uses Urgency. The tool MUST therefore allow the administrators to specify the external URIs to the company standard ALM vocabulary as follows:

See Also

• W3C Best Practice Recipes for Publishing RDF Vocabularies
• Best Practice: Use URIs to Represent Enumerated Values