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"

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?


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


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.


> Martin
> [1]
> 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]