DDSWEB — The URL prefix of the specification documents is not consistent with the XSD targetNamespace

The specification documents are all under the namespace: http://www.omg.org/spec/DDS-WEB/20131122
Whereas the XSD documents use targetNamespace that use different prefixes:

webdds_rest1.xsd sets targetNamespace="http://www.omg.org/spec/WEBDDS/20130601/"

webdds_soap1_types.xsd sets targetNamespace="http://www.omg.org/webdds/"
webdds_soap1.wsdl sets targetNamespace ="http://www.omg.org/spec/WEBDDS/20130601/
webdds_soap1_notify.wsdl sets targetNamespace ="http://www.omg.org/spec/WEBDDS/20130601/

While this is technically allowed it is likely to cause confusion because the xmlns used in an XML must match the targetNamespace of the referenced XSD.

For this reason it would be better that the three targetNamespace are consistent. For example, assume that the result of the FTF has the machine-readable documents under the URL prefix:
http://www.omg.org/spec/DDS-WEB/20140901/

Then the XSD documents should all use the same target namespace "http://www.omg.org/spec/DDS-WEB/20140901/"

Note that it is allowed for multiple schemas to have the same targetNamespace and it is one of the recommended practices when all the schemas are conceptually related and there is no need to separate identify the origin/lineage of each element.

Resolve by updating the schema file webdds_rest1.xsd and the non-normative example file webdds_rest1_example.xml

This issue is addresses by updating the XSD shema file (webdds_rest1.xsd ) and the the non-normative example file webdds_rest1_example.xml

The two files are attached. Replacing this two files is the only change to the specification to address the issue.

What follows is the detailed description of the changes performed to those files and the reasons for them.

• To increase the usability of the XSD the namespaces and imports should be re-organized. The webdds_rest1.xsd schema declaration should be modified to use http://www.omg.org/dds/ as the target namespace. The result should be as follows:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="http://www.omg.org/dds/" 
           xmlns:dds="http://www.omg.org/dds/" 
           xmlns:xtypes="http://www.omg.org/ptc/2011/01/07/XML_Type_Representation/" 
           targetNamespace="http://www.omg.org/dds/" 
           elementFormDefault="qualified"
           attributeFormDefault="unqualified">

• The import of DDS_QoSProfile.xsd in the webdds_rest1.xsd should be changed to a “include”.
  Also note the issue filed to change the definition of elementName:

       
      <!-- Issue filed on DDS4CCM (DDS_QoSProfile.xsd) change definition of elementName
           to <xs:pattern value="([a-zA-Z0-9_.])+" />
           Also make it into a Chameleon schema
      -->
      <xs:include	schemaLocation="DDS_QoSProfile.xsd"/>
  

This issue also impacts the XML files associated with that schema file should be modified accordingly.

• The root element for webdds_rest1_example.xml and elements xmlns, xmlns:dds, xmlns:xtype, and xsi:schemaLocation should be modified to match what is shown below:

  <!-- This is file webdds_rest1_example.xml -->
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns="http://www.omg.org/dds/"
      xsi:schemaLocation="http://www.omg.org/dds/    http://www.omg.org/spec/DDS-WEB/20150901/webdds_rest1.xsd"
   

• Consistently follow snake_case naming convention for the element names in the XSD. Rename all CamelCase to snake_case for the XSD elements. The XSD types can remain in CamelCase. This renames webdds_rest1.xsd XSD elements:

  sourceTimestamp, instanceHandle, validData, instanceState, sampleState, viewState, readSampleInfo, sampleData, writeSampleInfo, returnCode, returnMessage, accessToken, sessionId.

  To:

  source_timestamp, instance_handle, valid_data, instance_state, sample_state, view_state, read_sample_info, sample_data, write_sample_info, return_code, return_message, access_token, session_id.

• Consistently use lower case for all type definitions in the XSD with CamelCase convention.
  This rename webdds_rest1.xsd XSD types:

  RegisterType, Topic, TopicList, DataWriter, DataWriterList, DataReader, DataReaderList, Publisher, PublisherList, Subscriber, SubscriberList, DomainParticipant, DomainParticipantLibrary, StatusCondition, ReadCondition, ContentFilter, ParameterList, Waitset, ReturnStatus, Application, AuthenticatedSession

  To:

  registerType, topic, topicList, dataWriter, dataWriterList, dataReader, dataReaderList, publisher, publisherList, subscriber, subscriberList, domainParticipant, domainParticipantLibrary, statusCondition, readCondition, contentFilter, parameterList, waitset, returnStatus, application, authenticatedSession

• Introduce the following new definition on the webdds_rest1.xsd XSD:

      <xs:simpleType name="elementNameReference">
          <xs:restriction base="xs:string">
              <xs:whiteSpace value="collapse"/>
              <xs:pattern value="((::)?[a-zA-Z0-9_.])+"/>
          </xs:restriction>
      </xs:simpleType>
  

• Change the type of the “_ref” attributes (type_ref, register_type_ref, topic_ref), from “dds:elementName” to “elementNameReference”.
  Change the type of the “base_name” attribute on element domainParticipant to “elementNameReference”.

• Change all type attributes in the elements of webdds_rest1.xsd that refer to types defined in DDS_QoSProfile.xsd. Currently all these references have the prefix “dds:” drop that prefix since the target namespace is now the same. Effectively this removes all the “dds:” from the values of the “type=” attribute.

• Rename the webdds_rest1.xsd XSD types “Sample” and “SampleSeq” to “readSample” and “readSampleSeq” also changing the definition of “Sample” to use “xs:any” and “data” as an element name so the the type “xs:Sample” becomes:

       <xs:complexType name="anyDataValue">
  		<xs:sequence>
  			<xs:any processContents="lax" minOccurs="1" maxOccurs="1"/>
  		</xs:sequence>
       </xs:complexType>
  
      <xs:complexType name="readSample">
          <xs:sequence>
              <xs:element name="readSampleInfo" type="readSampleInfo" 
                                  minOccurs="0" maxOccurs="1"/>
              <xs:element name="data" type="anyDataValue" minOccurs="0" maxOccurs="1"/>
          </xs:sequence>
      </xs:complexType>
  

• Add the following definitions to the webdds_rest1.xsd XSD:

     <xs:complexType name="writeSample">
          <xs:sequence>
              <xs:element name="write_sample_info" type="writeSampleInfo" minOccurs="0" maxOccurs="1"/>
              <xs:element name="data" type="anyDataValue" minOccurs="0" maxOccurs="1"/>
          </xs:sequence>
      </xs:complexType>
      
       <xs:complexType name="writeSampleSeq">
          <xs:sequence>
              <xs:element name="sample" type="writeSample" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
      </xs:complexType>
  
      <xs:complexType name="writeSampleSeq">
          <xs:sequence>
              <xs:element name="sample" type="writeSample" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
      </xs:complexType>
  

• Modify the definition of application to match what follows. Remove unused type authenticatedSession from webdds_rest1.xsd

     <xs:complexType name="application">
        <xs:annotation>
          <xs:documentation xml:lang="en-US">
            The Application is a a collection of domain participants they can refer to participants
            in a domain_partitipant_library by the inheritance provided by the base_name attribute
          </xs:documentation>
        </xs:annotation>
        <xs:choice maxOccurs="unbounded">
          <xs:element name="domain_participant" maxOccurs="unbounded" type="domainParticipant"/>
        </xs:choice>
        <xs:attribute name="name" type="elementName" use="required"/>
      </xs:complexType>
  

• Add types qosLibraryList, qosProfileList, applicationList, domainParticipantList, to webdds_rest1.xsd

  <!-- definitions to be added to webdds_rest1.xsd -->
   <xs:complexType name="applicationList">
         <xs:sequence minOccurs="0" maxOccurs="unbounded">
             <xs:element name="application" minOccurs="0" type="application"/>
         </xs:sequence>
      </xs:complexType>  
  
   <xs:complexType name="qosLibraryList">
         <xs:sequence minOccurs="0" maxOccurs="unbounded">
             <xs:element name="qos_library" minOccurs="0" type="qosLibrary"/>
         </xs:sequence>
      </xs:complexType>    
    
  <xs:complexType name="qosProfileList">
         <xs:sequence minOccurs="0" maxOccurs="unbounded">
             <xs:element name="qos_profile" minOccurs="0" type="qosProfile"/>
         </xs:sequence>
      </xs:complexType>    
  
  <xs:complexType name="domainParticipantList">
         <xs:sequence minOccurs="0" maxOccurs="unbounded">
             <xs:element name="domain_participant" minOccurs="0" type="domainParticipant"/>
         </xs:sequence>
      </xs:complexType>    
  

• Add types dataset and datasetLibrary to the webdds_rest1.xsd XSD.

   <!--  ======================================================================== -->
      <xs:complexType name="dataset">
          <xs:all  minOccurs="0" maxOccurs="1">  
              <xs:element name="read_sample_seq" type="readSampleSeq" minOccurs="0" maxOccurs="1" />
              <xs:element name="write_sample_seq" type="writeSampleSeq"  minOccurs="0" maxOccurs="1" />
          </xs:all>
          <xs:attribute name="name" type="elementName" use="required"/>
      </xs:complexType>
      
      <xs:complexType name="datasetLibrary">
          <xs:annotation>
              <xs:documentation>
                  Contains Collections of data samples
              </xs:documentation>
          </xs:annotation>
          <xs:sequence>
              <xs:choice maxOccurs="unbounded">
                  <xs:element name="dataset" type="dataset" minOccurs="0" maxOccurs="unbounded"/>
              </xs:choice>
          </xs:sequence>
          <xs:attribute name="name" type="elementName" use="required"/>
      </xs:complexType>
  

• Modify webdds_rest1.xsd XSD as follows
  Rename element “restdds” to “dds”
  Modify the type “dataReader” moving the documentation annotation on the “query_condition” element to the “content_filter” element.
  Rename the type “contentFilter” to “filter” and modify documentation accordingly
  Remove the type definitions for instanceState, viewState, and sampleState. Change references the these types in type readSampleInfo to instanceStateKind, viewStateKind, and sampleStateKind, respectively. Change also readSampleInfo type so that so that minOccurs of any of the child elements 0 instead of 1. The resulting readSampleInfo type should match this:

<xs:complexType name="readSampleInfo">
        <xs:all>
            <xs:element name="source_timestamp" type="time" minOccurs="0" maxOccurs="1"/>
            <xs:element name="valid_data" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
            <xs:element name="instance_handle" type="instanceHandle" minOccurs="0" maxOccurs="1"/>
            <xs:element name="instance_state" type="instanceStateKind" minOccurs="0" maxOccurs="1"/>
            <xs:element name="sample_state" type="sampleStateKind" minOccurs="0" maxOccurs="1"/>
            <xs:element name="view_state" type="viewStateKind" minOccurs="0" maxOccurs="1"/>
        </xs:all>
    </xs:complexType>

Modify the definition of the “registerType” type adding a “format” attribute.

   <xs:attribute name="format" type="xs:string" use="optional">
          <xs:annotation>
              <xs:documentation>
                  Format used to read/write data of this type. If left unspecified
                  the default format is “XML”
               </xs:documentation>
           </xs:annotation>
        </xs:attribute>

• Modify the definition of element “condition” within type “waitset” adding an intermediate “waitsetCondition” type that is just a reference to a condition. The added waitsetCondition and modified waitset is:

     <xs:complexType name="waitsetCondition">
              <xs:attribute name="condition_ref" type="elementNameReference" use="required">
             <xs:annotation>
                <xs:documentation xml:lang="en-US">
                    Must refer to a condition associated with a DDS entity
                </xs:documentation>
             </xs:annotation>
          </xs:attribute>
      </xs:complexType>
      
      <xs:complexType name="waitset">
          <xs:sequence>
              <xs:element name="condition" type="waitsetCondition"/>
          </xs:sequence> 
          <xs:attribute name="name" type="elementName" use="required"/>                      
      </xs:complexType>
   

• Modify the restdds element of webdds_rest1_example.xml to include the additional children and also to refer to the xtypes:types element directly. The resulting element is:

     <xs:element name="dds">
          <xs:complexType>
              <xs:sequence>
                   <xs:choice maxOccurs="unbounded">
                      <xs:element name="qos_library" type="qosLibrary" minOccurs="0" maxOccurs="unbounded"/>
                      <xs:element ref="xtypes:types" minOccurs="0" maxOccurs="unbounded"/>
                      <xs:element name="waitset_library" type="waitsetLibrary" minOccurs="0" maxOccurs="unbounded"/>                   
                      <xs:element name="domain_participant_library" type="domainParticipantLibrary" maxOccurs="unbounded"/>
                      <xs:element name="application" type="application"  maxOccurs="unbounded"/>
                      <xs:element name="dataset_library" type="datasetLibrary" maxOccurs="unbounded"/>
                  </xs:choice>
              </xs:sequence>        
          </xs:complexType>
      </xs:element>
  

• Modify the non-normative webdds_rest1_example.xml to match the changes in the XSD. Also add example use for more of the elements defined in the XSD, this means adding examples for qos_library, dataset, waitset_library. Also change the type “ShapeType” to be inside a module.