| [Thread Prev]
| [Thread Next]
| [Date Next]
| [Thread Index]
| [List Home]
Subject: Re: [oslc-core] Review requested: "OSLC Core Common Vocabulary 3.0"
- From: Steve K Speicher <email@example.com>
- To: Martin P Pain <firstname.lastname@example.org>
- Date: Wed, 11 Mar 2015 15:52:53 -0400
Actions taken interwoven below...
> From: Martin P Pain <email@example.com>
> To: Steve K Speicher/Raleigh/IBM@IBMUS
> Cc: "OASIS OSLC Core TC Discussion List"
> Date: 02/18/2015 11:35 AM
> Subject: Re: [oslc-core] Review requested: "OSLC
Core Common Vocabulary 3.0"
> Sent by: <firstname.lastname@example.org>
> Comment 1: Section 2: Terminology
> I expect this is the definition that was decided during the discussion
> the "archived" term, but this definition doesn't sound right
> "Archived Resource
> A resource in which an explicit action has been performed to capture
> current state of a resource and should be considered immutable."
> That almost sounds like the definition of a snapshot to me. To me,
> archived probably does imply immutability, the intention is more to
> the fact that it is no longer needed for current operations/activities,
> can be "put aside" for most purposes.
> Something like: "A resource in which an explicit action has been
> 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
> state of the resource for purposes such as reference, historical record
> audits. It should be considered immutable."
> The description in the vocab file itself seems more accurate to me:
> 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
> terms from the definition of the terms themselves. The motivation
> document as a whole has already been covered in the intro. I would
> moving the motivation paragraphs into Section A: RDF Vocabulary, seeing
> (unlike the other OSLC documents) the vocabulary is the primary topic
> this document. As this document is not a specification, I see it as
> different from the spec documents, and so it would be better to use
> 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
> the motivation paragraphs into the RDF vocabulary section, then these
> 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
> HTML from the vocab file, but I think this document would be much
> 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,
> 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,
> just their own.
> This might suggest that the terms ought to be split up into separate
> files, so then we could generate each of those sections from each
> 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
> review, although that could be argued isn't part of reviewing this
> A quick pass:
> A. resourceType: "The expected resource type URI of the resource
> 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
> Prefixed Name." - I presume that is accurate, that this is only
> property names? We might want to say something like "for all
> 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
> properties." is that 'possible properties for the subject resource',
> that depend on context?
> D. rel: "If present and set to 'alternate' then indicates that
> is provided, behavior for other values is undefined." The linked
> 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
> 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
> If there is a scenario defined for it somewhere, do we want to make
> 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.
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
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
> also be easier if we had sections as suggested above). Or will we
> separate specs for errors, discussion, etc? (In which case I'm not
> terms should be in this document).
Ya, on todo list. I just ran out of steam when
I was moving things over.
>  http://open-services.net/bin/view/Main/
> <email@example.com> wrote on 13/02/2015 21:20:01:
> > From: Steve K Speicher <firstname.lastname@example.org>
> > To: "OASIS OSLC Core TC Discussion List" <email@example.com>
> > Date: 13/02/2015 21:21
> > Subject: [oslc-core] Review requested: "OSLC Core Common
> > Sent by: <firstname.lastname@example.org>
> > If not about Thursday's meeting, I would like to have a couple
> > people sign up to review this document .
> > In the spirit of keeping thing easily consumable, this document
> > fairly small.
> > Please email the list if you are willing to be a reviewer and
> > feedback you have. Thanks in advance.
> > : 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
> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire
| [Thread Prev]
| [Thread Next]
| [Date Next]
| [Thread Index]
| [List Home]