idnits 2.17.1 draft-ietf-core-dynlink-13.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 60 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 22, 2021) is 1152 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-13) exists of draft-irtf-t2trg-rest-iot-06 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group M. Koster 3 Internet-Draft SmartThings 4 Intended status: Informational B. Silverajan, Ed. 5 Expires: August 26, 2021 Tampere University 6 February 22, 2021 8 Dynamic Resource Linking for Constrained RESTful Environments 9 draft-ietf-core-dynlink-13 11 Abstract 13 This specification defines Link Bindings, which provide dynamic 14 linking of state updates between resources, either on an endpoint or 15 between endpoints, for systems using CoAP (RFC7252). This 16 specification also defines Conditional Notification and Control 17 Attributes that work with Link Bindings or with CoAP Observe 18 (RFC7641). 20 Editor note 22 The git repository for the draft is found at https://github.com/core- 23 wg/dynlink 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on August 26, 2021. 42 Copyright Notice 44 Copyright (c) 2021 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 3. Conditional Attributes . . . . . . . . . . . . . . . . . . . 4 62 3.1. Conditional Notification Attributes . . . . . . . . . . . 4 63 3.1.1. Greater Than (gt) . . . . . . . . . . . . . . . . . . 5 64 3.1.2. Less Than (lt) . . . . . . . . . . . . . . . . . . . 5 65 3.1.3. Change Step (st) . . . . . . . . . . . . . . . . . . 6 66 3.1.4. Notification Band (band) . . . . . . . . . . . . . . 6 67 3.1.5. Edge (edge) . . . . . . . . . . . . . . . . . . . . . 7 68 3.2. Conditional Control Attributes . . . . . . . . . . . . . 7 69 3.2.1. Minimum Period (pmin) . . . . . . . . . . . . . . . . 8 70 3.2.2. Maximum Period (pmax) . . . . . . . . . . . . . . . . 8 71 3.2.3. Minimum Evaluation Period (epmin) . . . . . . . . . . 9 72 3.2.4. Maximum Evaluation Period (epmax) . . . . . . . . . . 9 73 3.2.5. Confirmable Notification (con) . . . . . . . . . . . 9 74 3.3. Server processing of Conditional Attributes . . . . . . . 9 75 4. Link Bindings . . . . . . . . . . . . . . . . . . . . . . . . 10 76 4.1. The "bind" attribute and Binding Methods . . . . . . . . 11 77 4.1.1. Polling . . . . . . . . . . . . . . . . . . . . . . . 12 78 4.1.2. Observe . . . . . . . . . . . . . . . . . . . . . . . 12 79 4.1.3. Push . . . . . . . . . . . . . . . . . . . . . . . . 13 80 4.1.4. Execute . . . . . . . . . . . . . . . . . . . . . . . 13 81 4.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 13 82 5. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 14 83 6. Implementation Considerations . . . . . . . . . . . . . . . . 15 84 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 85 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 86 8.1. Resource Type value 'core.bnd' . . . . . . . . . . . . . 16 87 8.2. Link Relation Type . . . . . . . . . . . . . . . . . . . 17 88 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 17 89 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 17 90 11. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 18 91 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 92 12.1. Normative References . . . . . . . . . . . . . . . . . . 21 93 12.2. Informative References . . . . . . . . . . . . . . . . . 21 94 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 22 95 A.1. Minimum Period (pmin) example . . . . . . . . . . . . . . 22 96 A.2. Maximum Period (pmax) example . . . . . . . . . . . . . . 22 97 A.3. Greater Than (gt) example . . . . . . . . . . . . . . . . 24 98 A.4. Greater Than (gt) and Period Max (pmax) example . . . . . 24 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 101 1. Introduction 103 IETF Standards for machine to machine communication in constrained 104 environments describe a REST protocol [RFC7252] and a set of related 105 information standards that may be used to represent machine data and 106 machine metadata in REST interfaces. CoRE Link-format [RFC6690] is a 107 standard for doing Web Linking [RFC8288] in constrained environments. 109 This specification introduces the concept of a Link Binding, which 110 defines a new link relation type to create a dynamic link between 111 resources over which state updates are conveyed. Specifically, a 112 Link Binding is a unidirectional link for binding the states of 113 source and destination resources together such that updates to one 114 are sent over the link to the other. CoRE Link Format 115 representations are used to configure, inspect, and maintain Link 116 Bindings. This specification additionally defines Conditional 117 Notification and Control Attributes for use with Link Bindings and 118 with CoRE Observe [RFC7641]. 120 2. Terminology 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 124 "OPTIONAL" in this document are to be interpreted as described in 125 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 126 capitals, as shown here. 128 This specification requires readers to be familiar with all the terms 129 and concepts that are discussed in [RFC8288], [RFC6690] and 130 [RFC7641]. This specification makes use of the following additional 131 terminology: 133 Link Binding: A unidirectional logical link between a source 134 resource and a destination resource, over which state information 135 is synchronized. 137 State Synchronization: Depending on the binding method (Polling, 138 Observe, Push) different REST methods may be used to synchronize 139 the resource values between a source and a destination. The 140 process of using a REST method to achieve this is defined as 141 "State Synchronization". The endpoint triggering the state 142 synchronization is the synchronization initiator. 144 Notification Band: A resource value range that results in state 145 sychronization. The value range may be bounded by a minimum and 146 maximum value or may be unbounded having either a minimum or 147 maximum value. 149 3. Conditional Attributes 151 This specification defines conditional attributes, which provide for 152 fine-grained control of notification and state synchronization when 153 using CoRE Observe [RFC7641] or Link Bindings (see Section 4). When 154 resource interfaces following this specification are made available 155 over CoAP, the CoAP Observation mechanism [RFC7641] MAY also be used 156 to observe any changes in a resource, and receive asynchronous 157 notifications as a result. A resource marked as Observable in its 158 link description SHOULD support these conditional attributes. 160 Note: In this draft, we assume that there are finite quantization 161 effects in the internal or external updates to the value representing 162 the state of a resource; specifically, that a resource state may be 163 updated at any time with any valid value. We therefore avoid any 164 continuous-time assumptions in the description of the conditional 165 attributes and instead use the phrase "sampled value" to refer to a 166 member of a sequence of values that may be internally observed from 167 the resource state over time. 169 3.1. Conditional Notification Attributes 171 Conditional Notification Attributes define the conditions that 172 trigger a notification. Conditional Notification Attributes SHOULD 173 be evaluated on all potential notifications from a resource, whether 174 resulting from an internal server-driven sampling process or from 175 external update requests to the server. 177 The set of Conditional Notification Attributes defined here allow a 178 client to control how often a client is interested in receiving 179 notifications and how much a value should change for the new 180 representation state to be interesting. One or more Conditional 181 Notification Attributes MAY be included as query parameters in an 182 Observe request. 184 Conditional Notification Attributes are defined below: 186 +-------------------+-----------+-----------------+ 187 | Attribute | Parameter | Value | 188 +-------------------+-----------+-----------------+ 189 | Greater Than | gt | xs:decimal | 190 | | | | 191 | Less Than | lt | xs:decimal | 192 | | | | 193 | Change Step | st | xs:decimal (>0) | 194 | | | | 195 | Notification Band | band | xs:boolean | 196 | | | | 197 | Edge | edge | xs:boolean | 198 +-------------------+-----------+-----------------+ 200 Table 1: Conditional Notification Attributes 202 3.1.1. Greater Than (gt) 204 When present, Greater Than indicates the upper limit value the 205 sampled value SHOULD cross before triggering a notification. A 206 notification is sent whenever the sampled value crosses the specified 207 upper limit value, relative to the last reported value, and the time 208 fpr pmin has elapsed since the last notification. The sampled value 209 is sent in the notification. If the value continues to rise, no 210 notifications are generated as a result of gt. If the value drops 211 below the upper limit value then a notification is sent, subject 212 again to the pmin time. 214 The Greater Than parameter can only be supported on resources with a 215 scalar numeric value. 217 3.1.2. Less Than (lt) 219 When present, Less Than indicates the lower limit value the resource 220 value SHOULD cross before triggering a notification. A notification 221 is sent when the samples value crosses the specified lower limit 222 value, relative to the last reported value, and the time fpr pmin has 223 elapsed since the last notification. The sampled value is sent in 224 the notification. If the value continues to fall no notifications 225 are generated as a result of lt. If the value rises above the lower 226 limit value then a new notification is sent, subject to the pmin 227 time. 229 The Less Than parameter can only be supported on resources with a 230 scalar numeric value. 232 3.1.3. Change Step (st) 234 When present, the change step indicates how much the value 235 representing a resource state SHOULD change before triggering a 236 notification, compared to the old state. Upon reception of a query 237 including the st attribute, the current resource state representing 238 the most recently sampled value is reported, and then set as the last 239 reported value (last_rep_v). When a subsequent sampled value or 240 update of the resource state differs from the last reported state by 241 an amount, positive or negative, greater than or equal to st, and the 242 time for pmin has elapsed since the last notification, a notification 243 is sent and the last reported value is updated to the new resource 244 state sent in the notification. The change step MUST be greater than 245 zero otherwise the receiver MUST return a CoAP error code 4.00 "Bad 246 Request" (or equivalent). 248 The Change Step parameter can only be supported on resource states 249 represented with a scalar numeric value. 251 Note: Due to sampling and other constraints, e.g. pmin, the change in 252 resource states received in two sequential notifications may differ 253 by more than st. 255 3.1.4. Notification Band (band) 257 The notification band attribute allows a bounded or unbounded (based 258 on a minimum or maximum) value range that may trigger multiple 259 notifications. This enables use cases where different ranges results 260 in differing behaviour. For example, in monitoring the temperature 261 of machinery, whilst the temperature is in the normal operating 262 range, only periodic updates are needed. However as the temperature 263 moves to more abnormal ranges more frequent state updates may be sent 264 to clients. 266 Without a notification band, a transition across a less than (lt), or 267 greater than (gt) limit only generates one notification. This means 268 that it is not possible to describe a case where multiple 269 notifications are sent so long as the limit is exceeded. 271 The band attribute works as a modifier to the behaviour of gt and lt. 272 Therefore, if band is present in a query, gt, lt or both, MUST be 273 included. 275 When band is present with the lt attribute, it defines the lower 276 bound for the notification band (notification band minimum). 277 Notifications occur when the resource value is equal to or above the 278 notification band minimum. If lt is not present there is no minimum 279 value for the band. 281 When band is present with the gt attribute, it defines the upper 282 bound for the notification band (notification band maximum). 283 Notifications occur when the resource value is equal to or below the 284 notification band maximum. If gt is not present there is no maximum 285 value for the band. 287 If band is present with both the gt and lt attributes, notification 288 occurs when the resource value is greater than or equal to gt or when 289 the resource value is less than or equal to lt. 291 If a band is specified in which the value of gt is less than that of 292 lt, in-band notification occurs. That is, notification occurs 293 whenever the resource value is between the gt and lt values, 294 including equal to gt or lt. 296 If the band is specified in which the value of gt is greater than 297 that of lt, out-of-band notification occurs. That is, notification 298 occurs when the resource value not between the gt and lt values, 299 excluding equal to gt and lt. 301 The Notification Band parameter can only be supported on resources 302 with a scalar numeric value. 304 3.1.5. Edge (edge) 306 When present, the Edge attribute indicates interest for receiving 307 notifications of either the falling edge or the rising edge 308 transition of a boolean resource state. When the value of the Edge 309 attribute is 0, the server notifies the client each time a resource 310 state changes from True to False. When the value of the Edge 311 attribute is 1, the server notifies the client each time a resource 312 state changes from False to True. 314 The Edge attribute can only be supported on resources with a boolean 315 value. 317 3.2. Conditional Control Attributes 319 Conditional Control Attributes define the time intervals between 320 consecutive notifications as well as the cadence of the measurement 321 of the conditions that trigger a notification. Conditional Control 322 Attributes can be used to configure the internal server-driven 323 sampling process for performing measurements of the conditions of a 324 resource. One or more Conditional Control Attributes MAY be included 325 as query parameters in an Observe request. 327 Conditional Control Attributes are defined below: 329 +-------------------------------+-----------+-----------------+ 330 | Attribute | Parameter | Value | 331 +-------------------------------+-----------+-----------------+ 332 | Minimum Period (s) | pmin | xs:decimal (>0) | 333 | | | | 334 | Maximum Period (s) | pmax | xs:decimal (>0) | 335 | | | | 336 | Minimum Evaluation Period (s) | epmin | xs:decimal (>0) | 337 | | | | 338 | Maximum Evaluation Period (s) | epmax | xs:decimal (>0) | 339 | | | | 340 | Confirmable Notification | con | xs:boolean | 341 +-------------------------------+-----------+-----------------+ 343 Table 2: Conditional Control Attributes 345 3.2.1. Minimum Period (pmin) 347 When present, the minimum period indicates the minimum time, in 348 seconds, between two consecutive notifications (whether or not the 349 resource state has changed). In the absence of this parameter, the 350 minimum period is up to the server. The minimum period MUST be 351 greater than zero otherwise the receiver MUST return a CoAP error 352 code 4.00 "Bad Request" (or equivalent). 354 A server MAY update the resource state with the last sampled value 355 that occured during the pmin interval, after the pmin interval 356 expires. 358 Note: Due to finite quantization effects, the time between 359 notifications may be greater than pmin even when the sampled value 360 changes within the pmin interval. Pmin may or may not be used to 361 drive the internal sampling process. 363 3.2.2. Maximum Period (pmax) 365 When present, the maximum period indicates the maximum time, in 366 seconds, between two consecutive notifications (whether or not the 367 resource state has changed). In the absence of this parameter, the 368 maximum period is up to the server. The maximum period MUST be 369 greater than zero and MUST be greater than, or equal to, the minimum 370 period parameter (if present) otherwise the receiver MUST return a 371 CoAP error code 4.00 "Bad Request" (or equivalent). 373 3.2.3. Minimum Evaluation Period (epmin) 375 When present, the minimum evaluation period indicates the minimum 376 time, in seconds, the client recommends to the server to wait between 377 two consecutive measurements of the conditions of a resource since 378 the client has no interest in the server doing more frequent 379 measurements. When the minimum evaluation period expires after the 380 previous measurement, the server MAY immediately perform a new 381 measurement. In the absence of this parameter, the minimum 382 evaluation period is not defined and thus not used by the server. 383 The server MAY use pmin, if defined, as a guidance on the desired 384 measurement cadence. The minimum evaluation period MUST be greater 385 than zero otherwise the receiver MUST return a CoAP error code 4.00 386 "Bad Request" (or equivalent). 388 3.2.4. Maximum Evaluation Period (epmax) 390 When present, the maximum evaluation period indicates the maximum 391 time, in seconds, the server MAY wait between two consecutive 392 measurements of the conditions of a resource. When the maximum 393 evaluation period expires after the previous measurement, the server 394 MUST immediately perform a new measurement. In the absence of this 395 parameter, the maximum evaluation period is not defined and thus not 396 used by the server. The maximum evaluation period MUST be greater 397 than zero and MUST be greater than the minimum evaluation period 398 parameter (if present) otherwise the receiver MUST return a CoAP 399 error code 4.00 "Bad Request" (or equivalent). 401 3.2.5. Confirmable Notification (con) 403 When present with a value of 1 in a query, the con attribute 404 indicates a notification MUST be confirmable, i.e., the server MUST 405 send the notification in a confirmable CoAP message, to request an 406 acknowledgement from the client. When present with a value of 0 in a 407 query, the con attribute indicates a notification can be confirmable 408 or non-confirmable, i.e., it can be sent in a confirmable or a non- 409 confirmable CoAP message. 411 3.3. Server processing of Conditional Attributes 413 Conditional Notification Attributes and Conditional Control 414 Attributes may be present in the same query. However, they are not 415 defined at multiple prioritization levels. The server sends a 416 notification whenever any of the parameter conditions are met, upon 417 which it updates its last notification value and time to prepare for 418 the next notification. Only one notification occurs when there are 419 multiple conditions being met at the same time. The reference code 420 below illustrates the logic to determine when a notification is to be 421 sent. 423 bool notifiable( Resource * r ) { 425 #define BAND r->band 426 #define SCALAR_TYPE ( num_type == r->type ) 427 #define STRING_TYPE ( str_type == r->type ) 428 #define BOOLEAN_TYPE ( bool_type == r->type ) 429 #define PMIN_EX ( r->last_sample_time - r->last_rep_time >= r->pmin ) 430 #define PMAX_EX ( r->last_sample_time - r->last_rep_time > r->pmax ) 431 #define LT_EX ( r->v < r->lt ^ r->last_rep_v < r->lt ) 432 #define GT_EX ( r->v > r->gt ^ r->last_rep_v > r->gt ) 433 #define ST_EX ( abs( r->v - r->last_rep_v ) >= r->st ) 434 #define IN_BAND ( ( r->gt <= r->v && r->v <= r->lt ) || ( r->lt <= r->gt && r->gt <= r->v ) || ( r->v <= r->lt && r->lt <= r->gt ) ) 435 #define VB_CHANGE ( r->vb != r->last_rep_vb ) 436 #define VS_CHANGE ( r->vs != r->last_rep_vs ) 438 return ( 439 PMIN_EX && 440 ( SCALAR_TYPE ? 441 ( ( !BAND && ( GT_EX || LT_EX || ST_EX || PMAX_EX ) ) || 442 ( BAND && IN_BAND && ( ST_EX || PMAX_EX) ) ) 443 : STRING_TYPE ? 444 ( VS_CHANGE || PMAX_EX ) 445 : BOOLEAN_TYPE ? 446 ( VB_CHANGE || PMAX_EX ) 447 : false ) 448 ); 449 } 451 Figure 1: Code logic for conditional notification attribute 452 interactions 454 4. Link Bindings 456 In a M2M RESTful environment, endpoints may directly exchange the 457 content of their resources to operate the distributed system. For 458 example, a light switch may supply on-off control information that 459 may be sent directly to a light resource for on-off control. 460 Beforehand, a configuration phase is necessary to determine how the 461 resources of the different endpoints are related to each other. This 462 can be done either automatically using discovery mechanisms or by 463 means of human intervention and a so-called commissioning tool. 465 In this specification such an abstract relationship between two 466 resources is defined, called a Link Binding. The configuration phase 467 necessitates the exchange of binding information, so a format 468 recognized by all CoRE endpoints is essential. This specification 469 defines a format based on the CoRE Link-Format to represent binding 470 information along with the rules to define a binding method which is 471 a specialized relationship between two resources. 473 The purpose of such a binding is to synchronize content updates 474 between a source resource and a destination resource. The 475 destination resource MAY be a group resource if the authority 476 component of the destination URI contains a group address (either a 477 multicast address or a name that resolves to a multicast address). 478 Since a binding is unidirectional, the binding entry defining a 479 relationship is present only on one endpoint. The binding entry may 480 be located either on the source or the destination endpoint depending 481 on the binding method. 483 Conditional Notification Attributes defined in Section 3 can be used 484 with Link Bindings in order to customize the notification behavior 485 and timing. 487 4.1. The "bind" attribute and Binding Methods 489 A binding method defines the rules to generate the network-transfer 490 exchanges that synchronize state between source and destination 491 resources. By using REST methods content is sent from the source 492 resource to the destination resource. 494 This specification defines a new CoRE link attribute "bind". This is 495 the identifier for a binding method which defines the rules to 496 synchronize the destination resource. This attribute is mandatory. 498 +----------------+-----------+-----------+ 499 | Attribute | Parameter | Value | 500 +----------------+-----------+-----------+ 501 | Binding method | bind | xs:string | 502 +----------------+-----------+-----------+ 504 Table 3: The bind attribute 506 The following table gives a summary of the binding methods defined in 507 this specification. 509 +---------+------------+-------------+---------------+ 510 | Name | Identifier | Location | Method | 511 +---------+------------+-------------+---------------+ 512 | Polling | poll | Destination | GET | 513 | | | | | 514 | Observe | obs | Destination | GET + Observe | 515 | | | | | 516 | Push | push | Source | PUT | 517 | | | | | 518 | Execute | exec | Source | POST | 519 +---------+------------+-------------+---------------+ 521 Table 4: Binding Method Summary 523 The description of a binding method defines the following aspects: 525 Identifier: This is the value of the "bind" attribute used to 526 identify the method. 528 Location: This information indicates whether the binding entry is 529 stored on the source or on the destination endpoint. 531 REST Method: This is the REST method used in the Request/Response 532 exchanges. 534 Conditional Notification: How Conditional Notification Attributes 535 are used in the binding. 537 The binding methods are described in more detail below. 539 4.1.1. Polling 541 The Polling method consists of sending periodic GET requests from the 542 destination endpoint to the source resource and copying the content 543 to the destination resource. The binding entry for this method MUST 544 be stored on the destination endpoint. The destination endpoint MUST 545 ensure that the polling frequency does not exceed the limits defined 546 by the pmin and pmax attributes of the binding entry. The copying 547 process MAY filter out content from the GET requests using value- 548 based conditions (e.g based on the Change Step, Less Than, Greater 549 Than attributes). 551 4.1.2. Observe 553 The Observe method creates an observation relationship between the 554 destination endpoint and the source resource. On each notification 555 the content from the source resource is copied to the destination 556 resource. The creation of the observation relationship requires the 557 CoAP Observation mechanism [RFC7641] hence this method is only 558 permitted when the resources are made available over CoAP. The 559 binding entry for this method MUST be stored on the destination 560 endpoint. The binding conditions are mapped as query parameters in 561 the Observe request (see Section 3). 563 4.1.3. Push 565 The Push method can be used to allow a source endpoint to replace an 566 outdated resource state at the destination with a newer 567 representation. When the Push method is assigned to a binding, the 568 source endpoint sends PUT requests to the destination resource when 569 the Conditional Notification Attributes are satisfied for the source 570 resource. The source endpoint SHOULD only send a notification 571 request if any included Conditional Notification Attributes are met. 572 The binding entry for this method MUST be stored on the source 573 endpoint. 575 4.1.4. Execute 577 An alternative means for a source endpoint to deliver change-of-state 578 notifications to a destination resource is to use the Execute Method. 579 While the Push method simply updates the state of the destination 580 resource with the representation of the source resource, Execute can 581 be used when the destination endpoint wishes to receive all state 582 changes from a source. This allows, for example, the existence of a 583 resource collection consisting of all the state changes at the 584 destination endpoint. When the Execute method is assigned to a 585 binding, the source endpoint sends POST requests to the destination 586 resource when the Conditional Notification Attributes are satisfied 587 for the source resource. The source endpoint SHOULD only send a 588 notification request if any included Conditional Notification 589 Attributes are met. The binding entry for this method MUST be stored 590 on the source endpoint. 592 Note: Both the Push and the Execute methods are examples of Server 593 Push mechanisms that are being researched in the Thing-to-Thing 594 Research Group (T2TRG) [I-D.irtf-t2trg-rest-iot]. 596 4.2. Link Relation 598 Since Binding involves the creation of a link between two resources, 599 Web Linking and the CoRE Link-Format used to represent binding 600 information. This involves the creation of a new relation type, 601 "boundto". In a Web link with this relation type, the target URI 602 contains the location of the source resource and the context URI 603 points to the destination resource. 605 5. Binding Table 607 The Binding Table is a special resource that describes the bindings 608 on an endpoint. An endpoint offering a representation of the Binding 609 Table resource SHOULD indicate its presence and enable its discovery 610 by advertising a link at "/.well-known/core" [RFC6690]. If so, the 611 Binding Table resource MUST be discoverable by using the Resource 612 Type (rt) 'core.bnd'. 614 The Methods column defines the REST methods supported by the Binding 615 Table, which are described in more detail below. 617 +---------------+----------+----------+----------------+ 618 | Resource | rt= | Methods | Content-Format | 619 +---------------+----------+----------+----------------+ 620 | Binding Table | core.bnd | GET, PUT | link-format | 621 +---------------+----------+----------+----------------+ 623 Table 5: Binding Table Description 625 The REST methods GET and PUT are used to manipulate a Binding Table. 626 A GET request simply returns the current state of a Binding Table. A 627 request with a PUT method and a content format of application/link- 628 format is used to clear the bindings to the table or replaces its 629 entire contents. All links in the payload of a PUT rquest MUST have 630 a relation type "boundto". 632 The following example shows requests for discovering, retrieving and 633 replacing bindings in a binding table. 635 Req: GET /.well-known/core?rt=core.bnd (application/link-format) 636 Res: 2.05 Content (application/link-format) 637 ;rt=core.bnd;ct=40 639 Req: GET /bnd/ 640 Res: 2.05 Content (application/link-format) 641 ; 642 rel=boundto;anchor=/a/fan,;bind="obs", 643 ; 644 rel=boundto;anchor=/a/light;bind="obs" 646 Req: PUT /bnd/ (Content-Format: application/link-format) 647 ; 648 rel="boundto";anchor="/a/light";bind="obs";pmin=10;pmax=60 649 Res: 2.04 Changed 651 Req: GET /bnd/ 652 Res: 2.05 Content (application/link-format) 653 ; 654 rel="boundto";anchor="/a/light";bind="obs";pmin=10;pmax=60 656 Figure 2: Binding Table Example 658 Additional operations on the Binding Table can be specified in future 659 documents. Such operations can include, for example, the usage of 660 the iPATCH or PATCH methods [RFC8132] for fine-grained addition and 661 removal of individual bindings or binding subsets. 663 6. Implementation Considerations 665 When pmax and pmin are equal, the expected behaviour is that 666 notifications will be sent every (pmin == pmax) seconds. However, 667 these notifications can only be fulfilled by the server on a best 668 effort basis. Because pmin and pmax are designed as acceptable 669 tolerance bounds for sending state updates, a query from an 670 interested client containing equal pmin and pmax values must not be 671 seen as a hard real-time scheduling contract between the client and 672 the server. 674 When using multiple resource bindings (e.g. multiple Observations of 675 resource) with different bands, consideration should be given to the 676 resolution of the resource value when setting sequential bands. For 677 example: Given BandA (Abmn=10, Bbmx=20) and BandB (Bbmn=21, Bbmx=30). 678 If the resource value returns an integer then notifications for 679 values between and inclusive of 10 and 30 will be triggered. Whereas 680 if the resolution is to one decimal point (0.1) then notifications 681 for values 20.1 to 20.9 will not be triggered. 683 The use of the notification band minimum and maximum allow for a 684 synchronization whenever a change in the resource value occurs. 685 Theoretically this could occur in-line with the server internal 686 sample period or the configuration of epmin and epmax values for 687 determining the resource value. Implementors SHOULD consider the 688 resolution needed before updating the resource, e.g. updating the 689 resource when a temperature sensor value changes by 0.001 degree 690 versus 1 degree. 692 The initiation of a Link Binding can be delegated from a client to a 693 link state machine implementation, which can be an embedded client or 694 a configuration tool. Implementation considerations have to be given 695 to how to monitor transactions made by the configuration tool with 696 regards to Link Bindings, as well as any errors that may arise with 697 establishing Link Bindings in addition to established Link Bindings. 699 When a server has multiple observations with different measurement 700 cadences as defined by the epmin and epmax values, the server MAY 701 evaluate all observations when performing the measurement of any one 702 observation. 704 7. Security Considerations 706 Consideration has to be given to what kinds of security credentials 707 the state machine of a configuration tool or an embedded client needs 708 to be configured with, and what kinds of access control lists client 709 implementations should possess, so that transactions on creating Link 710 Bindings and handling error conditions can be processed by the state 711 machine. 713 8. IANA Considerations 715 8.1. Resource Type value 'core.bnd' 717 This specification registers a new Resource Type Link Target 718 Attribute 'core.bnd' in the Resource Type (rt=) registry established 719 as per [RFC6690]. 721 Attribute Value: core.bnd 723 Description: See Section 5. This attribute value is used to discover 724 the resource representing a binding table, which describes the link 725 bindings between source and destination resources for the purposes of 726 synchronizing their content. 728 Reference: This specification. Note to RFC editor: please insert the 729 RFC of this specification. 731 Notes: None 733 8.2. Link Relation Type 735 This specification registers the new "boundto" link relation type as 736 per [RFC8288]. 738 Relation Name: boundto 740 Description: The purpose of a boundto relation type is to indicate 741 that there is a binding between a source resource and a 742 destination resource for the purposes of synchronizing their 743 content. 745 Reference: This specification. Note to RFC editor: please insert 746 the RFC of this specification. 748 Notes: None 750 Application Data: None 752 9. Acknowledgements 754 Acknowledgement is given to colleagues from the SENSEI project who 755 were critical in the initial development of the well-known REST 756 interface concept, to members of the IPSO Alliance where further 757 requirements for interface types have been discussed, and to Szymon 758 Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have 759 provided useful discussion and input to the concepts in this 760 specification. Christian Amsuss supplied a comprehensive review of 761 draft -06. Hannes Tschofenig and Mert Ocak highlighted syntactical 762 corrections in the usage of pmax and pmin in a query. Discussions 763 with Ari Keraenen led to the addition of an extra binding method 764 supporting POST operations. Alan Soloway contributed text leading to 765 the inclusion of epmin and epmax. David Navarro proposed allowing 766 for pmax to be equal to pmin. 768 10. Contributors 769 Christian Groves 770 Australia 771 email: cngroves.std@gmail.com 773 Zach Shelby 774 ARM 775 Vuokatti 776 FINLAND 777 phone: +358 40 7796297 778 email: zach.shelby@arm.com 780 Matthieu Vial 781 Schneider-Electric 782 Grenoble 783 France 784 phone: +33 (0)47657 6522 785 eMail: matthieu.vial@schneider-electric.com 787 Jintao Zhu 788 Huawei 789 Xi'an, Shaanxi Province 790 China 791 email: jintao.zhu@huawei.com 793 11. Changelog 795 draft-ietf-core-dynlink-13 797 o Conditional Atttributes section restructured 799 o "edge" and "con" attributes added 801 o Implementation considerations, clarifications added when pmax == 802 pmin 804 o rewritten to remove talk of server reporting values to clients 806 draft-ietf-core-dynlink-12 808 o Attributes epmin and epmax included 810 o pmax now can be equal to pmin 812 draft-ietf-core-dynlink-11 814 o Updates to author list 816 draft-ietf-core-dynlink-10 817 o Binding methods now support both POST and PUT operations for 818 server push. 820 draft-ietf-core-dynlink-09 822 o Corrections in Table 1, Table 2, Figure 2. 824 o Clarifications for additional operations to binding table added in 825 section 5 827 o Additional examples in Appendix A 829 draft-ietf-core-dynlink-08 831 o Reorganize the draft to introduce Conditional Notification 832 Attributes at the beginning 834 o Made pmin and pmax type xs:decimal to accommodate fractional 835 second timing 837 o updated the attribute descriptions. lt and gt notify on all 838 crossings, both directions 840 o updated Binding Table description, removed interface description 841 but introduced core.bnd rt attribute value 843 draft-ietf-core-dynlink-07 845 o Added reference code to illustrate attribute interactions for 846 observations 848 draft-ietf-core-dynlink-06 850 o Document restructure and refactoring into three main sections 852 o Clarifications on band usage 854 o Implementation considerations introduced 856 o Additional text on security considerations 858 draft-ietf-core-dynlink-05 860 o Addition of a band modifier for gt and lt, adapted from draft- 861 groves-core-obsattr 863 o Removed statement prescribing gt MUST be greater than lt 864 o General: Reverted to using "gt" and "lt" from "gth" and "lth" for 865 this draft owing to concerns raised that the attributes are 866 already used in LwM2M with the original names "gt" and "lt". 868 o New author and editor added. 870 draft-ietf-core-dynlink-02 872 o General: Changed the name of the greater than attribute "gt" to 873 "gth" and the name of the less than attribute "lt" to "lth" due to 874 conlict with the core resource directory draft lifetime "lt" 875 attribute. 877 o Clause 6.1: Addressed the editor's note by changing the link 878 target attribute to "core.binding". 880 o Added Appendix A for examples. 882 draft-ietf-core-dynlink-01 884 o General: The term state synchronization has been introduced to 885 describe the process of synchronization between destination and 886 source resources. 888 o General: The document has been restructured the make the 889 information flow better. 891 o Clause 3.1: The descriptions of the binding attributes have been 892 updated to clarify their usage. 894 o Clause 3.1: A new clause has been added to discuss the 895 interactions between the resources. 897 o Clause 3.4: Has been simplified to refer to the descriptions in 898 3.1. As the text was largely duplicated. 900 o Clause 4.1: Added a clarification that individual resources may be 901 removed from the binding table. 903 o Clause 6: Formailised the IANA considerations. 905 draft-ietf-core-dynlink Initial Version 00: 907 o This is a copy of draft-groves-core-dynlink-00 909 draft-groves-core-dynlink Draft Initial Version 00: 911 o This initial version is based on the text regarding the dynamic 912 linking functionality in I.D.ietf-core-interfaces-05. 914 o The WADL description has been dropped in favour of a thorough 915 textual description of the REST API. 917 12. References 919 12.1. Normative References 921 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 922 Requirement Levels", BCP 14, RFC 2119, 923 DOI 10.17487/RFC2119, March 1997, 924 . 926 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 927 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 928 . 930 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 931 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 932 May 2017, . 934 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 935 DOI 10.17487/RFC8288, October 2017, 936 . 938 12.2. Informative References 940 [I-D.irtf-t2trg-rest-iot] 941 Keranen, A., Kovatsch, M., and K. Hartke, "RESTful Design 942 for Internet of Things Systems", draft-irtf-t2trg-rest- 943 iot-06 (work in progress), May 2020. 945 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 946 Application Protocol (CoAP)", RFC 7252, 947 DOI 10.17487/RFC7252, June 2014, 948 . 950 [RFC7641] Hartke, K., "Observing Resources in the Constrained 951 Application Protocol (CoAP)", RFC 7641, 952 DOI 10.17487/RFC7641, September 2015, 953 . 955 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 956 FETCH Methods for the Constrained Application Protocol 957 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 958 . 960 Appendix A. Examples 962 This appendix provides some examples of the use of binding attribute 963 / observe attributes. 965 Note: For brevity the only the method or response code is shown in 966 the header field. 968 A.1. Minimum Period (pmin) example 970 Observed CLIENT SERVER Actual 971 t State | | State 972 ____________ | | ____________ 973 1 | | 974 2 unknown | | 18.5 Cel 975 3 +----->| Header: GET 976 4 | GET | Token: 0x4a 977 5 | | Uri-Path: temperature 978 6 | | Uri-Query: pmin="10" 979 7 | | Observe: 0 (register) 980 8 | | 981 9 ____________ |<-----+ Header: 2.05 982 10 | 2.05 | Token: 0x4a 983 11 18.5 Cel | | Observe: 9 984 12 | | Payload: "18.5 Cel" 985 13 | | ____________ 986 14 | | 987 15 | | 23 Cel 988 16 | | 989 17 | | 990 18 | | 991 19 | | ____________ 992 20 ____________ |<-----+ Header: 2.05 993 21 | 2.05 | 26 Cel Token: 0x4a 994 22 26 Cel | | Observe: 20 995 23 | | Payload: "26 Cel" 996 24 | | 997 25 | | 999 Figure 3: Client registers and receives one notification of the 1000 current state and one of a new state state when pmin time expires. 1002 A.2. Maximum Period (pmax) example 1004 Observed CLIENT SERVER Actual 1005 t State | | State 1006 ____________ | | ____________ 1007 1 | | 1008 2 unknown | | 18.5 Cel 1009 3 +----->| Header: GET 1010 4 | GET | Token: 0x4a 1011 5 | | Uri-Path: temperature 1012 6 | | Uri-Query: pmax="20" 1013 7 | | Observe: 0 (register) 1014 8 | | 1015 9 ____________ |<-----+ Header: 2.05 1016 10 | 2.05 | Token: 0x4a 1017 11 18.5 Cel | | Observe: 9 1018 12 | | Payload: "18.5 Cel" 1019 13 | | 1020 14 | | 1021 15 | | ____________ 1022 16 ____________ |<-----+ Header: 2.05 1023 17 | 2.05 | 23 Cel Token: 0x4a 1024 18 23 Cel | | Observe: 16 1025 19 | | Payload: "23 Cel" 1026 20 | | 1027 21 | | 1028 22 | | 1029 23 | | 1030 24 | | 1031 25 | | 1032 26 | | 1033 27 | | 1034 28 | | 1035 29 | | 1036 30 | | 1037 31 | | 1038 32 | | 1039 33 | | 1040 34 | | 1041 35 | | 1042 36 | | ____________ 1043 37 ____________ |<-----+ Header: 2.05 1044 38 | 2.05 | 23 Cel Token: 0x4a 1045 39 23 Cel | | Observe: 37 1046 40 | | Payload: "23 Cel" 1047 41 | | 1048 42 | | 1050 Figure 4: Client registers and receives one notification of the 1051 current state, one of a new state and one of an unchanged state when 1052 pmax time expires. 1054 A.3. Greater Than (gt) example 1056 Observed CLIENT SERVER Actual 1057 t State | | State 1058 ____________ | | ____________ 1059 1 | | 1060 2 unknown | | 18.5 Cel 1061 3 +----->| Header: GET 1062 4 | GET | Token: 0x4a 1063 5 | | Uri-Path: temperature 1064 6 | | Uri-Query: gt=25 1065 7 | | Observe: 0 (register) 1066 8 | | 1067 9 ____________ |<-----+ Header: 2.05 1068 10 | 2.05 | Token: 0x4a 1069 11 18.5 Cel | | Observe: 9 1070 12 | | Payload: "18.5 Cel" 1071 13 | | 1072 14 | | 1073 15 | | ____________ 1074 16 ____________ |<-----+ Header: 2.05 1075 17 | 2.05 | 26 Cel Token: 0x4a 1076 18 26 Cel | | Observe: 16 1077 29 | | Payload: "26 Cel" 1078 20 | | 1079 21 | | 1081 Figure 5: Client registers and receives one notification of the 1082 current state and one of a new state when it passes through the 1083 greater than threshold of 25. 1085 A.4. Greater Than (gt) and Period Max (pmax) example 1087 Observed CLIENT SERVER Actual 1088 t State | | State 1089 ____________ | | ____________ 1090 1 | | 1091 2 unknown | | 18.5 Cel 1092 3 +----->| Header: GET 1093 4 | GET | Token: 0x4a 1094 5 | | Uri-Path: temperature 1095 6 | | Uri-Query: pmax=20;gt=25 1096 7 | | Observe: 0 (register) 1097 8 | | 1098 9 ____________ |<-----+ Header: 2.05 1099 10 | 2.05 | Token: 0x4a 1100 11 18.5 Cel | | Observe: 9 1101 12 | | Payload: "18.5 Cel" 1102 13 | | 1103 14 | | 1104 15 | | 1105 16 | | 1106 17 | | 1107 18 | | 1108 19 | | 1109 20 | | 1110 21 | | 1111 22 | | 1112 23 | | 1113 24 | | 1114 25 | | 1115 26 | | 1116 27 | | 1117 28 | | 1118 29 | | ____________ 1119 30 ____________ |<-----+ Header: 2.05 1120 31 | 2.05 | 23 Cel Token: 0x4a 1121 32 23 Cel | | Observe: 30 1122 33 | | Payload: "23 Cel" 1123 34 | | 1124 35 | | 1125 36 | | ____________ 1126 37 ____________ |<-----+ Header: 2.05 1127 38 | 2.05 | 26 Cel Token: 0x4a 1128 39 26 Cel | | Observe: 37 1129 40 | | Payload: "26 Cel" 1130 41 | | 1131 42 | | 1133 Figure 6: Client registers and receives one notification of the 1134 current state, one when pmax time expires and one of a new state when 1135 it passes through the greater than threshold of 25. 1137 Authors' Addresses 1139 Michael Koster 1140 SmartThings 1141 665 Clyde Avenue 1142 Mountain View 94043 1143 USA 1145 Email: michael.koster@smartthings.com 1146 Bilhanan Silverajan (editor) 1147 Tampere University 1148 Kalevantie 4 1149 Tampere FI-33100 1150 Finland 1152 Email: bilhanan.silverajan@tuni.fi