Next steps on Search Web Services TC deliverable(s)

[Robin Cover <robin@oasis-open.org>]

Ray,

Per your earlier communications [1], I have examined the seven files
[5] that the TC wants to approve and advance for public review, once they
are brought into conformity with the new TC Process, TC Handbook,
TC Admin Submission Requests, and Naming Directives [2].

Much of the content/structure appears to be in the same shape
(template models, etc) as was common in 2007-2008, and will
need to be adjusted in some respects to adhere to the new
 2010-10 rules.

Scanning the material (but without deep dive), I identified ten
topics as needing discussion, and some decisions will need
to be made where TC discretion is a key factor.  We can help
you with the details, and I'm inclined to think that a phone call
with the TC (plenary) or its principals would be the best approach.

1. WP Registration: set up metadata and naming (WP abbreviation)
2. Work Product titles
3. Work Product part-whole relations (multi-part or not)
4. Work Product filenames based upon WP abbreviation
5. Work Product URIs: mandated use of directories for
   individual WPs and for each stage/release
6. Machine-readable files (domain, URIs, schemaLocation,
   clarification on status)
7. XML namespaces and namespace document(s)
8. Conformance section
9. Introduction: structure and content
10. Appendices: required, optional

Of these topics, probably the single most determinative for the
others is the matter of part-whole relations (#3 above).  It will
be necessary to decide whether the TC wants to approve
and publish the content as one or several Work Products,
using the TC Process rules that govern part-whole relations.
As explained below, the notions of "set" and "collection" are
not relevant in the OASIS process.

I am providing a summary of the key considerations and
requirements on multi-part below [3], and urge you to read the
description carefully as a first step.  If you want to construe the
content in the seven files (and the ancilliary machine-readable files)
as one Work Product, it will be necessary to create a top-level
"Overview" document that explains the structure and
relationship of the other prose parts and all file sets,
namespaces [4], etc.

Let's plan for a phone meeting at your convenience to talk
through the issues in the ten topics above.

- Robin

=========== Details and References:

[1] communications

Ray Denenberg
http://lists.oasis-open.org/archives/search-ws/201104/msg00009.html
Robin
http://lists.oasis-open.org/archives/search-ws/201104/msg00013.html
Ray
http://lists.oasis-open.org/archives/search-ws/201105/msg00004.html
Ray
http://lists.oasis-open.org/archives/search-ws/201106/msg00000.html


[2] October 2010 (new) policies and commentary

* Technical Committee (TC) Process
  http://www.oasis-open.org/committees/process-2010-07-28.php

* Technical Committee (TC) Process FAQ
  http://www.oasis-open.org/policies-guidelines/tc-process-2010-07-28/faq

* OASIS TC Handbook
   http://docs.oasis-open.org/TChandbook/

* TC Administration Submission Request Forms
  http://www.oasis-open.org/resources/tc-admin-requests

* OASIS Naming Directives
  http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html

  (supplements and in part obsoletes:
  Naming Guidelines
  http://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNaming.html
  http://docs.oasis-open.org/specGuidelines/namingGuidelines/metadata.html )


[3]
==============================================================
Multi-part
==============================================================

http://www.oasis-open.org/committees/process.php#quality-multiPart
http://docs.oasis-open.org/TChandbook/Reference/WPQualityRequirements.html#multi-part

The OASIS TC Process recognizes that most specifications (called
"Work Products) are "Multi-Part" in that they are represented
by a whole made up of constituent parts, where "parts" are
files or logical groups of files functioning as storage objects
for a conceptual unity ("part").

TC editors sometimes refer to Work Products or parts of
Work Products as "specifications" in a "set" or "collection"
of documents.  Those terms are acceptable for casual use,
but for the purpose of ballots, public reviews, and
publication of a TC's deliverables, we need to understand
the part-whole relations in terms of the TC Process.

TC Process has no notion of "set" or "collection" relations but
there is a strong notion of part-whole.  It is essential to
know exactly, and at all times, what parts (files) are
constituents of the whole for any given whole Work Product.

The "parts" are allowed to be almost any mixture of document
types: prose documents, XML schema files, image files, formal
language definitions of other types, code, or other
machine-readable or human-readable artifacts.

The key point to understand is that a Work Product must be
treated AS A WHOLE with respect to motions, votes, and
ballots that represent acts of approval by the TC. Similarly,
when an approved work product at some level of maturity is
published as an approved instance (release), all parts must be
identified and included in the publication. No constituent
part may be advanced separately (e.g., for public review) and
no part may be excluded from an approval event. A ZIP file
should be used to package all the parts.

All parts are considered to progress together with the same
Stage identifier and Revision number at all times -- whether
or not all parts are equally mature from a technical point
of view.  Some parts may have changed dozens of times in the
past few weeks (or since the previous CSD or CSPRD) and some
parts may not have changed at all.  Irrespective of change
history and maturity, all parts much be considered as part
of the whole for any revision/stage.

http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#stage
http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#revision

The TC Process does not require that all parts be
characterized as "normative."  It is necessary to consider
that all components (constituent parts) in the whole
belong to a single Track - in this case, the Standards
Track. But one or more parts may be Non-Normative in the
same manner as an Appendix in a prose specification document
may be labeled Non-Normative.  If you want all the major
parts to be Normative, that's OK too.

In its own words, here's what TC Process says:

 (5) Multi-Part Work Products. A Work Product may
 be composed of any number of files of different types,
 though any such multi-part Work Product must have a
 single Work Product name and version number.
 Irrespective of the number and status of the
 constituent parts, the Work Product as a whole must
 be approved by a single Work Product Ballot.

http://www.oasis-open.org/committees/process.php#quality-multiPart

As to the TC Process rule about document
approval via a single Work Product Ballot:

 "the Work Product as a whole must be approved by
 a single Work Product Ballot"

That means all the parts must be considered as
belonging to the whole at all times. The TC could
not vote to approve "Part 1" at CSD02 level, then
as CSPRD, while leaving Part 2 to the side at
CSD01 level. Note that some files might be edited
more often than others (e.g., in the SVN repository),
but with respect to official actions of the TC to
approve something, the same approval event must
cover the specification as a whole, including all
parts.

http://www.oasis-open.org/committees/process-2010-07-28.php#WPapproval
http://www.oasis-open.org/committees/process-2010-07-28.php#dWPballot

A Work Product Approval Motion is any motion to initiate
a Work Product Ballot.  A Work Product Ballot is any TC
ballot for the approval of a Committee Specification
Draft or Committee Note Draft, for start of a Public Review,
for approval of a Committee Specification, or a
Committee Note, or submission of a Committee Specification
as a Candidate OASIS Standard....

======================================================
Multi-Part Work Products

A Multi-Part Work Product may consist of:

- a single prose document
- a single prose document and one or more related
 files such as schemaa, dtds, classes, etc
- multiple prose documents
- multiple prose documents and one or more related
 files

The Work Product, even if multi-part, must have a single
name and version number, and must be approved at each
stage by a single Work Product Ballot. That is, the
constituent parts cannot advance independently of each
other or stand on their own.

In the case of multiple prose documents, there should
be a single primary prose document that then refers to
the distinct parts. Each distinct part should clearly
state that it is part of the Work Product and refer to
both the top-level document and any other related prose
documents.

FOR EXAMPLE

http://docs.oasis-open.org/office/v1.2/csprd03/
http://docs.oasis-open.org/office/v1.2/csprd03/OpenDocument-v1.2-csprd03.html
 See there:
 "Related Work... This specification consists of  this
  document as well as the following documents, schemas,
  and ontologies"

The Open Document Format for Office Applications
(OpenDocument) v1.2 Work Product consists of four prose
documents, with the first being the primary:

- Open Document Format for Office Applications
 (OpenDocument) Version 1.2
- Open Document Format for Office Applications
 (OpenDocument) Version 1.2 Part 1: OpenDocument Schema
- Open Document Format for Office Applications
 (OpenDocument) Version 1.2 Part 2: Recalculated Formula
- Open Document Format for Office Applications
 (OpenDocument) Version 1.2 Part 3: Packages

See:
http://docs.oasis-open.org/TChandbook/Reference/WPQualityRequirements.html#multi-part



[4] Example XML namespace names:

sruRequest   http://docs.oasis-open.org/ns/search-ws/sruRequest
diag         http://docs.oasis-open.org/ns/search-ws/diagnostic
facet        http://docs.oasis-open.org/ns/search-ws/facetedResults
scan         http://docs.oasis-open.org/ns/search-ws/scan
sra          http://docs.oasis-open.org/ns/search-ws/searchResultAnalysis
sruResponse  http://docs.oasis-open.org/ns/search-ws/sruResponse
xcql         http://docs.oasis-open.org/ns/search-ws/xcql
sru-soap     http://docs.oasis-open.org/ns/search-ws/soap

Note: the XML schemas, whether normative or non-normative, if
part of the work, need to be installed on an OASIS server and
have appropriate schemaLocation reference values, etc.


[5] searchRetrieve Operation: Binding for SRU 2.0
March 24, 2011
http://www.oasis-open.org/committees/download.php/41609/sru-2-0-march-24-2011.doc
 * "This is one of a set of documents for the OASIS Search Web
    Services (SWS) initiative...

 * "The set of documents includes the Abstract Protocol Definition (APD)
    for searchRetrieve operation

 * "The collection of documents also includes three bindings...
    The Scan specification... the Explain specification...

 * The seven documents in the collection of specifications are:
    1.	APD  [1]
    2.	SRU 1.2 Binding [2]
    3.	SRU 2.0 Binding (this document)
    4.	OpenSearch Binding [3]
    5.	CQL, the Contextual Query Language  [4]
    6.	Scan  [5]
    7.	Explain [6]

Scan Operation
December 2, 2010
http://www.oasis-open.org/committees/download.php/40475/scan-december-2-2010.doc

searchRetrieve Operation: Binding for SRU 1.2
March 24, 2011
http://www.oasis-open.org/committees/download.php/41608/sru-1-2-march-24-2011.doc

Binding for OpenSearch Version 1.0
April 4, 2011
http://www.oasis-open.org/committees/download.php/41715/opensearch-april-4-2011.doc

Explain Operation
April 4, 2011
http://www.oasis-open.org/committees/download.php/41716/explain-april-4-2011.doc

searchRetrieve Operation: Abstract Protocol Definition
April 5, 2011
http://www.oasis-open.org/committees/download.php/41734/apd-april-5-2011.doc

CQL: The Contextual Query Language
May 20, 2011
http://www.oasis-open.org/committees/download.php/42242/cql-may-20-2011.doc




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