Internet DRAFT - draft-groves-core-bas
draft-groves-core-bas
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">=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,
<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]
