OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

oslc-core message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

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.


•Basic properties (containing terms: label, shortTitle, resourceType,
•Archived Resources (containing term: archived)
  ├ Shape: discussion
  ├ Shape: comment
  └ Terms: discussion (containing terms: Discussion, Comment, inreplyTo,
     discussionAbout, discussedBy, comment)
  ├ 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,

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


[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]:
> core/specs/common-vocab.html
> Thanks,
> Steve Speicher
> IBM Rational Software
> OSLC - Lifecycle integration inspired by the web ->
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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]