[poe] Issue: 3. ODRL Information Model marked as Editorial

riannella has just labeled an issue for https://github.com/w3c/poe as 
"Editorial":

== 3. ODRL Information Model ==
> The basic context of an ODRL Policy is that only an explicitly 
permitted **use** may be **executed**. 

what? how's the context of an ODRL policy defined? how does one 
*execute* the *use*? the use of what?
Given that ODRL defines both `odrl:use` and `odrl:execute`, this might
 cause confusion.

> Any use not explicitly permitted is prohibited by default. An ODRL 
Policy only permits the action explicitly specified in a Permission 
and all other actions are implicitly prohibited. 

Isn't that domain specific? Why do we need to make those statements? 

> An action defined in a Prohibition SHOULD only refine (or directly 
relate to) the semantics of an action defined in one of the 
Permissions in the ODRL Policy.

that's not only limiting the applicability/usefulness of ODRL in 
general, but also not reflected in the examples of the spec.

> For example, an ODRL Policy that has the action “present” Permission
 and may also have the action “print” Prohibition (as these actions 
are related hierarchically in the ODRL Vocabulary [vocab-odrl]).

phrasing; do we need that part at all? -> remove

> Note that ODRL Profiles can be developed and used to refine the 
basic context of an ODRL Policy. Hence, the application of an ODRL 
Profile must be understood by the consuming community and systems.

do we need to mention profiles here? -> remove

> As the Information Model diagram shows the key Permission, 
Prohibition and Duty entities are subtypes of the abstract Rule class.
 

too much prose.. also s/entities/classes, s/subtypes/subclasses

> These Rules have the same relationships to the other key entities 
(Action, Constraint, Asset, and Party). 

what *Rules*? they all have the **same** relationships to other 
concepts? why do we need to make this statement?

> The core difference is in their semantics:
> - Permission says that the Party MAY perform an Action,
> - Duty says that the Party MUST perform an Action, and
> - Prohibition says that the Party MUST NOT perform an Action.

up to this point the reader does not know what a Party and/or Action 
is. What about assets? What if no party is defined? This list also 
suggests that a duty is a standalone concept, i.e., doesn't need to 
have a sorrounding permission to be applied to (which is wrong). 
I would also not use RFC2119 terms for non-implementation specific 
things.

> The Rule class also makes it possible to easily extend the 
Information Model in Profiles by adding policy expressions (as 
subclasses of Rule) that are not possible by default.

what's the purpose of this statement? -> remove

> The cardinalities shown in the ODRL Information Model allow for 
**the greatest flexibility** in expressing associations between the 
key entities. 

we don't need to sell ODRL to anyone + inappropriate for a W3C 
recommendation 

> A Permission MAY allow a particular Action to be executed on a 
related Asset,

again, executed as in `odrl:execute`? what's a related asset?

> A Constraint such as “at most 10 times” might be added to specify 
the Permission more precisely. 

which means? does it limit the validity of the rule it is defined for 
or are two rules one w/ and one w/out a constraint actually 
equivalent, but one is more precise than the other?

>  e.g., “assigner VirtualMusicShop grants the Permission to Assignee 
Alice”.

to do what? 

> Additionally, a Permission MAY be linked to Duty entities.

so..? 
do we need that paragraph at all? despite being hard to understand, we
 do explain all the concepts later on anyway.

> Similar to Permissions, a Duty states that a certain Action MUST be 
executed by the Party with the Role Assignee for the Permission to be 
valid, e.g. ...

wait what? why is this similar to permissions? for what permission? 
what if there's no party with role assignee defined (like in Example 
21)? What's the intended semantics of an invalid permission (or rule 
in general)? remove example

> The Prohibition entity is used in the same way as Permission, with 
the difference that it MUST NOT refer to Duties and that the Action 
MUST NOT be exercised, e.g. “Alice is forbidden to use abc.mp3 
commercially”.

so they are not used in the same way.. also (imho) misleading use of 
RFC2119 keywords;
how does one *refer* to a duty? *the Action* -> what action? 
*forbidden* == *prohibited*? remove example

> The following sections describes each entity of the Information 
Model in greater detail

so why do it sloppily here? 

My suggestion:
1. Remove all unnecessary/zero-value statements
2. Remove all informal examples  

fwiw, I very much like [SHACL's intro 
section](http://w3c.github.io/data-shapes/shacl/#shacl-example) 

See https://github.com/w3c/poe/issues/95

Received on Monday, 30 January 2017 02:34:58 UTC