Model editorial

[riannella]

@aisaac

4. Simple editorial suggestions:

• in 3.1 it would be good if the list of attributes could refer to the various sections that follow. And that these sections would be given in the order of the list! Otherwise the list’s explanations read quite rough.

• the order of subsections in 3(.1) seems quite unnatural. I don’t understand why I had to read about the intricacies of policy composition, conflict strategy or undefined actions before reading about the basics of rules and assets. This would for example caused me to ponder why ‘permission’ is used as a property in the JSON listings of example 1 and below, while it had been only refered to as a Class in the text so far.
  Going through the model via a ‘depth-first’ approach for each class has some advantages, but it does really prevent a newcomer to get the basics right. Maybe a first section could explain the basic classes and relationships between them, and a second question would tackle the rest of complex issues, class by class. Such organization would also allow to put some debated constructs (Undefined Actions in 3.1.4) more towards at the end of the document.

• in 3.1.1 the sentence with ’irreducible’ could mention that the notion is exemplified afterwards. Since it’s in italics without explanation, it made me feel that I should understand it, while it had not been defined. And ‘unambiguous’ could be removed, as it’s not defined or exemplified anywhere, as far as I can tell.

• why is dct:isReplacedBy in bold in “If a Policy contains the dc:isReplacedBy property” in 3.1.2? It’s not in bold in the bullet list above.

• in 3.1.3 “the print Action is a subset of the use Action”. This is confusing when one thinks of RDF/OWL class/sub-class relationships with set semantics. print and use are not classes. It would be more exact to write “the print Action is a specialization of the use Action”

• identifiers of sections in the HTML document structure should be checked. E.g. 3.1.5 has ‘inhertiance’ as id.

• in 3.3.1 “additiion” -> “addition”

• in 3.4 “An ODRL policy expression MAY contain at least one Permission.” is not really informative from a semantic perspective. Except for correcting the wrong understanding that can be caused by the sentence just before it (see comment above). But if that sentence is fixed, then this one could be removed.

• in 3.6 “this is used to refer the same Duty to multiple Permission entities.” -> “this is used to refer from a Duty to multiple Permission entities.” ?

• in 3.8 “EU dollars”???

[riannella]

1 - Added links
2 - Have reordered the sections
3 - Fixed and explained irredicible
4 - Fixed (now consistent)
5 - Fixed
6 - fixed
7/8 - Fixed previously with model update
9 - Updated

Commit 28791d6

[aisaac]

1. OK 2. Much better like this! 3. OK I understand it now! 4. OK 5. OK 6. OK 7/8. OK 9. OK

…

On 04/05/17 07:26, Renato Iannella wrote: 1 - Added links 2 - Have reordered the sections 3 - Fixed and explained irredicible 4 - Fixed (now consistent) 5 - Fixed 6 - fixed 7/8 - Fixed previously with model update 9 - Updated Commit 28791d6 <28791d6> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#163 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAnpresKdNRad_zNSr0wimqgGOaM4dqNks5r2WF1gaJpZM4NNsDd>.

[riannella]

Wide review changes accepted.