r6 - 2015-10-14 - 07:33:51 - NickCrossleyYou are here: TWiki >  LinkedData Web > BestPractices > UseUrisForEnums
This wiki: The development wiki is a work area where Jazz development teams plan and discuss technical designs and operations for the projects at Jazz.net. Work items often link to documents here. You are welcome to browse, follow along, and participate. Participation is what Jazz.net is all about! But please keep in mind that information here is "as is", unsupported, and may be outdated or inaccurate. For information on released products, consult IBM Knowledge Center, support tech notes, and the Jazz.net library. See also the Jazz.net Terms of Use.

New product names: The CE/CLM products were renamed in version 7.0. For details on the name change, see Renaming the IBM Continuous Engineering Portfolio. Some content might continue to use the previous names or contain a combination of the previous and current names.

Best Practice: Use URIs to Represent Enumerated Values

State: Approved

Contact: Nick Crossley

Scope

When modelling data, it is a common requirement to restrict the allowed values of some property to an enumerated set. This Best Practice recommends that each allowed value be described in RDF by a URI and that this URI, like any other term in an RDF vocabulary, be described in a vocabulary document.

This recommendation applies both to the case where the vocabulary is an industry or corporate standard, or is automatically generated by a development tool. In all cases, the enumerated values should have URIs and these should be dereferenceable via HTTP GET to a vocabulary document.

This Best Practice is closely related to Best Practice: Enable Users to Specify URIs for Custom Attributes and Values which discusses using the URIs of enumerated values when customizing tools. In particular, if the URI of an enumeration may be chosen (and therefore modified) by a user, then consideration must be given to the impact of changes to the URI on indexing and similar applications.

Recommendation

In RDF, when a property has an enumerated set of allowed values, then those values should be represented as URIs. The meaning of these URIs should be described in an RDF vocabulary document. That is, to find the meaning of the URI, the URI should be dereferenced via HTTP GET and the meaning should be given using standard RDF vocabulary description properties such as rdfs:label and rdfs:comment.

If it is likely that the URI may change over time - perhaps it is a user-definable custom property - then it is better to use an immutable URI to represent the property value in each instance of the relevant data, and use owl:sameAs used to equate that immutable URI to one of the user's choosing.

Example

Let's assume that a fictitious company, Acme, decides to standardize the allowed values of priority to be "High", Medium", and "Low". The following RDF vocabulary (in Turtle format) assigns URIs to these values and describes them:

@prefix acme: <http://acme.example.com/ns/cm#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

acme:High rdfs:label "High" ;
   rdfs:comment "High priority items should be done before any other items." .

acme:Medium rdfs:label "Medium" ;
   rdfs:comment "Medium priority items should be done after high priority items." .

acme:Low rdfs:label "Low" ;
   rdfs:comment "Low priority items should be done after medium priority items." .

A work item might use these terms as follows:

<cr1> a oslc_cm:ChangeRequest ;
   dcterms:description "This is a high priority defect" ;
   jazz_cm:severity acme:High .

Alternatively, and better in cases like this where the user might change the URI, the vocabulary and the work item should be modeled along these lines:

@prefix acme: <http://acme.example.com/ns/cm#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

@prefix : <http://clm1.acme.example.com:8080/clm-server/generated-uris/3a819573c6761bf8/>

:12345678
   owl:sameAs acme:High ;
   rdfs:label "High" ;
   rdfs:comment "High priority items should be done before any other items." .

:12345679
   owl:sameAs acme:Medium ;
   rdfs:label "Medium" ;
   rdfs:comment "Medium priority items should be done after high priority items." .

:1234567a
   owl:sameAs acme:Low ;
   rdfs:label "Low" ;
   rdfs:comment "Low priority items should be done after medium priority items." .

and:

<cr1> a oslc_cm:ChangeRequest ;
   dcterms:description "This is a high priority defect" ;
   jazz_cm:severity <http://clm1.acme.example.com:8080/clm-server/generated-uris/3a819573c6761bf8/12345678> .

Note that owl:sameAs is symmetric. Query writers and report builders MUST NOT assume the vocabulary uses a specific direction for owl:sameAs - that is, the vocabulary above could equally well have been written:

@prefix acme: <http://acme.example.com/ns/cm#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

@prefix : <http://clm1.acme.example.com:8080/clm-server/generated-uris/3a819573c6761bf8/>

:12345678
   rdfs:label "High" ;
   rdfs:comment "High priority items should be done before any other items." .

:12345679
   rdfs:label "Medium" ;
   rdfs:comment "Medium priority items should be done after high priority items." .

:1234567a
   rdfs:label "Low" ;
   rdfs:comment "Low priority items should be done after medium priority items." .

acme:High owl:sameAs :12345678 .
acme:Medium owl:sameAs :12345679 .
acme:Low owl:sameAs :1234567a .

Out of Scope Features

This recommendation does not address the problem of representing the order of the enumerated values. This is a valid requirement but is not addressed here. Possible solutions include an order property (possibly rdf:value) or the use of RDF collections.

This recommendation does not require that the RDF vocabulary for the enumerated values include an RDF class whose members are the enumerated values. The vocabulary MAY include an RDF class and each enumerated value MAY be defined to be of that type.

This recommendation does not provide a representation for the mappings from any context-dependent local display values to the URIs, and does not recommend that the local display values be indexed by query engines, e.g. Lifecycle Query Engine (LQE). Local display values allow for customization of the user interface of the tool in some context. When queries are executed on data that comes from multiple contexts, the query should be written in a context-independent way using RDF terms that define the meaning of the enumerated values.

See Also

Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r6 < r5 < r4 < r3 < r2 | More topic actions
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding TWiki? Send feedback