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