Re: [oslc-core] Review requested: "OSLC Core Common Vocabulary 3.0"

[Martin P Pain <martinpain@uk.ibm.com>]

Thanks Steve.

Responses inline


<oslc-core@lists.oasis-open.org> wrote on 11/03/2015
19:52:53:

> From: Steve K Speicher <sspeiche@us.ibm.com>
> To: Martin P Pain/UK/IBM@IBMGB
> Cc: "OASIS OSLC Core TC Discussion List"
<oslc-core@lists.oasis-open.org>
> Date: 11/03/2015 19:53
> Subject: Re: [oslc-core] Review requested: "OSLC
Core Common Vocabulary 3.0"
> Sent by: <oslc-core@lists.oasis-open.org>
> 
> Actions taken interwoven below...
> 
> > From: Martin P Pain <martinpain@uk.ibm.com> 
> > To: Steve K Speicher/Raleigh/IBM@IBMUS 
> > Cc: "OASIS OSLC Core TC Discussion List" <oslc-core@lists.oasis-open.org>
> > Date: 02/18/2015 11:35 AM 
> > Subject: Re: [oslc-core] Review requested: "OSLC Core Common
Vocabulary 3.0"
> > Sent by: <oslc-core@lists.oasis-open.org> 
> > 
> > Comment 1: Section 2: Terminology 
> > 
> > I expect this is the definition that was decided during the discussion
on 
> > the "archived" term, but this definition doesn't sound
right to me: 
> > 
> > "Archived Resource 
> > A resource in which an explicit action has been performed to
capture the 
> > current state of a resource and should be considered immutable."
> > 
> > That almost sounds like the definition of a snapshot to me. To
me, which 
> > archived probably does imply immutability, the intention is more
to do with 
> > the fact that it is no longer needed for current operations/activities,
so 
> > can be "put aside" for most purposes. 
> > 
> > Something like: "A resource in which an explicit action
has been performed 
> > to remove it from consideration for the majority of uses. As
a consequence, 
> > it should be considered immutable." 
> > Or: "A resource in which an explicit action has been performed
to remove it 
> > from consideration for day-to-day operations, instead capturing
the current 
> > state of the resource for purposes such as reference, historical
record or 
> > audits. It should be considered immutable." 
> > 
> > The description in the vocab file itself seems more accurate
to me: "no 
> > longer an actively updating resource" 
> 
> I reworked what I have, influenced from your feedback.  Let me
know 
> if you still have a reaction to it.

Perfect

> 
> > 
> > Comment 2: Section 4: Motivation 
> > 
> > It seems strange to me to separate the motivation for each term
orgroup of 
> > terms from the definition of the terms themselves. The motivation
for this 
> > document as a whole has already been covered in the intro. I
would suggest 
> > moving the motivation paragraphs into Section A: RDF Vocabulary,
seeing as 
> > (unlike the other OSLC documents) the vocabulary is the primary
topic of 
> > this document. As this document is not a specification, I see
it as very 
> > different from the spec documents, and so it would be better
to use a 
> > structure that suits its contents rather than being consistent
with 
> > documents that have a different purpose. 
> > 
> 
> I'm not sure what you mean by "not a specification", it
is 
> specifying vocabulary, rules and shapes.  It is not a "typical
> specification" in a sense but then again, each is a little different.


Never mind

> 
> I've decided to leave the motivation up front as is, I find it 
> better then having to piece together motivation from various 
> sections.  Perhaps the TC could discuss if there is a preference
> otherwise.  Perhaps adding links to various sections that address
> the motivating scenarios would be helpful, though the sections 
> follow immediately and fairly clear which goes with what. 

At least we could add sub-section headers into the
motivation section to separate the different things that we are discussing.

I still think that each of the different subject matters
(e.g. discussion, errors, vocabulary description) are fairly stand-alone
and independent from each other, so to me it would make more sense for
the spec template to be applied to each of them in turn (e.g. discussion:
terminology, motivation, conformance, shapes, vocabulary; errors: terminology,
motivation, conformance, shapes vocabulary; etc - to which the recent changes
have moved it closer) rather than splitting the discussion of each topic
across the whole document.
But I'm happy to leave that to check TC consensus
first.

> 
> > 
> > Comment 3: Section 5.3: Implementation Conformance -> Inverse
> Labels (and section 5.4)
> > 
> > How can an implementation conformance section be non-normative?
If we move 
> > the motivation paragraphs into the RDF vocabulary section, then
these sub-
> > sections could move too. 
> > 
> 
> Yes, in my opinion, there can be sections that are as long as they
> are clearly marked (as they are) 

Now these are no longer under "Implementation
conformance" this issue has gone away.

> 
> > 
> > Comment 4: Section 5.5: Shapes and Appendix A: RDF vocabulary
> > 
> > I know it probably means not using the automated script for creating
the 
> > HTML from the vocab file, but I think this document would be
much better if 
> > we grouped it by the type of thing that exists in the vocabulary.
> > 
> > e.g: 
> > 
> > •Basic properties (containing terms: label, shortTitle, resourceType,
> >   instanceShape) 
> > •Archived Resources (containing term: archived) 
> > •Discussion 
> >   ├ Shape: discussion 
> >   ├ Shape: comment 
> >   └ Terms: discussion (containing terms: Discussion, Comment,
inreplyTo, 
> >      discussionAbout, discussedBy, comment) 
> > •Errors 
> >   ├ Shape: Error 
> >   ├ Shape: ExtendedError 
> >   └ Terms: errors (containing terms: Error, ExtendedError,
statusCode, 
> >      moreInfo, message, extendedError, rel) 
> > •Terms for describing vocabularies (containing motivation/description
> >   for inverse labels & impact type, plus terms: name,
inverseLabel, 
> >   impactType) 
> > 
> > Note that the shapes can, of course, use properties from other
sections, not
> > just their own. 
> > 
> > This might suggest that the terms ought to be split up into separate
vocab 
> > files, so then we could generate each of those sections from
each individual
> > file. I don't know. 
> > 
> 
> I've structured it kind of like what you suggested without changing
> the vocab section.  Perhaps this could be done, though not entirely
> sure the work buys us that much more. 

Having looked at the changes so far, I'm happy for
the vocab section to stay where it is. I'd still move not only "Motivation"
but also "terminology" into each of the individual topic matters'
sections.

Also, for the sections that don't have shapes (so,
inverse labels, and impact type) I'd suggest (if possible) adding links
from the sectinos that describe them to the vocabulary terms that apply
to that section.

And, in addition to that, I'd add a "basic properties"
section that merely lists & links to label, shortTitle, resourceType,
& instanceShape (and we could probably author a "motivation"
for them too... maybe).
(should this be under the existing section 5 "common
properties"? I don't think so. I think I'd suggest making section
5.1 a top-level section, probably "5. Common properties implementation
conformance" - as it applies to all terms in the document, then a
new section between sections 5 and 6 called "6. Basic properties"
or similar. All these properties are "common", but the ones I
list as "basic" above can apply to any resource, whereas the
other common ones are for specific types.)

> 
> > 
> > Comment 5: term descriptions 
> > Then there's also the term description themselves which could
do with a 
> > review, although that could be argued isn't part of reviewing
this
> document itself. 
> > 
> > A quick pass: 
> > A. resourceType: "The expected resource type URI of the
resource that will 
> > be created using this creation factory." - is this really
only for
> creation factories? 
> 
> Yes, updated it. 
> 
> 
> > B. name: "Name of property being defined, i.e. second part
of property's 
> > Prefixed Name." - I presume that is accurate, that this
is only used for 
> > property names? We might want to say something like "for
all other uses, 
> > consider dcterms:title, oslc:shortTitle or oslc:label".
> 
> Updated it, though this term is so generic I wonder if we shouldn't
> limit its use as defined above to be only in the "Shape"
and then 
> definition to mean just a "name" for the resource. 

I suggest leaving it specific. As I can't see how
a more general definition could be reasonably different from dcterms:title/rdfs:label
(which as far as I know are already the same), oslc:shortTitle/oslc:label
(again, how are these different?) or dcterms:identifier (which seems to
be the closest to oslc:name, as a prefixed name is much more of a "technical"
name than the other predicates)

> 
> > C. instanceShape: "The URI of a Resource Shape that describes
the possible 
> > properties." is that 'possible properties for the subject
resource', or does
> > that depend on context? 
> 
> reworked. 
> 
> > D. rel: "If present and set to 'alternate' then indicates
that work-around 
> > is provided, behavior for other values is undefined." The
linked spec [1] 
> > doesn't specify more information on how to provide a work-around.
Do we have
> > a scenario for it? If not, at first sight this looks like a candidate
for 
> > deprecation. "rel" is usually used in the context of
a link, so I can't 
> > quite parse why rel=alternate here is saying there's a work-aroundprovided.
> > If there is a scenario defined for it somewhere, do we want to
make this 
> > more general-purpose to make it useful in other places? 
> 
> Looking closer, and going from experience, I'm not sure this portion
> was ever used or used much in 2.0 implementations. 
> 
> PROPOSAL: Deprecate the "rel" property 

Second

> 
> > E. message: "An informative message describing the error
that occurred." - 
> > we could easily make this more general-purpose. 
> 
> Sure. 
> 
> PROPOSAL: rewrite term definition to be "An information message
> associated with the subject resource". (not sure we even need
the 
> 'associated with' part) 

If we just went with "An information message",
what does the word "information" add? Maybe "A message that
is being communicated by the subject resource." (If it's being communicated
about the subject resource, rather than by it, then the "discussion"
vocabulary is probably more appropriate, but we don't have to constrain
that here if we don't want to.)

> 
> > F. discussionAbout/discussedBy - inverse properties? Should we
deprecate 
> > one? Or are they not truly inverse? Or both needed? 
> 
> Agree, duplicate.  I thought I had removed them all. 
> 
> I have done this now, keeping the "discussionAbout" version.
 I've 
> made the change, if anyone has issue with it...well, raise an issue
;) 
> 
> > 
> > 
> > Comment 6: Links to spec 
> > The terms still link to the v2 spec. Do we have places in the
v3 documents 
> > to link to. Should most of them be linking to this document?
(This would 
> > also be easier if we had sections as suggested above). Or will
we have 
> > separate specs for errors, discussion, etc? (In which case I'm
notsure the 
> > terms should be in this document). 
> > 
> 
> Ya, on todo list.  I just ran out of steam when I was moving
things over. 
> 
> Thanks, 
> Steve 
> 
> > 
> > 
> > Martin 
> > 
> > 
> > [1] http://open-services.net/bin/view/Main/
> > OslcCoreSpecification#Resource_Extended_Error 
> > 
> > 
> > 
> > <oslc-core@lists.oasis-open.org> wrote on 13/02/2015 21:20:01:
> > 
> > > From: Steve K Speicher <sspeiche@us.ibm.com> 
> > > To: "OASIS OSLC Core TC Discussion List" <oslc-core@lists.oasis-open.org>
> > > Date: 13/02/2015 21:21 
> > > Subject: [oslc-core] Review requested: "OSLC Core Common
Vocabulary 3.0" 
> > > Sent by: <oslc-core@lists.oasis-open.org> 
> > > 
> > > If not about Thursday's meeting, I would like to have a
couple of 
> > > people sign up to review this document [1]. 
> > > 
> > > In the spirit of keeping thing easily consumable, this document
is 
> > > fairly small. 
> > > 
> > > Please email the list if you are willing to be a reviewer
and any 
> > > feedback you have.  Thanks in advance. 
> > > 
> > > [1]: http://tools.oasis-open.org/version-control/browse/wsvn/oslc-
> > > core/specs/common-vocab.html 
> > > 
> > > Thanks,
> > > Steve Speicher
> > > IBM Rational Software
> > > OSLC - Lifecycle integration inspired by the web -> http://open-
> services.net
> > 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 
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