ODRL Policy Agreement Instantiation

1. Introduction

Policy instantiation defines the process of creating an agreement based on: (i) a set of ODRL policies, (ii) an ODRL Request, and (iii) additional information defined as the state of the world (SotW) at the time of the instantiation. From the execution of the instantiation algorithm, an ODRL agreement is created that reflects the matching of an ODRL request against the available policies and SotW.

As the ODRL specification defines a generic policy language, with many extension points for actions, constraints, parties, targets and other elements, it is important for the instantiation algorithm to be equally extensible to support these extensions.

1.1. Rule composition

Note: The ODRL Specification contains a section on Rule Composition, that defines the way ODRL policies can be converted into their atomic counterparts for evaluation. There does not seem to be clarity on the exact wat that a prohibition rule over two actions should be interpreted, which can be done either as the negation of a conjunction of actions, or as a conjunction of individually negated actions. In this specification, we use the latter interpretation of a policy expressing a prohibition rule for the actions of Drinking and Driving to be equivalent to the atomic representation of a prohibition for the action of drinking, (NOT (drinking)) AND (NOT (driving)). To prevent issues, we throw an error when a prohibition is passed with more than a single action. If more than one action needs to be prohibited, these must be passed as separate prohibitions. This means you cannot express the policy prohibiting drinking and driving at the same time, you can only enforce not drinking and not driving. Composite policies can only be modeled as constraints on atomic prohibitions.

2. Namespaces

Commonly used namespace prefixes used in this specification:

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix dpv:     <https://w3id.org/dpv#> .
@prefix eu-gdpr: <https://w3id.org/dpv/legal/eu/gdpr#> .
@prefix ex:      <http://example.org/> .
@prefix oac:     <https://w3id.org/oac#> .
@prefix odrl:    <http://www.w3.org/ns/odrl/2/> .
@prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix xsd:     <http://www.w3.org/2001/XMLSchema#> .

3. Requirements

In this section, we iterate the requirements for the instantiation algorithm.

The core ODRL Instantiation Algorithm MUST at least support the inclusion of all core ODRL elements as defined in the ODRL Information Model. This includes the following classes:

Policy - A non-empty group of Permissions (via the permission property) and/or Prohibitions (via the prohibition property) and/or Duties (via the obligation property). The Policy class is the parent class to the Set, Offer, and Agreement subclasses:
- Set - a subclass of Policy that supports expressing generic Rules.
- Offer - a subclass of Policy that supports offerings of Rules from assigner Parties.
- Agreement - a subclass of Policy that supports granting of Rules from assigner to assignee Parties.
Asset - A resource or a collection of resources that are the subject of a Rule (via the abstract relation property). The Asset class is the parent class to:
- AssetCollection - a subclass of Asset that identifies a collection of resources.
Party - An entity or a collection of entities that undertake Roles in a Rule (via the abstract function property). The Party class is the parent class to:
- PartyCollection - a subclass of Party that identifies a collection of entities.
Action - An operation on an Asset.
Rule - An abstract concept that represents the common characteristics of Permissions, Prohibitions, and Duties.
- Permission - The ability to exercise an Action over an Asset. The Permission MAY also have the duty property that expresses an agreed Action that MUST be exercised (as a pre-condition to be granted the Permission).
- Prohibition - The inability to exercise an Action over an Asset.
- Duty - The obligation to exercise an Action.
Constraint/LogicalConstraint - A boolean/logical expression that refines an Action and Party/Asset collection or the conditions applicable to a Rule.

4. Algorithm

The instantiation algorithm distills an ODRL Agreement that defines the Agreement reached based on (i) an ODRL Request, (ii) a set of ODRL Policies and (iii) a state of the world.

In this secion, we define the algorithm to distill the resulting ODRL Agreement from these parameters.

Note: In § 1.1 Rule composition, we define the problem with composite policies containing prohibition rules in ODRL. For this reason, policies containing prohibition rules with more than one action will be rejected by the algorithm.

4.1. Input Validation

The first step is the validation of the input parameters.

For (i), the request must be validated to be of type odrl:Request, and may be validated against a shacl shape that verifies the presence of the minimal subset of required properties.

For (ii), each policy of the set of policies is evaluated to be of either type odrl:Set or type odrl:Policy. Policies of type odrl:Offer and odrl:Request must be rejected. Additionally, the policies can be validated agains a known shape to validate the presence of required properties.

For (iii), the SOTW is expected to be trusted system input, but may be validated against a known shape to check for missing properties.

4.2. Converting to atomic policy composition

Following Rule Composition, we convert both (i) the ODRL Request parameter and (ii) the policies of the policy set parameter of the algorithm to their atomic form. This means that for each combination of rule type, action type and target value, the rule converted into a unique set of rules for each combination of rule type, action type and target value.

For the resulting set of policies, for each combination of rule, action and target, if multiple combinations of rule, action and target are found that are identical, these are merged together as a single rule, and all constraints, refinements and duties defined on these policies are merged.

If the request was atomized into multiple different requests, the algorithm MUST be repeated for each atomized request, and output a separate instantiation for each separate atomized request.

Verify the above algorithm with a concrete proof!

Note: This section makes the assumption that policy composition of odrl:prohibitions with multiple actions is impossible. If this is not the case, this part of the algorithm needs to be revised!

4.3. Target Matching

The next step is remove all policy rules that are not relevant for the request. As the requests are atomized in the step above, and for each different request a separate isntantiation is executed, any remaining policy rules will have a single target value, a single action value, but may contain multiple rule types (e.g. a permission and obligation targeting the same action on the same rule, under different conditions). Resulting policies that are left without rules should be disregarded similarly.

Note: In this step, we make the assumption that the ODRL Request cannot target a subset of a target defined by any of the policies in the input. It this were to be the case (for example when targeting a virtual file system), additional constraints need to be in place to decide if a subset of a policy target is defined as the request target.

4.4. Policy Evaluation

Note: This step is optional.

As an optional step, the request can be validated against the policies and the SOTW to check both the validity of the request and ensuring all required information for the instantiation procedure is present. If the input is trusted or pre-validated, this step can be skipped.

In case the policy evaluation succeeds for only part of the set of policies, the implementation can decide to either abort the execution (require full matching), or to remove the policy rules that did not validate (allow partial matching).

Note: when skipping policy evaluation, the execution flow might need to dynamically abort the instantiation algorithm or remove incomplete rules when trying to instantiate their properties and constraints with concrete values.

4.5. Instantiation algorithm

Now that all pre-processing is done, the instantiation algorithm can be run:

4.5.1. Agreement creation

Create a new entity of type odrl:Agreement that serves as the basis of the instantiated agreement.

4.5.2. Adding references

The instantiated agreement SHOULD reference the request and the policies that it is derived from. In privacy-sensitive cases, this step can be disregarded.

This is done by adding the dcterms:references property to the instantiated agreement with the identifiers of the request and all policies that are relevant at this point of the algorithm execution.

4.5.3. Iterating over rule types, actions and targets

As discussed in § 1.1 Rule composition, by not allowing prohibition rules consisting of multiple actions, all resulting policy rules can differ in type, but are identical in their action and target values.

Note: When stating the same target and same action, this includes refinements on this target and action value. In case of differing refinements, this does not hold.

Include refinements explicitly in the algorithm

For all remaining policies, iterate over the set of rules S that are identical in their combination of rule type, rule action and rule target.

Instantiate a new rule R for this combination of rule type, action and target on the above agreement.

4.5.4. Instantiating parties

For the rule R defined in the step above, the odrl:assigner and odrl:assignee properties must be defined. The odrl:assignee value MUST be defined on the ODRL Request parameter passed to the algorithm. This value must be added to the instantiated rule from the previous step.

For the odrl:assigner value, this information may be defined in the SotW parameter passed to the algorithm, be hardcoded or retrieved out of bounds. It SHOULD be defined on the instantiated rule from the previous step.

4.5.5. Instantiating constraints

Finally, for the set S of policy rules that share the combination of type, action and target to the instantiated rule R, iterate over the set of all unique constraints defined for the rules of the set S.

Iterating over each unique constraint of each rule in S

If an odrl:subject is found in the constraint, the combined graphs of both the ODRL Request parameter and the SotW parameter MUST be evaluated using a match function passing the constraint odrl:subject, leftOperand, operator and rightOperand values.

If the subject of the constraint can be entailed from the odrl:leftOperand value, it is up to the implementation on how to handle this, but the documentation should reflect the capabilities of the implementation to handle these cases.

The default interpretation of a constraint is that it is directly targeting the policy rule on which it is defined, and the match function must be called with the rule of the ODRL Request parameter, and evaluated over the combined knowledge graph of ODRL Request and SotW parameters.

Note: The match function is identical to how the ODRL Evaluation engine processes these constraints. This should be aligned with Wout!

4.5.5.1. The `match` function

The match function takes subject, leftOperand, operator and rightOperand parameters, as well as the Request and SotW.

(i) For each constraint, the subject is evaluated. If the subject identifier is of the rule defined in the Request, the function checks if a constraint is defined on this request that matches the provided function parameters.

If this is not the case, the subject, leftOperand, operator and rightOperand parameters are converted into a SPARQL query of the form

construct {
    <subject> <leftoperand> ?value.
} where {
    <subject> <leftoperand> ?value.
    FILTER (?value <mappedOperator> <rightOperand>).
}

with mappedOperator being the SPARQL operator that is identical to the enforced operator in the constraint.

Note: This match function is an extension point for the processing of custom constraints and mappings towards SPARQL filters.

4.6. Returning the instantiated agreement

After iterating over all rule combinations, the instantiated agreement is returned by the algorithm.

5. Examples

How should we define the legal basis requirement in the policy if we do not want to enforce a specific requirement?

The ODRL Policy parameter

<http://example.org/alice-HCPX> a odrl:Set ;
    odrl:uid ex:alice-HCPX ;
    dcterms:description "Alice allows her health data to be read by HCP X for bariatric care." ;
    odrl:permission <http://example.org/alice-HCPX-permission> .

<http://example.org/alice-HCPX-permission> a odrl:Permission ;
    odrl:action odrl:read ;
    odrl:target ex:health-data ;
    odrl:assigner ex:alice ;
    odrl:assignee ex:HCPx ;
    odrl:constraint <http://example.org/alice-HCPX-permission-purpose>, 
        <http://example.org/alice-HCPX-permission-legal-basis> .

<http://example.org/alice-HCPX-permission-purpose> a odrl:Constraint ;
    odrl:leftOperand odrl:purpose ;
    odrl:operator odrl:eq ;
    odrl:rightOperand ex:bariatric-care .

The ODRL Request parameter

<http://example.org/HCPX-request> a odrl:Request ;
    odrl:uid ex:HCPX-request ;
    odrl:profile oac: ;
    dcterms:description "HCP X requests to read Alice's health data for bariatric care." ;
    odrl:permission <http://example.org/HCPX-request-permission> .

<http://example.org/HCPX-request-permission> a odrl:Permission ;
    odrl:action odrl:read ;
    odrl:target ex:health-data ;
    odrl:assigner ex:alice ;
    odrl:assignee ex:HCPx ;
    odrl:constraint <http://example.org/HCPX-request-permission-purpose>,
        <http://example.org/HCPX-request-permission-lb> .

<http://example.org/HCPX-request-permission-purpose> a odrl:Constraint ;
    odrl:leftOperand odrl:purpose ; # can also be oac:Purpose, to conform with OAC profile
    odrl:operator odrl:eq ;
    odrl:rightOperand ex:bariatric-care .

<http://example.org/HCPX-request-permission-lb> a odrl:Constraint ;
    odrl:leftOperand oac:LegalBasis ;
    odrl:operator odrl:eq ;
    odrl:rightOperand eu-gdpr:A9-2-a .

The State of the World input parameter

ex:systemTime odrl:eq "2025-02-19T17:54:24.531Z"^^xsd:dateTime .

The Output Agreement

<http://example.org/Alice-HCPX-agreement> a odrl:Agreement ;
    odrl:uid ex:Alice-HCPX-agreement ;
    dcterms:references <http://example.org/alice-HCPX>, <http://example.org/HCPX-request> ;
    dcterms:description "Agreement for HCP X to read Alice's health data for bariatric care." ;
    odrl:permission <http://example.org/agreement-permission> .

<http://example.org/agreement-permission> a odrl:Permission ;
    odrl:action odrl:read ;
    odrl:target ex:health-data ;
    odrl:assigner ex:alice ;
    odrl:assignee ex:HCPx ;
    dpv:hasLegalBasis eu-gdpr:A9-2-a ;
    odrl:constraint <urn:constraint:purpose>, <urn:constraint:legalBasis> .

<urn:constraint:purpose> a odrl:Constraint ;
    odrl:leftOperand odrl:purpose ; 
    odrl:operator odrl:eq ;
    odrl:rightOperand ex:bariatric-care .

<urn:constraint:legalBasis> a odrl:Constraint ;
    odrl:leftOperand dpv:hasLegalBasis ;
    odrl:operator odrl:eq ;
    odrl:rightOperand ex:bariatric-care .

ODRL Policy Agreement Instantiation

Living Document, 13 May 2025

Abstract

1. Introduction

1.1. Rule composition

2. Namespaces

3. Requirements

4. Algorithm

4.1. Input Validation

4.2. Converting to atomic policy composition

4.3. Target Matching

4.4. Policy Evaluation

4.5. Instantiation algorithm

4.5.1. Agreement creation

4.5.2. Adding references

4.5.3. Iterating over rule types, actions and targets

4.5.4. Instantiating parties

4.5.5. Instantiating constraints

4.5.5.1. The `match` function

4.6. Returning the instantiated agreement

5. Examples

Conformance

References

Normative References

Issues Index

ODRL Policy Agreement Instantiation

Living Document, 13 May 2025

Abstract

1. Introduction

1.1. Rule composition

2. Namespaces

3. Requirements

4. Algorithm

4.1. Input Validation

4.2. Converting to atomic policy composition

4.3. Target Matching

4.4. Policy Evaluation

4.5. Instantiation algorithm

4.5.1. Agreement creation

4.5.2. Adding references

4.5.3. Iterating over rule types, actions and targets

4.5.4. Instantiating parties

4.5.5. Instantiating constraints

4.5.5.1. The match function

4.6. Returning the instantiated agreement

5. Examples

Conformance

References

Normative References

Issues Index

4.5.5.1. The `match` function