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

[Steve K Speicher <sspeiche@us.ibm.com>]

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.
 
> 
> Comment 2: Section 4: Motivation 
> 
> It seems strange to me to separate the motivation for each term or
group 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.

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.

> 
> 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)

> 
> 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.

> 
> 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.

> 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-around
provided.
> 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

> 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)

> 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 not
sure 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