[poe] Issue: What properties are used with which classes? marked as enhancement

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

== What properties are used with which classes? ==
The definitions of classes, more exactly the properties used on those classes, along the two documents (model and vocab) is not in sync. This makes reading the documents a bit difficult...

I have checked only the `Policy` class in more details:

1. The UML diagram in the model suggests that the allowed properties on that class are `uid`, `type`, `conflict`, `undefined`, `inheritAllowed`, and `profile`. By virtue of being a subclass of `Asset` it can also use `scope`, and via some UML tricks (that I do not really understand) the `inheritFrom` also appears.
2. The definition [in the text](https://w3c.github.io/poe/model/#h-policy) lists the first group, but does not refer to `scope`. O.k., that is still fine, but the fact that `inheritFrom` does not appear here bothers me.
3. The examples in the model document use the `@id` term which, I would think, corresponds to the `uid` by virtue of the JSON-LD encoding, and to `@type` for `type`. This is mentioned in a Note but I have not seen it clearly documented that the general terms map to these and these features of RDF. This is important to make the serialization in other syntaxes clear.
4. The examples in the model document also use properties like `permission` or `prohibition`. This comes out of the blue for the reader; of course, one can understand that these refer to a `Permission` or `Prohibition`, respectively, but on the spec level that isn't o.k.
5. One can then look at the [Definition in the vocab document](https://w3c.github.io/poe/vocab/#h-term-policy). The definition lists   `conflict`, `inheritAllowed`, `inheritFrom`, `permission`, `profile`, `prohibition`, `undefined`. Note that `permission` and `prohibition` is present, which is good. It does not explicitly refer to `uid` and `type` because those are RDF notions anyway; see above. Note the presence of `inheritFrom` which is fine.
6. But then... the examples include properties like `assigner`, `action`, `target`, and probably others, that are not listed anywhere.

(I have not checked the other classes but there may be similar issues...)

There are too many places defining properties and it is not clear which is the authoritative one. To be perfectly honest, the UML diagram does not really talk to me, and I just see it as an extra source of possible problems. But if we choose to keep it, things should be in sync... 

I wonder whether it would not make it easier to the reader if we placed a link to the relevant entry in the vocab document for each class (e.g., a link to 4.1.1. in the vocab from 3.1 in the model). The latter should also include the 'assigner', etc., if we want to keep them really (I am not 100% sure, it may be cleaner to use only expanded rules...). The vocab document should be the authoritative definition. 



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

Received on Thursday, 20 April 2017 04:25:03 UTC