Re: [sca-bindings] Re: Handling external reference to IETF JMS URIspecification

[Simon Holdsworth <simon_holdsworth@uk.ibm.com>]

Robin,

Thanks very much for that response.
  Given what you've said it appears the best we can do would be to
refer to the IETF JMS URI spec thus (factoring in a recent issue resolution):

[IETFJMS]        M. Phillips,
P. Adams, D. Rokicki, E. Johnson, URI Scheme for JavaTM Message
Service 1.0, http://tools.ietf.org/html/draft-merrick-jms-uri-12

             
  IETF Internet-Draft January 20, 2011, pending publication
of final approved version

I will discuss this at the next TC meeting.

Thanks, Simon

Simon Holdsworth
STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings TC Chair,
AT&T and Boeing Lab Advocate
MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK
Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898
Internet - Simon_Holdsworth@uk.ibm.com



From:      
 Robin Cover <robin@oasis-open.org>
To:      
 Simon Holdsworth/UK/IBM@IBMGB,
SCA Bindings TC List <sca-bindings@lists.oasis-open.org>
Cc:      
 Robin Cover <robin@oasis-open.org>
Date:      
 01/03/2011 15:54
Subject:    
   [sca-bindings]
Re: Handling external reference to IETF JMS URI specification

---

> Can we have a designated cross reference in an
OASIS
> specification to an external standards document, in
> particular an IETF specification, which is pending
> final standardisation?

Details for items A-E are presented below in [References].
With respect to OASIS documents A and B, which both cite
IETF draft C as a Normative Reference per the citation
text D, with footnotes E,

The SCA Bindings TC said: "[...] The IETF specification is in
the process of being standardised, but is currently still in
an editors draft state. The JMS Binding and Test Assertion
Specifications refers to a specific draft, of which there is a
more recent version, with no changes relevant to its use in the
OASIS specifications [...] The question is whether there is some
way to handle this external specification dependency in a way
that does not require us to formally revise/re-review the JMS
binding when the IETF specification becomes a standard
(expected timeframe for that is about 4 months), possibly via
a designated cross-reference?  The main concern here is whether
a move to Committee Specification for these two OASIS
specifications would then mean additional impacts/work to
update the reference when the IETF standardisation process
completes and the final URL is available."

Reply: As far as I know, the Designated Cross-Reference Change
feature is restricted to targets that are OASIS Work Products;
there is no provision for updating references to external
work products (not produced within OASIS TCs). The relevant
terms and phrases are (emphasis added):
   "in another *OASIS* Work Product" [a pending status change]
   "the other *OASIS* Work Products" [named in the motion]

http://www.oasis-open.org/committees/process-2010-07-28.php#crossRefs
http://www.oasis-open.org/committees/process-2010-07-28.php#quality-allowedChanges

I'm sure someone will correct me if my interpretation above
is in error.

A number of options are available, in theory, for developing
and completing an OASIS specification that contains
references to external (SSO/SDO) specifications or other
works which may not have reached final approval/publication.
Which option a TC elects depends upon many factors, including
a determination as to whether exact finalized text of the
external document, or the final approval event itself, is or
could be relevant to conformance clauses in the OASIS (subject)
specification.

In the range of my experience, it *is* common for specifications
being developed in one SSO/SDO to cite non-final specifications
being developed in other SSO/SDOs, with clarification and
qualification sufficient to let implementers know about any
contingencies that might impact application development. For
example, if the editors of Spec1 are confident that Spec2
(different org or working party) will be finalized, and that
any unexpected changes would NOT impact conformance to Spec1,
they may qualify the Spec2 citation with phrases like:
"pending publication of final approved version" OR alternately
"this version of any subsequent draft/final releases" OR
alternately "and any natural successor [New Version] of this
specification approved at a later time."

Citation of a non-final spec is done reqularly in cases where
the target spec is known to be in evolution (e.g., like the
Unicode Standard, etc) but where dependence upon the
referenced specification is conscious/intentional, as a
principled technology decision made in advance.

An OASIS TC using such strategy will need to be careful to
determine the consequences of any option in case what's
expected (final approval, new version, only non-substantive
changes) does NOT actually happen, viz., whether an unexpected
change in the cited work could create conflict with the intent
of the OASIS spec editors.  Because changes can sometimes
have unexpected consequences, some orgs specifically advise
against citing immature specifications as "Normative"
(e.g., W3C: "Normative references should be to stable and
mature resources (e.g., only Recommendations).")

Another stragegy, not mutually exclusive with the preceding
(qualifying/clarifying phrases in the citation) is to use a
"Latest Version" URI reference in the citation for any
(non-final) Spec2.  Again: this only makes sense when the
spec editors are indifferent to changes that may be approved
in a thus-cited "in flight" specification. I have provided
some examples of these citation URIs below, for how to cite
the "Latest Version" with carefully selected URI references;
see [Latest].

And similarly:

http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#appropriateURIs
http://www.w3.org/standards/faq#persistence

In the case of the IETF I-D "draft-merrick-jms-uri" (ref'd as
C )
( http://tools.ietf.org/id/draft-merrick-jms-uri-09.txt
)
you note that revision "-09" as cited is not the latest.
See now "-12" [2011-02-28]:

http://www.ietf.org/internet-drafts/draft-merrick-jms-uri-12.txt

IETF has changed its practices over the years with
respect to URIs that are persistent; it's tricky because
I-Ds will "expire" and sometimes will not be available
at a published URI following the expiration date.  See:

http://www.ietf.org/internet-drafts/draft-merrick-jms-uri-09.txt

If you are interested in citing the IETF spec "URI Scheme
for Java(tm) Message Service 1.0" using a URI reference
most likely to survive (to help locate the Latest Version),
I can investigate and report on the IETF's latest conventions
and practices.  These kinds of references seem to work,
for example:

1) IETF DataTracker: datatracker.ietf.org
https://datatracker.ietf.org/doc/draft-merrick-jms-uri/

2) HTML-ized Format (note the 2x diffs and Nits link)
http://tools.ietf.org/html/draft-merrick-jms-uri

3) Generated complete HTML (seemingly inconsistent)
http://tools.ietf.org/id/draft-jones-json-web-token
http://tools.ietf.org/id/draft-jones-json-web-token-00
http://tools.ietf.org/id/draft-jones-json-web-token-00.html


Best wishes, and apologies for the delayed response on
this question

- Robin

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

============= [References]:

A. http://www.oasis-open.org/committees/download.php/40397/docs.oasis-open.orgopencsasca-bindingssca-jmsbinding-1.1-spec-csprd03.html
= http://docs.oasis-open.org/opencsa/sca-bindings/sca-jmsbinding-1.1-spec-csprd03.html

B. http://www.oasis-open.org/committees/download.php/40393/docs.oasis-open.orgopencsasca-bindingssca-jmsbinding-1.1-test-assertions-1.0-csd01.html
= http://docs.oasis-open.org/opencsa/sca-bindings/sca-jmsbinding-1.1-test-assertions-1.0-csd01.html

C: http://tools.ietf.org/id/draft-merrick-jms-uri-09.txt

D: Citation in specs (sub "1.3 Normative References" and
    "1.2 Normative References"): "[IETF-JMS] M.
Phillips, P. Easton,
    D. Rokicki, E. Johnson, URI Scheme for Java Message Service
1.0
    http://tools.ietf.org/id/draft-merrick-jms-uri-09.txt
    IETF Internet-Draft September 2010 [1]"

E: Footnote "[1]" content: "Note that this URI scheme is
currently
    in draft. The reference for this specification will be updated
    when the IETF standard is finalized"
http://docs.oasis-open.org/opencsa/sca-bindings/sca-jmsbinding-1.1-test-assertions-1.0-csd01.html#_ftnref1
http://docs.oasis-open.org/opencsa/sca-bindings/sca-jmsbinding-1.1-spec-csprd03.html#_ftnref1

[Latest]

In some cases a TC may determine that making Reference to a
Work using its generic bibliographic metadata and
latest-version URI is adequate for citation purposes. Please
make sure the version-specific approval date and particular
maturity level are NOT part of the Reference in this case (generic
version-agnostic metadata includes the Latest Version URI
reference as one element).

Examples:

* for an IETF spec, use (for example)
xCal: The XML format for iCalendar
http://tools.ietf.org/html/draft-daboo-et-al-icalendar-in-xml
(not: http://tools.ietf.org/html/draft-daboo-et-al-icalendar-in-xml-07)

* for a W3C spec, use (for example)
OWL 2 Web Ontology Language Quick Reference Guide
http://www.w3.org/TR/owl2-quick-reference/

* for a WS-I spec
Basic Security Profile Version 1.0
http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0.html

* for a Unicode spec
Unicode Regular Expressions
http://www.unicode.org/reports/tr18/

* for a DCMI spec
Guidelines for Encoding Bibliographic Citation Information
http://dublincore.org/documents/dc-citation-guidelines/

-------------

On Tue, 1 Mar 2011, Simon Holdsworth wrote:

> Robin,
> 
> Following up on this query I wanted to pull out the specific question:
> 
> Can we have a designated cross reference in an OASIS specification
to an external standards document, in particular an IETF
> specification, which is pending final standardisation?
> 
> The specific example of this described is the JMS binding specification
and test assertions which refer to the current IETF
> JMS URI specification which is in the process of being standardised
but which may not complete standardisation before the JMS
> binding documents, and whose URL will change when it becomes a standard.
 We would like to avoid the need to revise and
> re-review the JMS binding specifications when the IETF standardisation
process completes.
> 
> Thanks, Simon
> 
> Simon Holdsworth
> STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings
TC Chair, AT&T and Boeing Lab Advocate
> MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK
> Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898
> Internet - Simon_Holdsworth@uk.ibm.com
> 
> __________________
> 
> Robin,
> 
> With regard to the specific link from the JMS and WS test case documents
to the test case artefacts I believe this is a
> general issue for all the SCA specs, and that Anish Karmarkar has
taken that issue forward with you, we are awaiting a
> response so that the TC knows what actions, if any, it needs to take
to update these documents to include the references.
> 
> We have a second concern regarding links, this one is from the JMS
Binding Specification [1] and JMS Binding Test Assertions
> Specification [2] to the IETF JMS URI specification [3] (designated
by the [IETFJMS] normative reference, with associated
> footnote).  The IETF specification is in the process of being
standardised, but is currently still in an editors draft state.
>  The JMS Binding and Test Assertion Specifications refers to
a specific draft, of which there is a more recent version, with
> no changes relevant to its use in the OASIS specifications.
> 
> [1]http://www.oasis-open.org/apps/org/workgroup/sca-bindings/download.php/40397/docs.oasis-open.orgopencsasca-bindingssca-jmsbinding-1.
> 1-spec-csprd03.html
> [2]http://www.oasis-open.org/apps/org/workgroup/sca-bindings/download.php/40393/docs.oasis-open.orgopencsasca-bindingssca-jmsbinding-1.
> 1-test-assertions-1.0-csd01.html
> [3] http://tools.ietf.org/id/draft-merrick-jms-uri-09.txt
> 
> The question is whether there is some way to handle this external
specification dependency in a way that does not require us
> to formally revise/re-review the JMS binding when the IETF specification
becomes a standard (expected timeframe for that is
> about 4 months), possibly via a designated cross-reference?  The
main concern here is whether a move to Committee
> Specification for these two OASIS specifications would then mean additional
impacts/work to update the reference when the
> IETF standardisation process completes and the final URL is available.
> 
> Thanks, Simon
> 
> Simon Holdsworth
> STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings
TC Chair, AT&T and Boeing Lab Advocate
> MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK
> Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898
> Internet - Simon_Holdsworth@uk.ibm.com
> 
> 
> 
> From:        Robin Cover <robin@oasis-open.org>
> To:        SCA Bindings TC List <sca-bindings@lists.oasis-open.org>
> Cc:        Bryan Aupperle <aupperle@us.ibm.com>,
Martin Chapman <MARTIN.CHAPMAN@oracle.com>, Robin Cover
> <robin@oasis-open.org>
> Date:        21/01/2011 20:06
> Subject:        Re: [sca-bindings] Missing links
in test case documents
> 
> ____________________________________________________________________________________________________________________________________
> 
> 
> 
> [Bryan said, in part]
> 
> > I noticed that the test case
> > documents for both the WS binding and the JMS binding do not
have links to
> > the respective test artifacts zips files.  This means the
reader really has
> > no way to know these zip files exist or where to find them.
> 
> [Martin replied]
> On Fri, Jan 21, 2011 at 11:08 AM, Martin Chapman
> <MARTIN.CHAPMAN@oracle.com> wrote:
> > Bryan,
> > Good observation. I?m not sure ?related work? is the right way
to do this
> > since the zip files are actually part of the same work product.
The TC
> > process does require a reference to these files without saying
how! I have
> > copied Robin since there was confusion over the Policy spec and
he may have
> > suggestions for doing this in a better way. I will also leave
it to his
> > judgement as to whether this would warrant a public review, since
it is only
> > making an implicit link explicit.
> >
> > Martin.
> 
> I agree with Martin's (implicit) doubt about the "right"
or "best" way
> to fulfill the terms of the TC Process [1] and (more importantly)
to
> help make readers/users aware of all essential "parts" in
a
> multi-part work [2].
> 
> I don't think it's wrong to use the "Related Works:" block
on a
> spec cover page for citation of a discrete work sub-part that
> merits special attention.  This was anticipated and recommended
> in the Naming Guidelines document [3] ("OASIS Naming Guidelines
> Part 2: Metadata and Versioning") that's no longer the latest
> reference for guidance, but was consistent with other instructions
> available from the OASIS Library /templates/ area.  I think that
> guidance is still applicable.
> 
> In particular, we have recommended consideration of the DCMI
> relational terms in the "Related Works:" block, including
> the following relations for part-whole:
> 
> hasPart:  The described resource includes the referenced
>              resource either physically
or logically
> isPartOf: The described resource is a physical or logical
>              part of the referenced
resource
> 
> And so, several OASIS TCs have used  "Related Works"
to reference
> parts of a whole (parent to children), or sibling parts, including
> "parts" that instantiate XML schemas, ontologies, and other
> machine readable files or packages.
> 
> See for example, "Related Work" in the recent OASIS
> OpenDocument specification:
> 
> http://docs.oasis-open.org/office/v1.2/csprd02/OpenDocument-v1.2-csprd02.html
> 
> Related Work:
> This specification consists of this document as well as the
> following documents, schemas and ontologies:
> 
> OpenDocument v1.2 part 1: OpenDocument Schema
> OpenDocument v1.2 part 2: Recalculated Formula (OpenFormula) Format
> OpenDocument v1.2 part 3: Packages
> OpenDocument v1.2 Relax NG Schema (.rng)
> OpenDocument v1.2 Manifest Schema  (.rng)
> OpenDocument v1.2 Digital Signature Schema  (.rng)
> OpenDocument v1.2 Metadata Manifest Ontology  (.owl)
> OpenDocument v1.2 Package Metadata Manifest Ontology  (.owl)
> 
> I'm planning to schedule some new work to study this topic (once
> the backlog of regular TC Admin support issues is handled).
> 
> Cheers,
> 
> - Robin
> 
> PS No interpretation just yet about additional public review as
> possibly occasioned by the suggested change.
> 
> [1] http://www.oasis-open.org/committees/process-2010-07-28.php#quality-formalLangDefns
> 
> [with respect to] "normative computer language definitions
> that are part of the Work Product, such as XML instances,
> schemas... Each text file must be ***referenced from*** the Work Product..."
> 
> Ignoring the awkwardness of saying (a) that schemas are
> "part of the Work Product" and that (b) they must be
> "referenced from the Work Product"   -- apparently
requiring that
> the latter use mean "from the relevant prose part(s) of the
> the Work Product, more immediately visible than the non-prose
> parts of the Work Product -- it's not clear by what means the
> CLDs are to be "referenced from" the (prose part(s) of)
the Work
> product.
> 
> TCs do want more guidance.  In the previous [pre-October-15]
> version of the Naming Guidelines, some discussion was
> presented about non-prose artifacts that are parts of multi-part
> works, but this content was not brought forward, and needs to be
> reworked in a Naming Directives document update, and maybe
> in spec templates.
> 
> [2] http://www.oasis-open.org/committees/process-2010-07-28.php#quality-multiPart
> 
> [3] http://docs.oasis-open.org/specGuidelines/namingGuidelines/metadata.html#relatedWork
> 
> Excerpt:
> 
> "Within a prose specification title "page", TC editors
should
> supply the title and applicable URI for any other resource
> closely associated with the specification, where reference to
> the related resource is deemed essential or strongly motivated.
> In most cases, the TC editors are to make a judgment,
> necessarily subjective, as to whether a Related Work reference
> would be of significant benefit to the human reader.
> 
> Informally (not with an intent to formally implement DCMI
> metadata models), OASIS TC editors may wish to study the
> collection of Dublin Core Metadata Initiative (DCMI) terms
> defined as element refinements of DCMI relation
> [label Relation] --- as these may prompt ideas for Related
> Work candidate references. In DCMI, a relation stores
> "a reference to a related resource... Recommended best
> practice is to reference the resource by means of a string
> or number conforming to a formal identification system."
> Here are some of the element refinements build from DCMI
> relation, usually reciprocal...
> 
> >
> >
> >
> > From: Bryan Aupperle [mailto:aupperle@us.ibm.com]
> > Sent: 21 January 2011 15:05
> > To: sca-bindings@lists.oasis-open.org
> > Subject: [sca-bindings] Missing links in test case documents
> >
> >
> >
> > I bring this up somewhat reluctantly since it could force additional
15-day
> > public reviews.
> >
> > While researching an issue in the Java TC, I noticed that the
test case
> > documents for both the WS binding and the JMS binding do not
have links to
> > the respective test artifacts zips files.  This means the
reader really has
> > no way to know these zip files exist or where to find them.
> >
> > The assembly and policy test case documents have links in the
Related Work
> > section of the front matter.  For example, from the assembly
document:
> >
> > The Test Suite artifacts relating to this document can be found
here:
> > http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-testcases-cd03.zip
> >
> > We probably should add these links.
> >
> > Bryan Aupperle, Ph.D.
> > STSM, WebSphere Enterprise Platform Software Solution Architect
> > WW Center of Excellence for Enterprise Systems & Banking
Center of
> > Excellence Application Integration Architect
> >
> > Research Triangle Park,  NC
> > +1 919-254-7508 (T/L 444-7508)
> > Internet Address: aupperle@us.ibm.com
> 
> 
> 
> --
> 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/who/staff.php#cover
> Cover Pages: http://xml.coverpages.org/
> Newsletter: http://xml.coverpages.org/newsletterArchive.html
> Tel: +1 972-296-1783
> 
> ---------------------------------------------------------------------
> 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:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
> 
> 
> 
> 
> 
> ____________________________________________________________________________________________________________________________________
> 
> 
> 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
> 
> 
> 
> 
> 
> 
> 
> 
> 
> ____________________________________________________________________________________________________________________________________
> 
> 
> 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
> 
> 
> 
> 
> 
> 
> 
>
---------------------------------------------------------------------
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:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

---

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