| [Thread Prev]
| [Thread Next]
| [Date Next]
| [Thread Index]
| [List Home]
Subject: Re: [oslc-core] Re: Review of core vocabulary
- From: "Nick Crossley" <firstname.lastname@example.org>
- To: "Jim Amsden" <email@example.com>
- Date: Fri, 19 Feb 2016 10:14:13 -0800
On the FOAF part - I had forgotten that OSLC Core 2.0 had a property table for foaf:Person. Given that it did, I withdraw any objections to defining a shape. We should keep the existing givenName and familyName properties because they are there in 2.0, even if they are not used in current tools. However, we really should add foaf:nick and foaf:mbox, because we want/need providers to add those properties in their implementations.
- foaf:nick is typically the login or authentication ID, and so is often used as the display column in UIs.
- foaf:mbox is likely to be a common value across different tools using different authentication mechanisms. For example, it is the only way today you can join users in Jazz tools with users in DOORS 9, Clearcase, etc.
For compatibility with OSLC Core 2.0, and for equivalence with the existing name properties, the cardinality of both these two new properties should be zero or many.
Jim Amsden---02/19/2016 09:17:57 AM---Nick, No problem, I know you are very busy. Comments embedded below. Jim Amsden, Senior Technical St
From: Jim Amsden/Raleigh/IBM@IBMUS
To: "OSLC Core TC (firstname.lastname@example.org)" <email@example.com>
Date: 02/19/2016 09:17 AM
Subject: [oslc-core] Re: Review of core vocabulary
Sent by: <firstname.lastname@example.org>
Nick, No problem, I know you are very busy. Comments embedded below.
Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
From: Nick Crossley/Irvine/IBM
To: Jim Amsden/Raleigh/IBM@IBMUS
Date: 02/18/2016 04:02 AM
Subject: Review of core vocabulary
Sorry for being so late, but here (finally) is my review of the Core Vocabulary.
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.
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.
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.
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>
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.
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>
Why include the vs:term_status “stable”?
<jra>I don't know, it was there and I left it. Its now removed.</jra>
Typo (extra ’T’) at start of rdfs:comment
rdfs:comment uses ‘another’ unnecessarily - just say “for an associated resource”
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.”
Impact property name not yet updated to “ImpactFollowsLink”.
This includes vs:term_status “archaic”, which is fine - but should the comment or the seeAlso include a reference to what we use instead?
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.
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>
rdfs:comment typo - “Representations” should be “Representation”, singular.
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
The Common Properties shape has several occurrences of the string ‘servicerProvider’. These should all be ‘serviceProvider’.
#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>
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>
See comments about this term in the vocabulary.
<jra>Copied the updated description from core</jra>
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>
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>
| [Thread Prev]
| [Thread Next]
| [Date Next]
| [Thread Index]
| [List Home]