idnits 2.17.1 draft-groves-core-bas-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (March 13, 2017) is 2599 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-14) exists of draft-ietf-core-dynlink-02 ** Downref: Normative reference to an Informational draft: draft-ietf-core-dynlink (ref. 'I-D.ietf-core-dynlink') == Outdated reference: A later version (-14) exists of draft-ietf-core-interfaces-08 ** Downref: Normative reference to an Informational draft: draft-ietf-core-interfaces (ref. 'I-D.ietf-core-interfaces') ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group C. Groves 3 Internet-Draft W. Yang 4 Intended status: Standards Track Huawei 5 Expires: September 14, 2017 March 13, 2017 7 Binding Attribute Scope 8 draft-groves-core-bas-01 10 Abstract 12 This document specifies an additional CoAP binding attribute that 13 allows binding attributes to be scoped to an item (sub-resource) in a 14 collection resource. This allows synchronisation of multiple 15 resources in a collection based on the value of one resource. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on September 14, 2017. 34 Copyright Notice 36 Copyright (c) 2017 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Requirements Language . . . . . . . . . . . . . . . . . . . . 2 52 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2.1. Usage of a collection . . . . . . . . . . . . . . . . . . 3 54 2.2. Multiple Conditions . . . . . . . . . . . . . . . . . . . 3 55 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 4. Binding Attributes . . . . . . . . . . . . . . . . . . . . . 4 57 4.1. Binding Attribute Scope . . . . . . . . . . . . . . . . . 5 58 4.2. Interactions . . . . . . . . . . . . . . . . . . . . . . 5 59 4.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 5 60 4.3.1. Example 1 - Item Binding Attribute . . . . . . . . . 6 61 4.3.2. Example 2 - Mutliple Observes . . . . . . . . . . . . 6 62 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 63 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 64 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 65 8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 7 66 9. Normative References . . . . . . . . . . . . . . . . . . . . 7 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 69 1. Requirements Language 71 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 72 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 73 "OPTIONAL" in this document are to be interpreted as described in 74 [RFC2119]. 76 2. Introduction 78 In some cases a CoAP client may require a notification of the value 79 of a resource based on some condition associated with another 80 resource. For example: a client wants to be notified of the machine 81 state once a temperature sensor threshold is crossed. Currently the 82 only way to implement this is for a client to be notified of the 83 temperature resource change and then for the client to do a seperate 84 read of the required resources. It would be more efficient to 85 provide the information in a single response. 87 This document defines a new "Binding Attribute Scope" binding 88 attribute to allow a client to request collection resource state 89 synchronisation based on a conditional value of an item in the 90 collection resource. 92 The "Binding Attribute Scope" (bas) attribute is set on a collection 93 and is used to indicate which item in a collection an Observe and 94 associated binding attributes apply to. A linked batch (or batch) 95 interface (sect.4.3/[I-D.ietf-core-interfaces]) is used on the 96 collection. The client constructs a collection resource using the 97 linked batch interface or uses a pre-provisioned collection via the 98 batch interface to set the information that it requires. By placing 99 the required information in a collection it allows a GET on the 100 collection to return all the information based on the conditional 101 value of an item. 103 Section Section 4 below indicates the text that would need to be 104 added to [I-D.ietf-core-dynlink] to add the Binding Attribute Scope 105 attribute. 107 2.1. Usage of a collection 109 [I-D.ietf-core-interfaces] indicates that a collection may be 110 observed. An observation returns a representation of the entire 111 collection. The "bas" binding attribute is only used on collection 112 (e.g. batch, linked-batch) resources which enables the use of the 113 binding attributes from [I-D.ietf-core-dynlink] on a collection. The 114 "bas" attribute points to one item in the collection. 116 This approach does have the downside that it requires the use of a 117 collection interface even if a single resource is required. The 118 scope of the synchronization is limited to the current collection. 119 However the use of a collection to return the information does seem 120 to fit with the principle that a GET of a resource should return the 121 same representation as a notification. 123 2.2. Multiple Conditions 125 Given that the "bas" binding attribute only applies to one item/sub- 126 resource in a collection it means that multiple resources cannot be 127 used as conditions for a binding synchronization. To allow the use 128 of conditions on multiple resources to determine resource 129 synchronization a different approach would be required. 131 One approach would be to use the FETCH method [I-D.ietf-core-etch] 132 with a set of request parameters. A content type could be defined 133 that allowed the binding attributes to be specified on multiple 134 resources. 136 For example: 138 FETCH /s/?pmin=1&pmax=100 content-type=application/conditionals+json 140 [ 141 { 142 "n": "/s/light", 143 "st": 5 144 }, 145 { 146 "n": "/s/temp", 147 "st": 1 148 }, 149 { 150 "n": "/s/humidity", 151 "lt": 40, 152 "gt" 70 153 } 154 ] 156 This approach would add complexity over the use of the bas binding 157 attribute however such complexity may be warranted in certain use 158 cases. A new content-format would need to be defined. This approach 159 is for further study. 161 3. Terminology 163 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 164 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 165 "OPTIONAL" in this specification are to be interpreted as described 166 in [RFC2119]. 168 This specification requires readers to be familiar with all the terms 169 and concepts that are discussed in [RFC5988] and [RFC6690]. 171 4. Binding Attributes 173 This document introduces one new attributes: 175 +-------------------------+-----------+-------------+ 176 | Attribute Name | Parameter | Data Format | 177 +-------------------------+-----------+-------------+ 178 | Binding Attribute Scope | bas | xsd:string | 179 +-------------------------+-----------+-------------+ 181 Table 1: Binding Attribute Summary 183 The xsd:string contains a Uri-Path. 185 4.1. Binding Attribute Scope 187 The binding attribute scope attribute allows a client to indicate 188 that the binding attributes contained in the query apply to a certain 189 item in a collection resource. 191 The collection containing the Observed resource and the additional 192 resources to be returned is first created through the use of the 193 Batch or Linked-Batch [I-D.ietf-core-interfaces] interface. The 194 Linked-Batch allows a client to dynamically associate resources. 196 The client then creates a binding (e.g. an Observe) with the 197 collection indicating the required binding attributes (e.g. "gt", 198 "lt" etc.) and to which sub-resource these apply through the use of 199 the "bas" binding attribute containing a URI-path. 201 A client may create multiple bindings for the collection. When using 202 Observe a client may use mutliple GET Observes with different queury 203 parameters. Each observation is identified through the use of 204 different Tokens. 206 If the server determines that the "bas" attribute contains an unknown 207 URI-path then it responds with response code 4.04 "Not Found". 209 State sychronisation occurs when the sub-resource (item) value meets 210 the conditions indicated by the binding attributes. When state 211 synchronisation occurs the collection resource (including sub- 212 resources) will be synchronised. 214 4.2. Interactions 216 The "bas" parameter modifies the scope of other binding attributes in 217 a query to apply to the resource specified in the "bas" URI-path. 219 *Editor's note: the interaction with sample time window/sample number 220 window needs to be added if accepted.* 222 4.3. Examples 224 Given the resource links: 226 Req: GET /.well-known/core 227 Res: 2.05 Content (application/link-format) 228 ;rt="simple.sen";if="core.b", 229 ;rt="simple.sen.light";if="core.s", 230 ;rt="simple.sen.tmp";if="core.s";obs, 231 ;rt="simple.sen.hum";if="core.s" 233 4.3.1. Example 1 - Item Binding Attribute 235 A Req: GET /s?bas="temp">=37 236 Token: 0x4a 237 Observe: 0 238 would produce the following when temp exceeds 37: 240 Res: 2.05 Content (application/senml+json) 241 Token: 0x4a 242 {"e":[ 243 { "n": "/s/light", "v": 123, "u": "lx" }, 244 { "n": "/s/temp", "v": 38, "u": "degC" }, 245 { "n": "/s/humidity", "v": 80, "u": "%RH" }], 246 } 248 4.3.2. Example 2 - Mutliple Observes 250 In addition to the GET in example 1 the client could also request a 251 notification when the humidity raises above 90%. 253 A Req: GET /s?bas="humidity">=90 254 Token: 0x4b 255 Observe: 0 256 would produce the following when temp exceeds 37: 258 Res: 2.05 Content (application/senml+json) 259 Token: 0x4b 260 {"e":[ 261 { "n": "/s/light", "v": 123, "u": "lx" }, 262 { "n": "/s/temp", "v": 16, "u": "degC" }, 263 { "n": "/s/humidity", "v": 92, "u": "%RH" }], 264 } 266 _Editor's note: Need to add example for pmin_ 268 5. Security Considerations 270 As per 5/[I-D.ietf-core-dynlink]. 272 6. IANA Considerations 274 None. 276 7. Acknowledgements 278 Michael Koster for his comments and suggestion of the FETCH approach. 279 Friedhelm Rodermund for stimulating discussion of the use case. 281 Mojan Mohajer for raising the multiple observes on a collection use 282 case. 284 8. Changelog 286 draft-groves-core-bas-01 288 o Section 2: Removed editor's note on alternate solution 290 o Section 2.1: Changed language around observe on collections. 292 o Section 4.1: Added text regarding multiple observations. 294 draft-groves-core-bas-00 296 o Initial version 298 9. Normative References 300 [I-D.ietf-core-dynlink] 301 Shelby, Z., Vial, M., Koster, M., and C. Groves, "Dynamic 302 Resource Linking for Constrained RESTful Environments", 303 draft-ietf-core-dynlink-02 (work in progress), February 304 2017. 306 [I-D.ietf-core-etch] 307 Stok, P., Bormann, C., and A. Sehgal, "Patch and Fetch 308 Methods for Constrained Application Protocol (CoAP)", 309 draft-ietf-core-etch-04 (work in progress), November 2016. 311 [I-D.ietf-core-interfaces] 312 Shelby, Z., Vial, M., Koster, M., and C. Groves, "Reusable 313 Interface Definitions for Constrained RESTful 314 Environments", draft-ietf-core-interfaces-08 (work in 315 progress), February 2017. 317 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 318 Requirement Levels", BCP 14, RFC 2119, 319 DOI 10.17487/RFC2119, March 1997, 320 . 322 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 323 DOI 10.17487/RFC5988, October 2010, 324 . 326 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 327 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 328 . 330 Authors' Addresses 332 Christian Groves 333 Huawei 334 Australia 336 Email: cngroves.std@gmail.com 338 Weiwei Yang 339 Huawei 340 P.R.China 342 Email: tommy@huawei.com