Skip to content

Commit 7de422c

Browse files
woutslabbinckwoutslabbinck
authored
Merge pull request #11 from SolidLabResearch/feat/policy-atomization
Feat/policy atomization
2 parents b8ef6bd + 867c08f commit 7de422c

File tree

19 files changed

+2747
-113
lines changed

19 files changed

+2747
-113
lines changed

‎RELEASE_NOTES.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,20 @@
11
# ODRL Evaluator
22

3+
## v0.4.0
4+
5+
### New features
6+
7+
- Support for [Policy Rule Composition ](https://www.w3.org/TR/odrl-model/#composition)
8+
- creation of the `Atomizer` class in `src/evaluator/Atomizer.ts`
9+
- creation of the `CompositeODRLEvaluator` class in `src/evaluator/Evaluate.ts`
10+
- example script in `demo/compact-rules.ts`
11+
- Creation of the script `MakeShapes` that exports shacl shape as a constant `SHAPES` to be used in the browser
12+
- also includes a simplified shape file of ODRL at `src/shapes/shape.ttl`
13+
- Creation of utility to work with Compliance Report Models
14+
- the function `parseComplianceReport` in `src/util/report/ComplianceReportUtil.ts`
15+
- exports `prefixes` a set of commenly used prefixes used in ODRL and ODRL Evaluation
16+
- expands the vocabulary util to also include the Compliance Report and the full ODRL 2.2 Vocabulary
17+
318
## v0.3.0
419

520
### New features

‎demo/compact-rules.ts‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
import { Parser } from "n3";
2+
import { CompositeODRLEvaluator, ODRLEngineMultipleSteps, prefixes, ODRLEvaluator } from "../dist/index";
3+
import { write } from '@jeswr/pretty-turtle';
4+
5+
const sotw = `
6+
@prefix temp: <http://example.com/request/>.
7+
@prefix dct: <http://purl.org/dc/terms/>.
8+
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
9+
10+
temp:currentTime dct:issued "2024-02-12T11:20:10.999Z"^^xsd:dateTime.
11+
`
12+
13+
const request = `
14+
@prefix odrl: <http://www.w3.org/ns/odrl/2/> .
15+
16+
<urn:ucp:policy:2a797ad7-232a-4e1f-853f-81388969e4a1> a odrl:Request;
17+
odrl:permission <urn:ucp:rule:e3ba21f7-57b0-4a43-988a-3221aba858ef>.
18+
<urn:ucp:rule:e3ba21f7-57b0-4a43-988a-3221aba858ef> a odrl:Permission;
19+
odrl:action odrl:read;
20+
odrl:target <http://localhost:3000/alice/other/resource.txt>;
21+
odrl:assignee <https://both.pod.knows.idlab.ugent.be/profile/card#me>.
22+
`
23+
const compactPolicy = `
24+
@prefix ex: <http://example.org/>.
25+
@prefix odrl: <http://www.w3.org/ns/odrl/2/> .
26+
27+
ex:usagePolicy1 a odrl:Agreement ;
28+
odrl:permission ex:permission1, ex:permission2 ;
29+
odrl:prohibition <urn:uuid:9477c997-adc1-4d64-a12c-fa9e0f6b80f0> .
30+
31+
32+
ex:permission1 a odrl:Permission ;
33+
odrl:action odrl:modify, odrl:read ;
34+
odrl:target <http://localhost:3000/alice/other/resource.txt> ;
35+
odrl:assignee <https://both.pod.knows.idlab.ugent.be/profile/card#me> .
36+
37+
ex:permission2 a odrl:Permission ;
38+
odrl:action odrl:modify ;
39+
odrl:target <http://localhost:3000/alice/other/resource.txt> ;
40+
odrl:assignee <https://modify.pod.knows.idlab.ugent.be/profile/card#me> .
41+
42+
43+
<urn:uuid:9477c997-adc1-4d64-a12c-fa9e0f6b80f0> a odrl:Prohibition ;
44+
odrl:assignee ex:bob ;
45+
odrl:target <http://localhost:3000/alice/other/resource.txt> ;
46+
odrl:action odrl:use .
47+
48+
<urn:uuid:95efe0e8-4fb7-496d-8f3c-4d78c97829bc> a odrl:Set;
49+
odrl:permission <urn:uuid:f5199b0a-d824-45a0-bc08-1caa8d19a001>.
50+
<urn:uuid:f5199b0a-d824-45a0-bc08-1caa8d19a001> a odrl:Permission;
51+
odrl:action odrl:read;
52+
odrl:target ex:x;
53+
odrl:assignee ex:alice;
54+
odrl:assigner ex:zeno.
55+
`
56+
57+
async function main() {
58+
const parser = new Parser()
59+
// ODRL Evaluator inputs
60+
const sotwQuads = parser.parse(sotw)
61+
const requestQuads = parser.parse(request)
62+
const compactPolicyQuads = parser.parse(compactPolicy)
63+
const odrlEvaluator = new CompositeODRLEvaluator(new ODRLEngineMultipleSteps());
64+
65+
const report = await odrlEvaluator.evaluate(compactPolicyQuads, requestQuads, sotwQuads);
66+
console.log(await write(report, { prefixes }));
67+
68+
const evaluator = new ODRLEvaluator(new ODRLEngineMultipleSteps());
69+
const report1 = await evaluator.evaluate(compactPolicyQuads, requestQuads, sotwQuads);
70+
console.log(await write(report1, { prefixes }));
71+
}
72+
main()

‎documentation/Atomization.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Evaluating ODRL Compact Rules through Atomization
2+
3+
## Compact Rules Problem
4+
The ODRL Evaluator was designed for evaluating ODRL policies with atomic rules.
5+
As such, policies with compact rules produced incorrect answers during evaluation (see [issue](https://github.com/SolidLabResearch/ODRL-Evaluator/issues/3)).
6+
7+
The reason is that all premises on a rule level report MUST be be satisfied.
8+
Request policy evaluation for a compact rule with two distinct actions would result in two action reports, where only one of them would be satisfied.
9+
10+
As such requesting a read action to rules with both read and write actions would always result into an inactive state at the rule level report.
11+
12+
## Solution through atomization
13+
14+
The issue was resolved through reducing each compact rule to a set of **atomic** rules prior to evaluation.
15+
16+
For this, the [`Atomizer`](../src/evaluator/Atomizer.ts) class was introduced that works together with the ODRL Evaluator.
17+
The first step ensures that each rule is properly atomized while preserving its link to the original ODRL rule.
18+
19+
Once atomized, each rule is evaluated individually. After evaluation, the atomic results are merged back together.
20+
For each compact rule, the corresponding rule reports are analyzed and a representative report is selected:
21+
- If any rule report is active, that atomic candidate is chosen.
22+
- Otherwise, the rule report with the highest number of satisfied premises is selected.
23+
Next, each atomic rule is evaluated individually.
24+
Now that each atomic rule is evaluated, we need to merge them again.
25+
26+
The final merged output is returned as a unified policy report.
27+
28+
A specific ODRL Evaluator, the [`CompositeODRLEvaluator`](../src/evaluator/Evaluate.ts) is then created to deal with these kind of policies.
29+
30+
Here is a code snippet:
31+
```ts
32+
const request = ... // list of quads representing the evaluation request
33+
const compactPolicy = ... // list of quads representing the compact policy
34+
const sotw = ... // list of quads representing the state of the world
35+
36+
const odrlEvaluator = new CompositeODRLEvaluator(new ODRLEngineMultipleSteps());
37+
38+
const report = await odrlEvaluator.evaluate(compactPolicy, request, sotw);
39+
40+
```
41+
42+
### Detailed description of the solution
43+
NOTE: this is implemented in the `Atomizer` class
44+
45+
This is how it works in more details:
46+
47+
policy with a compact rule
48+
```turtle
49+
@prefix ex: <http://example.org/>.
50+
@prefix odrl: <http://www.w3.org/ns/odrl/2/> .
51+
52+
ex:usagePolicy1 a odrl:Agreement ;
53+
odrl:permission ex:permission1 ;
54+
odrl:prohibition <urn:uuid:9477c997-adc1-4d64-a12c-fa9e0f6b80f0> .
55+
56+
57+
ex:permission1 a odrl:Permission ;
58+
odrl:action odrl:modify, odrl:read ;
59+
odrl:target <http://localhost:3000/alice/other/resource.txt> ;
60+
odrl:assignee <https://both.pod.knows.idlab.ugent.be/profile/card#me> .
61+
```
62+
63+
Atomization: transform the policy
64+
```turtle
65+
# Atomized Rule 1 for http://example.org/permission1
66+
<http://example.org/usagePolicy1> <http://www.w3.org/ns/odrl/2/permission> _:n3-23 .
67+
_:n3-23 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/ns/odrl/2/Permission> .
68+
_:n3-23 <http://example.org/ns/derivedFrom> <http://example.org/permission1> .
69+
_:n3-23 <http://www.w3.org/ns/odrl/2/target> <http://localhost:3000/alice/other/resource.txt> .
70+
_:n3-23 <http://www.w3.org/ns/odrl/2/action> <http://www.w3.org/ns/odrl/2/modify> .
71+
_:n3-23 <http://www.w3.org/ns/odrl/2/assignee> <https://both.pod.knows.idlab.ugent.be/profile/card#me> .
72+
73+
# Atomized Rule 2 for http://example.org/permission1
74+
<http://example.org/usagePolicy1> <http://www.w3.org/ns/odrl/2/permission> _:n3-24 .
75+
_:n3-24 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/ns/odrl/2/Permission> .
76+
_:n3-24 <http://example.org/ns/derivedFrom> <http://example.org/permission1> .
77+
_:n3-24 <http://www.w3.org/ns/odrl/2/target> <http://localhost:3000/alice/other/resource.txt> .
78+
_:n3-24 <http://www.w3.org/ns/odrl/2/action> <http://www.w3.org/ns/odrl/2/read> .
79+
_:n3-24 <http://www.w3.org/ns/odrl/2/assignee> <https://both.pod.knows.idlab.ugent.be/profile/card#me> .
80+
```
81+
82+
Report for the atomized policy
83+
```turtle
84+
@prefix cr: <https://w3id.org/force/compliance-report#> .
85+
@prefix dct: <http://purl.org/dc/terms/created> .
86+
@prefix ex: <http://example.org/> .
87+
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
88+
89+
<urn:uuid:c7359d5f-c3b9-494e-afc9-5b8abcb05781> a cr:PolicyReport ;
90+
<http://purl.org/dc/terms/created> "2024-02-12T11:20:10.999Z"^^xsd:dateTime ;
91+
cr:policy ex:usagePolicy1 ;
92+
cr:policyRequest <urn:ucp:policy:2a797ad7-232a-4e1f-853f-81388969e4a1> ;
93+
cr:ruleReport <urn:uuid:8ab45cc2-6fdf-4ba1-ba51-95688949cfae>, <urn:uuid:da2e5ad3-f5eb-4e4d-ad43-062457baec06> .
94+
95+
<urn:uuid:8ab45cc2-6fdf-4ba1-ba51-95688949cfae> a cr:PermissionReport ;
96+
cr:attemptState cr:Attempted ;
97+
cr:rule _:n3-23 ;
98+
cr:ruleRequest <urn:ucp:rule:e3ba21f7-57b0-4a43-988a-3221aba858ef> ;
99+
cr:premiseReport <urn:uuid:0b4f74f6-8792-49a3-a9b3-0b0c98eeb153>, <urn:uuid:5db6380d-7e05-4735-8a37-8b2acb88cb69>, <urn:uuid:9b0c2710-615e-4b3a-ae24-e76c26ac1be2> ;
100+
cr:activationState cr:Inactive .
101+
102+
<urn:uuid:da2e5ad3-f5eb-4e4d-ad43-062457baec06> a cr:PermissionReport ;
103+
cr:attemptState cr:Attempted ;
104+
cr:rule _:n3-24 ;
105+
cr:ruleRequest <urn:ucp:rule:e3ba21f7-57b0-4a43-988a-3221aba858ef> ;
106+
cr:premiseReport <urn:uuid:0b4f74f6-8792-49a3-a9b3-0b0c98eeb153>, <urn:uuid:5db6380d-7e05-4735-8a37-8b2acb88cb69>, <urn:uuid:abb81f69-15ae-46e4-adcb-aa2bd7093e69> ;
107+
cr:activationState cr:Active .
108+
109+
<urn:uuid:0b4f74f6-8792-49a3-a9b3-0b0c98eeb153> a cr:TargetReport ;
110+
cr:satisfactionState cr:Satisfied .
111+
112+
<urn:uuid:5db6380d-7e05-4735-8a37-8b2acb88cb69> a cr:PartyReport ;
113+
cr:satisfactionState cr:Satisfied .
114+
115+
<urn:uuid:9b0c2710-615e-4b3a-ae24-e76c26ac1be2> a cr:ActionReport ;
116+
cr:satisfactionState cr:Unsatisfied .
117+
118+
<urn:uuid:abb81f69-15ae-46e4-adcb-aa2bd7093e69> a cr:ActionReport ;
119+
cr:satisfactionState cr:Satisfied .
120+
```
121+
122+
Final report -> selecting the active one
123+
```turtle
124+
@prefix cr: <https://w3id.org/force/compliance-report#> .
125+
@prefix dct: <http://purl.org/dc/terms/created> .
126+
@prefix ex: <http://example.org/> .
127+
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
128+
129+
<urn:uuid:c7359d5f-c3b9-494e-afc9-5b8abcb05781> a cr:PolicyReport ;
130+
<http://purl.org/dc/terms/created> "2024-02-12T11:20:10.999Z"^^xsd:dateTime ;
131+
cr:policy ex:usagePolicy1 ;
132+
cr:policyRequest <urn:ucp:policy:2a797ad7-232a-4e1f-853f-81388969e4a1> ;
133+
cr:ruleReport <urn:uuid:da2e5ad3-f5eb-4e4d-ad43-062457baec06> .
134+
135+
<urn:uuid:da2e5ad3-f5eb-4e4d-ad43-062457baec06> a cr:PermissionReport ;
136+
cr:attemptState cr:Attempted ;
137+
cr:rule _:n3-24 ;
138+
cr:ruleRequest <urn:ucp:rule:e3ba21f7-57b0-4a43-988a-3221aba858ef> ;
139+
cr:premiseReport <urn:uuid:0b4f74f6-8792-49a3-a9b3-0b0c98eeb153>, <urn:uuid:5db6380d-7e05-4735-8a37-8b2acb88cb69>, <urn:uuid:abb81f69-15ae-46e4-adcb-aa2bd7093e69> ;
140+
cr:activationState cr:Active .
141+
142+
<urn:uuid:0b4f74f6-8792-49a3-a9b3-0b0c98eeb153> a cr:TargetReport ;
143+
cr:satisfactionState cr:Satisfied .
144+
145+
<urn:uuid:5db6380d-7e05-4735-8a37-8b2acb88cb69> a cr:PartyReport ;
146+
cr:satisfactionState cr:Satisfied .
147+
148+
<urn:uuid:abb81f69-15ae-46e4-adcb-aa2bd7093e69> a cr:ActionReport ;
149+
cr:satisfactionState cr:Satisfied .
150+
```

0 commit comments

Comments
 (0)