draft-ietf-core-dynlink-07.txt		draft-ietf-core-dynlink-08.txt
	CoRE Working Group Z. Shelby		CoRE Working Group Z. Shelby
	Internet-Draft ARM		Internet-Draft ARM
	Intended status: Informational M. Koster		Intended status: Informational M. Koster
	Expires: April 25, 2019 SmartThings		Expires: September 9, 2019 SmartThings
	C. Groves		C. Groves
	J. Zhu		J. Zhu
	Huawei		Huawei
	B. Silverajan, Ed.		B. Silverajan, Ed.
	Tampere University of Technology		Tampere University
	October 22, 2018		March 08, 2019
	Dynamic Resource Linking for Constrained RESTful Environments		Dynamic Resource Linking for Constrained RESTful Environments
	draft-ietf-core-dynlink-07		draft-ietf-core-dynlink-08
	Abstract		Abstract
	For CoAP (RFC7252), Dynamic linking of state updates between		This specification defines Link Bindings, which provide dynamic
	resources, either on an endpoint or between endpoints, is defined		linking of state updates between resources, either on an endpoint or
	with the concept of Link Bindings. This specification defines		between endpoints, for systems using CoAP (RFC7252). This
	conditional observation attributes that work with Link Bindings or		specification also defines Conditional Notification Attributes that
	with CoAP Observe (RFC7641).		work with Link Bindings or with CoAP Observe (RFC7641).
	Editor note		Editor note
	The git repository for the draft is found at https://github.com/core-		The git repository for the draft is found at https://github.com/core-
	wg/dynlink		wg/dynlink
	Status of This Memo		Status of This Memo
	This Internet-Draft is submitted in full conformance with the		This Internet-Draft is submitted in full conformance with the
	provisions of BCP 78 and BCP 79.		provisions of BCP 78 and BCP 79.
	skipping to change at page 1, line 46 ¶		skipping to change at page 1, line 46 ¶
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute		Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-		working documents as Internet-Drafts. The list of current Internet-
	Drafts is at https://datatracker.ietf.org/drafts/current/.		Drafts is at https://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	This Internet-Draft will expire on April 25, 2019.		This Internet-Draft will expire on September 9, 2019.
	Copyright Notice		Copyright Notice
	Copyright (c) 2018 IETF Trust and the persons identified as the		Copyright (c) 2019 IETF Trust and the persons identified as the
	document authors. All rights reserved.		document authors. All rights reserved.
	This document is subject to BCP 78 and the IETF Trust's Legal		This document is subject to BCP 78 and the IETF Trust's Legal
	Provisions Relating to IETF Documents		Provisions Relating to IETF Documents
	(https://trustee.ietf.org/license-info) in effect on the date of		(https://trustee.ietf.org/license-info) in effect on the date of
	publication of this document. Please review these documents		publication of this document. Please review these documents
	carefully, as they describe your rights and restrictions with respect		carefully, as they describe your rights and restrictions with respect
	to this document. Code Components extracted from this document must		to this document. Code Components extracted from this document must
	include Simplified BSD License text as described in Section 4.e of		include Simplified BSD License text as described in Section 4.e of
	the Trust Legal Provisions and are provided without warranty as		the Trust Legal Provisions and are provided without warranty as
	described in the Simplified BSD License.		described in the Simplified BSD License.
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
	2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3		2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
	3. Link Bindings . . . . . . . . . . . . . . . . . . . . . . . . 4		3. Conditional Notification Attributes . . . . . . . . . . . . . 4
	3.1. The "bind" attribute and Binding Methods . . . . . . . . 4		3.1. Attribute Definitions . . . . . . . . . . . . . . . . . . 4
	3.1.1. Polling . . . . . . . . . . . . . . . . . . . . . . . 5		3.1.1. Minimum Period (pmin) . . . . . . . . . . . . . . . . 5
	3.1.2. Observe . . . . . . . . . . . . . . . . . . . . . . . 5		3.1.2. Maximum Period (pmax) . . . . . . . . . . . . . . . . 5
	3.1.3. Push . . . . . . . . . . . . . . . . . . . . . . . . 6		3.1.3. Change Step (st) . . . . . . . . . . . . . . . . . . 5
	3.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 6		3.1.4. Greater Than (gt) . . . . . . . . . . . . . . . . . . 6
	4. Binding and Resource Observation Attributes . . . . . . . . . 6		3.1.5. Less Than (lt) . . . . . . . . . . . . . . . . . . . 6
	4.1. Minimum Period (pmin) . . . . . . . . . . . . . . . . . . 7		3.1.6. Notification Band (band) . . . . . . . . . . . . . . 7
	4.2. Maximum Period (pmax) . . . . . . . . . . . . . . . . . . 7		3.2. Server processing of Conditional Notification Attributes 8
	4.3. Change Step (st) . . . . . . . . . . . . . . . . . . . . 7		4. Link Bindings . . . . . . . . . . . . . . . . . . . . . . . . 8
	4.4. Greater Than (gt) . . . . . . . . . . . . . . . . . . . . 8		4.1. The "bind" attribute and Binding Methods . . . . . . . . 9
	4.5. Less Than (lt) . . . . . . . . . . . . . . . . . . . . . 8		4.1.1. Polling . . . . . . . . . . . . . . . . . . . . . . . 10
	4.6. Notification Band (band) . . . . . . . . . . . . . . . . 8		4.1.2. Observe . . . . . . . . . . . . . . . . . . . . . . . 10
	4.7. Attribute Interactions . . . . . . . . . . . . . . . . . 9		4.1.3. Push . . . . . . . . . . . . . . . . . . . . . . . . 11
	5. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 10		4.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 11
	6. Implementation Considerations . . . . . . . . . . . . . . . . 11		5. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 11
	7. Security Considerations . . . . . . . . . . . . . . . . . . . 12		6. Implementation Considerations . . . . . . . . . . . . . . . . 12
	8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12		7. Security Considerations . . . . . . . . . . . . . . . . . . . 13
	8.1. Interface Description . . . . . . . . . . . . . . . . . . 12		8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
			8.1. Resource Type value 'core.bnd' . . . . . . . . . . . . . 13
	8.2. Link Relation Type . . . . . . . . . . . . . . . . . . . 13		8.2. Link Relation Type . . . . . . . . . . . . . . . . . . . 13
	9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13		9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14
	10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 13		10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 14
	11. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 13		11. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 14
	12. References . . . . . . . . . . . . . . . . . . . . . . . . . 15		12. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
	12.1. Normative References . . . . . . . . . . . . . . . . . . 15		12.1. Normative References . . . . . . . . . . . . . . . . . . 16
	12.2. Informative References . . . . . . . . . . . . . . . . . 16		12.2. Informative References . . . . . . . . . . . . . . . . . 17
	Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 16		Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 17
	A.1. Greater Than (gt) example . . . . . . . . . . . . . . . . 16		A.1. Greater Than (gt) example . . . . . . . . . . . . . . . . 17
	A.2. Greater Than (gt) and Period Max (pmax) example . . . . . 17		A.2. Greater Than (gt) and Period Max (pmax) example . . . . . 18
			Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18
	1. Introduction		1. Introduction
	IETF Standards for machine to machine communication in constrained		IETF Standards for machine to machine communication in constrained
	environments describe a REST protocol [RFC7252] and a set of related		environments describe a REST protocol [RFC7252] and a set of related
	information standards that may be used to represent machine data and		information standards that may be used to represent machine data and
	machine metadata in REST interfaces. CoRE Link-format [RFC6690] is a		machine metadata in REST interfaces. CoRE Link-format [RFC6690] is a
	standard for doing Web Linking [RFC8288] in constrained environments.		standard for doing Web Linking [RFC8288] in constrained environments.
	This specification introduces the concept of a Link Binding, which		This specification introduces the concept of a Link Binding, which
	defines a new link relation type to create a dynamic link between		defines a new link relation type to create a dynamic link between
	resources over which state updates are conveyed. Specifically, a		resources over which state updates are conveyed. Specifically, a
	Link Binding is a unidirectional link for binding the states of		Link Binding is a unidirectional link for binding the states of
	source and destination resources together such that updates to one		source and destination resources together such that updates to one
	are sent over the link to the other. CoRE Link Format		are sent over the link to the other. CoRE Link Format
	representations are used to configure, inspect, and maintain Link		representations are used to configure, inspect, and maintain Link
	Bindings. This specification additionally defines a set of		Bindings. This specification additionally defines Conditional
	conditional Observe Attributes for use with Link Bindings and with		Notification Attributes for use with Link Bindings and with the CoRE
	the standalone CoRE Observe [RFC7641] method.		Observe [RFC7641] method.
	2. Terminology		2. Terminology
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and		"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
	"OPTIONAL" in this document are to be interpreted as described in BCP		"OPTIONAL" in this document are to be interpreted as described in BCP
	14 [RFC2119] [RFC8174] when, and only when, they appear in all		14 [RFC2119] [RFC8174] when, and only when, they appear in all
	capitals, as shown here.		capitals, as shown here.
	This specification requires readers to be familiar with all the terms		This specification requires readers to be familiar with all the terms
	skipping to change at page 4, line 5 ¶		skipping to change at page 4, line 7 ¶
	the resource values between a source and a destination. The		the resource values between a source and a destination. The
	process of using a REST method to achieve this is defined as		process of using a REST method to achieve this is defined as
	"State Synchronization". The endpoint triggering the state		"State Synchronization". The endpoint triggering the state
	synchronization is the synchronization initiator.		synchronization is the synchronization initiator.
	Notification Band: A resource value range that results in state		Notification Band: A resource value range that results in state
	sychronization. The value range may be bounded by a minimum and		sychronization. The value range may be bounded by a minimum and
	maximum value or may be unbounded having either a minimum or		maximum value or may be unbounded having either a minimum or
	maximum value.		maximum value.
	3. Link Bindings		3. Conditional Notification Attributes
	In a M2M RESTful environment, endpoints may directly exchange the
	content of their resources to operate the distributed system. For
	example, a light switch may supply on-off control information that
	may be sent directly to a light resource for on-off control.
	Beforehand, a configuration phase is necessary to determine how the
	resources of the different endpoints are related to each other. This
	can be done either automatically using discovery mechanisms or by
	means of human intervention and a so-called commissioning tool. In
	this specification such an abstract relationship between two
	resources is defined, called a link Binding. The configuration phase
	necessitates the exchange of binding information so a format
	recognized by all CoRE endpoints is essential. This specification
	defines a format based on the CoRE Link-Format to represent binding
	information along with the rules to define a binding method which is
	a specialized relationship between two resources. The purpose of
	such a binding is to synchronize the content between a source
	resource and a destination resource. The destination resource MAY be
	a group resource if the authority component of the destination URI
	contains a group address (either a multicast address or a name that
	resolves to a multicast address). Since a binding is unidirectional,
	the binding entry defining a relationship is present only on one
	endpoint. The binding entry may be located either on the source or
	the destination endpoint depending on the binding method.
	3.1. The "bind" attribute and Binding Methods
	A binding method defines the rules to generate the web-transfer
	exchanges that synchronize state between source and destination
	resources. By using REST methods content is sent from the source
	resource to the destination resource.
	In order to use binding methods, this specification defines a special
	CoRE link attribute "bind". This is the identifier of a binding
	method which defines the rules to synchronize the destination
	resource. This attribute is mandatory.
	+----------------+-----------+------------+
	| Attribute | Parameter | Value |
	+----------------+-----------+------------+
	| Binding method | bind | xsd:string |
	+----------------+-----------+------------+
	Table 1: The bind attribute
	The following table gives a summary of the binding methods defined in
	this specification.
	+---------+------------+-------------+---------------+
	| Name | Identifier | Location | Method |
	+---------+------------+-------------+---------------+
	| Polling | poll | Destination | GET |
	| | | | |
	| Observe | obs | Destination | GET + Observe |
	| | | | |
	| Push | push | Source | PUT |
	+---------+------------+-------------+---------------+
	Table 2: Binding Method Summary
	The description of a binding method must define the following
	aspects:
	Identifier: This is the value of the "bind" attribute used to
	identify the method.
	Location: This information indicates whether the binding entry is
	stored on the source or on the destination endpoint.
	REST Method: This is the REST method used in the Request/Response
	exchanges.
	Conditions: A binding method definition must state how the condition
	attributes of the abstract binding definition are actually used in
	this specialized binding.
	The binding methods are described in more detail below.
	3.1.1. Polling
	The Polling method consists of sending periodic GET requests from the
	destination endpoint to the source resource and copying the content
	to the destination resource. The binding entry for this method MUST
	be stored on the destination endpoint. The destination endpoint MUST
	ensure that the polling frequency does not exceed the limits defined
	by the pmin and pmax attributes of the binding entry. The copying
	process MAY filter out content from the GET requests using value-
	based conditions (e.g based on the Change Step, Less Than, Greater
	Than attributes).
	3.1.2. Observe
	The Observe method creates an observation relationship between the
	destination endpoint and the source resource. On each notification
	the content from the source resource is copied to the destination
	resource. The creation of the observation relationship requires the
	CoAP Observation mechanism [RFC7641] hence this method is only
	permitted when the resources are made available over CoAP. The
	binding entry for this method MUST be stored on the destination
	endpoint. The binding conditions are mapped as query string
	parameters (see Section 4).
	3.1.3. Push
	When the Push method is assigned to a binding, the source endpoint
	sends PUT requests to the destination resource when the binding
	condition attributes are satisfied for the source resource. The
	source endpoint MUST only send a notification request if the binding
	conditions are met. The binding entry for this method MUST be stored
	on the source endpoint.
	3.2. Link Relation
	Since Binding involves the creation of a link between two resources,
	Web Linking and the CoRE Link-Format are a natural way to represent
	binding information. This involves the creation of a new relation
	type, named "boundto". In a Web link with this relation type, the
	target URI contains the location of the source resource and the
	context URI points to the destination resource.
	4. Binding and Resource Observation Attributes		3.1. Attribute Definitions
	In addition to "bind", this specification further defines Web link		This specification defines Conditional Notification Attributes, which
	attributes allowing a fine-grained control of the type of state		provide for fine-grained control of notification and state
	synchronization along with the conditions that trigger an update.		synchronization when using CoRE Observe [RFC7641] or Link Bindings
			(see Section 4). Conditional Notification Attributes define the
			conditions that trigger a notification.
	When resource interfaces following this specification are made		When resource interfaces following this specification are made
	available over CoAP, the CoAP Observation mechanism [RFC7641] MAY		available over CoAP, the CoAP Observation mechanism [RFC7641] MAY
	also be used to observe any changes in a resource, and receive		also be used to observe any changes in a resource, and receive
	asynchronous notifications as a result. A resource using an		asynchronous notifications as a result. A resource marked as
	interface description defined in this specification and marked as		Observable in its link description SHOULD support these Conditional
	Observable in its link description SHOULD support these observation		Notification Attributes.
	parameters.
	In addition, the set of parameters are defined here allow a client to		The set of parameters defined here allow a client to control how
	control how often a client is interested in receiving notifications		often a client is interested in receiving notifications and how much
	and how much a resource value should change for the new		a resource value should change for the new representation to be
	representation to be interesting, as query parameters.		interesting.
	These query parameters MUST be treated as resources that are read		One or more Notification Attributes MAY be included as query
	using GET and updated using PUT, and MUST NOT be included in the		parameters in an Observe request.
	Observe request. Multiple parameters MAY be updated at the same time
	by including the values in the query string of a PUT. Before being
	updated, these parameters have no default value.
	These attributes are defined below:		These attributes are defined below:
	+--------------------+-----------+------------------+		+--------------------+-----------+------------------+
	| Attribute | Parameter | Value |		| Attribute | Parameter | Value |
	+--------------------+-----------+------------------+		+--------------------+-----------+------------------+
	| Minimum Period (s) | pmin | xsd:integer (>0) |		| Minimum Period (s) | pmin | xsd:decimal (>0) |
	| | | |		| | | |
	| Maximum Period (s) | pmax | xsd:integer (>0) |		| Maximum Period (s) | pmax | xsd:decimal (>0) |
	| | | |		| | | |
	| Change Step | st | xsd:decimal (>0) |		| Change Step | st | xsd:decimal (>0) |
	| | | |		| | | |
	| Greater Than | gt | xsd:decimal |		| Greater Than | gt | xsd:decimal |
	| | | |		| | | |
	| Less Than | lt | xsd:decimal |		| Less Than | lt | xsd:decimal |
	| | | |		| | | |
	| Notification Band | band | xsd:boolean |		| Notification Band | band | xsd:boolean |
	+--------------------+-----------+------------------+		+--------------------+-----------+------------------+
	Table 3: Binding Attributes Summary		Table 1: Conditional Notification Attributes
	4.1. Minimum Period (pmin)		Conditional Notification Attributes SHOULD be evaluated on all
			potential notifications from a resource, whether resulting from an
			internal server-driven sampling process or from external update
			requests to the server.
	When present, the minimum period indicates the minimum time to wait		Note: In this draft, we assume that there are finite quantization
	(in seconds) before triggering a new state synchronization (even if		effects in the internal or external updates to the value of a
	it has changed). In the absence of this parameter, the minimum		resource; specifically, that a resource may be updated at any time
	period is up to the synchronization initiator. The minimum period		with any valid value. We therefore avoid any continuous-time
	MUST be greater than zero otherwise the receiver MUST return a CoAP		assumptions in the description of the Conditional Notification
	error code 4.00 "Bad Request" (or equivalent).		Attributes and instead use the phrase "sampled value" to refer to a
			member of a sequence of values that may be internally observed from
			the resource state over time.
	4.2. Maximum Period (pmax)		3.1.1. Minimum Period (pmin)
	When present, the maximum period indicates the maximum time in		When present, the minimum period indicates the minimum time, in
	seconds between two consecutive state synchronizations (regardless if		seconds, between two consecutive notifications (whether or not the
	it has changed). In the absence of this parameter, the maximum		resource value has changed). In the absence of this parameter, the
	period is up to the synchronization initiator. The maximum period		minimum period is up to the server. The minimum period MUST be
	MUST be greater than zero and MUST be greater than the minimum period		greater than zero otherwise the receiver MUST return a CoAP error
			code 4.00 "Bad Request" (or equivalent).
			A server MAY report the last sampled value that occured during the
			pmin interval, after the pmin interval expires.
			Note: Due to finite quantization effects, the time between
			notifications may be greater than pmin even when the sampled value
			changes within the pmin interval. Pmin may or may not be used to
			drive the internal sampling process.
			3.1.2. Maximum Period (pmax)
			When present, the maximum period indicates the maximum time, in
			seconds, between two consecutive notifications (whether or not the
			resource value has changed). In the absence of this parameter, the
			maximum period is up to the server. The maximum period MUST be
			greater than zero and MUST be greater than the minimum period
	parameter (if present) otherwise the receiver MUST return a CoAP		parameter (if present) otherwise the receiver MUST return a CoAP
	error code 4.00 "Bad Request" (or equivalent).		error code 4.00 "Bad Request" (or equivalent).
	4.3. Change Step (st)		3.1.3. Change Step (st)
	When present, the change step indicates how much the value of a		When present, the change step indicates how much the value of a
	resource SHOULD change before triggering a new state synchronization		resource SHOULD change before triggering a notification, compared to
	(compared to the value of the previous synchronization). Upon		the value of the previous notification. Upon reception of a query
	reception of a query including the st attribute the current value		including the st attribute, the most recently sampled value of the
	(CurrVal) of the resource is set as the initial value (STinit). Once		resource is reported, and then set as the last reported value
	the resource value differs from the STinit value (i.e. CurrVal >=		(last_rep_v). When a subsequent sample or update of the resource
	STinit + ST or CurrVal <= STint - ST) then a new state		value differs from the last reported value by an amount, positive or
	synchronization occurs. STinit is then set to the state		negative, greater than or equal to st, and the time for pmin has
	synchronization value and new state synchronizations are based on a		elapsed since the last notification, a notification is sent and the
	change step against this value. The change step MUST be greater than		last reported value is updated to the value sent in the notification.
	zero otherwise the receiver MUST return a CoAP error code 4.00 "Bad		The change step MUST be greater than zero otherwise the receiver MUST
	Request" (or equivalent).		return a CoAP error code 4.00 "Bad Request" (or equivalent).
	The Change Step parameter can only be supported on resources with an		The Change Step parameter can only be supported on resources with a
	atomic numeric value.		scalar numeric value.
	Note: Due to the state synchronization based update of STint it may		Note: Due to sampling and other constraints, e.g. pmin, the resource
	result in that resource value received in two sequential state		value received in two sequential notifications may differ by more
	synchronizations differs by more than st.		than st.
	4.4. Greater Than (gt)		3.1.4. Greater Than (gt)
	When present, Greater Than indicates the upper limit value the		When present, Greater Than indicates the upper limit value the
	resource value SHOULD cross before triggering a new state		sampled value SHOULD cross before triggering a notification. A
	synchronization. State synchronization only occurs when the resource		notification is sent whenever the sampled value crosses the specified
	value exceeds the specified upper limit value. The actual resource		upper limit value, relative to the last reported value, and the time
	value is used for the synchronization rather than the gt value. If		fpr pmin has elapsed since the last notification. The sampled value
	the value continues to rise, no new state synchronizations are		is sent in the notification. If the value continues to rise, no
	generated as a result of gt. If the value drops below the upper		notifications are generated as a result of gt. If the value drops
	limit value and then exceeds the upper limit then a new state		below the upper limit value then a notification is sent, subject
	synchronization is generated.		again to the pmin time.
	4.5. Less Than (lt)		The Greater Than parameter can only be supported on resources with a
			scalar numeric value.
			3.1.5. Less Than (lt)
	When present, Less Than indicates the lower limit value the resource		When present, Less Than indicates the lower limit value the resource
	value SHOULD cross before triggering a new state synchronization.		value SHOULD cross before triggering a notification. A notification
	State synchronization only occurs when the resource value is less		is sent when the samples value crosses the specified lower limit
	than the specified lower limit value. The actual resource value is		value, relative to the last reported value, and the time fpr pmin has
	used for the synchronization rather than the lt value. If the value		elapsed since the last notification. The sampled value is sent in
	continues to fall no new state synchronizations are generated as a		the notification. If the value continues to fall no notifications
	result of lt. If the value rises above the lower limit value and		are generated as a result of lt. If the value rises above the lower
	then drops below the lower limit then a new state synchronization is		limit value then a new notification is sent, subject to the pmin
	generated.		time..
	4.6. Notification Band (band)		The Less Than parameter can only be supported on resources with a
			scalar numeric value.
			3.1.6. Notification Band (band)
	The notification band attribute allows a bounded or unbounded (based		The notification band attribute allows a bounded or unbounded (based
	on a minimum or maximum) value range that may trigger multiple state		on a minimum or maximum) value range that may trigger multiple
	synchronizations. This enables use cases where different ranges		notifications. This enables use cases where different ranges results
	results in differing behaviour. For example: monitoring the		in differing behaviour. For example: monitoring the temperature of
	temperature of machinery. Whilst the temperature is in the normal		machinery. Whilst the temperature is in the normal operating range
	operating range only periodic observations are needed. However as		only periodic observations are needed. However as the temperature
	the temperature moves to more abnormal ranges more frequent		moves to more abnormal ranges more frequent synchronization/reporting
	synchronization/reporting may be needed.		may be needed.
	Without a notification band, a transition across a less than (lt), or		Without a notification band, a transition across a less than (lt), or
	greater than (gt) limit only generates one notification. This means		greater than (gt) limit only generates one notification. This means
	that it is not possible to describe a case where multiple		that it is not possible to describe a case where multiple
	notifications are sent so long as the limit is exceeded.		notifications are sent so long as the limit is exceeded.
	The band attribute works as a modifier to the behaviour of gt and lt.		The band attribute works as a modifier to the behaviour of gt and lt.
	Therefore, if band is present in a query, gt, lt or both, MUST be		Therefore, if band is present in a query, gt, lt or both, MUST be
	included.		included.
	When band is present with the lt attribute, it defines the lower		When band is present with the lt attribute, it defines the lower
	bound for the notification band (notification band minimum). State		bound for the notification band (notification band minimum).
	synchronization occurs when the resource value is equal to or above		Notifications occur when the resource value is equal to or above the
	the notification band minimum. If lt is not present there is no		notification band minimum. If lt is not present there is no minimum
	minimum value for the band.		value for the band.
	When band is present with the gt attribute, it defines the upper		When band is present with the gt attribute, it defines the upper
	bound for the notification band (notification band maximum). State		bound for the notification band (notification band maximum).
	synchronization occurs when the resource value is equal to or below		Notifications occur when the resource value is equal to or below the
	the notification band maximum. If gt is not present there is no		notification band maximum. If gt is not present there is no maximum
	maximum value for the band.		value for the band.
	If band is present with both the gt and lt attributes, two kinds of		If band is present with both the gt and lt attributes, notification
	signaling bands are specified.		occurs when the resource value is greater than or equal to gt or when
			the resource value is less than or equal to lt.
	If a band is specified in which the value of gt is less than that of		If a band is specified in which the value of gt is less than that of
	lt, in-band signaling occurs. State synchronization occurs whenever		lt, in-band notification occurs. That is, notification occurs
	the resource value is between the notification band minimum and		whenever the resource value is between the gt and lt values,
	maximum or is equal to the notification band minimum or maximum.		including equal to gt or lt.
	On the other hand if the band is specified in which the value of gt		If the band is specified in which the value of gt is greater than
	is greater than that of lt, out-of-band signaling occurs. State		that of lt, out-of-band notification occurs. That is, notification
	synchronization occurs whenever the resource value is outside the		occurs when the resource value not between the gt and lt values,
	notification band minimum and maximum or is equal to the notification		excluding equal to gt and lt.
	band minimum or maximum.
	4.7. Attribute Interactions		The Notification Band parameter can only be supported on resources
			with a scalar numeric value.
	Pmin, pmax, st, gt and lt may be present in the same query.		3.2. Server processing of Conditional Notification Attributes
	Parameters are not defined at multiple prioritization levels.
	Instead, the server state machine generates a notification whenever		Pmin, pmax, st, gt, lt and band may be present in the same query.
	any of the parameter conditions are met, after which it performs a		Howver, they are not defined at multiple prioritization levels. The
	reset on all the requested conditions. State synchronization also		server sends a notification whenever any of the parameter conditions
	occurs only once even if there are multiple conditions being met at		are met, upon which it updates its last notification value and time
	the same time. The reference code below illustrates how		to prepare for the next notification. Only one notification occurs
	notifications are generated.		when there are multiple conditions being met at the same time. The
			reference code below illustrates the logic to determine when a
			notification is to be sent.
	bool notifiable( Resource * r ) {		bool notifiable( Resource * r ) {
	#define BAND r->band		#define BAND r->band
	#define SCALAR_TYPE ( num_type == r->type )		#define SCALAR_TYPE ( num_type == r->type )
	#define STRING_TYPE ( str_type == r->type )		#define STRING_TYPE ( str_type == r->type )
	#define BOOLEAN_TYPE ( bool_type == r->type )		#define BOOLEAN_TYPE ( bool_type == r->type )
	#define PMIN_EX ( r->last_sample_time - r->last_rep_time >= r->pmin )		#define PMIN_EX ( r->last_sample_time - r->last_rep_time >= r->pmin )
	#define PMAX_EX ( r->last_sample_time - r->last_rep_time > r->pmax )		#define PMAX_EX ( r->last_sample_time - r->last_rep_time > r->pmax )
	#define LT_EX ( r->v < r->lt ^ r->last_rep_v < r->lt )		#define LT_EX ( r->v < r->lt ^ r->last_rep_v < r->lt )
	skipping to change at page 10, line 33 ¶		skipping to change at page 8, line 44 ¶
	( ( !BAND && ( GT_EX || LT_EX || ST_EX || PMAX_EX ) ) ||		( ( !BAND && ( GT_EX || LT_EX || ST_EX || PMAX_EX ) ) ||
	( BAND && IN_BAND && ( ST_EX || PMAX_EX) ) )		( BAND && IN_BAND && ( ST_EX || PMAX_EX) ) )
	: STRING_TYPE ?		: STRING_TYPE ?
	( VS_CHANGE || PMAX_EX )		( VS_CHANGE || PMAX_EX )
	: BOOLEAN_TYPE ?		: BOOLEAN_TYPE ?
	( VB_CHANGE || PMAX_EX )		( VB_CHANGE || PMAX_EX )
	: false )		: false )
	);		);
	}		}
	Figure 1: Code logic for attribute interactions for observe		Figure 1: Code logic for conditional notification attribute
	notification		interactions
			4. Link Bindings
			In a M2M RESTful environment, endpoints may directly exchange the
			content of their resources to operate the distributed system. For
			example, a light switch may supply on-off control information that
			may be sent directly to a light resource for on-off control.
			Beforehand, a configuration phase is necessary to determine how the
			resources of the different endpoints are related to each other. This
			can be done either automatically using discovery mechanisms or by
			means of human intervention and a so-called commissioning tool.
			In this specification such an abstract relationship between two
			resources is defined, called a Link Binding. The configuration phase
			necessitates the exchange of binding information, so a format
			recognized by all CoRE endpoints is essential. This specification
			defines a format based on the CoRE Link-Format to represent binding
			information along with the rules to define a binding method which is
			a specialized relationship between two resources.
			The purpose of such a binding is to synchronize content updates
			between a source resource and a destination resource. The
			destination resource MAY be a group resource if the authority
			component of the destination URI contains a group address (either a
			multicast address or a name that resolves to a multicast address).
			Since a binding is unidirectional, the binding entry defining a
			relationship is present only on one endpoint. The binding entry may
			be located either on the source or the destination endpoint depending
			on the binding method.
			Conditional Notification Attributes defined in Section 3 can be used
			with Link Bindings in order to customize the notification behavior
			and timing.
			4.1. The "bind" attribute and Binding Methods
			A binding method defines the rules to generate the network-transfer
			exchanges that synchronize state between source and destination
			resources. By using REST methods content is sent from the source
			resource to the destination resource.
			This specification defines a new CoRE link attribute "bind". This is
			the identifier for a binding method which defines the rules to
			synchronize the destination resource. This attribute is mandatory.
			+----------------+-----------+------------+
			| Attribute | Parameter | Value |
			+----------------+-----------+------------+
			| Binding method | bind | xsd:string |
			+----------------+-----------+------------+
			Table 2: The bind attribute
			The following table gives a summary of the binding methods defined in
			this specification.
			+---------+------------+-------------+---------------+
			| Name | Identifier | Location | Method |
			+---------+------------+-------------+---------------+
			| Polling | poll | Destination | GET |
			| | | | |
			| Observe | obs | Destination | GET + Observe |
			| | | | |
			| Push | push | Source | PUT |
			+---------+------------+-------------+---------------+
			Table 3: Binding Method Summary
			The description of a binding method defines the following aspects:
			Identifier: This is the value of the "bind" attribute used to
			identify the method.
			Location: This information indicates whether the binding entry is
			stored on the source or on the destination endpoint.
			REST Method: This is the REST method used in the Request/Response
			exchanges.
			Conditional Notification: How Conditional Notification Attributes
			are used in the binding.
			The binding methods are described in more detail below.
			4.1.1. Polling
			The Polling method consists of sending periodic GET requests from the
			destination endpoint to the source resource and copying the content
			to the destination resource. The binding entry for this method MUST
			be stored on the destination endpoint. The destination endpoint MUST
			ensure that the polling frequency does not exceed the limits defined
			by the pmin and pmax attributes of the binding entry. The copying
			process MAY filter out content from the GET requests using value-
			based conditions (e.g based on the Change Step, Less Than, Greater
			Than attributes).
			4.1.2. Observe
			The Observe method creates an observation relationship between the
			destination endpoint and the source resource. On each notification
			the content from the source resource is copied to the destination
			resource. The creation of the observation relationship requires the
			CoAP Observation mechanism [RFC7641] hence this method is only
			permitted when the resources are made available over CoAP. The
			binding entry for this method MUST be stored on the destination
			endpoint. The binding conditions are mapped as query parameters in
			the Observe request (see Section 3).
			4.1.3. Push
			When the Push method is assigned to a binding, the source endpoint
			sends PUT requests to the destination resource when the Conditional
			Notification Attributes are satisfied for the source resource. The
			source endpoint SHOULD only send a notification request if any
			included Conditional Notification Attributes are met. The binding
			entry for this method MUST be stored on the source endpoint.
			4.2. Link Relation
			Since Binding involves the creation of a link between two resources,
			Web Linking and the CoRE Link-Format used to represent binding
			information. This involves the creation of a new relation type,
			"boundto". In a Web link with this relation type, the target URI
			contains the location of the source resource and the context URI
			points to the destination resource.
	5. Binding Table		5. Binding Table
	The Binding table is a special resource that gives access to the		The Binding Table is a special resource that describes the bindings
	bindings on a endpoint. This section defines a REST interface for		on an endpoint. An endpoint offering a representation of the Binding
	Binding table resources. The Binding table resource MUST support the		Table resource SHOULD indicate its presence and enable its discovery
	Binding interface defined below. The interface supports the link-		by advertising a link at "/.well-known/core" [RFC6690]. If so, the
	format type.		Binding Table resource MUST be discoverable by using the Resource
			Type (rt) 'core.bnd'.
	The if= column defines the Interface Description (if=) attribute		The Methods column defines the REST methods supported by the Binding
	value to be used in the CoRE Link Format for a resource conforming to		Table, which are described in more detail below.
	that interface. When this value appears in the if= attribute of a
	link, the resource MUST support the corresponding REST interface
	described in this section. The resource MAY support additional
	functionality, which is out of scope for this specification.
	Although this interface description is intended to be used with the
	CoRE Link Format, it is applicable for use in any REST interface
	definition.
	The Methods column defines the REST methods supported by the		+---------------+----------+----------+----------------+
	interface, which are described in more detail below.		| Resource | rt= | Methods | Content-Format |
			+---------------+----------+----------+----------------+
			| Binding Table | core.bnd | GET, PUT | link-format |
			+---------------+----------+----------+----------------+
	+-----------+----------+-------------------+-----------------+		Table 4: Binding Table Description
	| Interface | if= | Methods | Content-Formats |
	+-----------+----------+-------------------+-----------------+
	| Binding | core.bnd | GET, POST, DELETE | link-format |
	+-----------+----------+-------------------+-----------------+
	Table 4: Binding Interface Description		The REST methods GET and PUT are used to manipulate a Binding Table.
			A GET request simply returns the current state of a Binding Table. A
			request with a PUT method and a content format of application/link-
			format is used to clear the bindings to the table or replaces its
			entire contents. All links in the payload of a PUT rquest MUST have
			a relation type "boundto".
	The Binding interface is used to manipulate a binding table. A		(Editor's Note: Usage of the PATCH method for fine-grained addition
	request with a POST method and a content format of application/link-		and removal of individual bindings is under study.)
	format simply appends new bindings to the table. All links in the
	payload MUST have a relation type "boundto". A GET request simply
	returns the current state of a binding table whereas a DELETE request
	empties the table. Individual entries may be deleted from the table
	by specifying the resource path in a DELETE request.
	The following example shows requests for adding, retrieving and		The following example shows requests for discovering, retrieving and
	deleting bindings in a binding table.		replacing bindings in a binding table.
	Req: POST /bnd/ (Content-Format: application/link-format)		Req: GET /.well-known/core?rt=core.bnd (application/link-format)
			Res: 2.05 Content (application/link-format)
			</bnd/>;rt=core.bnd;ct=40
			Req: GET /bnd/
			Res: 2.05 Content (application/link-format)
			<coap://sensor.example.com/a/switch1/>;
			rel=boundto;bind=obs;anchor=/a/fan,;bind="obs",
			<coap://sensor.example.com/a/switch2/>;
			rel=boundto;bind=obs;anchor=/a/light;bind="obs"
			Req: PUT /bnd/ (Content-Format: application/link-format)
	<coap://sensor.example.com/s/light>;		<coap://sensor.example.com/s/light>;
	rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60"		rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60"
	Res: 2.04 Changed		Res: 2.04 Changed
	Req: GET /bnd/		Req: GET /bnd/
	Res: 2.05 Content (application/link-format)		Res: 2.05 Content (application/link-format)
	<coap://sensor.example.com/s/light>;		<coap://sensor.example.com/s/light>;
	rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60"		rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60"
	Req: DELETE /bnd/a/light		Figure 2: Binding Table Example
	Res: 2.04 Changed
	Req: DELETE /bnd/
	Res: 2.04 Changed
	Figure 2: Binding Interface Example
	6. Implementation Considerations		6. Implementation Considerations
	When using multiple resource bindings (e.g. multiple Observations of		When using multiple resource bindings (e.g. multiple Observations of
	resource) with different bands, consideration should be given to the		resource) with different bands, consideration should be given to the
	resolution of the resource value when setting sequential bands. For		resolution of the resource value when setting sequential bands. For
	example: Given BandA (Abmn=10, Bbmx=20) and BandB (Bbmn=21, Bbmx=30).		example: Given BandA (Abmn=10, Bbmx=20) and BandB (Bbmn=21, Bbmx=30).
	If the resource value returns an integer then notifications for		If the resource value returns an integer then notifications for
	values between and inclusive of 10 and 30 will be triggered. Whereas		values between and inclusive of 10 and 30 will be triggered. Whereas
	if the resolution is to one decimal point (0.1) then notifications		if the resolution is to one decimal point (0.1) then notifications
	for values 20.1 to 20.9 will not be triggered.		for values 20.1 to 20.9 will not be triggered.
	The use of the notification band minimum and maximum allow for a		The use of the notification band minimum and maximum allow for a
	synchronization whenever a change in the resource value occurs.		synchronization whenever a change in the resource value occurs.
	Theoretically this could occur in-line with the server internal		Theoretically this could occur in-line with the server internal
	sample period for the determining the resource value. Implementors		sample period for the determining the resource value. Implementors
	SHOULD consider the resolution needed before updating the resource,		SHOULD consider the resolution needed before updating the resource,
	e.g. updating the resource when a temperature sensor value changes by		e.g. updating the resource when a temperature sensor value changes by
	0.001 degree versus 1 degree.		0.001 degree versus 1 degree.
	The initiation of a link binding can be delegated from a client to a		The initiation of a Link Binding can be delegated from a client to a
	link state machine implementation, which can be an embedded client or		link state machine implementation, which can be an embedded client or
	a configuration tool. Implementation considerations have to be given		a configuration tool. Implementation considerations have to be given
	to how to monitor transactions made by the configuration tool with		to how to monitor transactions made by the configuration tool with
	regards to link bindings, as well as any errors that may arise with		regards to Link Bindings, as well as any errors that may arise with
	establishing link bindings as well as with established link bindings.		establishing Link Bindings in addition to established Link Bindings.
	7. Security Considerations		7. Security Considerations
	Consideration has to be given to what kinds of security credentials		Consideration has to be given to what kinds of security credentials
	the state machine of a configuration tool or an embedded client needs		the state machine of a configuration tool or an embedded client needs
	to be configured with, and what kinds of access control lists client		to be configured with, and what kinds of access control lists client
	implementations should possess, so that transactions on creating link		implementations should possess, so that transactions on creating Link
	bindings and handling error conditions can be processed by the state		Bindings and handling error conditions can be processed by the state
	machine.		machine.
	8. IANA Considerations		8. IANA Considerations
	8.1. Interface Description		8.1. Resource Type value 'core.bnd'
	The specification registers the "binding" CoRE interface description		This specification registers a new Resource Type Link Target
	link target attribute value as per [RFC6690].		Attribute 'core.bnd' in the Resource Type (rt=) registry established
			as per [RFC6690].
	Attribute Value: core.bnd		Attribute Value: core.bnd
	Description: The binding interface is used to manipulate a binding		Description: See Section 5. This attribute value is used to discover
	table which describes the link bindings between source and		the resource representing a binding table, which describes the link
	destination resources for the purposes of synchronizing their		bindings between source and destination resources for the purposes of
	content.		synchronizing their content.
	Reference: This specification. Note to RFC editor: please insert the		Reference: This specification. Note to RFC editor: please insert the
	RFC of this specification.		RFC of this specification.
	Notes: None		Notes: None
	8.2. Link Relation Type		8.2. Link Relation Type
	This specification registers the new "boundto" link relation type as		This specification registers the new "boundto" link relation type as
	per [RFC8288].		per [RFC8288].
	skipping to change at page 13, line 47 ¶		skipping to change at page 14, line 35 ¶
	Matthieu Vial		Matthieu Vial
	Schneider-Electric		Schneider-Electric
	Grenoble		Grenoble
	France		France
	Phone: +33 (0)47657 6522		Phone: +33 (0)47657 6522
	EMail: matthieu.vial@schneider-electric.com		EMail: matthieu.vial@schneider-electric.com
	11. Changelog		11. Changelog
			draft-ietf-core-dynlink-08
			o Reorganize the draft to introduce Conditional Notification
			Attributes at the beginning
			o Made pmin and pmax type xsd:decimal to accommodate fractional
			second timing
			o updated the attribute descriptions. lt and gt notify on all
			crossings, both directions
			o updated Binding Table description, removed interface description
			but introduced core.bnd rt attribute value
	draft-ietf-core-dynlink-07		draft-ietf-core-dynlink-07
	o Added reference code to illustrate attribute interactions for		o Added reference code to illustrate attribute interactions for
	observations		observations
	draft-ietf-core-dynlink-06
	o Document restructure and refactoring into three main sections		o Document restructure and refactoring into three main sections
	o Clarifications on band usage		o Clarifications on band usage
	o Implementation considerations introduced		o Implementation considerations introduced
	o Additional text on security considerations		o Additional text on security considerations
	draft-ietf-core-dynlink-05		draft-ietf-core-dynlink-05
	skipping to change at page 19, line 26 ¶		skipping to change at page 20, line 26 ¶
	Jintao Zhu		Jintao Zhu
	Huawei		Huawei
	No.127 Jinye Road, Huawei Base, High-Tech Development District		No.127 Jinye Road, Huawei Base, High-Tech Development District
	Xi'an, Shaanxi Province		Xi'an, Shaanxi Province
	China		China
	Email: jintao.zhu@huawei.com		Email: jintao.zhu@huawei.com
	Bilhanan Silverajan (editor)		Bilhanan Silverajan (editor)
	Tampere University of Technology		Tampere University
	Korkeakoulunkatu 10		Kalevantie 4
	Tampere FI-33720		Tampere FI-33100
	Finland		Finland
	Email: bilhanan.silverajan@tut.fi		Email: bilhanan.silverajan@tuni.fi
End of changes. 59 change blocks.
	324 lines changed or deleted		372 lines changed or added
This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/