Review comments for OSLC Core Vocabulary 3.0

[David Honey <david.honey@uk.ibm.com>]

My review comments on https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/core-vocab.html
in 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.


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.

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.

The [SysML] link does not
work.

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.

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/

Representation column
I thought this only applied
to statements to resources. Should that column be blank or "N/A"
for literals?

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?

dcterms:relation 
Many tools use dcterms:references.
This should this be added to the common properties?

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?

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/

7.2 Shape: Comment
dcterms:creator 
The range is defined as foaf:Person,
which is inconsistent with the table for common properties.

9.1 Inverse Labels
[LinkGuidance]
discourages the creation of inverse predicates. 
The [LinkGuidance] link does
not work.

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?

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.

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

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