IVOA Document Standards RFC (Version 1.2)

This document will act as RFC centre for the IVOA Document Standards 1.2 Proposed Recommendation.

Review period: 12 May 2009 to 11 June 2009

In order to add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your WikiName so authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Discussion about any of the comments or responses should be conducted on the Standing Committee on Standards & Processes mailing list, stdproc@ivoa.net.

For reference, here is a link to the first RFC (Version 1.1)

The comments (M. Deimletner, M. Taylor) posted on the page open for comments on V1.2 WD are copied below.

Comments

Minimal implementation rules

I'm not sure if this is one of these "not again" topics, but I'd really like so see something on the implementation side. Let me dream for a moment: What if the document said something like "A PR describing protocols, formats or similar computer processible artefacts can only become REC if (a) at least two independent implementations [fantasy: one of them in a C-linkable language; this would almost immediately allow bindings for basically all major languages] are available and (b) a validation suite is provided that allows implementors to verify the conformity of their implementation [for what it's worth]".

As a matter of fact, I think the validation suite would be worth more than all words and probably even formal specifications, since the behaviour defined by it is behaviour clients can rely on.

Now, I admit that if something like this were to become part of the standards process, more diligence is needed as to the wording, and certain details would have to be worked out (if I had my way, I'd require the implementations to be published under a DFSG-free licence, for starters). But I'm convinced the VO would be more fun to work and more robust with if rules like these were adopted. -- MarkusDemleitner - 17 Feb 2009

Me too

I welcome the introduction since v1.0 of a reference to validation tools in the WD->PR promotion rules (section 2.1). However, the language is pretty pusillanimous:

"Preferably, the WG should be able to demonstrate two interoperable implementations of each feature, and validation tools should be available. If the chair of the WG believes that broader review is critical, the chair may advance the document to Proposed Recommendation even without adequate implementation experience. In this case the document status section should indicate why the chair promoted the document directly to PR."

I have two issues with this text.

1. The language here makes it sound like two interoperable implementations and the validation tools are very much an optional extra. I would like the document authors to justify why these should not be made a requirement, or at the very least a condition for which explicit exemption (perhaps by the TCG) is required.
2. The phrasing seems disingenuous to me. The document may be advanced to PR if the chair believes (and how this 'belief' is to be assessed is another matter) that broader review is critical. That sounds just about plausible, since PR means a requirement for feedback from other WGs. However, the requirement for two implementations and validation tools is not reiterated at the PR->REC boundary. So there's nothing in the DocStd document to say that a document can't go from WD to REC with inadequate implementation experience simply because the WG chair believes it needed broader review while it was still a WD. If that is really what's meant (and I hope it is not) then it ought to be made explicit; if not, the implementation requirements should be reiterated more strongly in section 2.2.

I prepared the above comments before reading Markus's contribution above. Emboldened by him, I'll state it a little more strongly: why on earth shouldn't two interoperating implementations plus comprehensive validation suite be an absolute requirement? In my experience, writing the implementation is a breeze compared to thrashing out the standard. Unless of course the standard is so written as to be difficult or impossible to implement. Writing and testing an implementation is absolutely the best way to find out whether this is the case or not.

-- MarkTaylor - 18 Feb 2009

Having slept on it I think maybe I should backtrack slightly - if there is a comprehensive validation suite, I think that a single implementation is probably sufficient. Two independently written bits of interoperating software is a good test of a standard - either two implementations or an implementation and a validation suite (which is a kind of implementation in any case). Having a validation suite is a massive help when it comes to ensuring that later implementations are correct.

-- MarkTaylor - 19 Feb 2009

Having a good validation suite is very valuable, but is no substitute for having at least two interoperable implementations as a standard is developed. The problem is that a single implementation and a corresponding validation suite may be written by the same folks, and the fact they they agree with each other tells us little, and is not a reliable test of whether the standard is sufficiently understandable and complete to be implemented by others.

-- DougTody - 12 May 2009

I only want to reinforce (in case more votes are needed) what Markus and Mark already clearly stated: we have to have a validation service (mandatory and not recommended, as instead stated in paragraph 2.4): it is necessary (though obviously not sufficient) to ensure smooth operations. The advantages, at all levels, are so obvious that I do not see how we can live (or survive) without it.

-- AlbertoMicol - 13 May 2009

Versioning

However, the matter of how this impacts (web) service standards still remains open and needs addressing. To recap, any new version/revision of a (web) service standard will have to have an integer increment since it will be incompatible with previous versions: service request/response messages use namespaces to identify the version, e.g.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope">
  <soapenv:Header>
  <soapenv:Body>
    <PushToVoSpace xmlns="http://www.net.ivoa/xml/VOSpaceContract-v1.0">
...

The namespace on the message body - http://www.net.ivoa/xml/VOSpaceContract-v1.0 - indicates that this is a message to a VOSpace-1.0 compliant service. The same message to a VOSpace 1.1 service would utilise the namespace http://www.net.ivoa/xml/VOSpaceContract-v1.1 instead. A VOSpace-1.0 client cannot be used with a VOSpace-1.1 service and vice versa. So by the new rule VOSpace-1.1 should actually be VOSpace-2.0. The same argument applies, however, to minor changes, e.g. VOSpace-1.13 to VOSpace-1.14.

This brings up another point - how should associated schema, WSDLs, etc., in fact anything with a namespace, be versioned? With the version number of the associated document? For example, the change from v1.13 to v1.14 of a standard just reflects a format change in the WSDL document but this is "new incompatible" version. Should all service standards just employ integer versioning?

I also think that the language about supplementary resources needs to be strengthened. For a web service, the WSDL and any accompanying schema formally define the service interface and contract - these are really not supplemental in any sense but the machine-readable equivalent of the human-readable specification that the document represents. Additional implementations in these contexts will employ different namespaces and so will be not be interoperable. I do not think it is necessary to include the full text of such accompaniments in the human spec but they must be referenced and authoritative versions deposited with the IVOA Document Coordinator. We already have locations for such things: http://www.ivoa.net/xml, http://www.ivoa.net/wsdl and http://www.ivoa.net/rdf and these should be referenced in this document.

-- MatthewGraham - 12 May 2009

Comments from the TCG during the normal RFC period (starting 12/05/2009)

Applications (Tom McGlynn, Mark Taylor)

Data Access Layer (Keith Noddle, Jesus Salgado)

Data Model (Mireille Louys, AnitaRichards)

Grid&Web Sevices (Matthew Graham, Paul Harrison)

Registry (Ray Plante, Aurelien Stebe)

Semantics (Sebastien Derriere, Norman Gray)

VOEvent (Rob Seaman, Alasdair Allan)

VO Query Language (Pedro Osuna, Yuji Shirasaki)

VOTable (François Ochsenbein)

Standard and Processes (Francoise Genova)

Astro RG (Masatoshi Ohishi)

Data Curation & Preservation (Bob Hanisch)

Theory (Herve Wozniak, Claudio Gheller)

TCG (ChristopheArviset, Severin Gaudet)

I approve the document.