Policy Structures

The ODRL Information Model supports flexibility in the information structures to declare ODRL expressions. A Policy MAY contain multiple Rules, and each Rule MAY contain multiple Assets, Parties, Actions, Constraints, and Duties. A Policy MAY also contain Assets, Parties, and Actions at the Policy level, and these apply to all of the enclosing Rules in the Policy.

At the core atomic level, an ODRL Rule (Permission and/or Prohibition) would typically contain one Asset, one or more Parties, one Action, and potentially one Constraint and/or Duty, as shown in the example below:

{
    "@context": {
    "odrl": "http://www.w3.org/ns/odrl/2/"
    }
    "type": "odrl:Agreement",
    "uid": "http://example.com/policy:8888",
    "permission": [{
        "target": "http://example.com/music/1999.mp3",
        "assigner": "http://example.com/org/sony-music",
        "assignee": "http://example.com/people/billie",
        "action": "odrl:play",
        "constraint": "...",
        "duty": "..."
        }]
    }]
}  

As multiple Assets, Parties, and Actions are support for each Rule, then the following (snippet) example with two Assets:

    "permission": [{
        "target": "http://example.com/music/1999.mp3",
        "target": "http://example.com/music/PurpleRain.mp3",
        "assigner": "http://example.com/org/sony-music",
        "assignee": "http://example.com/people/billie",
        "action": "odrl:play",
        "constraint": "...",
        "duty": "..."
        }]

Would then be mapped to two atomic Rules:

    "permission": [{
        "target": "http://example.com/music/1999.mp3",
        "assigner": "http://example.com/org/sony-music",
        "assignee": "http://example.com/people/billie",
        "action": "odrl:play",
        "constraint": "...",
        "duty": "..."
        }]
    "permission": [{
        "target": "http://example.com/music/PurpleRain.mp3",
        "assigner": "http://example.com/org/sony-music",
        "assignee": "http://example.com/people/billie",
        "action": "odrl:play",
        "constraint": "...",
        "duty": "..."
        }]

The processing model for Permission/Prohibition Rules with multiple Assets, Parties, and Actions to generate atomic Rules includes:

1. If there are multiple Assets (with the same Relation), then create new Rules (one for each Asset) and include one Asset relation, and all the other (non-Asset) entities.
2. If there are multiple Parties (with the same Role), then create new Rules (one for each Party) and include one Party Role, and all the other (non-Party Role) entities.
3. If there are multiple Actions, then create new Rules (one for each Action) and include one Action, and all the other (non-Action) entities.

An ODRL Policy MAY also declare multiple Assets, Parties, and Actions at the Policy level. This indicates that these are all common to all the enclosing Rules, as shown in the below example:

{
    "@context": {
    "odrl": "http://www.w3.org/ns/odrl/2/"
    }
    "type": "odrl:Agreement",
    "uid": "http://example.com/policy:8888",
    "target": "http://example.com/music/1999.mp3",
    "assigner": "http://example.com/org/sony-music",
    "action": "odrl:play",
    "permission": [{
        "assignee": "http://example.com/people/billie"
        },
        {
        "assignee": "http://example.com/people/murphy"
        }]
    }]
}  

To fully expand the Rules, the Policy-level Assets, Parties, and Actions MUST be added to all the Rules in the Policy. As shown below, the policy-level Target, Assigner, and Action are added to the two permission Rules:

{
    "@context": {
    "odrl": "http://www.w3.org/ns/odrl/2/"
    }
    "type": "odrl:Agreement",
    "uid": "http://example.com/policy:8888",
    "permission": [{
        "target": "http://example.com/music/1999.mp3",
        "assigner": "http://example.com/org/sony-music",
        "action": "odrl:play",
        "assignee": "http://example.com/people/billie"
        },
        {
        "assignee": "http://example.com/people/murphy"
        "target": "http://example.com/music/1999.mp3",
        "assigner": "http://example.com/org/sony-music",
        "action": "odrl:play",
        }]
    }]
}  

The processing model for Policies with multiple Assets, Parties, and Actions includes:

1. Replicate all Policy-level Assets in the enclosing Permission/Prohibition Rules.
2. Replicate all Policy-level Parties in the enclosing Permission/Prohibition Rules.
3. Replicate all Policy-level Actions in the enclosing Permission/Prohibition Rules.
4. Follow the processing model (defined above) to create atomic Rules.

Policy Provenance

Provenance attributes MAY be added to the Policy entity to support additional authenticity, integrity, and interpretation. Typically, these will be from external community vocabularies.

The following Dublin Core Metadata Terms [[!DCTERMS]] SHOULD be used:

• dc:creator - the individual, agent, or organisation that authored the Policy.
• dc:issued - the date (and time) the Policy was first issued.
• dc:modified - the date (and time) the Policy was updated.
• dc:coverage - the jurisdiction under which the Policy is relevant.
• dc:replaces - the identifier (uid) of a Policy that this Policy supersedes.
• dc:isReplacedBy - the identifier (uid) of a Policy that supersedes this Policy.

The processing model for Policies with the above provenance properties include:

1. If a Policy contains the dc:isReplacedBy property, then the identified Policy MUST be retrieved and processed.

Example Use Case:The below Policy contains provenace properties that indicate who created it, when it was issued, which jurisdiction is relevant, and an older version of the Policy it replaces.

{
    "@context": [{ "odrl": "http://www.w3.org/ns/odrl/2/",
                   "dc": "http://purl.org/dc/terms/ }],
    "type": "odrl:Agreement",
    "uid": "http://example.com/policy:8888",
    "dc:creator": "billie@example.com",
    "dc:issued": "2017-01-01:12:00",
    "dc:jurisiction: "Queensland, Australia",
    "dc:replaces: "http://example.com/policy:8887",
    "permission": [{ ... }]
}  

Policy Conflict

The conflict attribute is used to establish strategies to resolve conflicts that arise from the merging of Policies or conflicts between Permissions and Prohibitions in the same Policy. Conflicts may arise when merging Policies about the same Asset and the resultant Actions are inconsistent. For example, one Policy stated that Assignee Fred had been granted an "exclusive" distribution Permission, and the other Policy said the same for Assignee Mary. In the same Policy, conflicts can also arise when the same Action is used in a Permission and a Prohibition.

The conflict attribute MUST take one of the following values:

• perm: the Permissions MUST override the Prohibitions
• prohibit: the Prohibitions MUST override the Permissions
• invalid: the entire Policy MUST be invalid if any conflict is detected

If the conflict attribute is not explicitly set, its default value of invalid will be used.

The processing model for Policies conflict strategies includes:

1. If a Policy has the conflict attribute of perm and there are detected conflicts between a Permission and a Prohibition, then the Permission MUST overide the Prohibition.
2. If a Policy has the conflict attribute of prohibit and there are detected conflicts between a Permission and a Prohibition, then the Prohibition MUST overide the Permission.
3. If a Policy has the conflict attribute of invalid and there are detected conflicts between a Permission and a Prohibition, then the entire Policy MUST be processed as invalid .
4. If a Policy has multiple conflict attribute values (for example, after a Policy merge) AND there are detected conflicts between a Permission and a Prohibition, then the entire Policy MUST be processed as invalid .

Example Use Case: Two Policies are associated to the same target Asset http://example.com/asset:1212. The first Policy http://example.com/policy:0001 allows to use the Asset. The second Policy http://example.com/policy:0002 allows for the display of the Asset, but it prohibits print. Both policies explicitly state how to deal with conflicts through the conflict attribute being set to perm. Hence the Permissions will always override any Prohibitions. In this use case, since the print Action is a subset of the use Action, there could be a conflict. However, the perm conflict strategy means that the use Permission will override the print Prohibition.

{
"@context": {
    "odrl": "http://www.w3.org/ns/odrl/2/"
    }
    "type": "odrl:Set",
    "uid": "http://example.com/policy:0001",
    "conflict": "perm",
    "permission": [{
        "target": "http://example.com/asset:1212",
        "action": "odrl:use",
        "assigner": "http://example.com/owner:181"
    }]
}

{
"@context": {
    "odrl": "http://www.w3.org/ns/odrl/2/"
    }
    "type": "odrl:Set",
    "uid": "http://example.com/policy:0002",
    "conflict": "perm",
    "permission": [{
        "target": "http://example.com/asset:1212",
        "action": "odrl:display",
        "assigner": "http://example.com/owner:182"
    }]
    "prohibition": [{
        "target": "http://example.com/asset:1212",
        "action": "odrl:print"
    }]
}

In the above use case, if the second Policy had the conflict value of prohibit, then the outcome would be a direct contradiction, and the result will be an invalid Policy.

Undefined Actions

The undefined attribute is used to indicate how to process unsupported Actions. That is, if an ODRL expression contains an Action that is not from a known (or supported) ODRL vocabulary, how should the Action be treated in the context of the whole ODRL Policy?

The undefined attribute MUST take one of the following values:

• support: the undefined Action is to be supported as part of the Policy – and the Policy remains valid
• ignore: the undefined Action is to be ignored and is not part of the Policy – and the Policy remains valid
• invalid: the undefined Action is unknown – and the entire Policy is invalid

In all cases, systems that process ODRL expressions SHOULD provide mechanisms that adequately address these three outcomes. That is, how the Action can be supported, or ignored, or the entire Policy is invalid.

If the undefined attribute is not explicitly set, its default value of invalid SHALL be used.

The processing model for undefined actions includes:

1. If a Policy has the undefined attribute of support and there are actions in the Policy now known to the processing system, then the processing system MUST support these actions as part of the valid Policy.
2. If a Policy has the undefined attribute of ignore and there are actions in the Policy now known to the processing system, then the processing system MUST disregard these actions as part of the valid Policy.
3. If a Policy has the undefined attribute of invalid and there are actions in the Policy now known to the processing system, then the processing system MUST process the entire Policy as invalid.
4. If a Policy has multiple undefined attribute values (for example, after a Policy merge) AND there are actions in the Policy now known to the processing system, then the entire Policy MUST be processed as invalid.

Example Use Case: A Policy of type Set states that the Asset can be recorded. The processing system does not understand this Action, and since the undefined attribute is invalid, then the entire Policy is deemed invalid.

{
    "@context": {
    "odrl": "http://www.w3.org/ns/odrl/2/"
    }
    "type": "odrl:Set",
    "uid": "http://example.com/policy:8888",
    "undefined": "invalid",
    "permission": [{
        "target": "http://example.com/music/1999.mp3",
        "action": "http://example.com/ns/recorded"
        }]
    }]
}  

Policy Inheritance

ODRL supports a simple inheritance mechanism in which a (child) Policy may inherit all the information structures of another (parent) Policy. The inheritance is aimed at including data structures between Policies.

The inheritAllowed attribute in the Policy entity is used to indicate if the Policy expression can be used in any inheritance relationship. If present, the value of the inheritAllowed attribute MUST take one of the following values:

• true: the Policy expression can be used for inheritance
• false: the Policy expression can not be used for inheritance

If the inheritAllowed attribute is not explicitly set, its default value of true will be used.

The following attributes SHOULD be used in a child Policy that is inheriting from a parent Policy in which that parent Policy MUST allow inheritance (via the inheritAllowed attribute) :

• inheritFrom: the identifier of the parent Policy from which this child Policy inherits from
• inheritRelation: the identifier of the relationship context of this inheritance structure

The inheritFrom association in the (child) Policy will uniquely identify (via a UID) the (parent) Policy from which the inheritance will be performed.

The inheritRelation attribute in the (child) Policy will uniquely identify (via a UID) the context of inheritance from the (parent) Policy. For example, this may indicate the business scenario, such as subscription, or prior arrangements between the Parties (that are not machine representable). Such terms SHOULD be defined in the ODRL vocabulary [[!vocab-odrl]] or ODRL Profiles. For example, an Assigner and Assignee may have a historical arrangement related to the specific use of content they make available to each other. The business model (identified with a URI) is used in the inheritRelation attribute in their subsequent ODRL Policies they exchange. This will require the ODRL Policy to be interpreted with the additional information identified by the URI. For example, this may include additional permission Actions or constraints (etc) that is documented in their business model arrangement.

Both the inheritFrom association and inheritRelation attribute may be used independently.

The following restrictions apply when using inheritance:

• Single inheritance is only supported. (One parent Policy to one or more child Policy entities. No child Policy can inherit from two or more parent Policy entities.)
• Inheritance can be to any depth. (Multiple levels of children Policy entities.)
• Inheritance MUST NOT be circular.
• No state information is transferred from the parent Policy to the child Policy.

Example Use Case:Consider the below (parent) Policy that has been expressed primarly for inheritance purposes:

{
    "@context": {
    "odrl": "http://www.w3.org/ns/odrl/2/"
    }
    "type": "odrl:Set",
    "uid": "http://example.com/policy:3333",
    "target": "http://example.com/asset:3333",
    "assigner": "http://example.com/boss:0001",
    "permission": [{
        "action": "odrl:use"
    }]
}  

The below (child) Policy includes the inheritFrom attribute pointing to the above (parent) Policy. The (child) Policy also includes its own specific policy-level asset, and two Permission Rules.

{
    "@context": {
    "odrl": "http://www.w3.org/ns/odrl/2/"
    }
    "type": "odrl:Agreement",
    "uid": "http://example.com/policy:4444",
    "inheritFrom": "http://example.com/policy:3333",
    "target": "http://example.com/asset:5555",
    "permission": [{
        "assignee": "http://example.com/guest:0001",
        "action": "odrl:display"
    }],
    "permission": [{
        "assignee": "http://example.com/guest:0002",
        "action": "odrl:print"
    }]
}  

After the inheritance is performed - where the (parent) Policy information structures are added to the (child) Policy - the resultant Policy is shown below:

{
    "@context": {
    "odrl": "http://www.w3.org/ns/odrl/2/"
    }
    "type": "odrl:Agreement",
    "uid": "http://example.com/policy:4444",
    "target": [
       "http://example.com/asset:5555",
       "http://example.com/asset:3333" ]
    "assigner": "http://example.com/boss:0001",
    "permission": [{
        "assignee": "http://example.com/guest:0001",
        "action": "odrl:display"
    }],
    "permission": [{
        "assignee": "http://example.com/guest:0002",
        "action": "odrl:print"
    }],
    "permission": [{
        "action": "odrl:use"
    }]
}  

The processing model for ODRL Policy Inheritance includes:

1. A (child) Policy with an inheritFrom attribute MUST first verify that the (parent) Policy does not contain the inhertiAllowed attribute with the value "false".
2. The (child) Policy MUST access the (parent) Policy and replicate the following in the (child) Policy:
• All policy-level Assets, Parties, Actions.
• All Permission and Prohibition Rules.
3. The (child) Policy can then be further expanded (into atomic Rules) by following the processing models defined in the Policy Structure section.

Relation

The Relation entity is an association class and can be used to link to an Asset from either Permission, Duty or Prohibition, indicating how the Asset SHOULD be utilised in respect to the entity that links to it.

The Relation entity contains the following attribute:

• relation: indicates the relationship of the Asset to the linked entity (REQUIRED)

The default value for the relation attribute is target which indicates that the Asset is the primary object to which the Permission, Duty or Prohibition actions apply.

Other values for the Relation entity SHOULD be defined in the ODRL Vocabulary [[!vocab-odrl]] and ODRL Profiles.

Scope

The scope attribute SHOULD be used to indicate the context under which to interpret the Asset entity. The purpose of scope is to provide additional information about the Asset. For example, the Asset identifier may refer to a resource which many characteristics, but the scope may limit that to only one specific characteristic.

The scope attribute URI values SHOULD be defined in the ODRL vocabulary [[!vocab-odrl]] and ODRL Profiles.

Role

The Role entity is an association class and can be used to link to a Party from either Permission, Duty or Prohibition, indicating which Role the Party takes with respect to the entity that links to it.

The Role entity contains the following attributes:

• function: the functional role the Party takes (REQUIRED)

The function attribute MUST support the following values:

• assigner: indicates that the Party has assigned the associated Permission, Duty, or Prohibition. In other words, the Party grants a Permission or requires a Duty to be performed or states a Prohibition.
• assignee: indicates that the Party has been assigned the associated entity, i.e., they are granted a Permission or required to perform a Duty or have to adhere to a Prohibition.

Other values for the function attribute SHOULD be defined in the ODRL vocabulary [[!vocab-odrl]] and ODRL Profiles.

Scope

The scope attribute SHOULD be used to indicate the context under which to interpret the Party entity. The purpose of scope is to provide additional information about the Party that may also reduce the extent of the Party identifier. For example, the Party identifier may refer to all users at a University, but the scope may limit that to only staff members at the University.

The scope attribute SHOULD take one of the following values:

• individual: indicates that the Party entity is a single individual. The linked Permission, Duty or Prohibition is applicable for that individual only.
• group: indicates that the Party entity represents a group. The group consisting of many individual members. The linked Permission, Duty or Prohibition is applicable for each member of that group. For example, a Permission to play a movie 5 times is valid for each Party member or the Duty to pay 3 EUR has to be fulfilled by each Party member.

Other URI values for the scope attribute SHOULD be defined in the ODRL vocabulary [[!vocab-odrl]] and ODRL Profiles.

Constraint Relations

Constraint objects MAY also be used as both of the values for the leftOperandand rightOperand of a Constraint expression. This supports more complex constraint relations and allows for two constraints to be compared and processed accordingly. The two constraints MUST be atomic Constraints, that is, not a constraint that includes constraint relations.

The applicable operators that can be used for constraint relations are:

• or - at least one of the Constraints (in the left or right operand) MUST be satisfied
• xor - only one of the Constraints (in the left or right operand) MUST be satisfied
• and - both of the Constraints (in the left or right operand) MUST be satisfied
• isNecessaryFor - the left operand Constraints MUST be satisfied before processing the left operand Constraint which then MUST be satisfied.

The processing model for Constraint relations includes:

1. If the Constraint leftOperand refers to a Constraint object, then the rightOperand MUST also refer to a Constraint object.
2. The Constraint objects both MUST be atomic Constraints.
3. The Constraint operator MUST only be of the values; or, xor, and, isNecessaryFor.
4. The Constraint MUST not use the rightOperandReference, dataType, unit, or status attributes.
5. If the Constraint operator is or then at least one of the Constraints (in the left or right operands) MUST be satisfied for the entire Constraint to be satisfied.
6. If the Constraint operator is xor then at only one of the Constraints (in the left or right operands) MUST be satisfied for the entire Constraint to be satisfied.
7. If the Constraint operator is and then both of the Constraints (in the left and right operands) MUST be satisfied for the entire Constraint to be satisfied.
8. If the Constraint operator is isNecessaryFor then the left operand Constraint MUST be satisfied before the right operand Constraint is processed. The right operand Constraint MUST then be satisifed for the entire Constraint to be satisfied.

Example Use Case:The Policy below shows a Permission to play the target asset that can either be a maximum of 100 times, or unlimited play until the end of 2017.

{
   "@context": {
    "odrl": "http://www.w3.org/ns/odrl/2/"
    }
    "type": "odrl:Offer",
    "uid": "http://example.com/policy:88",
    "permission": [{
        "target": "http://example.com/book/1999.mp3",
        "assigner": "http://example.com/org/paisley-park",
        "action": "odrl:play",
        "constraint": [{
                "leftOperand": "http://example.com/policy:88/C1",
                "operator": "odrl:xor",
                "rightOperand": "http://example.com/policy:88/C2"
            }],
    }],
   "constraint": {
       "@id": "http://example.com/policy:88/C1"
       "leftOperand": "odrl:count",
       "operator": "odrl:lteq",
       "rightOperand": "100"
   },
   "constraint": {
       "@id": "http://example.com/policy:88/C2"
       "leftOperand": "odrl:dateTime",
       "operator": "odrl:lteq",
       "rightOperand": "2017-12-31"
   }
}  

Example Use Case:The Policy below shows a Permission to distribute photos in which the first constraint (the event "football/game/2017" has passed) is statisfied, then the second constraint (wait for 60 minutes) is processed, and is then satisfied. Note that the operator value of isNecessaryFor is not the same as and as for the latter both operand Constraints must be satisfied, but could be processed at the same time.

{
   "@context": {
    "odrl": "http://www.w3.org/ns/odrl/2/"
    }
    "type": "odrl:Offer",
    "uid": "http://example.com/policy:88",
    "permission": [{
        "target": "http://example.com/photo.jpg",
        "assigner": "http://example.com/org/fifa",
        "action": "odrl:distribute",
        "constraint": [{
                "leftOperand": "http://example.com/policy:88/C1",
                "operator": "odrl:isNecessaryFor",
                "rightOperand": "http://example.com/policy:88/C2"
            }],
    }],
   "constraint": {
       "@id": "http://example.com/policy:88/C1"
       "leftOperand": "odrl:event",
       "operator": "odrl:gteq",
       "rightOperand": "http://example.com/football/game/2017"
   },
   "constraint": {
       "@id": "http://example.com/policy:88/C2"
       "leftOperand": "odrl:dateTime",
       "operator": "odrl:gteq",
       "rightOperand": "P60M"
   }
}