Re: [oslc-core] Review comments for OSLC Core Vocabulary 3.0

["Jim Amsden" <jamsden@us.ibm.com>]

David, 
Thanks for the great review. Comments
embedded below in <jra> tags.

Things that may need additional discussion:

1. Should dcterms:contributor and dcterms:creator
be dcterm:Agent and not foaf:Person?

2. dcterms:creator (and other similar
properties) have unspecified oslc:range in common porperties, but use foaf:Person
for Comment. Is this intended, or should oslc:range by convention be left
unspecified in OSLC Core, as it is in many domains? There aren't any other
instances of oslc:range with value foaf:Person other than in the Comment
shape.




Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575




From:      
 David Honey <david.honey@uk.ibm.com>
To:      
 "OASIS OSLC Core
TC Discussion List" <oslc-core@lists.oasis-open.org>
Date:      
 01/29/2016 12:13 PM
Subject:    
   [oslc-core]
Review comments for OSLC Core Vocabulary 3.0
Sent by:    
   <oslc-core@lists.oasis-open.org>

---

My review comments on https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/core-vocab.htmlin this colour. 

Best regards, 
David 

--------------------------------------- 


3. Terminology 
Terminology is based on OSLC Core Overview [OSLCCore3],
W3C Linked Data Platform [LDP],
W3C's Architecture of the World Wide Web [WEBARCH],
Hyper-text Transfer Protocol [HTTP11].
The [LDP], [WEBARCH] and [HTTP11]  links do not work.
<jra>This is a recent ReSpec issue
regarding generation of the bibliographic references that Nick is aware
of. Hopefully we'll have a fix sometime next week.</jra>

Archived Resource 
It seems odd starting of with this. The section 4 below it seems to include
a motivation for oslc:archived. It seems like it is in the wrong place.
I think it would be better described in 6.1 Properties on any resource.
If that needs further explanation of what archived means, perhaps it would
be better moved to a.1.245 archived. 
<jra>This is mostly OASIS boilerplate,
defining terms introduced or used in the specification that might be helpful
towards the front of the document.</jra>

4. Motivation 
It seems odd starting of with motivations for specific properties like
archived. I was expecting a more general introduction that described the
motivation of the core specification, and some basic conceptual material,
before moving onto specific items. 
<jra>Agreed. I added a couple of
brief paragraphs introducing the motivation for core vocabulary.</jra>

The [SysML] link does not work. 
<jra>None of the bibliography links
will work until the ReSpec issue is addressed.</jra>

5. Resource Shape 
The [ResourceShapes] and [SHACL] links do not work. I think this section
would be improved by describing what a resource shape is. It might also
be worth describing the difference between a resource shape (as used in
a creation factory) versus one used for query, versus an instance shape.
While the Resource Shape document provides normative information, it helps
to define the overall context in which shapes might be referenced and used.
<jra>I added some common uses of
resource shapes by OSLC, but don't want to duplicate information in other
mutli-part specifications.</jra>

6. Common Properties 
6.1 Properties on Any Resource 
It might be useful to include a reference to dcterms in the spec, for example:
http://dublincore.org/documents/dcmi-terms/
<jra>I added link to dcterms, foaf
and rdfs</jra>

Representation column 
I thought this only applied to statements to resources. Should that column
be blank or "N/A" for literals? 
<jra>Addressed by OSLCCORE-51
</jra>

dcterms:contributor and dcterms:creator
DCMI says the range should be dcterms:Agent which can be a foaf:Person
or organization or software agent. Should the spec mention that rather
than just foaf:Person? 
<jra>I think this relates to authentication
- the value of dcterms:creator would be the user who is authenticated to
do the creation. If this can be a software agent, or organization, then
we should use dcterms:Agent. If its a proxy user used to authenticate the
software agent or represent the organization, then foaf:Person may be sufficient.</jra>

dcterms:relation 
Many tools use dcterms:references. This should this be added to the common
properties? 
<jra>Not sure its needed unless
there are usages of it in OSLC Core or current domains. Otherwise servers
are already free to use it as they wish.</jra>

dcterms:subject 
DCMI says "This term is intended to be used with
non-literal values as defined in the DCMI Abstract Model (http://dublincore.org/documents/abstract-model/).
As of December 2007, the DCMI Usage Board is seeking a way to express this
intention with a formal range declaration. ".
Whereas OSLC usage is for literal strings. 
Because OSLC usage is not-conformant with DCMI, should the spec explicitly
advise users of this? 
<jra>Its not clear its non-conforming.
the comment says: "Typically, the subject will be represented using
keywords, key phrases, or classification codes. Recommended best practice
is to use a controlled vocabulary." This seems consistent with the
its use for tags in OSLC.</jra>

6.2 Person Properties 
The summary says "Person is a common resource
because a Person resource is required as the value for a dcterms:creator
or dcterms:contributor property. ".
However, the table before it does not require that dcterms:creator or dcterms:contributor
be a foaf:Person. 
Suggested revised wording:  "Person is a
common resource because a Person resource is commonly used as the value
for a dcterms:creator or dcterms:contributor property. "
It might be useful to include a link to foaf: http://xmlns.com/foaf/spec/
<jra>I've updated that description
to clarify the shape is intended to express constraints for usage of foaf:Person
in the context of OSLC. Regarding the oslc:range of properties such as
dcterms:creator, OSLC convention is to not overly constrain these properties
to provide server flexibility. The use of foaf:Person as a value is therefore
a recommendation in the description, but not required.</jra>

7.2 Shape: Comment 
dcterms:creator 
The range is defined as foaf:Person, which is inconsistent with the table
for common properties. 
<jra>I see that inconsistency,
and it is unspecified in OSLC2. Not sure why this was specified, perhaps
because Steve wanted to tighten up these properties and provide more specific
metadata for OSLC3.</jra>

9.1 Inverse Labels 
[LinkGuidance]
discourages the creation of inverse predicates. 
The [LinkGuidance] link does not work. 
<jra>Agreed, but since existing
OSLC domains specify things that look like inverses, and tools have implemented
them as co-variant inverses, we have the problem to address. And its only
guidance, not something servers can't do.<jra>

9.2 Traceability and Impact type 
I know that Nick wants to change the names used by Arthur Ryman in http://open-services.net/wiki/core/Vocabulary-Annotation-Vocabulary/.
Should the spec refer to that document? 
Or does this spec supersede it? 
<jra>I supersedes it. I'm personally
not that fond of upstream/downstream, incomming/outgoing because the rely
on perspective. I'd rather see these terms to simply indicate if the impact
is in the same or opposite direction of the property itself - subject-to-object
or object-to-subject. This works from either perspective.<jra>

A.1 Resource: Compact 
A.2 Resource: Preview 
This section appears to duplicate information in the Resource preview document:
https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/resource-preview.html
Are both generated from the same data? 
Perhaps the section should just reference that document since it potentially
needs to describe both RDF predicates and JSON property names.
<jra>This is the whole OSLC Core vocabulary,
for all the multi-part specifications. This information is not duplicated
in the other documents, only the shapes are included in those documents.
This was done to keep the vocabulary in one place, support the requirement
that the vocabulary be in one addressable resource (through open-services
namespace), and the fact that ReSpec doesn't support generation of vocabulary
fragments like it does for shapes.</jra>

B. JSON Representation Format 
I don't think this belongs here. It's already covered in https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/resource-preview.html
<jra>Appendix B is Acknowledgements.
There's no reference to JSON in core-vocab.html. Maybe you were looking
at a different document?<jra>

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU