[Docs] [txt|pdf|xml] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01

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)
     </s/>;rt="simple.sen";if="core.b",
     </s/light>;rt="simple.sen.light";if="core.s",
     </s/temp>;rt="simple.sen.tmp";if="core.s";obs,
     </s/humidity>;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"&gt=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"&gt=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,
              <http://www.rfc-editor.org/info/rfc2119>.

   [RFC5988]  Nottingham, M., "Web Linking", RFC 5988,
              DOI 10.17487/RFC5988, October 2010,
              <http://www.rfc-editor.org/info/rfc5988>.

   [RFC6690]  Shelby, Z., "Constrained RESTful Environments (CoRE) Link
              Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
              <http://www.rfc-editor.org/info/rfc6690>.



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]


Html markup produced by rfcmarkup 1.124, available from https://tools.ietf.org/tools/rfcmarkup/