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

• RDF Schema
• Best Practice: Enable Users to Specify URIs for Custom Attributes and Values