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

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

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"



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.



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.



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.



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?
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".
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?
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?
E. message: "An informative message
describing the error that occurred." - we could easily make this more
general-purpose.
F. discussionAbout/discussedBy - inverse
properties? Should we deprecate one? Or are they not truly inverse? Or
both needed?



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



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