<p> 1Bindings for OBIX: SOAP Bindings Version 1.0</p><p>2Working Draft 01</p><p>322 February 2013</p><p>4Technical Committee: 5 OASIS Open Building Information Exchange (oBIX) TC 6Chair: 7 Toby Considine ([email protected]), University of North Carolina at Chapel Hill 8Editor: 9 Markus Jung ([email protected]), Institute of Computer Aided Automation 10Additional artifacts: 11 This prose specification is one component of a Work Product which also includes: 12  oBIX XML Schema: obix.xsd 13 14Related work: 15 This specification replaces or supersedes: 16  Specifications replaced by this specification (hyperlink, if available) 17 This specification is related to: 18  oBIX 2.0 core specification 19Declared XML namespaces: 20  http://obix.org/ns/wsdl/1.1 21  http://obix.org/ns/schema/1.1 22Abstract: 23 This document specifies SOAP protocol bindings for oBIX. 24Status: 25 This Working Draft (WD) has been produced by one or more TC Members; it has not yet been 26 voted on by the TC or approved as a Committee Draft (Committee Specification Draft or a 27 Committee Note Draft). The OASIS document Approval Process begins officially with a TC vote 28 to approve a WD as a Committee Draft. A TC may approve a Working Draft, revise it, and re- 29 approve it any number of times as a Committee Draft. 30Initial URI pattern: 31 http://docs.oasis-open.org/obix/OBIX-SOAP/v1.0/csd01/OBIX-SOAP-v1.0-csd01.doc 32 (Managed by OASIS TC Administration; please don’t modify.) 33 34 35Copyright © OASIS Open 2013. All Rights Reserved. 36All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual 37Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website. 38This document and translations of it may be copied and furnished to others, and derivative works that 39comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, 40and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice 41and this section are included on all such copies and derivative works. However, this document itself may 42not be modified in any way, including by removing the copyright notice or references to OASIS, except as 43needed for the purpose of developing any document or deliverable produced by an OASIS Technical 44Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must 45be followed) or as required to translate it into languages other than English.</p><p>1OBIX-SOAP-v1.0-wd01 Working Draft 01 22 February 2013 2Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 1 of 12 46The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors 47or assigns. 48This document and the information contained herein is provided on an "AS IS" basis and OASIS 49DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY 50WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY 51OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 52PARTICULAR PURPOSE. 53</p><p>3OBIX-SOAP-v1.0-wd01 Working Draft 01 22 February 2013 4Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 2 of 12 54Table of Contents</p><p>551 Introduction...... 4 56 1.1 Terminology...... 4 57 1.2 Normative References...... 4 58 1.3 Non-Normative References...... 4 592 SOAP Binding...... 5 60 2.1 SOAP Example...... 5 61 2.2 Error Handling...... 5 62 2.3 Security...... 5 63 2.4 Localization...... 5 64 2.5 WSDL...... 6 653 SOAP over CoAP...... 8 664 Conformance...... 9 67Appendix A. Acknowledgments...... 10 68Appendix B. Non-Normative Text...... 11 69 B.1 Subsidiary section...... 11 70 B.1.1 Sub-subsidiary section...... 11 71Appendix C. Revision History...... 12 72</p><p>5OBIX-SOAP-v1.0-wd01 Working Draft 01 22 February 2013 6Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 3 of 12 731 Introduction 74This document specifies the SOAP protocol bindings for oBIX 2. The SOAP protocol can be used on top 75of HTTP or CoAP as transport protocol. CoAP is a reasonable choice if the SOAP binding for oBIX should 76be used within constrained devices and networks (e.g. 6LoWPAN). This document provides a WSDL 1.1 77description for a SOAP interface to oBIX which uses the XML schema provided as additional resource. </p><p>781.1 Terminology 79The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD 80NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described 81in [oBIX2].</p><p>821.2 Normative References 83 [oBIX2] Open Building Information Exchange Version 2., ???, OASIS Committee 84 Specification, http://??. 85 [WS-I] R. Chumbley, J. Durand, G. Pilz, T. Rutt, Basic Profile Version 2.0, Web Services 86 Interoperability Organization, 09 November 2010</p><p>871.3 Non-Normative References 88 [REST] RT Fielding Architectural Styles and the Design of Network-based Software 89 Architectures, Dissertation, University of California at Irvine, 2000, 90 http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm 91 [SOAP] M Gudgin, M Hadley, N Mendelsohn, J Moreau, H Nielsen, A Karmarkar, Y 92 Lafon, W3C SOAP Version 1.2 (Second Edition), W3C Recommendation 27 April 93 2007 94 [CoAP] Z. Shelby, K. Hartke, C. Bormann, Constrained Application Protocol (CoAP), 95 Draft 14, IETF Draft, 12 March 2003 96 97</p><p>7OBIX-SOAP-v1.0-wd01 Working Draft 01 22 February 2013 8Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 4 of 12 982 SOAP Binding 99The SOAP binding defines a SOAP operation for each of the three oBIX request types: read, write and 100invoke. Like the HTTP binding, read is supported by every object, write is supported by objects whose 101writable attribute is true, and invoke is only supported by operations. Inputs and outputs of each 102request are specific to the target object. 103 104Unlike the HTTP binding, requests are not accessed via the URI of the target object, but instead via the 105URI of the SOAP server with the object’s URI encoded into the body of the SOAP envelope.</p><p>1062.1 SOAP Example 107The following is a SOAP request to an oBIX server’s About object: 108 <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> 109 <env:Body> 110 <obixWS:read xmlns:obixWS="http://obix.org/ns/wsdl/1.1" 111 xmlns="http://obix.org/ns/schema/1.1" 112 href="http://localhost/obix/about" /> 113 </env:Body> 114 </env:Envelope> 115 116An example response to the above request: 117 <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> 118 <env:Body> 119 <obixWS:response xmlns:obixWS="http://obix.org/ns/wsdl1.1" 120 xmlns="http://obix.org/ns/schema/1.1"> 121 <obj name="about" 122 href="http://localhost/obix/about/"> 123 <str name="obixVersion" val="1.1"/> 124 <str name="serverName" val="obix"/> 125 <abstime name="serverTime" val="2006-02-08T09:40:55.000+05:00:00Z"/> 126 <abstime name="serverBootTime" val="2006-02-08T09:33:31.980+05:00:00Z"/> 127 <str name="vendorName" val="Acme, Inc."/> 128 <uri name="vendorUrl" val="http://www.acme.com"/> 129 <str name="productName" val="Acme oBIX Server"/> 130 <str name="productVersion" val="1.0.3"/> 131 <uri name="productUrl" val="http://www.acme.com/obix"/> 132 </obj> 133 </obixWS:response> 134 </env:Body> 135 </env:Envelope></p><p>1362.2 Error Handling 137The oBIX specification defines no SOAP faults. If a request is processed by an oBIX server, then a valid 138oBIX document SHOULD be returned with a failure indicated via the err object.</p><p>1392.3 Security 140Refer to the recommendations in WS-I Basic Profile 2.0 for security [WS-I]</p><p>1412.4 Localization 142SOAP bindings SHOULD follow localization patterns defined for the HTTP binding when applicable (see 143Section Error: Reference source not found of [oBIX2]). 144</p><p>9OBIX-SOAP-v1.0-wd01 Working Draft 01 22 February 2013 10Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 5 of 12 1452.5 WSDL 146In the types section of the WSDL document, the oBIX schema is imported. Server implementations might 147consider providing the schemaLocation attribute which is absent in the standard document. 148Missing from the standard oBIX WSDL is the service element. This element binds a SOAP server 149instance with a network address. Each instance will have to provide its own services section of the WSDL 150document. The following is an example of the WSDL service element: 151 <wsdl:service name="obix"> 152 <wsdl:port name="obixPort" binding="tns:obixSoapBinding"> 153 <soap:address location="http://localhost/obix/soap"/> 154 </wsdl:port> 155 </wsdl:service> 156 157Standard oBIX WSDL is: 158 <wsdl:definitions targetNamespace="http://obix.org/ns/wsdl/1.1" 159 xmlns="http://obix.org/ns/wsdl/1.1" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 160 xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 161 xmlns:xsd="http://www.w3.org/2001/XMLSchema" 162 xmlns:obix="http://obix.org/ns/schema/1.1"> 163 <wsdl:types> 164 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 165 xmlns:obix="http://obix.org/ns/schema/1.1" elementFormDefault="qualified" 166 xmlns:obixWS="http://obix.org/ns/wsdl/1.1" 167 targetNamespace="http://obix.org/ns/wsdl/1.1" 168 xmlns="http://obix.org/ns/wsdl/1.1"> 169 170 <xsd:import namespace="http://obix.org/ns/schema/1.1" 171 schemaLocation="obix.xsd" /> 172 173 <xsd:complexType name="ReadReq"> 174 <xsd:attribute name="href" type="xsd:anyURI" /> 175 </xsd:complexType> 176 177 <xsd:complexType name="WriteReq"> 178 <xsd:complexContent> 179 <xsd:extension base="ReadReq"> 180 <xsd:group ref="obix:objGroup" /> 181 </xsd:extension> 182 </xsd:complexContent> 183 </xsd:complexType> 184 185 <xsd:complexType name="InvokeReq"> 186 <xsd:complexContent> 187 <xsd:extension base="ReadReq"> 188 <xsd:group ref="obix:objGroup" /> 189 </xsd:extension> 190 </xsd:complexContent> 191 </xsd:complexType> 192 193 <xsd:complexType name="ResponseType"> 194 <xsd:group ref="obix:objGroup" minOccurs="1" 195 maxOccurs="1" /> 196 </xsd:complexType> 197 198 <xsd:element name="read" type="obixWS:ReadReq" /> 199 <xsd:element name="response" type="obixWS:ResponseType" /> 200 <xsd:element name="write" type="obixWS:WriteReq" /> 201 <xsd:element name="invoke" type="obixWS:InvokeReq" /> 202 </xsd:schema> 203 </wsdl:types> 204 205 <wsdl:message name="readSoapReq"> 206 <wsdl:part name="body" element="read" /> 207 208 </wsdl:message> 209 <wsdl:message name="readSoapRes"> 210 211 <wsdl:part name="body" element="response" /></p><p>11OBIX-SOAP-v1.0-wd01 Working Draft 01 22 February 2013 12Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 6 of 12 212 </wsdl:message> 213 214 <wsdl:message name="writeSoapReq"> 215 <wsdl:part name="body" element="write" /> 216 </wsdl:message> 217 218 <wsdl:message name="writeSoapRes"> 219 <wsdl:part name="body" element="response" /> 220 </wsdl:message> 221 222 <wsdl:message name="invokeSoapReq"> 223 <wsdl:part name="body" element="invoke" /> 224 </wsdl:message> 225 <wsdl:message name="invokeSoapRes"> 226 <wsdl:part name="body" element="response" /> 227 228 </wsdl:message> 229 <wsdl:portType name="oBIXSoapPort"> 230 <wsdl:operation name="read"> 231 <wsdl:input message="readSoapReq" /> 232 <wsdl:output message="readSoapRes" /> 233 </wsdl:operation> 234 <wsdl:operation name="write"> 235 <wsdl:input message="writeSoapReq" /> 236 <wsdl:output message="writeSoapRes" /> 237 </wsdl:operation> 238 <wsdl:operation name="invoke"> 239 <wsdl:input message="invokeSoapReq" /> 240 <wsdl:output message="invokeSoapRes" /> 241 </wsdl:operation> 242 </wsdl:portType> 243 <wsdl:binding name="oBIXSoapBinding" type="oBIXSoapPort"> 244 <soap:binding style="document" 245 transport="http://schemas.xmlsoap.org/soap/http" /> 246 <wsdl:operation name="read"> 247 <soap:operation soapAction="http://obix.org/ns/wsdl/1.1/read" 248 style="document" /> 249 <wsdl:input> 250 <soap:body use="literal" /> 251 </wsdl:input> 252 <wsdl:output> 253 <soap:body use="literal" /> 254 </wsdl:output> 255 </wsdl:operation> 256 <wsdl:operation name="write"> 257 <soap:operation soapAction="http://obix.org/ns/wsdl/1.1/write" 258 style="document" /> 259 260 <wsdl:input> 261 <soap:body use="literal" /> 262 </wsdl:input> 263 <wsdl:output> 264 <soap:body use="literal" /> 265 </wsdl:output> 266 </wsdl:operation> 267 <wsdl:operation name="invoke"> 268 <soap:operation soapAction="http://obix.org/ns/wsdl/1.1/invoke" 269 style="document" /> 270 <wsdl:input> 271 <soap:body use="literal" /> 272 </wsdl:input> 273 <wsdl:output> 274 <soap:body use="literal" /> 275 </wsdl:output> 276 </wsdl:operation> 277 </wsdl:binding> 278 </wsdl:definitions> 279</p><p>13OBIX-SOAP-v1.0-wd01 Working Draft 01 22 February 2013 14Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 7 of 12 280SOAP over CoAP 281An oBIX server MAY provide a SOAP endpoint binding using CoAP. This binding is reasonable within 282constrained environments, e.g. found in 6LoWPANs and allows an efficient SOAP message exchange. 283The WSDL defined in section 2.5 remains the same, except the SOAP binding element specifies CoAP 284instead of HTTP.</p><p>285</p><p>15OBIX-SOAP-v1.0-wd01 Working Draft 01 22 February 2013 16Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 8 of 12 2863 Conformance 287The last numbered section in the specification must be the Conformance section. Conformance 288Statements/Clauses go here.</p><p>17OBIX-SOAP-v1.0-wd01 Working Draft 01 22 February 2013 18Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 9 of 12 289Appendix A. Acknowledgments</p><p>290The following individuals have participated in the creation of this specification and are gratefully 291acknowledged: 292Participants: 293 [Participant Name, Affiliation | Individual Member] 294 [Participant Name, Affiliation | Individual Member] 295</p><p>19OBIX-SOAP-v1.0-wd01 Working Draft 01 22 February 2013 20Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 10 of 12 296Appendix B. Non-Normative Text</p><p>297text</p><p>298B.1 Subsidiary section 299text</p><p>300B.1.1 Sub-subsidiary section 301text</p><p>21OBIX-SOAP-v1.0-wd01 Working Draft 01 22 February 2013 22Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 11 of 12 302Appendix C. Revision History</p><p>303 Revision Date Editor Changes Made [Rev number] [Rev Date] [Modified By] [Summary of Changes]</p><p>304 305</p><p>23OBIX-SOAP-v1.0-wd01 Working Draft 01 22 February 2013 24Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 12 of 12</p>