CoRE Working Group C. Groves Internet-Draft W. Yang Intended status: Standards Track Huawei Expires: September 14, 2017 March 13, 2017 Binding Attribute Scope draft-groves-core-bas-01 Abstract This document specifies an additional CoAP binding attribute that allows binding attributes to be scoped to an item (sub-resource) in a collection resource. This allows synchronisation of multiple resources in a collection based on the value of one resource. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on September 14, 2017. Copyright Notice Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Groves & Yang Expires September 14, 2017 [Page 1] Internet-Draft Binding Att. Scope March 2017 Table of Contents 1. Requirements Language . . . . . . . . . . . . . . . . . . . . 2 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2.1. Usage of a collection . . . . . . . . . . . . . . . . . . 3 2.2. Multiple Conditions . . . . . . . . . . . . . . . . . . . 3 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 4. Binding Attributes . . . . . . . . . . . . . . . . . . . . . 4 4.1. Binding Attribute Scope . . . . . . . . . . . . . . . . . 5 4.2. Interactions . . . . . . . . . . . . . . . . . . . . . . 5 4.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 5 4.3.1. Example 1 - Item Binding Attribute . . . . . . . . . 6 4.3.2. Example 2 - Mutliple Observes . . . . . . . . . . . . 6 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 7 9. Normative References . . . . . . . . . . . . . . . . . . . . 7 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 1. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 2. Introduction In some cases a CoAP client may require a notification of the value of a resource based on some condition associated with another resource. For example: a client wants to be notified of the machine state once a temperature sensor threshold is crossed. Currently the only way to implement this is for a client to be notified of the temperature resource change and then for the client to do a seperate read of the required resources. It would be more efficient to provide the information in a single response. This document defines a new "Binding Attribute Scope" binding attribute to allow a client to request collection resource state synchronisation based on a conditional value of an item in the collection resource. The "Binding Attribute Scope" (bas) attribute is set on a collection and is used to indicate which item in a collection an Observe and associated binding attributes apply to. A linked batch (or batch) interface (sect.4.3/[I-D.ietf-core-interfaces]) is used on the collection. The client constructs a collection resource using the Groves & Yang Expires September 14, 2017 [Page 2] Internet-Draft Binding Att. Scope March 2017 linked batch interface or uses a pre-provisioned collection via the batch interface to set the information that it requires. By placing the required information in a collection it allows a GET on the collection to return all the information based on the conditional value of an item. Section Section 4 below indicates the text that would need to be added to [I-D.ietf-core-dynlink] to add the Binding Attribute Scope attribute. 2.1. Usage of a collection [I-D.ietf-core-interfaces] indicates that a collection may be observed. An observation returns a representation of the entire collection. The "bas" binding attribute is only used on collection (e.g. batch, linked-batch) resources which enables the use of the binding attributes from [I-D.ietf-core-dynlink] on a collection. The "bas" attribute points to one item in the collection. This approach does have the downside that it requires the use of a collection interface even if a single resource is required. The scope of the synchronization is limited to the current collection. However the use of a collection to return the information does seem to fit with the principle that a GET of a resource should return the same representation as a notification. 2.2. Multiple Conditions Given that the "bas" binding attribute only applies to one item/sub- resource in a collection it means that multiple resources cannot be used as conditions for a binding synchronization. To allow the use of conditions on multiple resources to determine resource synchronization a different approach would be required. One approach would be to use the FETCH method [I-D.ietf-core-etch] with a set of request parameters. A content type could be defined that allowed the binding attributes to be specified on multiple resources. For example: Groves & Yang Expires September 14, 2017 [Page 3] Internet-Draft Binding Att. Scope March 2017 FETCH /s/?pmin=1&pmax=100 content-type=application/conditionals+json [ { "n": "/s/light", "st": 5 }, { "n": "/s/temp", "st": 1 }, { "n": "/s/humidity", "lt": 40, "gt" 70 } ] This approach would add complexity over the use of the bas binding attribute however such complexity may be warranted in certain use cases. A new content-format would need to be defined. This approach is for further study. 3. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC2119]. This specification requires readers to be familiar with all the terms and concepts that are discussed in [RFC5988] and [RFC6690]. 4. Binding Attributes This document introduces one new attributes: +-------------------------+-----------+-------------+ | Attribute Name | Parameter | Data Format | +-------------------------+-----------+-------------+ | Binding Attribute Scope | bas | xsd:string | +-------------------------+-----------+-------------+ Table 1: Binding Attribute Summary The xsd:string contains a Uri-Path. Groves & Yang Expires September 14, 2017 [Page 4] Internet-Draft Binding Att. Scope March 2017 4.1. Binding Attribute Scope The binding attribute scope attribute allows a client to indicate that the binding attributes contained in the query apply to a certain item in a collection resource. The collection containing the Observed resource and the additional resources to be returned is first created through the use of the Batch or Linked-Batch [I-D.ietf-core-interfaces] interface. The Linked-Batch allows a client to dynamically associate resources. The client then creates a binding (e.g. an Observe) with the collection indicating the required binding attributes (e.g. "gt", "lt" etc.) and to which sub-resource these apply through the use of the "bas" binding attribute containing a URI-path. A client may create multiple bindings for the collection. When using Observe a client may use mutliple GET Observes with different queury parameters. Each observation is identified through the use of different Tokens. If the server determines that the "bas" attribute contains an unknown URI-path then it responds with response code 4.04 "Not Found". State sychronisation occurs when the sub-resource (item) value meets the conditions indicated by the binding attributes. When state synchronisation occurs the collection resource (including sub- resources) will be synchronised. 4.2. Interactions The "bas" parameter modifies the scope of other binding attributes in a query to apply to the resource specified in the "bas" URI-path. *Editor's note: the interaction with sample time window/sample number window needs to be added if accepted.* 4.3. Examples Given the resource links: Req: GET /.well-known/core Res: 2.05 Content (application/link-format) ;rt="simple.sen";if="core.b", ;rt="simple.sen.light";if="core.s", ;rt="simple.sen.tmp";if="core.s";obs, ;rt="simple.sen.hum";if="core.s" Groves & Yang Expires September 14, 2017 [Page 5] Internet-Draft Binding Att. Scope March 2017 4.3.1. Example 1 - Item Binding Attribute A Req: GET /s?bas="temp">=37 Token: 0x4a Observe: 0 would produce the following when temp exceeds 37: Res: 2.05 Content (application/senml+json) Token: 0x4a {"e":[ { "n": "/s/light", "v": 123, "u": "lx" }, { "n": "/s/temp", "v": 38, "u": "degC" }, { "n": "/s/humidity", "v": 80, "u": "%RH" }], } 4.3.2. Example 2 - Mutliple Observes In addition to the GET in example 1 the client could also request a notification when the humidity raises above 90%. A Req: GET /s?bas="humidity">=90 Token: 0x4b Observe: 0 would produce the following when temp exceeds 37: Res: 2.05 Content (application/senml+json) Token: 0x4b {"e":[ { "n": "/s/light", "v": 123, "u": "lx" }, { "n": "/s/temp", "v": 16, "u": "degC" }, { "n": "/s/humidity", "v": 92, "u": "%RH" }], } _Editor's note: Need to add example for pmin_ 5. Security Considerations As per 5/[I-D.ietf-core-dynlink]. 6. IANA Considerations None. 7. Acknowledgements Michael Koster for his comments and suggestion of the FETCH approach. Friedhelm Rodermund for stimulating discussion of the use case. Groves & Yang Expires September 14, 2017 [Page 6] Internet-Draft Binding Att. Scope March 2017 Mojan Mohajer for raising the multiple observes on a collection use case. 8. Changelog draft-groves-core-bas-01 o Section 2: Removed editor's note on alternate solution o Section 2.1: Changed language around observe on collections. o Section 4.1: Added text regarding multiple observations. draft-groves-core-bas-00 o Initial version 9. Normative References [I-D.ietf-core-dynlink] Shelby, Z., Vial, M., Koster, M., and C. Groves, "Dynamic Resource Linking for Constrained RESTful Environments", draft-ietf-core-dynlink-02 (work in progress), February 2017. [I-D.ietf-core-etch] Stok, P., Bormann, C., and A. Sehgal, "Patch and Fetch Methods for Constrained Application Protocol (CoAP)", draft-ietf-core-etch-04 (work in progress), November 2016. [I-D.ietf-core-interfaces] Shelby, Z., Vial, M., Koster, M., and C. Groves, "Reusable Interface Definitions for Constrained RESTful Environments", draft-ietf-core-interfaces-08 (work in progress), February 2017. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/RFC5988, October 2010, . [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, . Groves & Yang Expires September 14, 2017 [Page 7] Internet-Draft Binding Att. Scope March 2017 Authors' Addresses Christian Groves Huawei Australia Email: cngroves.std@gmail.com Weiwei Yang Huawei P.R.China Email: tommy@huawei.com Groves & Yang Expires September 14, 2017 [Page 8]