This document describes rules to take into account when implementing SOAP-based web services. It explains also how to check conformance to these rules. It can be read as a "Guideline to VO Web Service Interoperability" or a "How to provide interoperable VO web services".
This is an IVOA Proposed Recommendation made available for public review.
It is appropriate to reference this document only as a recommended standard that is under review and which may be changed
before it is accepted as a full recommendation.
The first release of this document was 2010 February 26.
This document has been developed with support from the National Science Foundation's Information Technology Research Program under Cooperative Agreement AST0122449 with The Johns Hopkins University, from the UK Particle Physics and Astronomy Research Council (PPARC), from the European Commission's (EC) Sixth Framework Programme via the Optical Infrared Coordination Network (OPTICON), and from EC's Seventh Framework Programme via its eInfrastructure Science Repositories initiative.
This work is based on discussions      and actions from the interoperability meetings in Cambridge MA, 24-28 May 2004, in Pune, 27-29 September 2004, in Kyoto, 16-20 May 2005 in Madrid, 6-7 October 2005 and in Moscow, 18-21 September 2006.
The words "MUST", "SHALL", "SHOULD", "MAY", "RECOMMENDED", and "OPTIONAL" (in upper or lower case) used in this document are to be interpreted as described in IETF standard, RFC 2119 .
The Virtual Observatory (VO) is a general term for a collection of federated resources that can be used to conduct astronomical research, education, and outreach. The International Virtual Observatory Alliance (IVOA) is a global collaboration of separately funded projects to develop standards and infrastructure that enable VO applications. The International Virtual Observatory (IVO) application is an application that takes advantage of IVOA standards and infrastructure to provide some VO service.
The use of SOAP-based web services is common in the VO, e.g., footprint and spectrum services , SkyNodes and Open SkyQuery , registry interfaces  and CDS access . New service providers need to know how to use the existing industry specifications for SOAP-based services in an IVOA context. This guideline should be an "interoperability guarantee" for the future. Our goal is not to create this guideline from scratch but to base it on existing work, specifically that of the Web Services Interoperability (WS-I) organization . This document describes which parts of the existing WS-I profiles we want to use, which parts we want to replace with our own work and which parts are missing and where we want to add.
The IVOA Architecture  provides a high-level view of how IVOA standards work together to connect users and applications with providers of data and services, as depicted in the diagram in Fig. 1.
Figure 1. WS Basic Profile in the IVOA Architecture. This provides industry-backed guidelines on constructing SOAP-based web services so that they are interoperable.
In this architecture, users employ a variety of tools (from the User Layer) to discover and access archives and services of interest (represented in the Resource Layer). WS Basic Profile ensures that all SOAP-based interfaces that are part of this usage are interoperable.
The Web Services Interoperability  organization is an open industry effort chartered to promote web service interoperability across platforms, applications, and programming languages. Its role is not to develop new specifications (like the W3C, for example) but to interpret the existing ones and to explain how to make them work together in the best way.
The WS-I Basic Profile is a set of non-proprietary web service specifications (SOAP, WSDL, UDDI, XML, XML Schema, ...). It provides clarifications because using a specification is very well but using it correctly and in the same way than others is better for good interoperability. Specifications are also often ambiguous.
WS-I Basic Profile is supported by major world companies and working groups. For example:
The purpose of this specification is to define an IVOA Web Services Basic Profile based on the WS-I Basic Profile that takes into account VO standards and practices relating to SOAP-based web services.
SOAP (Simple Object Access Protocol)  is an XML-based messaging framework used for information exchange between peers (client and service) in a distributed environment. It defines the message structure but not the message content.
A SOAP message consists of a SOAP envelope that encloses the SOAP header and the SOAP body. The header is optional and contains information about the contents of the body, such as routing, transactional, security, contextual or user profile information. The body contains the actuall data (message payload) to be consumed and processed by the receiver of the message.
The WS-I Basic Profile 1.1  describes:
As far as discovery is concerned, the IVOA has decided not to adopt UDDI and so this part may be considered as being replaced by the work carried out by the IVOA Registry WG .
Security aspects are also covered by work carried out by the IVOA Grid and Web Services WG and this is described in Section 5.
In each part of the profile (HTTP, SOAP binding, etc.), recommendations are explained using the following syntax:
Rxxxx statement text
R0001 An instance of a web service MUST be defined by a WSDL service description
R1140 A message SHOULD be sent using HTTP/1.1
R1141 A message MUST be sent using either HTTP/1.1 or HTTP/1.0
Before each rule or set of rules, the document explains the context and justifies the rule creation. The rules are not all at the same level; the compliance to one rule can be mandatory and the compliance to another can be optional.
WS-I Basic Profile 1.0 and its errata are equivalent to WS-I Basic Profile 1.1 and the WS-I Simple SOAP Binding Profile . The Simple SOAP Binding Profile 1.0 is a "subset" of the Basic Profile 1.0 requirements related to the serialization of the SOAP envelope and its representation in the message.
VO web services shall be checked that they follow this profile when they do not use attachments.
The WS-I Attachment Profile  adds support for sending interoperable attachments with SOAP messages. It defines a MIME (Multipurpose Internet Mail Extensions) multipart structure for packaging attachments with SOAP messages. WS-I has chosen the most common solution but it is too restrictive and not mandatory to associate this profile with the WS-I Basic Profile 1.1.
Alternate industry solutions, such as DIME (Direct Internet Message Encapsulation)  and MTOM (Message Transmission Optimization Mechanism, inside attachments) , have been defined and there is varying support for these from software libraries, such as Axis.
In light of this, this document does not define an attachment profile and VO service providers may select whichever solution best suits their requirements.
The basic security profile for VO services is defined by the IVOA Single-Sign-On Profile . This replaces the VS-I Basic Security Profile .
The VO has not implemented any conformance checking software of its own but relies instead on tools provided by industry for this purpose. In this section we briefly explain which tools we have used to check conformance with the WS-I standards.
Within the VO, the conformance testing tools have been tried with services implemented using both Tomcat/Axis and .NET infrastructures. This has been done against both the WS-I Basic Profile 1.0 and the WS-I Basic Profile 1.1 and WS-I Simple SOAP Binding 1.0 specifications.
Due to a very restrictive license, these tools and their related libraries cannot be integrated into other tools and applications. They are, however, available to download and standalone usage with both Java and C# implementations.
VO SOAP-based web services must be compliant with WS-I specifications as follows:
R0001 An IVOA SOAP-based web service MUST be compliant with the WS-I Basic Profile 1.1 
R0002 An IVOA SOAP-based seb service MUST be compliant with the WS-I Simple SOAP Binding 1.0 
These rules may be validated through the WS-I Testing tools .
VO SOAP-based web services must be compliant with the IVOA Support Interfaces (VOSI) specification  as follows:
R0100 The "getCapabilities" interface SHALL return a valid document describing the metadata of this service.
R0110 A VO service SHALL implement the "getAvailability" interface.
R0111 The "getAvailability" interface SHALL return an XML document as defined in the VOSI specification 
R0120 A VO service returning tabular data SHALL implement an interface for retrieving table metadata.
R0121 The interface for turning table metadata SHALL return an XML document as defined in the VOSI specification 
Note that VOSI does not explicitly define a SOAP binding so that SOAP-based web services must employ the defined REST binding.
These rules may be validated through the VOSI validator.
The tool developed to test the conformance with the IVOA Support Interfaces is based on a similar assertion definition than the WS-I tools. It can be easily evolved in the future to test conformance to other IVOA standards.
<?xml version="1.0" encoding="UTF-8"?> <vowsbasicprofile version="1.0"> <description> This document contains the test assertions for the VOSI component of the IVOA WS Basic Profile </description> <testAssertion id="R0100" type="required" enabled="true"> <context>Support Interfaces</context> <assertionDescription> capabilities interface testing </assertionDescription> <failureMessage>the "capabilities" interface is missing</failureMessage> <failureDetailDescription>an IVOA Web Service should provide a "capabilities" interface </failureDetailDescription> <testToDo> <InterfaceChecking>capabilities</InterfaceChecking> </testToDo> </testAssertion> <testAssertion id="R0110" type="required" enabled="true"> <context>Support Interfaces</context> <assertionDescription>capabilities interface return testing </assertionDescription> <failureMessage>capabilities do not return an XML file conform to the VOSICapabilities schema</failureMessage> <failureDetailDescription>the "capabilities" interface shall return an XML document conform to the VOSICapabilities schema</failureDetailDescription> <testToDo> <OutputChecking type="XSD" interface="capabilities">link to VOSICapabilities schema </OutputChecking> </testToDo> </testAssertion> <testAssertion id="R0200" type="required" enabled="true"> <context>Support Interfaces</context> <assertionDescription> availability interface testing </assertionDescription> <failureMessage>the "availability" interface is missing</failureMessage> <failureDetailDescription>an IVOA Web Service shall provide a "availability" interface </failureDetailDescription> <testToDo> <InterfaceChecking>availability</InterfaceChecking> </testToDo> </testAssertion> <testAssertion id="R0210" type="required" enabled="true"> <context>Support Interfaces</context> <assertionDescription>availability interface return testing</assertionDescription> <failureMessage>availability does not return an XML file conform to the VOSIAvailability schema</failureMessage> <failureDetailDescription>the "availability" interface shall return an XML document conform to the VOSIAvailability schema </failureDetailDescription> <testToDo> <OutputChecking type="XSD" interface="availability">link to VOSIAvailability schema </OutputChecking> </testToDo> </testAssertion> </vowsbasicprofile>
A conformant service shall be claimed if the service is compliant both with the WS-I Basic Profile 1.1 and the WS-I Simple SOAP Binding 1.0 and VOSI 1.0. The wording of the claim shall be:
This web service is compliant with the IVOA Web Services Basic Profile 1.0 (or later)This shall be understood to mean that at least all the mandatory rules are true. The list of all the optional rules which are also verified should be also provided.
 Schaaff A., A few words about WS-I Basic Profile,
 Schaaff A., VO Web Services Basic Profile,
 Schaaff A., VO WS Basic Profile,
 Schaaff A., VO Web Service Basic Profile Status,
 Schaaff A., Final report on Basic Profile,
 RFC 2119, http://www.ietf.org/rfc/rfc2119.txt
 Footprint and Spectrum services, http://voservices.net
 Skynodes and Open SkyQuery, http://openskyquery.net
 Benson K., et al., IVOA Registry Interfaces,