Actions taken interwoven below...
> From: Martin P Pain <>
> 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: <>
>
> 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
>
>
>
> <> wrote on 13/02/2015 21:20:01:
>
> > From: Steve K Speicher <>
> > To: "OASIS OSLC Core TC Discussion List" <>
> > Date: 13/02/2015 21:21
> > Subject: [oslc-core] Review requested: "OSLC Core Common
Vocabulary 3.0"
> > Sent by: <>
> >
> > 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
