Re: Review of core vocabulary

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

Nick, No problem, I know you are very busy.
Comments embedded below.



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




From:      
 Nick Crossley/Irvine/IBM
To:      
 Jim Amsden/Raleigh/IBM@IBMUS
Date:      
 02/18/2016 04:02 AM
Subject:    
   Review of core
vocabulary

---

Jim,

Sorry for being so late, but here (finally)
is my review of the Core Vocabulary.

Nick.


Core vocabulary HTML

Section 3 - archived resource - typo
“achieved resource” in second sentence.

I agree with other reviewers that the
structure of section 4, Motivation, is awkward. The first two paragraphs
are fine, but then the text leaps into introducing some specific terms
or use cases without any transition. Perhaps simply making the following
5 paragraphs into a bulleted list might help. However, I am not convinced
most of this text is needed at all - much of it repeats what is in later
sections.

<jra>I added the
following to the end of paragraph 2 to create a better transition:

"The follow paragraphs
describe the kinds of common terms defined by OSLC core in order to achieve
the stated intent."

And I rewrote the last
paragraph in this section on impact to eliminate the redundancy with the
normative section.</jra>

Para 4 on comments: the phrase “it
would be valuable to have a common way to express this discussion” is
weak. You should say that we have a way to do so, and mention the relevant
classes or properties, just as you did for oslc:archived. Similar comments
apply to the next several paragraphs.

<jra>Fixed</jra>

Why is section 5, Resource Shape, non-normative?
It uses normative words such as SHOULD, MAY, etc.

<jra>Fixed. I moved
the one sentence that should be normative into a separate normative sub-section.</jra>

Section 11, Discovery: I do not feel
the first sentence “No additional discovery needs.” adds any value -
I think it should be deleted.

<jra>Fixed</jra>


Core vocabulary Turtle sources

Why still two vocabulary source files?

<jra>Hummm. I was
thinking to keep ResourcesShapes vocabulary separate so it could be used
independently of OSLC core or domain vocabularies. 

But I see this was incomplete,
many of the shapes rdf:Properties were still defined in core. I merged
the shapes vocabulary into Core and deleted the resouce-shape-vocab.ttl
file.</jra>

@prefix dc and @prefix dcterms - the
vocabs (and some shapes?) use a mixture - we should use just dcterms.

<jra>Agreed, fixed</jra>

The “# **********” comments do not
seem to match the following terms in numerous places. For example, core#Comment
and core#Discussion follow # ***** OSLC2 Paging *****, and not # **********
Properties: Comment **********, nor # ********** Resource Types (Classes)
********** 

<jra>I removed most
of them. They appeared to be a lame attempt at defining structured classes
inside an ontology. The ReSpec generated HTML is for human consumption,
these .ttl files are mostly for machines.</jra>

Several of the rdfs:seeAlso references
refer to the old open-services.net wiki pages. Do you plan to update or
remove those>

<jra>As for Change
Management, I removed all the seeAlso items, they're not that useful.</jra>

<#prov>
Shouldn’t this be linked from the ontology
with a dcterms:provenance clause? ShapeChecker needs to be updated to handle
this if we are going to use it as  a convention.

<#prov>
What does “Authored with OSLC Common
Vocab 3.0” mean? Is that left over from when there were several vocabulary
docs?\

<jra>Fixed. I think
this just means the ontology was specified by the core vocabulary specification.
I reworded this. </jra>

core#Comment
Why include the vs:term_status “stable”?

<jra>I don't know,
it was there and I left it. Its now removed.</jra>

core#Preview
Typo (extra ’T’) at start of rdfs:comment

<jra>Fixed</jra>

core#Compact
rdfs:comment uses ‘another’ unnecessarily
- just say “for an associated resource”

core#shortId
The description (rdfs:comment) copied
from the previous OSLC 2 vocab is wrong, or at least misleading. dcterms:identifier
is typically not human-readable. oslc:shortId is inteded to be human-readable,
and as such, is usually not an abbreviated form of dcterms:identifier.
See http://open-services.net/pipermail/oslc-core_open-services.net/2013-February/001573.html.
I suggest an rdfs:comment of “A short, human-readable, plain text value.
This value should be unique in some context that is apparent to human users
of a service.”

<jra>Fixed</jra>

core#FollowsLink
Impact property name not yet updated
to “ImpactFollowsLink”.

<jra>Fixed</jra>


core#initialHeight
This includes vs:term_status “archaic”,
which is fine - but should the comment or the seeAlso include a reference
to what we use instead?

<jra>Fixed</jra>


core#totalCount, core#results, …
The use of leading spaces in “””
literals spanning several lines leads to odd formatting of the resulting
RDF - the spaces are retained. I suggest avoiding “”” where possible,
and avoiding leading spaces on continuation lines where “”” is used.

<jra>Fixed</jra>

core#allowedValues
The rdfs:comment includes a sentence
“Range of oslc:AllowedValues”. Since the term has an explicit rdfs:range
property, this text is redundant.

<jra>Fixed, and
the description was weak. I've fixed the description of oslc:allowedValues
(essentially an enumeration) and oslc:allowedValue (essentially an anonymous
enumeration) to be a little clearer.</jra>

core#Either
rdfs:comment typo - “Representations”
should be “Representation”, singular.

<jra>Fixed</jra>


core#futureAction, core#executes
What should we do about these?

<jra>I think these
should be left for backward compatibility (they're in the core 2.0 vocabulary)
and to recognize that Actions and Automation 2.0 are still valid OSLC specifications,
just not migrated to OASIS and 3.0 yet. </jra>

Do you intend to use the enum pattern
for things like oslc:representation and oslc:valueType values?

<jra>Yes, fixed.
I noticed some properties were missing an rdf:type and fixed these too.</jra>


Review of selected shapes

CommonProperties-shapes.ttl

The Common Properties shape has several
occurrences of the string ‘servicerProvider’. These should all be ‘serviceProvider’.

<jra>Fixed</jra>

#contributor et al
I thought we were getting rid of the
phrase “It is likely that the target resource will be a …”, and optionally
using oslc:range instead.

<jra>That's still
under study re: OSLCCORE-45, but yes, this will likely be addressed with
oslc:range.<jra>

#Person
I still do not think it right for OSLC
to define a shape for foaf:Person. Even if we do, why did you choose that
specific set of properties? I am not aware that IBM tools use foaf:familyName,
but we do use foaf:mbox and foaf:nick.

<jra>I pulled these
properties from the OSLC 2.0 common vocabulary. Why can't OSLC constrain
foaf:Person for its purposes? Isn't that the purpose of shapes? Regarding
foaf:mbox and foaf:nick, those are reasonable things for an implementation
to include, but do they need to be included in the OSLC specification?
That is, these FOAF properties would seem to be the minimum from FOAF that
OSLC expects.</jra>

#relation, #discussedBy, …
Why the spaces at the front of the comment?

<jra>Probably a
copy/paste issue, removed</jra>

#shortId
See comments about this term in the
vocabulary.

<jra>Copied the
updated description from core</jra>

ResourceShapes-shape.ttl

#property
Description uses the phrase ‘contained
in the described resources’. This is not very RDF-appropriate language.
Better would be something like ‘Indicates an expected property of instances
of the described resources’, or just ‘Indicates an expected property
of the described resources’. Also, should this property include oslc:range,
or oslc:valueShape?

<jra>Fixed the description
as suggested. I don't know of a constraint that is applicable beyone oslc:range,
so I don't know of any oslc:valueShape to specify. I'll deal with oslc:range
when I address the resolution to OSLCCORE-45</jra> 

#occurs, #representation, #valueType
Should define oslc:allowedValue[s] and/or
oslc:range to define the enum of possible values.

<jra>I've created
the enumeration classes, so those can be used. I'll address the oslc:range
with OSLCCORE-45</jra>

#allowedValue
Since you reuse this property defintion
for both the Property and AllowedValues classes, the occurs value is tricky.
You want it to be zero or more for Property, but one or more for AllowedValues.

<jra>Right, I separated
them and adjusted the cardinality</jra>