Best Practices

From Permissions and Obligations Expression Working Group
Jump to: navigation, search

Introduction

This page gathers examples of use of ODRL, good practices and is intended to be a first cookbook. Examples are first given as Turtle, other serializations to come. For every Turtle excerpt that follows, the following prefix must be understood.

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

Examples

1. How to grant Alice the permission to use an asset (I)

The following ODRL policiy might be read as "Alice can use Asset 1".

<http://example.org/policy/1> odrl:permission [
  odrl:target <http://example.com/asset/1> ;
  odrl:assignee <http://example.com/party/Alice> ;
  odrl:action odrl:use
] ;
Figure1.jpg

2. How to grant Alice the permission to use an asset (II)

The property odrl:permission accepts as value either an action or an odrl:Permission. The following expression is also valid.

<http://example.org/policy/1> 
  odrl:permission odrl:use ;
  odrl:target <http://example.com/asset/1> ;
  odrl:assignee <http://example.com/party/Alice> ;
] ;
Figure2x.jpg

3. How to grant Alice the permission to use an asset (III)

The Dublin Core license predicate is used to infer the relationship between the Asset and the Policy. This practice is accepted within ODRL.

@prefix dct: <http://purl.org/dc/terms/> .
<http://example.com/asset/1> dct:license <http://example.org/policy/1> .
<http://example.org/policy/1> 
  odrl:permission odrl:use ;
  odrl:assignee <http://example.com/party/Alice> ;
] ;
Figure3.png

See also Example 1 of the vocab as of May (http://w3c.github.io/poe/vocab/)

4. How to declare a policy with permissions and prohibitions

The following ODRL policiy might be read as "Alice can use Asset 1, whereas Bob has it forbidden.".

<http://example.org/policy/1>
  odrl:target <http://example.com/asset/1> ;
  odrl:action odrl:use ;
  odrl:permission [
    odrl:assignee <http://example.com/party/Alice> ;
   ];
  odrl:prohibition [
    odrl:assignee <http://example.com/party/Bob> ;
] .

Please note that the asset and the target are now properties of the policy, and not properties of each rule. This is the preferred form if the result is more compact. But indeed, the alternative version is possible(target and action properties of each permission)

<http://example.org/policy/1> odrl:permission [
  odrl:target <http://example.com/asset/1> ;
  odrl:assignee <http://example.com/party/Alice> ;
  odrl:action odrl:use
];
odrl:prohibition [
  odrl:target <http://example.com/asset/1> ;
  odrl:assignee <http://example.com/party/Bob> ;
  odrl:action odrl:use ;
] .

In the following, the compact form will be used.

5. How to grant everybody the permission to use an asset

The following ODRL policiy might be read as "Everybody can use Asset 1".

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

In the absence of asignee, the rule affects every party.

6. How to forbid the use of an asset

The following ODRL policy might be read as "Nobody can use Asset 1".

<http://example.org/policy/1> odrl:prohibition [
  odrl:target <http://example.com/asset/1> ;
  odrl:action odrl:use
] ;

7. How to make an offer

The following ODRL policy might be read as "asset:9898.movie is offered to be played by party:org:abc".

<http://example.com/policy:1011>
   a odrl:Offer;
   odrl:permission [
     odrl:target <http://example.com/asset:9898.movie> ;
     odrl:assigner <http://example.com/party:org:abc> ;
     odrl:action odrl:play .
   ] .

This policy is based on Example 2 of http://w3c.github.io/poe/model/ Every offer must have an assigner.

8. How to declare a duty: payment

The following ODRL policy might be read as "Alice can play Asset1 but she must pay 5000 EUR".

<http://example.org/policy/1> odrl:permission [
  odrl:target <http://example.com/asset/1> ;
  odrl:assignee <http://example.com/party/Alice> ;
  odrl:action odrl:play ;
  odrl:duty [
    odrl:action odrl:compensate ;
    odrl:constraint [
      odrl:leftOperand odrl:payAmount ;
      odrl:operator odrl:eq ;
      odrl:rightOperand "5000.00" ;
      odrl:unit <http://cvx.iptc.org/iso4217a:EUR> ;    
    ] ;
  ] ;
] .

This policy is based on Example 3 of http://w3c.github.io/poe/vocab/#term-payAmount (original in XML).

Alternatively, other ways of referring to currencies are possible. Ex: https://www.currency-iso.org/dam/downloads/lists/list_one.xml#AUD

9. How to constrain assets and parties

The following ODRL policy might be read as "Anybody above 18 can play the asset".

<http://example.org/policy/1> odrl:permission [
  odrl:action odrl:play ;
  odrl:target <http://example.com/asset/AdultContent123> ;
  odrl:assignee [
    a odrl:CollectiveParty ;
    odrl:constraint [               
      odrl:leftOperand foaf:age ;
      odrl:operator odrl:ge ;
      odrl:rightOperand 18 
    ] ; 
  ] ;
] .

10. How to impose spatial constraints

The following ODRL policy might be read as "Asset1 cannot be played in France".

<http://example.org/policy/1> odrl:prohibition [
  odrl:action odrl:play ;
  odrl:target <http://example.com/asset/123> ;
    odrl:constraint [               
      odrl:leftOperand odrl:spatial ;
      odrl:operator odrl:eq ;
      odrl:rightOperand <http://www.itu.int/tML/tML-ISO-3166:fr> 
    ] ; 
  ] ;
] .

11. How to declare temporal restrictions

The following ODRL policy might be read as "Asset1 cannot be played before 2018.".

<http://example.org/policy/1> odrl:prohibition [
  odrl:action odrl:play ;
  odrl:target <http://example.com/asset/123> ;
    odrl:constraint [               
      odrl:leftOperand odrl:datetime ;
      odrl:operator odrl:eq ;
      odrl:rightOperand "2017-12-31"@xsd:dateTime 
    ] ; 
  ] ;
] .

The definition of datetime says it is at the time of execution.

12. How to impose an attribution duty

The following ODRL policy might be read as "Alice can distribute Asset1 as long as the Australia Gov. is attributed.".

<http://example.org/policy/1> odrl:permission [
  odrl:target <http://example.com/asset/1> ;
  odrl:assignee <http://example.com/party/Alice> ;
  odrl:action odrl:distribute ;
  odrl:duty [
    odrl:action odrl:attribute ;
    odrl:attributedParty <http://australia.gov.au/> .
  ] .

13. How to precise that parties are individuals or organizations

The following ODRL policy might be read as "Sony Music authorizes Billie to play Asset 1. Sony is an org, Billie a person.".

@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .
<http://example.org/policy/1> 
  odrl:permission odrl:play ;
  odrl:target <http://example.com/asset/1> ;
  odrl:assigner <http://example.com/org/sony-music> ;
  odrl:assignee <http://example.com/people/billie> .

<http://example.com/org/sony-music> a vcard:Organization, odrl:CollectiveParty ;
  vcard:fn "Sony Music LLC" ;
  vcard:hasEmail "sony-contact@example.com" .

<http://example.com/people/billie> a vcard:Individual, odrl:IndividualParty ;
  vcard:fn "Billie Zhan";
  vcard:hasEmail "billie@example.com" .

14. How to declare a compound constraint

The following ODRL policy might be read as "Asset1 can be played up to 100 times before 2018".

<http://example.org/policy/1> odrl:permission [
  odrl:action odrl:play ;
  odrl:target <http://example.com/asset/1> ;
    odrl:constraint [               
      odrl:leftOperand <http://example.org/constraint/1> ;
      odrl:operator odrl:andSequence ;
      odrl:rightOperand <http://example.org/constraint/2> 
    ] ; 
  ] ;
] .
<http://example.org/constraint/1> [
  odrl:leftOperand odrl:count ;
  odrl:operator odrl:lteq ;
  odrl:rightOperand "100"
] .

<http://example.org/constraint/2> [
  odrl:leftOperand odrl:dateTime ;
  odrl:operator odrl:lteq ;
  odrl:rightOperand "2017-12-31":xsd:dateTime 
] .

15. How to declare a profile is being used

The following ODRL policy might be read as "Dataset1 can be distributed but not rebased. LinkedData terms like "rebase" are defined in an external profile.".

@prefix void: <http://rdfs.org/ns/void#> .
@prefix ldr: <http://purl.oclc.org/NET/ldr/ns#> .

<http://example.com/dataset/1> a void:Dataset ;
  dct:license [ 
    odrl:profile ldr: .
    odrl:permission odrl:distribution ;
    odrl:prohibition ldr:rebaseURI ;
  ] .

Please note that LDR is a profile (actions like ldr:rebaseURI are subclasses of ODRL classes) whereas VoID is not (no relation per se with ODRL).

16. How to declare a policy to extend another one

The ODRL policy 2 might be read as "In addition to policy 1 (which says that Alice can use Asset 1), Bob cannot use it".

<http://example.org/policy/1>
  odrl:target <http://example.com/asset/1> ;
  odrl:action odrl:use ;
  odrl:permission [
    odrl:assignee <http://example.com/party/Alice> ;
   ] .

<http://example.org/policy/2>
  odrl:inheritFrom <http://example.org/policy/1>
  odrl:prohibition [
    odrl:assignee <http://example.com/party/Bob> ;
] .

Please note that this example has the same meaning as in Example 4.

Style Considerations

Comment on RDF compactness

RDFs processors can infer the type declarations given for the Permission (from the odrl:permission range) and Policy (from odrl:permission domain). As odrl:Set is the default policy type, it can also be ommitted. An equivalent, but more verbose version of Example 1, follows:

<http://example.org/policy/1> 
  a odrl:Policy, odrl:Set;
  odrl:permission [
    a odrl:Permission ;
    odrl:target <http://example.com/asset/1> ;
    odrl:assignee <http://example.com/party/Alice> ;
    odrl:action odrl:use
] ;


THIS DOCUMENT IS OBSOLET. PLEASE REFER TO THE CURRENT validation PAGES