ODRL V2.2 Implementation Best Practices

Prefix	Namespace	Description
odrl	http://www.w3.org/ns/odrl/2/	ODRL Vocabulary
rdf	http://www.w3.org/1999/02/22-rdf-syntax-ns#	[[rdf11-concepts]]
rdfs	http://www.w3.org/2000/01/rdf-schema#	[[rdf-schema]]
owl	http://www.w3.org/2002/07/owl#	[[owl2-overview]]
xsd	http://www.w3.org/2001/XMLSchema#	[[xmlschema11-2]]
skos	http://www.w3.org/2004/02/skos/core#	[[skos-reference]]
dcterms	http://purl.org/dc/terms/	[[dcterms]]
vcard	http://www.w3.org/2006/vcard/ns#	[[vcard-rdf]]
foaf	http://xmlns.com/foaf/0.1/	[[foaf]]
schema	http://schema.org/	schema.org
cc	https://creativecommons.org/ns#	creativecommons.org
ex	http://example.com/ns#

Scenarios

ODRL is a structured language to express that something is permitted, forbidden or obliged, possibly limited by some constraints. ODRL is of particular interest for representing computer policies, licenses and any document where deontic modalities need to have a digital form. ODRL was specified considering 27 use cases, nonetheless a few examples of use follow.

Scenario 1: Representation of common licenses

The use of common licenses has become popular among those publishing software, data, photographs and other resources online. These text licenses describe under which conditions the resource can be used. Examples of licenses are the GNU General Public License, the Creative Commons CC-BY 4.0 license, or the UK Open Government License. The key information in these text documents (waived rights, constraints, prohibitions and obligations) can be represented in a structured language (they have been actually represented in RDF, for example see the latter). ODRL can also be used to describe the core information in the licenses. Having the licensing information in a digital form enables:

Search-by-license. If resources are published along with an ODRL license, applications can be developed that perform a search-by-license, where one of the fields in a search form is the type of license of the resource, or the presence of a specific right or obligation (e.g. give me photos of Rome that I can publish in commercial applications ).
License compatibility. Some works are created as a derivation of two existing works. The licenses of the reused works can limit the license of the composite work, and even certain licenses are incompatible cannot be used in resources bundled together. The digital expression of rights favours smart applications to reason on license compatibility.
Reducing the impact of license proliferation. Even if the number of licenses has not stopped growing, having an ODRL version of non-famous licenses would enable their renderization using visual elements to make the license understandable in a glimpse.

Scenario 2: Representation of access policies to digital resources

Computer policies govern the access to digital resources. Whereas ODRL provides no mechanism whatsoever to implement any access control logic, ODRL policies can describe how an external access control system should behave. Advantages of having an ODRL representation of access policies:

Neutrality. ODRL is completely neutral about the technology used (if any) to grant access to a certain resource.
Extendability. New allowed actions and new constraints can be created. They can be arranged in a hierarchical form.

Scenario 3: Representation of rights in rules

Even if ODRL is not capable of accessing the subtleties of legislation, the actions that are forbidden in a certain sorts of noms can be represented in ODRL and act as a summary. See UC4. Advantages of an ODRL representation:

Summarization. Key actions that are prohibited or permitted are captured in an ODRL policy, hence favoring summarization.
Compliance checking. Business processes can be determined as compliant or non-compliant.

While ODRL can represent elements of a license or regulation for machine consumption, it cannot replace them in court! It is best practice to explicitly point to the license or regulation that a policy models using the dc:terms property provided by the Dublin Core Metadata Initiative.

Cookbook

Simple Permissions

How to represent a policy in JSON-LD

The following ODRL policy might be read as "Movie 9898 can be used".

Example 1

00  {
01	 "@context": "http://www.w3.org/ns/odrl.jsonld",
02	 "@type": "Set",
03	 "uid": "https://w3c.github.io/odrl/bp/examples/1",
04	 "permission": [{
05 		"target": "http://example.com/asset:9898.movie",
06 		"action": "use"
07	 }]
08  }

Explanation line by line:

An ODRL policy is represented as a JSON Object (lines 00 and 08). In particular, ODRL policies can be represented in JSON-LD -a lightweight Linked Data format.
The context of the JSON-LD policy is, as in every ODRL policy, http://www.w3.org/ns/odrl.jsonld (see line 01).
Type odrl:Set means this is positive assertion. Somebody affirms that Movie 9898 can be used (line 02).
The policy is identified as https://w3c.github.io/odrl/bp/examples/1. ODRL policies are best identified with URIs (see line 03).
ODRL policies have one or more rules: permissions, obligations, prohibitions (line 04). You may want to see the main ODRL diagram.
The target of the policy is the resource referenced by http://example.com/asset:9898.movie, probably a movie (line 05). Assets are best identified with URIs.
The permitted action on the asset is use (line 06). You may want to read its definition, or browse other possible actions predefined by the ODRL specs.

How to represent an ODRL policy with RDF Turtle

JSON-LD is only one of the possible serializations of ODRL a policy. The following example shows the same policy as in Example 1 but in RDF Turtle. An ODRL policy is an instance of the class odrl:Policy, which is defined in the ODRL Ontology. No knowledge on the ODRL Ontology is needed if you want to use ODRL.

Example 1 (turtle)

@prefix odrl: <http://www.w3.org/ns/odrl/2/>

<http://example.org/policy/1> a odrl:Policy, odrl:Set ;
  odrl:permission [
    odrl:target <https://w3c.github.io/odrl/bp/examples/1> ;
    odrl:assignee <http://example.com/party/Alice> ;
    odrl:action odrl:use
  ] ;

How to restrict the permission to a specified party

If the example above permitted the general use of Movie 9898, this permission permits only John to play the movie.

Example 2

{
 "@context": "http://www.w3.org/ns/odrl.jsonld",
 "@type": "Set",
 "uid": "https://w3c.github.io/odrl/bp/examples/2",
 "permission": [{
 	"target": "http://example.com/asset:9898.movie",
	"assignee": "John",
	"action": "play"
 }]
}

How to restrict the validity of a permission to a specific location

Photographs are often licensed on a geographic basis: global rights will likely be more expensive than a country-specific permission. Such conditions are frequently modelled in ODRL by Constraints. The way of representing a geographic entity has not been standardized, though.

Example 3

{
 "@context": "http://www.w3.org/ns/odrl.jsonld",
 "@type": "Set",
 "uid": "https://w3c.github.io/odrl/bp/examples/3",
 "permission": [{
 	"target": "http://example.com/asset:9898.movie",
	"action": "display",
	"constraint": [{
           "leftOperand": "spatial",
           "operator": "eq",
           "rightOperand":  "https://www.wikidata.org/resource/Q183",
	         "dct:comment": "i.e Germany"
       }]
 }]
}

How to restrict the validity of a permission to a specific time

Photographs for the news media can sometimes be "embargoed" - only publishable after a certain data. We can achieve this by putting a time-Constraint on the Permission.

The following permission can only be exercised after the turn of the New Year in 2019.

Example 4

{
 "@context": "http://www.w3.org/ns/odrl.jsonld",
 "@type": "Set",
 "uid": "https://w3c.github.io/odrl/bp/examples/4",
 "permission": [{
 	"target": "http://example.com/asset:9898.movie",
	"action": "display",
	"constraint": [{
           "leftOperand": "dateTime",
           "operator": "gte",
           "rightOperand":  { "@value": "2019-01-01", "@type": "xsd:date" }
       }]
 }]
}

How to restrict the validity of a permission to both a location and a time

We can easily create a permission that only allows the picture to be displayed in Germany after 2018 by adding both Constraints. In this simple scenario, ODRL insists both Constraints are satisfied before the Permission becomes active.

Example 5

{
 "@context": "http://www.w3.org/ns/odrl.jsonld",
 "@type": "Set",
 "uid": "https://w3c.github.io/odrl/bp/examples/5",
 "permission": [{
 	"target": "http://example.com/asset:9898.movie",
	"action": "display",
	"constraint": [{
           "leftOperand": "dateTime",
           "operator": "gte",
           "rightOperand":  { "@value": "2019-01-01", "@type": "xsd:date" }
	   }, {
           "leftOperand": "spatial",
           "operator": "eq",
           "rightOperand":  "https://www.wikidata.org/resource/Q183",
	   "comment": "i.e Germany"
       }]
 }]
}

How to narrow the applicability of an Action

The following Permission allows the distribution of a video but restricts the delivery channel to mobile networks only. This video cannot be distributed from a website under this Permission.

Example 6

{
    "@context": "http://www.w3.org/ns/odrl.jsonld",
    "@type": "Set",
    "uid": "https://w3c.github.io/odrl/bp/examples/6",
    "permission": [{
       "target": "http://example.com/asset:9898.movie",
       "assigner": "http://example.com/org:616",
       "action": [{
          "action": "distribute",
          "refinement": [{
             "leftOperand": "deliveryChannel",
             "operator": "eq",
             "rightOperand": "http://example.com/cv/audMedia/MOBILE"
          }]
      }]
   }]
}

Obligations and permissions

How to specify an obligation

This example shows how to oblige John to play the movie.

Example 7

{
 "@context": "http://www.w3.org/ns/odrl.jsonld",
 "@type": "Set",
 "uid": "https://w3c.github.io/odrl/bp/examples/7",
 "obligation": [{
	"target": "http://example.com/asset:9898.movie",
	"assignee": "John",
	"action": "play"
 }]
}

How to represent a prohibition

This example shows how to prohibit John playing the movie.

Example 8

{
 "@context": "http://www.w3.org/ns/odrl.jsonld",
 "@type": "Set",
 "uid": "https://w3c.github.io/odrl/bp/examples/8",
 "prohibition": [{
	"target": "http://example.com/asset:9898.movie",
	"assignee": "John",
	"action": "play"
 }]
}

How to represent a permission and a prohibition

An ODRL can represent one or more rules. For example, the following ODRL policy might be read as "Alice can use Asset 1, but Bob can't".

Example 9

{
	"@context": "http://www.w3.org/ns/odrl.jsonld",
	"@type": "Set",
	"uid": "http://example.org/policy/9",
	"permission": [{
		"target": "http://example.com/asset/1",
		"assignee": "http://example.com/party/Alice",
		"action": "use"
	}],
	"prohibition": [{
		"target": "http://example.com/asset/1",
		"assignee": "http://example.com/party/Bob",
		"action": "use"
	}]
}

Practical questions

How to simplify policies with more than one rule

ODRL policies with more than one rule can be simplified (Section 2.7.1 in the Information Model). Elements common to every rule can be expressed at root level. Policies making use of this feature are called compact policies, an example of them follows.

Example 10

{
	"@context": "http://www.w3.org/ns/odrl.jsonld",
	"@type": "Set",
	"uid": "http://example.org/policy/10",
	"action": "use",
	"target": "http://example.com/asset/1",
	"permission": [{
		"assignee": "http://example.com/party/Alice",
	}],
	"prohibition": [{
		"assignee": "http://example.com/party/Bob",
	}]
}

How to use the class hierarchy

Permitting (or prohibiting) some general actions entail permitting (or prohibiting) other specific actions. In the example below, permitting display is redundant because having permitted play also implies permitting display.

Example 11

{
	"@context": "http://www.w3.org/ns/odrl.jsonld",
	"@type": "Set",
	"uid": "http://example.org/policy/11",
	"permission": [{
		"assignee": "http://example.com/party/Alice",
		"action": [ "play", "display" ],
		"target": "http://example.com/asset/1"
	}]
}

The figure represents these dependencies.

Actions in the ODRL Core Vocabulary (and how they are dependant) Also, one action in the profile may declare that some other actions are necessary for their execution (using :implies), hence if the former is permitted the latter cannot be prohibited. Although the actions in the ODRL Core Vocabulary do not have these implications, and although the actions in the ODRL Core Vocabulary are hardly dependent from each other, this may be of interest if you some day want to define your own actions.

How to connect an odrl:Agreement with an odrl:Offer and an odrl:Request

A party publishes an odrl:Offer policy for the target data http://example.com/asset:1 and a second party makes an odrl:Request to that asset. The parties reach an agreement which is recorded using an odrl:Agreement.

The dcterms:references property should be used to connect the agreement with the offer and the request that originated it.

Example 12

			ex:offer a odrl:Offer ;
				odrl:uid <http://example.com/offer:1> ;
				odrl:permission [
					odrl:target <http://example.com/asset:1> ;
					odrl:assigner <http://example.com/party:A> ;
					odrl:action odrl:use
				] .

			ex:request a odrl:Request ;
				odrl:uid <http://example.com/request:1> ;
				odrl:permission [
					odrl:target <http://example.com/asset:1> ;
					odrl:assignee <http://example.com/party:B> ;
					odrl:action odrl:use
				] .

			ex:agreement a odrl:Agreement ;
				dcterms:references ex:offer, ex:request ;
				odrl:uid <http://example.com/agreement:1> ;
				odrl:permission [
					odrl:target <http://example.com/asset:1> ;
					odrl:assigner <http://example.com/party:A> ;
					odrl:assignee <http://example.com/party:B> ;
					odrl:action odrl:use
				] .

How to use inferences

As per RDFS entailment rule rdfs2, the class of the policy resource odrl:Policy can be inferred, hence its specification is not necessary. As per the ODRL Information Model (2.1.1 Set Class), Set is the default type of policy, hence its specification is not necessary. The policy shown in Example 3 is also equivalent to the policies in Example 1 (odrl prefix declaration has also been removed for clarity).

Example 13

<http://example.org/policy/13> odrl:permission [
  odrl:target <http://example.com/asset:9898.movie> ;
  odrl:action odrl:use
] ;

How to use hasPolicy

Alternative forms for the same policy are also possible. For example, one might want to attribute a certain policy to a certain asset. As specified in the ODRL Information Model, the following code would be equivalent. The RDF triple in line 02 of Example 3b may be stored in a content repository, whereas lines 03 through 06 may be stored in a license repository.

Example 14

01 @prefix dct: <http://purl.org/dc/terms/> 
02 <http://example.com/asset:9898.movie> odrl:hasPolicy <http://example.org/policy/14> .
03 <http://example.org/policy/14> odrl:permission [
04   odrl:target <http://example.com/asset:9898.movie> ;
05   odrl:action odrl:use
06 ] ;

How to embed a policy within a license

Let us imagine there is a license already in RDF, but with no embedded policies (like DPLA's license). In this case, an odrl:permission is added, provided that the upper resource is made to be a odrl:Policy too.

Example 15

  <http://rightsstatements.org/rs/ic-edu> a dcterms:RightsStatement , odrl:Policy ;
    skos:prefLabel "In Copyright - Educational Use Only"@en ;
    skos:definition "This digital object is protected by copyright and/or related rights. For educational uses, no additional copyright permission is required from the copyright holder. Please refer to the Data Provider for additional information."@en ;
    dc:creator: "Digital Public Library of America and Europeana Rights Working Group" ;
    dcterms:hasVersion "1.0" ;
    dcterms:modified "2014-12-18" ;
    dc:identifier "ic-edu" ;
    skos:relatedMatch premiscopy:cpr ;
    odrl:permission [
           odrl:action odrl:use ;
           odrl:constraint [
             odrl:operator odrl:eq ;
             odrl:purpose <http://rightsstatements.org/purpose/education> # This would be preferably from an existing namespace, not ours.
           ]
    ] .

Introduction

Document Conventions