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


Help: OASIS Mailing Lists Help | MarkMail Help

oslc-promcode message

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

Subject: Re: [oslc-promcode] Re: Including files in specifications for PROMCODE

> The files in question are RDF which do qualify as computer language files

Yes, I would have thought so, given the principal intended use of any common (.n3, .ttl, etc) serialization.  So, thanks, Arthur.  I think I understand (enough) about various serializations you might want to use, including support for any of these, as we have already agreed:


The OASIS TC Process section on "Computer Language Definitions" is motivated by the concern that machine-readable files be made available AS (separate) plain text -- that is, separate from an Appendix or (Sub-)Section within a narrative prose document.  Prior to the formulation of the TC Process rule (here:  https://www.oasis-open.org/policies-guidelines/tc-process#quality-formalLangDefns ). OASIS TCs would sometimes present an XSD, DTD, or other machine-readable file ONLY in the prose document, from which users would need to screen-scrape or otherwise extract content to create a usable "file" (directly usable by a parser or other applications software).  Arguably, that extraction process is error-prone, and may not preserve white space conventions, etc, etc, etc.   Hence: the requirement that any such representations (serializations, formats, whatever), even if displayed verbatim as display text within the prose document, must be included as separate files in each release.  The manifest document we publish with each release includes an MD5/SHA-1 digest value for each such separate machine-readable file (QA support).

We have already agreed to provide support for transparent content negotiation, as needed, in providing representations (e.g., based upon Accept headers in requests).

The OASIS requirement to publish "plain text" as separate files is agnostic about how the plain text "computer language definition" files (static storage objects) are created or generated.  We do want them created AS files and placed (bitwise) on the file system in the official publication hierarchy.

Similarly, it's understood that you can indeed generate the HTML for a vocabulary as part of your processing (XSLT or whatever).  That's great (and cool).

So I think nothing is in doubt here other that the details about construction of the URIs for the primary prose document (or for multiple independently titled prose documents in a Multi-Part Work Product), where the URIs for a prose specification cover page should conform to the Naming Directives.  For that purpose, is essential that commitment is made to "Work Product" as the fundamental entity: it is key to construction of the URIs, which transparently reflect the directory hierarchy in the production/publication server. 

To make that clearer, perhaps: the section "Required Document URIs" pertains to construction of URI references for a prose Document Cover Page; see: 

For a simple Work Product, there would be only one main/principal titled prose document, and it must conform to the template provided by TC Administation, with al the required sections.  Its cover page displays the required URIs (aka "document URI") which identify the Work Product as a whole.   Any other HTML documents that are part of the Work Product need not conform to the same "document URI" pattern: the filenames may be release-agostic and version-agnostic, for example (incorporating no filename component for Version or Stage or Revision).

The rules for constructing  (prose cover page) "document URIs" are a bit more verbose, but follow the same essential pattern as for a simple Work  Product having one primary prose document; the URIs add components for "parts" if the Multi-Part Work Product has independently titled prose parts:


Please let me know if we can provide additional guidance here.  

- Robin

On Wed, Dec 17, 2014 at 12:30 PM, Arthur Ryman <ryman@ca.ibm.com> wrote:

The files in question are RDF which do qualify as computer language files.
RDF is not itself a format. RDF can be represented in several formats,
e.g. RDF/XML, Turtle. That explains why we have both .rdf and .ttl files.
In practice, Turtle is the source that humans edit. We programmatically
generate RDF/XML since not all applications support Turtle. In addition,
we programmatically generate HTML. We do this to provide a human-readable
representation. Think of this as being like Javadoc.

The RDF resource itself has a URI that omits the file extension. It is
supposed to identify the conceptual resource. We use HTTP content
negotiation to serve up the format preferred by the requester. This is a
W3C Best Practice. See [1].

[1] http://www.w3.org/TR/cooluris/
Arthur Ryman
Chief Data Officer
SWG | Rational
905.413.3077 (phone) | 416.939.5063 (cell)
IBM InterConnect 2015

From:   Robin Cover <robin@oasis-open.org>
To:     Kazuhiro Funakoshi <k-f@bk.jp.nec.com>
Cc:     Arthur Ryman/Toronto/IBM@IBMCA,
"oslc-promcode@lists.oasis-open.org" <oslc-promcode@lists.oasis-open.org>,
Steve K Speicher <sspeiche@us.ibm.com>, Robin Cover <robin@oasis-open.org>
Date:   12/17/2014 09:59 AM
Subject:        Re: [oslc-promcode] Re: Including files in specifications


Time out.   I see now upon morning's re-read of my message below that in
the final portion, I cited the expected naming patterns for a typical
OASIS Work Products "prose document", which incorporates what we call a
"document identifier".   I overlooked an embedded message (Arthur's) which
suggested that one or more of the files in question be treated as computer
language definition files.  The example URI reference I provided for an
HTML representation would match a typical OASIS Work Products "prose
document" -- and we don't usually consider an HTML document a "computer
language definition".

TC Process uses examples to describe "Computer Language Definitions" [1],
-- XML instances, schemas, and Java code, including fragments of such --
which must be published as "separate plain text files", referenced by URI
reference from the Work Product's narrative/prose specification document

b) ... " machine-readable computer language definitions (e.g.,DTDs,
schemas, WSDLs, XML/JSON artifacts...) [Naming Directives]

A "machine-readable" (aka) "Computer Language Definition" file in plain
text is one intended primarily for machine processing, not in styled
rendering intended primarily for reading as narrative by a human.

But I can see the need for clarifying discussion about the constitution of
Work Products in the PROMCODE TC and in related OSLC TCs, and I recall
that Steve sketched an outline of the types of files and resources that
would make up a typical Work Product (obviously a Multi-Part Work
Product).  Let's take a step back -- and initially off-list -- to get
clarification on some of these details.


- Robin

[1]  TC Process: Computer Language Definitions

(7) Computer Language Definitions. All normative computer language
definitions that are part of the Work Product, such as XML instances,
schemas and Java(TM) code, including fragments of such, must be well
formed and valid.
(7a) For Standards Track Work Products:
All normative computer language definitions must be provided in separate
plain text files;
Each text file must be referenced from the Work Product; and
Where any definition in these separate files disagrees with the definition
found in the specification, the definition in the separate file prevails.
(7b) For Non-Standards Track Work Products:
All computer language definitions should be provided in separate plain
text files; and
Each text file should be referenced from the Work Product.

On Tue, Dec 16, 2014 at 7:59 PM, Robin Cover <robin@oasis-open.org> wrote:

> Hi Robin,
> (2) above also has been discussed, right?
> Is it a correct behavior that v1.0 shapes refer to v2.0 or newer


Your question in the context of this thread seems to relate to the notion
of "Version" with respect to the OASIS identifier schemes -- and not to
vocabulary "versions" under a (different) open-services.net versioning
scheme ... right?  Assuming that you mean OASIS "Version", I'll try to
clarify how we use namespace name identifiers and versioning

* Version:

A "Version" is identified with a unique Work Product, used in all releases
for the specification lifecycle for that Work Product ( WD, CSD, CS, COS,
OS).  Once the Work Product comes to CS or OS (OASIS Standard) level (or
is abandoned), that "Version" is complete.

While a Work Product is progressed through its lifecycle, namespace name
identifiers can also be revisioned (e.g., incremented using numeric
components in sequence), per the wishes of the TC

The Naming Directives document clarifies that for namespace URIs using the
docs.oasis-open.org domain ( pattern:
http://docs.oasis-open.org/[tc-shortname]/ns/xxxx ), the final "xxxx"
should ( should, not must) "incorporate a versioning subcomponent (e.g., a
string like 201011 representing a date or v1.1 representing a version
number)".  In the case of the OSLC specs, where legacy namespace name URIs
and construction patterns are being used, the OASIS guidance about
"versioning subcomponent" is not directly applicable

If the TC wants to use a namespace name URI for a spec that applies to
more than one Version of the specification  (e.g.,
http://open-services.net/ns/promcode# ) -- that should be OK as far as I
know.  Whatever URI aliasing machinery is set up to deliver the correct
representation from the OASIS server when the "open-services.net" URI
reference is dereferenced -- should fetch/deliver whatever the TC elects.
In the case of traditional OASIS specs, namespace name URIs have often
been versioned (per Naming Directives "should") in support of a TC's goals
for implementation, conformance, etc.  But if you don't want to (verbatim)
version your namespace names, I think that's up to you, per SemWeb

Irrespective of the above, the use of "Latest version:" URIs is scoped to
a particular OASIS "Version".  That's orthogonal to the conventions your
TC may want to use in versioning or nor versioning a namespace name URI

How OASIS "Latest version:" URIs work in the case of "Versions": the KMIP
Profiles will illustrate the point: "Latest" is bound to one Version, and
does not cross Versions


A couple more clarifications below:

On Tue, Dec 16, 2014 at 7:05 PM, Kazuhiro Funakoshi <k-f@bk.jp.nec.com>

Thank you for information.
I will change current our shape document as you told me.

However, the following lines seems not correct, does it?




In the case of a Work Product "projectshape", we expect for the
version-specific (per release) identifiers:




Hope that helps.  If not, or if I messed up something (on too little
sleep), please let me know.

- Robin

They should be:



I will change our shape document in WebSVN as once they are approved, then
we can simply copy from WebSVN to docs.oasis-open.org.

When we have v2.0, if we use [1] as stable @prefix for v1.0 shape document
it will means v1.0 shape documents uses v2.0 vocabulary document, because
[1] redirect to v2.0 vocabulary document.
I understand we will never change existing v1.0 content but only extend as
v2.0, still confusing.
This wouldn't happen for shape document because it seems not have stable
redirect URL between major versions as you said:

> The shape document for Project resources will be:
> http://open-services.net/ns/promocode/shapes/1.0/project

Is my understanding correct?

[1] http://open-services.net/ns/promcode#

Hi Robin,

(2) above also has been discussed, right?
Is it a correct behavior that v1.0 shapes refer to v2.0 or newer


-----Original Message-----
From: oslc-promcode@lists.oasis-open.org
[mailto:oslc-promcode@lists.oasis-open.org] On Behalf Of Arthur Ryman
Sent: Wednesday, December 17, 2014 2:36 AM
To: oslc-promcode@lists.oasis-open.org
Cc: Steve K Speicher; robin@oasis-open.org
Subject: RE: [oslc-promcode] Re: Including files in specifications for


I forgot that vocabularies and shapes are "computer language definitions".
Therefore we can use simpler URLs, e.g. the latest versions would be


Arthur Ryman
Chief Data Officer
SWG | Rational
905.413.3077 (phone) | 416.939.5063 (cell) IBM InterConnect 2015

Arthur Ryman/Toronto/IBM wrote on 12/16/2014 11:49:48 AM:

> From: Arthur Ryman/Toronto/IBM
> To: "oslc-promcode@lists.oasis-open.org"
> Cc: Steve K Speicher/Raleigh/IBM@IBMUS, robin@oasis-open.org
> Date: 12/16/2014 11:49 AM
> Subject: RE: [oslc-promcode] Re: Including files in specifications for
> Kaz,
> Originally I thought we would use the oasis-open.org domain for URIs.
> However, I talked with Robin and Steve and the thinking now is that
> since we already have a lot of vocabularies on the open- services.net
> domain, we should continue to use that. I've asked Steve to post an
> official policy statement to this mailing list, which he will do as
> soon as he gets access. Here is my summary.
> The PROMCODE core vocabulary URI will be:
> http://open-services.net/ns/promcode#
> This URI never changes as we evolve the vocabulary in later versions.
> We just add more terms. We do not change the names or meanings of
> existing terms
> We will configure the open-services.net server to redirect to the
> latest version on docs.oasis-open.
> We will host the approved versions of the vocabulary documents on
> docs.oasis-open. There are OASIS naming directives [1] that we have to
> follow. For example, the latest version would be at:

> In addition to the latest version, we also publish each approved
> revision of each stage, e.g. for Committee Specification Draft,
> revision
> http://docs.oasis-open.org/oslc-promcode/corevocab/v1.0/csd04/
> corevocab-v1.0-csd04.rdf
> http://docs.oasis-open.org/oslc-promcode/corevocab/v1.0/csd04/
> corevocab-v1.0-csd04.ttl
> http://docs.oasis-open.org/oslc-promcode/corevocab/v1.0/csd04/
> corevocab-v1.0-csd04.html
> We do a similar thing for shape documents. One difference is that it
> makes sense to change their URI since the URI identifies the document
> as a whole instead of terms within the document.
> The shape document for Project resources will be:
> http://open-services.net/ns/promocode/shapes/1.0/project
> This will redirect to the latest version:
> http://docs.oasis-open.org/oslc-promcode/projectshape/v1.0/
> projectshape-v1.0.rdf
> http://docs.oasis-open.org/oslc-promcode/projectshape/v1.0/
> projectshape-v1.0.ttl
> http://docs.oasis-open.org/oslc-promcode/projectshape/v1.0/
> projectshape-v1.0.html
> You asked if you could put all the HTML shapes in one document. In
> that case we would publish its latest version at:
> http://docs.oasis-open.org/oslc-promcode/shapes/v1.0/shapes-v1.0.html
> And we would redirect HTML requests on http://open-services.net/ns/
> promocode/shapes/1.0/project to

> [1]
> http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html
> _________________________________________________________
> Arthur Ryman
> Chief Data Officer
> SWG | Rational
> 905.413.3077 (phone) | 416.939.5063 (cell) IBM InterConnect 2015
> [image removed]
> <oslc-promcode@lists.oasis-open.org> wrote on 12/15/2014 11:54:56 PM:
> > From: Kazuhiro Funakoshi <k-f@bk.jp.nec.com>
> > To: Arthur Ryman/Toronto/IBM@IBMCA
> > Cc: "oslc-promcode@lists.oasis-open.org" <oslc-
> promcode@lists.oasis-open.org>
> > Date: 12/15/2014 11:56 PM
> > Subject: RE: [oslc-promcode] Re: Including files in specifications
> > for PROMCODE Sent by: <oslc-promcode@lists.oasis-open.org>
> >
> > Arthur,
> >
> > Let me confirm the expected changes. Because I could not understand
> > intention of the E-mail to Robin Cover very well.
> >
> > (1)
> > Our shape document should have @base address like [1] which
> redirects to real
> > files [2] in case of text/turtle, and [3] in case of text/html.
> > Therefore each
> > of @base address should be [3].
> >
> > [1] https://doc.open-services.net/oslc-promcode/ns/shape/Artifact
> > [2]
> > https://tools.oasis-open.org/version-control/browse/wsvn/oslc-
> > promcode/shape/trunk/Artifact.ttl
> > [3]
> > https://tools.oasis-open.org/version-control/browse/wsvn/oslc-
> > promcode/shape/trunk/Artifact.html
> > [4] https://doc.open-services.net/oslc-promcode/ns/shape/
> >
> > (2)
> > Can I change these as:
> > [1'] https://doc.open-services.net/oslc-promcode/ns/shape#Artifact
> > [2]
> > https://tools.oasis-open.org/version-control/browse/wsvn/oslc-
> > promcode/shape/trunk/Artifact.ttl
> > [3']
> > https://tools.oasis-open.org/version-control/browse/wsvn/oslc-
> > promcode/shape.html#Artifact
> > [4'] https://doc.open-services.net/oslc-promcode/ns/shape#
> >
> > I would prefer to generate single html document for shape.html
> > request like [1] as [2] or [3'], rather than Artifact.html or
> > The reason is that ReSpec seems to generate entire document in
> > single
> > with a big header and it is not suitable for each documents about
> individual
> > resource shapes.
> > And no change to resource shape files [2], they are individual ttl
> > files about individual resource shape.
> > Is this able to be done with .htaccess file as well?
> >
> > --
> > Kaz
> >
> >
> > From: oslc-promcode@lists.oasis-open.org
> > [mailto:oslc-promcode@lists.oasis-open.org] On Behalf Of Robin Cover
> > Sent: Saturday, December 06, 2014 3:04 AM
> > To: Arthur Ryman
> > Cc: oslc-promcode@lists.oasis-open.org; Robin Cover
> > Subject: Re: [oslc-promcode] Re: Including files in specifications
> > for

> >
> > On Fri, Dec 5, 2014 at 9:30 AM, Arthur Ryman <ryman@ca.ibm.com> wrote:
> > Robin,
> >
> > Thanks for the information. I confess to have not previously read
> > http://docs.oasis-open.org/specGuidelines/ndr/
> > namingDirectives.html#ns-pathElementReserved
> > .  I agree that we shouldn't store the actual information resources
> > in
> > /ns path. In fact, at jazz.net all the information resources are
stored in
> > our wiki and the .htaccess file redirects to it.
> >
> > OK, great.
> >
> > I read the OASIS Naming Directives. RDF vocabularies are Work
> >
> > Whether a single "RDF Vocabulary" is itself a(n entire) "Work Product"
> > whether its variant representations may be constituent parts of a
> Multi-Part
> > Work Product [
> >

> ]
> > can be clarified, but I think the "Vocabulary" would be a "part" or
> > represented in 2+ "parts"  [1b]
> >
> > but they are computer language definitions, so we'd use a fixed
> > e.g. core.rdf, and put the various stages at different paths
> >
> > Whether every representation of an OSLC vocabulary is a "computer
> > definition": unsure, but I'd think some are and at least one is
> probably now.
> >
> > But no matter: we can indeed expect fixed filenames for actual
> files(bits) on
> > a file system, similar to the three examples for files below
> >
> > , e.g. for
> > v1.0, Working Draft revision 01, the three representations of
> > http://docs.oasis-open/oslc-promcode/ns/core# would have the
> > following
> > URIs:
> >
> > http://docs.oasis-open.org/oslc-promcode/core-vocab/v1.0/wd01/core.r
> > df
> > http://docs.oasis-open.org/oslc-promcode/core-vocab/v1.0/wd01/core.t
> > tl
> >
> >
> > It this correct?
> >
> > In the abstract: yes, that seems correct, modulo a couple nits
> >
> > a) the OASIS Library is not used for Working Draft level content
> > [2b]
> >
> > b) I'd need more explanation/description to understand the notion
> ofthe three
> > resources (files) being "representations of" the namespace URI,
> > ifyou
> > anything other than that dereferencing the NS URI with variable
> > Accept headers will result in Web delivery of different
> > "representations" (of the
> > vocabulary)
> > associated with the namespace URI... I think that's what you mean.
> >
> >
> > I'll send you the details of .htaccess for jazz.net off-list.
> >
> > Perfect, and thanks!   We welcome your assistance in the process
> of upgrading
> > our web server functionality to support SemWeb /LOD expectations.
> >
> > _________________________________________________________
> > Arthur Ryman
> > Chief Data Officer
> > SWG | Rational
> > 905.413.3077 (phone) | 416.939.5063 (cell) IBM InterConnect 2015
> >
> >
> >
> >
> > [1b]
> > http://open-services.net/wiki/core/Vocabulary-index/#Vocabularies-
> > and-Specifications
> >
> > Specification (HTML):
> > http://open-services.net/bin/view/Main/OslcCoreSpecification
> > Namespace name: http://open-services.net/ns/core# RDF Schema (.rdf):
> > http://open-services.net/ns/core/core.rdf
> > Vocabulary "OslcCoreVocabulary":
> > http://open-services.net/bin/view/Main/OslcCoreVocabulary
> >  (HTML may be generated from .rdf or .ttl vocabulary file via XSLT)
> >
> > [2b] On Working Draft: the Naming Directives document recommends and
> > illustrates the use of revisioning identifers (01, 02, 03) in
> connection with
> > content released/published at Working Draft level, when such
> identifiers are
> > natural in the spec development process.  However, since content at
> > Draft level is not TC "Approved" work, we do not publish Working
> > Drafts in the OASIS Library, per the definition [
> > http://docs.oasis-open.org/specGuidelines/ndr/
> > namingDirectives.html#dfn-OASIS-Library ]
> > .   OASIS TCs are welcome to use wd01, wd02, wd02 when uploading
content to
> > the TC's Kavi repository (similarly to the TC discussion list,
> Wiki, version
> > control system), but since those venues have their own native
> version-control
> > identifier schemes, many TCs don't use "wd01" etc.  Kavi, for
> > example,
> > something it calls "revisions", starting with the natural counting
> number zero
> >
> > Thus, if you inspect examples in the OASIS Library, you should not
> > see

> > releases with the identifier component "wd", but Work Product
> > progressions that begin with "csd01" (Standards Track):
> >
> > http://docs.oasis-open.org/tosca/TOSCA/v1.0/
> >  (CSD01 to OS)
> > http://docs.oasis-open.org/camp/camp-spec/v1.1/
> >  (CSD01 to CS01)
> >
> > TC Process clarifies that the approval process begins with
> > "Committee Specification Draft" (CSD):
> > Approval Process (progression of Standards Track Work Products))
> >

> >
> > Aside: I think the TC Process definition for Working Draft is borked
> > (perpetually causes confusion), but see:
> > "Working Draft" Definition
> >
> >
> >
> >
> >
> >
> >
> >
> >
> > Unfortunately, varying statements about "Working Draft" and TC

To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:

Robin Cover
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Email: robin@oasis-open.org
Staff bio: http://www.oasis-open.org/people/staff/robin-cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1 972-296-1783

Robin Cover
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Email: robin@oasis-open.org
Staff bio: http://www.oasis-open.org/people/staff/robin-cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1 972-296-1783

Robin Cover
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Email: robin@oasis-open.org
Staff bio: http://www.oasis-open.org/people/staff/robin-cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1 972-296-1783

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