Bindings for OBIX: SOAP Bindings Version 1.0

1Bindings for OBIX: SOAP Bindings Version 1.0

2Working Draft 01

322 February 2013

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.

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

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

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.

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

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

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

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.

1062.1 SOAP Example 107The following is a SOAP request to an oBIX server’s About object: 108 109 110 113 114 115 116An example response to the above request: 117 118 119 121 123 124 125 126 127 128 129 130 131 132 133 134 135

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.

1392.3 Security 140Refer to the recommendations in WS-I Basic Profile 2.0 for security [WS-I]

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

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 152 153 154 155 156 157Standard oBIX WSDL is: 158 163 164 169 170 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211

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 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 246 247 249 250 251 252 253 254 255 256 257 259 260 261 262 263 264 265 266 267 268 270 271 272 273 274 275 276 277 278 279

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.

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.

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

297text

298B.1 Subsidiary section 299text

300B.1.1 Sub-subsidiary section 301text

303 Revision Date Editor Changes Made [Rev number] [Rev Date] [Modified By] [Summary of Changes]

304 305