idnits 2.17.1 draft-koster-t2trg-hsml-01.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([I-D.ietf-core-senml], [RFC5988], [T2TRG], [RFC6690], [W3C-WoT], [REST]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 320: '... client MUST interpret the items in ...' RFC 2119 keyword, line 323: '... collection MUST be added to the bas...' RFC 2119 keyword, line 1263: '...esponse. The group response SHOULD be...' RFC 2119 keyword, line 1963: '...g and encryption SHOULD use the mechan...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 13, 2017) is 2600 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Outdated reference: A later version (-14) exists of draft-ietf-core-interfaces-08 == Outdated reference: A later version (-10) exists of draft-ietf-core-links-json-06 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-09 == Outdated reference: A later version (-16) exists of draft-ietf-core-senml-05 -- Obsolete informational reference (is this intentional?): RFC 1866 (Obsoleted by RFC 2854) -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Thing-to-Thing Research Group M. Koster 3 Internet-Draft SmartThings 4 Intended status: Experimental March 13, 2017 5 Expires: September 14, 2017 7 Media Types for Hypertext Sensor Markup 8 draft-koster-t2trg-hsml-01 10 Abstract 12 The scale and scope of the worldwide web has been in part driven by 13 the availability of HTML as a common serialization, data model, and 14 interaction model for structured resources on the web. By contrast, 15 the general use of appropriate hypermedia techniques for machine 16 interfaces has been limited by the lack of a common format for 17 serialization and exchange of structured machine resources and 18 sensor/actuator data which includes or embeds standardized hypermedia 19 controls. The IRTF Thing to Thing Research Group [T2TRG] has a 20 charter to investigate the use of REST design style [REST]for machine 21 interactions. The W3C Web of Things Interest Group [W3C-WoT] are 22 investigating abstract hypermedia controls and interaction models for 23 machines. Machine optimized content formats exist for web links 24 [RFC5988] [RFC6690] and for data items [I-D.ietf-core-senml]. 26 Structured data which contains both links and items is known as the 27 collection pattern. This draft describes media types for 28 representation of machine resources structured as collections. A 29 simple, reusable data model is described with a representation 30 format, using a well known set of keywords to expose hypermedia 31 controls, which inform clients how to perform state transfer 32 operations on resources. The underlying assumptions regarding 33 transfer layer processing are specified in this document. The HSML 34 media type described in this document is compatible with SenML and 35 CoRE Link-format by reusing the keyword identifiers and element 36 structures from these content formats. Representations of HSML 37 document content may be obtained in CoRE Link-Format and SenML 38 content formats. 40 Status of This Memo 42 This Internet-Draft is submitted in full conformance with the 43 provisions of BCP 78 and BCP 79. 45 Internet-Drafts are working documents of the Internet Engineering 46 Task Force (IETF). Note that other groups may also distribute 47 working documents as Internet-Drafts. The list of current Internet- 48 Drafts is at http://datatracker.ietf.org/drafts/current/. 50 Internet-Drafts are draft documents valid for a maximum of six months 51 and may be updated, replaced, or obsoleted by other documents at any 52 time. It is inappropriate to use Internet-Drafts as reference 53 material or to cite them other than as "work in progress." 55 This Internet-Draft will expire on September 14, 2017. 57 Copyright Notice 59 Copyright (c) 2017 IETF Trust and the persons identified as the 60 document authors. All rights reserved. 62 This document is subject to BCP 78 and the IETF Trust's Legal 63 Provisions Relating to IETF Documents 64 (http://trustee.ietf.org/license-info) in effect on the date of 65 publication of this document. Please review these documents 66 carefully, as they describe your rights and restrictions with respect 67 to this document. Code Components extracted from this document must 68 include Simplified BSD License text as described in Section 4.e of 69 the Trust Legal Provisions and are provided without warranty as 70 described in the Simplified BSD License. 72 Table of Contents 74 1. Scope of this document . . . . . . . . . . . . . . . . . . . 4 75 2. Overview and Use Case Requirements . . . . . . . . . . . . . 4 76 3. Data Model and Interaction Model . . . . . . . . . . . . . . 4 77 3.1. Informative Representation Examples . . . . . . . . . . . 5 78 3.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 5 79 3.3. Collections . . . . . . . . . . . . . . . . . . . . . . . 5 80 3.4. Link Embedding . . . . . . . . . . . . . . . . . . . . . 5 81 3.4.1. Batch operations on multiple items in a collection . 6 82 3.4.2. Collective operation on groups of linked resources . 6 83 4. Abstract Transfer Model . . . . . . . . . . . . . . . . . . . 6 84 5. Collections . . . . . . . . . . . . . . . . . . . . . . . . . 7 85 5.1. Base element . . . . . . . . . . . . . . . . . . . . . . 7 86 5.2. Link element . . . . . . . . . . . . . . . . . . . . . . 7 87 5.3. Item element . . . . . . . . . . . . . . . . . . . . . . 8 88 5.3.1. Items embedded in the collection . . . . . . . . . . 8 89 5.3.2. Items stored as collections . . . . . . . . . . . . . 9 90 6. Representation Formats . . . . . . . . . . . . . . . . . . . 11 91 6.1. Example Serialization Formats . . . . . . . . . . . . . . 11 92 6.1.1. Collection Formats . . . . . . . . . . . . . . . . . 12 93 6.1.2. Link Formats . . . . . . . . . . . . . . . . . . . . 13 94 6.1.3. Item Formats . . . . . . . . . . . . . . . . . . . . 13 95 7. URI and Parameter Processing . . . . . . . . . . . . . . . . 15 96 7.1. URI Path Processing . . . . . . . . . . . . . . . . . . . 15 97 7.2. URI Parameter processing . . . . . . . . . . . . . . . . 15 98 7.2.1. Resource selection . . . . . . . . . . . . . . . . . 16 99 8. Transfer Model Mapping to Collections . . . . . . . . . . . . 16 100 8.1. Target Resource is Collection, Format is Collection . . . 16 101 8.1.1. RETRIEVE . . . . . . . . . . . . . . . . . . . . . . 16 102 8.1.2. UPDATE . . . . . . . . . . . . . . . . . . . . . . . 17 103 8.1.3. CREATE . . . . . . . . . . . . . . . . . . . . . . . 18 104 8.1.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 20 105 8.2. Target Resource is Collection, Format is Link . . . . . . 21 106 8.2.1. RETRIEVE . . . . . . . . . . . . . . . . . . . . . . 21 107 8.2.2. UPDATE . . . . . . . . . . . . . . . . . . . . . . . 21 108 8.2.3. CREATE . . . . . . . . . . . . . . . . . . . . . . . 22 109 8.2.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 23 110 8.3. Target Resource is Collection, Format is Item . . . . . . 24 111 8.3.1. Link Embedding Items . . . . . . . . . . . . . . . . 24 112 8.3.2. RETRIEVE . . . . . . . . . . . . . . . . . . . . . . 24 113 8.3.3. UPDATE . . . . . . . . . . . . . . . . . . . . . . . 25 114 8.3.4. CREATE . . . . . . . . . . . . . . . . . . . . . . . 26 115 8.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 27 116 8.4. Target Resource is Item . . . . . . . . . . . . . . . . . 28 117 8.4.1. RETRIEVE . . . . . . . . . . . . . . . . . . . . . . 28 118 8.4.2. UPDATE . . . . . . . . . . . . . . . . . . . . . . . 28 119 8.4.3. CREATE . . . . . . . . . . . . . . . . . . . . . . . 29 120 8.4.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 29 121 8.5. Groups . . . . . . . . . . . . . . . . . . . . . . . . . 29 122 8.5.1. RETRIEVE . . . . . . . . . . . . . . . . . . . . . . 30 123 8.5.2. UPDATE . . . . . . . . . . . . . . . . . . . . . . . 31 124 8.5.3. CREATE . . . . . . . . . . . . . . . . . . . . . . . 32 125 8.5.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 33 126 9. Link extensions . . . . . . . . . . . . . . . . . . . . . . . 34 127 9.1. Actions . . . . . . . . . . . . . . . . . . . . . . . . . 34 128 9.2. Link Bindings and Monitors . . . . . . . . . . . . . . . 35 129 10. Reserved Identifiers . . . . . . . . . . . . . . . . . . . . 36 130 10.1. Default namespace . . . . . . . . . . . . . . . . . . . 37 131 10.2. URI Processing Parameters . . . . . . . . . . . . . . . 37 132 10.3. Link Keywords . . . . . . . . . . . . . . . . . . . . . 37 133 10.3.1. Link Relation Types . . . . . . . . . . . . . . . . 38 134 10.3.2. Link Attribute Types . . . . . . . . . . . . . . . . 38 135 10.4. Item Keywords . . . . . . . . . . . . . . . . . . . . . 38 136 10.5. Link Parameters used in Actions . . . . . . . . . . . . 39 137 10.6. Link Parameters used in Link Bindings and Monitors . . . 40 138 10.7. Conditional Observe Parameters used in Monitors . . . . 41 139 10.8. Link Attribute Values . . . . . . . . . . . . . . . . . 41 140 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 141 11.1. Media Types . . . . . . . . . . . . . . . . . . . . . . 42 142 11.2. CoRE Parameters Content Formats . . . . . . . . . . . . 43 143 11.3. Link Parameters . . . . . . . . . . . . . . . . . . . . 43 144 11.4. Link Relation Types . . . . . . . . . . . . . . . . . . 44 145 11.5. New CoRE Interface Types . . . . . . . . . . . . . . . . 44 146 11.6. Transfer Layer Methods . . . . . . . . . . . . . . . . . 44 147 12. Security Considerations . . . . . . . . . . . . . . . . . . . 44 148 12.1. Object Signing . . . . . . . . . . . . . . . . . . . . . 44 149 12.2. Signed Embedded Time Stamps . . . . . . . . . . . . . . 44 150 12.3. Signed Embedded Access Control . . . . . . . . . . . . . 45 151 12.4. Secure State Updates . . . . . . . . . . . . . . . . . . 45 152 12.5. Object Signing and Encryption . . . . . . . . . . . . . 45 153 13. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 45 154 14. Informative References . . . . . . . . . . . . . . . . . . . 47 155 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 48 157 1. Scope of this document 159 This is a broadly scoped document which specifies representation 160 formats, data models, interaction models, transfer mapping, URI 161 processing, and design pattern extensions including actions and 162 monitors. 164 The features listed above and new features may be specified and 165 extended as needed in other documents which refer to this document. 167 2. Overview and Use Case Requirements 169 Use case requirements include the following. 171 A standardized way to expose self-describing resource representations 172 using embedded hyperlinks and link annotations. 174 A standardized way of organizing and interacting with resource 175 instances using hypermedia controls such as links and forms. 177 A standardized encapsulation of resources for modeling things, 178 capabilities, groups, indices, and other common structures. 180 3. Data Model and Interaction Model 182 The HSML data model consists of collections containing links which 183 point to items. An instance of a collection is a resource and is 184 identified by a URI. 186 Links are standard web links as in [RFC5988] or [RFC6690]. Items are 187 identified by links in collections. 189 Links in a collection may point to items within the context of the 190 collection or they may point to items external to the collection, on 191 the same server or on other servers. 193 Items are data elements, either within the context the collection, or 194 outide the context of the collection. An instance of an item is a 195 resource and is identified by a URI. 197 An Item may only be in the context of one collection, but may be 198 identified by any number of links in any number of collections. 200 Items in the collection that use an HSML compatible data model, for 201 example SenML, see [I-D.ietf-core-senml], may be embedded in the 202 collection and transferred either along with the links or separately 203 from links. 205 3.1. Informative Representation Examples 207 JSON formatted examples are used in this document to illustrate 208 normative and informative concepts. Representations in other formats 209 may be derived from the JSON representations. For example, compact 210 binary mappings may be defined using available models. 212 3.2. Links 214 Links follow the specifications in [RFC5988] and [RFC6690] with 215 extensions to implement actions and monitors as described in this 216 document and any referencing extension documents. 218 HSML Links may be stored in Resource Directories for discovery using 219 CoRE Resource Directory [I-D.ietf-core-resource-directory]. 221 3.3. Collections 223 Collections contain one or more links and extended links, and may 224 contain data items referred to by the links. A representation of a 225 collection may contain both links and data items, plus any extended 226 links such as action forms. 228 3.4. Link Embedding 230 Link embedding enables the transfer of one or more items in a 231 collection using a single transfer operation. This document 232 describes two types of link embedding for items in the collection. 233 Batch link embedding allows one or more resource instances (item) to 234 each contribute part of an aggregate (collection) representation. 235 Group link embedding allows a particular operation to be repeated for 236 each member (item) of a group (collection). 238 3.4.1. Batch operations on multiple items in a collection 240 A collection of items enables operations on more than one item at a 241 time by exposing a structured a representation of multiple resources 242 in the collection. 244 Applications may select resources by using URI parameters, and 245 transfer representations of multiple named resources using the HSML 246 or SenML multi-item formats. 248 3.4.2. Collective operation on groups of linked resources 250 Resource links in the collection may specify group transfer 251 semantics, where transfer operations are routed to each resource in 252 the collection specified by a group link. Group responses are 253 aggregated using a multi-item format which identifies each item by 254 URI. 256 4. Abstract Transfer Model 258 The HSML media type assumes a transfer model capable of interacting 259 with representations using a simple CRUD model, allowing for basic 260 life cycle operations on resources and collections. 262 CREATE 263 Create an instance of a resource as specified using the payload as 264 a constructor. Optionally return a reference to the created 265 resource. Typically uses POST in CoAP [RFC7252] or HTTP, may use 266 PUBLISH in pubsub protocols. 268 RETRIEVE 269 Obtain a representation of the selected resource. Typically uses 270 GET in CoAP or HTTP, could use SUBSCRIBE with message retention in 271 pubsub. 273 UPDATE 274 Replace or partially replace the representation of the selected 275 resource. Typically uses PUT or PATCH in CoAP and HTTP, could use 276 PUBLISH in pubsub in the frequent case that CREATE and UPDATE are 277 not needed on the same resource. 279 DELETE 280 Remove the representation of the selected resource. Typically 281 uses DELETE in CoAP or HTTP. There is no natural mapping to 282 pubsub if a remove operation is not provided. 284 OBSERVE 285 Obtain a sequence of representations of the selected resource, 286 indicating state updates which occur on the resource. Typically 287 uses CoAP Observe, HTTP EventSource, MQTT SUBSCRIBE. OBSERVE is 288 the transfer equivalent of performing a RETRIEVE on the resource 289 immediately following each state change of the resource. 291 5. Collections 293 Collection representations in HSML include Base Elements, Link 294 Elements, and Item Elements. 296 5.1. Base element 298 A base elements describes the context under which to interpret values 299 embedded in subsequent items within the representation of a 300 collection. 302 The base identifier element (bi) may contain an absolute URI or an 303 absolute path reference from which to base relative references found 304 in the links. It functions as a base URI embedded in content as per 305 [RFC3986] Section 5.1.1 307 URI reference follows the definition in [RFC3986] Section 5. 309 The format of base elements are specified in [I-D.ietf-core-senml]. 310 Figure 1 is an example of a base element. 312 { 313 "bi": "/sensors/" 314 } 316 Figure 1: Example Base URI 318 Other base items from SenML are permissible, including base time (bt) 319 and base value(bv). If additional senml base values are present, the 320 client MUST interpret the items in the collection in the context of 321 the applicable base elements. For example, if there is a "bv" or 322 base value elment, all of the returned values from items in the 323 collection MUST be added to the base value as per 324 [I-D.ietf-core-senml]. 326 5.2. Link element 328 A link element is a hyperlink based on the structure and syntax of 329 [RFC6690] and [I-D.ietf-core-links-json]. An example link element is 330 shown in Figure 2. 332 { 333 "href": "temp", 334 "rt": "some.sensor.temp" 335 } 337 Figure 2: Example Link Element 339 5.3. Item element 341 An item element in a collection is a data element that is referenced 342 by a link in the collection. 344 Items in the collection are indicated by hyperlink references 345 ("href") that serve as selection variables for matching to URI 346 parameters and resource names ("n")in multi-resource 347 representataions. Reference resolution should use the rules defined 348 in [RFC3986]. 350 Items may be embedded in the collection, they may be subresources of 351 the collection, or they may be items in other collections referenced 352 by links in the collection. An example item element is shown in 353 Figure 3 355 { 356 "n": "temp", 357 "v": 27 358 } 360 Figure 3: Example Item Element 362 5.3.1. Items embedded in the collection 364 Items may be stored as simple sets of key-value pairs in the context 365 of the collection. Links about these items may be obtained from the 366 collection that contains them. 368 [ 369 { 370 "bi": "/sensors/" 371 }, 372 { 373 "href": "temp", 374 "rel": "item" 375 }, 376 { 377 "href": "humid", 378 "rel": "item" 379 }, 380 { 381 "n": "temp", 382 "v": 27 383 }, 384 { 385 "n": "humid", 386 "v": 50 387 } 388 ] 390 Figure 4: Items Embedded in a Collection 392 5.3.2. Items stored as collections 394 Alternatively, items themselves may be stored as single-item 395 collections, pointed to by links in another collection. Items stored 396 as collections may contain an item with a zero length href and name, 397 and a self link for the item as shown in the collection 398 representation of the item in Figure 5. Items stored in this way may 399 be augmented by adding additional resources and link content to the 400 collection. Items stored as collections may offer link format and 401 collection format representations. 403 base collection: 404 [ 405 { 406 "bi": "/sensors/" 407 }, 408 { 409 "href": "temp/" 410 }, 411 { 412 "href": "humid/" 413 } 414 ] 416 "temp" item: 417 [ 418 { 419 "bi": "/sensors/temp/" 420 }, 421 { 422 "href": "", //may be elided 423 "rel": ["self","item"] 424 }, 425 { 426 "n": "", //may be elided 427 "v": 27 428 } 429 ] 431 "humid" item: 432 [ 433 { 434 "bi": "/sensors/humid/" 435 }, 436 { 437 "rel": ["self","item"] 438 }, 439 { 440 "v": 50 441 } 442 ] 444 Figure 5: Items as Separate Collections 446 Items embedded in collections, and items linked and stored as 447 separate collections, will all be returned using the item 448 representation format as shown in Figure 6. A client interacting 449 with the items representation of the example collection at /sensors/ 450 would not need to understand the difference between embedded items 451 and linked items that exposed similar content. 453 [ 454 { 455 "bi": "/sensors/" 456 }, 457 { 458 "n": "temp", 459 "v": 27 460 }, 461 { 462 "n": "humid", 463 "v": 50 464 } 465 ] 467 Figure 6: Example Items Representation 469 6. Representation Formats 471 The HSML media type includes multiple content types and interface 472 types [I-D.ietf-core-interfaces] to enable the client to select 473 representations that optimize communication for the workflow. 474 Representation formats include links and items together (collection 475 formats), links alone (link formats), or items alone (item formats). 477 Link formats are useful for discovery workflow, item formats are 478 useful for interaction with resource state machines, and link+item 479 formats are useful for constructing and modifying resource instances. 481 In addition to HSML native formats, standard CoRE Link-Format 482 [RFC6690] and SenML formats [I-D.ietf-core-senml] may be exposed. 484 6.1. Example Serialization Formats 486 Figure 7 shows an example document in hsml+json format. This example 487 contains a base element, three link elements, and two item elements. 489 RETRIEVE /sensors/ accept=application/hsml+json 490 or 491 RETRIEVE /sensors/ accept=application/hsml.collection+json 492 or 493 RETRIEVE /sensors/ 494 accept=application/hsml+json?if=hsml.collection 495 Response Payload: 496 [ 497 { 498 "bi": "/sensors/" 499 }, 500 { 501 "anchor": "/sensors/", 502 "rel": ["self", "index"] 503 }, 504 { 505 "href": "temp", 506 "rt": "some.sensor.temp" 507 }, 508 { 509 "href": "humid", 510 "rt": "some.sensor.humid" 511 }, 512 { 513 "n": "temp", 514 "v": 27 515 }, 516 { 517 "n": "humid", 518 "v": 50 519 } 520 ] 522 Figure 7: Example Collection Format 524 The HSML media type defines content formats and corresponding CoRE 525 Interface Types that may select partial representations of the 526 resource for interaction. 528 6.1.1. Collection Formats 530 Collection formats as shown in Figure 7 expose all of the elements of 531 a resource, including items, links, and link extensions. 533 6.1.2. Link Formats 535 Link content formats, when used in an "accept" option or "content- 536 type" option in a transfer header, or when selected by the 537 "if=hsml.link" URI parameter, will select the link elements in the 538 collection for interaction as in Figure 8. 540 RETRIEVE /sensors/ accept=application/hsml.link+json 541 or 542 RETRIEVE /sensors/ accept=application/hsml+json?if=hsml.link 543 Response Payload: 544 [ 545 { 546 "anchor": "/sensors/", 547 "rel": ["self", "index"] 548 }, 549 { 550 "href": "temp", 551 "rt": "some.sensor.temp" 552 }, 553 { 554 "href": "humid", 555 "rt": "some.sensor.humid" 556 } 557 ] 559 Figure 8: Example Lnk Format 561 CoRE link-format content formats, for example application/link- 562 format+json, select RFC6690 compliant links, and may not include 563 representations of extended links (rel=action, rel=monitor). 565 6.1.3. Item Formats 567 Item content formats, when used in an "accept" option or "content- 568 type" option in a transfer header, or when selected by the 569 "if=hsml.item" URI parameter, will select the item elements in the 570 collection for interaction as in Figure 9. 572 RETRIEVE /sensors/ accept=application/hsml.item+json 573 or 574 RETRIEVE /sensors/ accept=application/hsml+json?if=hsml.item 575 Response Payload: 576 [ 577 { 578 "bi": "/sensors/" 579 }, 580 { 581 "n": "temp", 582 "v": 27 583 }, 584 { 585 "n": "humid", 586 "v": 50 587 } 588 ] 590 Figure 9: Example Item Format 592 URI Parameters for matching link attributes and relations may be used 593 to select items when item representations are being specified using 594 either content-format (accept) or interface parameters (if=). For 595 example: 597 RETRIEVE /sensors/?if=hsml.item&rt=some.sensor.temp 598 Response Payload: 599 [ 600 { 601 "bi": "/sensors/" 602 }, 603 { 604 "n": "temp", 605 "v": 27 606 } 607 ] 609 Figure 10: Item Selection Using Link Parameter 611 SenML content formats select data records and return SenML compliant 612 resource names. "bn" may optionally be returned when compliant 613 resource names "n" may be resolved through simple string 614 concatenation as per [I-D.ietf-core-senml]. 616 7. URI and Parameter Processing 618 The HSML media type defines URI reference processing and URI Query 619 processing but does not in general define fragment (#) references in 620 URIs. 622 If fragment references are provided in a particular transfer 623 implementation, they should be used to select single items in 624 collections in accordance with current practice. 626 7.1. URI Path Processing 628 The path part of the URI reference used to indicate HSML resources 629 may be used as a reference to a collection or to an item in a 630 collection. Collection references should contain the trailing slash 631 character "/" in accordance with [RFC3986]. Server implementations 632 should return links to collections with the trailing "/", and should 633 attempt to accept references to collections without the trailing "/" 634 if such references can be used to construct unambiguous references. 636 References to items in a collection should not contain the trailing 637 "/" character. Servers should return items in response to references 638 that do not contain the trailing "/" character, and should attempt to 639 accept references to items in collections with the trailing "/" if 640 such references can be used to construct unambiguous references. 642 URI references may be routed to collections in the order in which 643 path segments appear in the reference, from left to right reading the 644 path string, separated by "/" characters. 646 URI references may alternatively be routed as opaque strings to 647 resources. In this case, the resolution of relative references to 648 items in a collection should be possible by concatenating the 649 relative reference to the context URI of the collection. Note that 650 this may enforce certain naming conventions such as the trailing 651 slash in practice. 653 7.2. URI Parameter processing 655 URI Parameters, typically mapped as query parameters in HTTP and 656 CoAP, are used for selecting resources, selecting partial 657 representations, and otherwise modifying aspects of the expected or 658 included representation. In this way, they may be considered part of 659 the URI, since they help identify a unique representation to be 660 transferred. 662 7.2.1. Resource selection 664 URI Parameters may be used to select resources in a collection for 665 transfer. This is done using the common parameter matching rules 666 specified in [RFC6690]. 668 Resource selection is performed based on matching URI Parameters with 669 Link Parameters of all links in the collection which are exposed by 670 the indicated media type and interface type. URI Parameters listed 671 in Section 10.2 are excluded from the matching process. 673 The target resource selection depends on the content-format specified 674 in the request or the interface type specified in the URI parameters. 676 The collection content-formats or interface types select all links 677 and items in the collection, including link extensions. URI 678 parameters included in the request should be matched against link 679 parameters for selecting links and associated items. 681 The link content formats or interface types select all links in the 682 collection. URI parameters included in the request should be matched 683 against link parameters for link selection. 685 The item content formats or interface types select all items in the 686 collection. URI parameters included in the request should be matched 687 against link parameters associated with items in the collection for 688 item selection as shown in Figure 10. 690 8. Transfer Model Mapping to Collections 692 8.1. Target Resource is Collection, Format is Collection 694 When the reference of a request targets a collection resource, using 695 a collection format, the representation may contain both links and 696 items. It is implied that operations using this format will interact 697 with both links and items. The collection format is indicated by 698 using a collection content type in the accept or content-type header, 699 or by specifying a collection interface type e.g. if=hsml.collection. 701 8.1.1. RETRIEVE 703 Retrieve returns a representation of selected elements, consisting of 704 a list of elements in the collection, including base element, links, 705 and optionally representations of items, as shown in Figure 11. 706 Elements may include link extenstions, for example action links and 707 monitor links. 709 RETRIEVE /sensors/ accept=application/hsml.collection+json 710 Response Payload: 711 [ 712 { 713 "bi": "/sensors/" 714 }, 715 { 716 "anchor": "/sensors/", 717 "rel": ["self", "index"] 718 }, 719 { 720 "href": "temp", 721 "rt": "some.sensor.temp" 722 }, 723 { 724 "href": "humid", 725 "rt": "some.sensor.humid" 726 }, 727 { 728 "n": "temp", 729 "v": 27 730 }, 731 { 732 "n": "humid", 733 "v": 50 734 } 735 ] 737 Figure 11: Retrieve Collection 739 8.1.2. UPDATE 741 Update replaces all selected elements in the collection with elements 742 included in the payload. Update operations may include replace (PUT) 743 and partial update (PATCH) oprations where supported in the transfer 744 protocol. The server response should indicate that the resource was 745 Changed. 747 UPDATE /sensors/?href=temp 748 content-type=application/hsml.collection+json 749 Payload: 750 [ 751 { 752 "rt": ["some.sensor.temp", "some.other.type"] 753 } 754 ] 755 Response: Changed 757 RETRIEVE /sensors/ accept=application/hsml.collection+json 758 Response Payload: 759 [ 760 { 761 "bi": "/sensors/" 762 }, 763 { 764 "anchor": "/sensors/", 765 "rel": ["self", "index"] 766 }, 767 { 768 "href": "temp", 769 "rt": ["some.sensor.temp", "some.other.type"] 770 }, 771 { 772 "href": "humid", 773 "rt": "some.sensor.humid" 774 }, 775 { 776 "n": "temp", 777 "v": 27 778 }, 779 { 780 "n": "humid", 781 "v": 50 782 } 783 ] 785 Figure 12: Update Item in Collection 787 8.1.3. CREATE 789 Create adds elements to a collection, including links and items, 790 where the elements are specified by representations included in the 791 payload. Hints and directives about the created resource may be 792 included in the payload as link parameters, for example a value for 793 href, specifying the location of the created resource. The server is 794 expected to return the location of created resource instances to the 795 client in a header or other response parameter. For example, the 796 "Location" option in CoAP or "Location" header in HTTP should be used 797 to identify the created resource. The server response should 798 indicate that a resource was Created. 800 CREATE /sensors/ content-type=application/hsml.collection+json 801 Payload: 802 [ 803 { 804 "href": "barometer", 805 "rt": "some.sensor.mbar" 806 }, 807 { 808 "n": "barometer", 809 "v": 993 810 } 811 ] 812 Response: Created 813 Location: "barometer" 815 RETRIEVE /sensors/ accept=application/hsml.collection+json 816 Response Payload: 817 [ 818 { 819 "bi": "/sensors/" 820 }, 821 { 822 "anchor": "/sensors/", 823 "rel": ["self", "index"] 824 }, 825 { 826 "href": "barometer", 827 "rt": "some.sensor.mbar" 828 }, 829 { 830 "href": "temp", 831 "rt": ["some.sensor.temp", "some.other.type"] 832 }, 833 { 834 "href": "humid", 835 "rt": "some.sensor.humid" 836 }, 837 { 838 "n": "barometer", 839 "v": 993 840 }, 841 { 842 "n": "temp", 843 "v": 27 844 }, 845 { 846 "n": "humid", 847 "v": 50 848 } 849 ] 851 Figure 13: Create Item in Collection 853 8.1.4. DELETE 855 Delete removes selected elements from the collection. If no elements 856 are selected, delete removes the entire collection. The server 857 response should indicate that the resource was Deleted. 859 DELETE /sensors/?href=barometer 860 Response: Deleted 862 RETRIEVE /sensors/ accept=application/hsml.collection+json 863 Response Payload: 864 [ 865 { 866 "bi": "/sensors/" 867 }, 868 { 869 "anchor": "/sensors/", 870 "rel": ["self", "index"] 871 }, 872 { 873 "href": "temp", 874 "rt": ["some.sensor.temp", "some.other.type"] 875 }, 876 { 877 "href": "humid", 878 "rt": "some.sensor.humid" 879 }, 880 { 881 "n": "temp", 882 "v": 27 883 }, 884 { 885 "n": "humid", 886 "v": 50 887 } 888 ] 890 Figure 14: Delete Item in Collection 892 8.2. Target Resource is Collection, Format is Link 894 When a collection is referenced and the link format is indicated, 895 using a link content format in the header or specifying a link 896 interface type, e.g. if=hsml.link, it is expected that the request 897 will interact with the links in the collection. 899 8.2.1. RETRIEVE 901 Retrieve returns a list containing selected links, as shown in 902 Figure 15. 904 RETRIEVE /sensors/ accept=application/hsml.link+json 905 Response Payload: 906 [ 907 { 908 "anchor": "/sensors/", 909 "rel": ["self", "index"] 910 }, 911 { 912 "href": "temp", 913 "rt": ["some.sensor.temp", "some.other.type"] 914 }, 915 { 916 "href": "humid", 917 "rt": "some.sensor.humid" 918 } 919 ] 921 RETRIEVE /sensors/?rt=some.sensor.temp 922 accept=application/hsml.link+json 923 Response Payload: 924 [ 925 { 926 "href": "temp", 927 "rt": ["some.sensor.temp", "some.other.type"] 928 } 929 ] 931 Figure 15: Retrieve Links 933 8.2.2. UPDATE 935 Update modifies selected links, replacing link elements with elements 936 included in the payload. Update operations may include replace (PUT) 937 and partial update (PATCH) oprations where supported in the transfer 938 protocol. The server response should indicate that the resource was 939 Changed. 941 UPDATE /sensors/?href=temp 942 content-type=application/hsml.link+json 943 Payload: 944 [ 945 { 946 "rt": "some.sensor.temp" 947 } 948 ] 950 RETRIEVE /sensors/ accept=application/hsml.link+json 951 Response Payload: 952 [ 953 { 954 "anchor": "/sensors/", 955 "rel": ["self", "index"] 956 }, 957 { 958 "href": "temp", 959 "rt": "some.sensor.temp", 960 }, 961 { 962 "href": "humid", 963 "rt": "some.sensor.humid" 964 } 965 ] 967 Figure 16: Update Links 969 8.2.3. CREATE 971 Create adds links to the collection, where the links are included in 972 the payload. The server response should indicate that the resource 973 was Changed. 975 CREATE /sensors/ content-type=application/hsml.link+json 976 Payload: 977 [ 978 { 979 "href": "/sensor-group/" 980 } 981 ] 982 Response: Changed 984 RETRIEVE /sensors/ accept=application/hsml.link+json 985 Response Payload: 986 [ 987 { 988 "href": "/sensor-group/" 989 }, 990 { 991 "anchor": "/sensors/", 992 "rel": ["self", "index"] 993 }, 994 { 995 "href": "temp", 996 "rt": "some.sensor.temp", 997 }, 998 { 999 "href": "humid", 1000 "rt": "some.sensor.humid" 1001 } 1002 ] 1004 Figure 17: Create Links 1006 8.2.4. DELETE 1008 Delete removes selected links from the collection. The server 1009 response should indicate that the resource was Changed. If links 1010 point to items in the context of the collection, either remove the 1011 items as well as the links, or leave the collection as is and return 1012 a method error (Method Not Allowed). 1014 DELETE /sensors/?href=sensor-group 1015 Response: Changed 1017 RETRIEVE /sensors/ accept=application/hsml.link+json 1018 Response Payload: 1019 [ 1020 { 1021 "anchor": "/sensors/", 1022 "rel": ["self", "index"] 1023 }, 1024 { 1025 "href": "temp", 1026 "rt": "some.sensor.temp", 1027 }, 1028 { 1029 "href": "humid", 1030 "rt": "some.sensor.humid" 1031 } 1032 ] 1034 Figure 18: Delete Links 1036 8.3. Target Resource is Collection, Format is Item 1038 Whan a collection is referenced and the item format is indicated, 1039 either by including an item content type in the request header or 1040 using an item interface type, e.g. if=hsml.item, it is expected that 1041 the request will interact with the items in a collection. 1043 Specifying item interaction with a collection invokes the link 1044 embedding operations. 1046 8.3.1. Link Embedding Items 1048 Collective operations on items in collections are invoked by using 1049 the URI of the collections, along with URI parameters, to select one 1050 or more items in the collection. 1052 Items which are compatible with the HSML item format may be returned 1053 with multiple items embedded in a single representation. 1055 8.3.2. RETRIEVE 1057 Retrieve returns a list containing a base element and a composite 1058 representation of the selected items as shown in Figure 19. 1060 RETRIEVE /sensors/ accept=application/hsml.item+json 1061 Response Payload: 1062 [ 1063 { 1064 "bi": "/sensors/" 1065 }, 1066 { 1067 "n": "temp", 1068 "v": 27 1069 }, 1070 { 1071 "n": "humid", 1072 "v": 50 1073 } 1074 ] 1076 RETRIEVE /sensors/?href=temp 1077 accept=application/hsml.item+json 1078 Response Payload: 1079 [ 1080 { 1081 "bi": "/sensors/" 1082 }, 1083 { 1084 "n": "temp", 1085 "v": 27 1086 } 1087 ] 1089 Figure 19: Retrieve Items 1091 8.3.3. UPDATE 1093 Update modifies selected items, replacing items in the collection 1094 with items included in the payload which match by name "n" value. 1095 Update operations may include replace (PUT) and partial update 1096 (PATCH) oprations where supported in the transfer protocol. The 1097 server response should indicate that the resource was Changed. 1099 UPDATE /sensors/ content-type=application/hsml.item+json 1100 Payload: 1101 [ 1102 { 1103 "n": "temp", 1104 "v": 30 1105 } 1106 ] 1107 Response: Changed 1109 RETRIEVE /sensors/ accept=application/hsml.item+json 1110 Response Payload: 1111 [ 1112 { 1113 "bi": "/sensors/" 1114 }, 1115 { 1116 "n": "temp", 1117 "v": 30 1118 }, 1119 { 1120 "n": "humid", 1121 "v": 50 1122 } 1123 ] 1125 Figure 20: Update Items 1127 8.3.4. CREATE 1129 Create adds new items to the collection along with system-constructed 1130 links. Link content is determined by the resource type or traits 1131 defined by application semantics. Server is expected to return the 1132 location of created resource instances to the client in a header or 1133 other response parameter. For example, the "Location" option in CoAP 1134 or "Location" header in HTTP should be used to identify the created 1135 resource. THe server response should indicate that a resource was 1136 Created. 1138 CREATE /sensors/ content-type=application/hsml.item+json 1139 Payload: 1140 [ 1141 { 1142 "n": "barometer", 1143 "v": 1002 1144 } 1145 ] 1146 Response: Created 1148 RETRIEVE /sensors/ accept=application/hsml.item+json 1149 Response Payload: 1150 [ 1151 { 1152 "bi": "/sensors/" 1153 }, 1154 { 1155 "n": "temp", 1156 "v": 30 1157 }, 1158 { 1159 "n": "barometer", 1160 "v": 1002 1161 }, 1162 { 1163 "n": "humid", 1164 "v": 50 1165 } 1166 ] 1168 Figure 21: Create Items 1170 8.3.5. DELETE 1172 Delete removes selected items and corresponding links from the 1173 collection. The server response should indicate that the resource 1174 was Deleted. If no items are selected, return a not found error. 1176 DELETE /sensors/?href=barometer 1177 Response: Deleted 1179 RETRIEVE /sensors/ accept=application/hsml.item+json 1180 Response Payload: 1181 [ 1182 { 1183 "bi": "/sensors/" 1184 }, 1185 { 1186 "n": "temp", 1187 "v": 30 1188 }, 1189 { 1190 "n": "humid", 1191 "v": 50 1192 } 1193 ] 1195 Figure 22: Delete Items 1197 8.4. Target Resource is Item 1199 When the URI of a reference points to an item in a collection, it is 1200 expected that the request will interact with a single item. 1202 8.4.1. RETRIEVE 1204 Retrieve returns a representation of the item in the content type 1205 according to the accept option of the RETRIEVE request, or using a 1206 system defined content-format if there is no accept option provided. 1208 RETRIEVE /sensors/temp accept=text/plain 1209 Response Payload: 1210 30 1212 Figure 23: Retrieve One Item 1214 8.4.2. UPDATE 1216 Update replaces the resource state with the state defined in the 1217 supplied representation according to the content-type or ct option. 1218 Update operations may include replace (PUT) and partial update 1219 (PATCH) oprations where supported in the transfer protocol. The 1220 server response should indicate that the resource was Changed. 1222 UPDATE /sensors/temp content-type=text/plain 1223 Payload: 1224 33 1226 RETRIEVE /sensors/temp accept=text/plain 1227 Response Payload: 1228 33 1230 Figure 24: Update One Item 1232 8.4.3. CREATE 1234 Not Defined, application dependent. 1236 8.4.4. DELETE 1238 Delete removes any links to the item from the collection, and removes 1239 the item. If the item is stored as a collection, delete removes the 1240 collection. The server response should indicate that the resource 1241 was Deleted. 1243 DELETE /sensors/temp 1245 RETRIEVE /sensors/temp accept=text/plain 1246 Response: Not Found 1248 Figure 25: Delete One Item 1250 8.5. Groups 1252 Group transfer operations are provided by collections that contain 1253 links with the "grp" relation value. 1255 Transfer operations which specify the collection URI as target and 1256 use the item content format are routed to the resolved URI of each 1257 link in the collection that contains the "grp" relation. 1259 URI Parameters used for resource selection and matching are sent to 1260 the target URIs of all links that contain the "grp" relation. 1262 Responses from the selected group resources are aggregated and by 1263 default returned as a single response. The group response SHOULD be 1264 returned as an outer array where such representation is available, 1265 for example a JSON array which contains elements consisting of SenML 1266 responses. 1268 Optionally, a chunked response may be specified, if provided by the 1269 transfer implementation, in which the response from each group member 1270 is returned individually within a sequence of responses. 1272 The return code should be based on successful responses from link 1273 targets. An implementation of a group collection may choose to allow 1274 some rejected responses from link targets, depending on the 1275 composition of the link targets. A group may not be required to be 1276 composed of link targets that always accept all requests; this is at 1277 the discretion of the resource designer. 1279 No mechanism is provided in this document to enable a client to 1280 inspect the separate return codes from each group link target 1281 resource. Multiple transfer headers may be supplied in some 1282 representations, or mapped to metadata in others. 1284 The following examples assume the prior example from Figure 5 indexed 1285 by a group collection as in Figure 26. 1287 RETRIEVE /sensor-group/ accept=application/hsml.collection+json 1288 Response Payload: 1289 [ 1290 { 1291 "bi": "/sensor-group/" 1292 }, 1293 { 1294 "anchor": "/sensor-group/", 1295 "rel": ["self", "index"] 1296 }, 1297 { 1298 "href": "/sensors/temp/", 1299 "rel": "grp" 1300 }, 1301 { 1302 "href": "/sensors/humid/", 1303 "rel": "grp" 1304 } 1305 ] 1307 Figure 26: Example Group Collection 1309 8.5.1. RETRIEVE 1311 Retrieve requests are routed to each link in the collection that 1312 contains the "grp" relation. The response from each link target is 1313 returned as an element in an array representation. 1315 RETRIEVE /sensor-group/ accept=application/hsml.item+json 1316 Response Payload: 1317 [ 1318 [ 1319 { 1320 "bi": "/sensors/temp/" 1321 }, 1322 { 1323 "v": 33 1324 } 1325 ], 1326 [ 1327 { 1328 "bi": "/sensors/humid/" 1329 }, 1330 { 1331 "v": 41 1332 } 1333 ] 1334 ] 1336 Figure 27: Group Retrieve 1338 8.5.2. UPDATE 1340 Update requests are routed to each link in the collection that 1341 contains the "grp" relation. The target resource of each group link 1342 processes the request, including URI parameters and content format. 1343 The result code returned should indicate that the resource is Changed 1344 if any resource state may have been updated. 1346 UPDATE /sensor-group/ content-type=application/hsml.item+json 1347 Payload: 1348 [ 1349 { 1350 "v": 0 1351 } 1352 ] 1353 Response: Changed 1355 RETRIEVE /sensor-group/ accept=application/hsml.item+json 1356 Response Payload: 1357 [ 1358 [ 1359 { 1360 "bi": "/sensors/temp/" 1361 }, 1362 { 1363 "v": 0 1364 } 1365 ], 1366 [ 1367 { 1368 "bi": "/sensors/humid/" 1369 }, 1370 { 1371 "v": 0 1372 } 1373 ] 1374 ] 1376 Figure 28: Group Update 1378 8.5.3. CREATE 1380 Create requests are routed to each link in the collection that 1381 contains the "grp" relation. In the example shown in Figure 29, an 1382 additional named resource is being created within each (collection 1383 type) item to hold a location value for that item. The result code 1384 should indicate that a resource was Created if any resource was 1385 created as a result of the create operation. 1387 CREATE /sensor-group/ content-type=application/hsml.item+json 1388 Payload: 1389 [ 1390 { 1391 "n": "location", 1392 "vs": "living room" 1393 } 1394 ] 1395 Response: Created 1397 RETRIEVE /sensor-group/ accept=application/hsml.item+json 1398 Response Payload: 1399 [ 1400 [ 1401 { 1402 "bi": "/sensors/temp/" 1403 }, 1404 { 1405 "v": 0 1406 }, 1407 { 1408 "n": "location", 1409 "vs": "living room" 1410 } 1412 ], 1413 [ 1414 { 1415 "bi": "/sensors/humid/" 1416 }, 1417 { 1418 "v": 0 1419 }, 1420 { 1421 "n": "location", 1422 "vs": "living room" 1423 } 1424 ] 1425 ] 1427 Figure 29: Group Create 1429 8.5.4. DELETE 1431 Delete requests are routed to each link in the collection that 1432 contains the "grp" relation. In the example shown in Figure 30, the 1433 URI parameter ?href=location selects the resource at the relative URI 1434 reference "location" at each group link target for delete. The 1435 result code should indicate that a resource was Deleted if any 1436 resource was deleted as a result of the delete operation. 1438 DELETE /sensor-group/?href=location 1439 Response: Deleted 1441 RETRIEVE /sensor-group/ accept=application/hsml.item+json 1443 Response Payload: 1444 [ 1445 [ 1446 { 1447 "bi": "/sensors/temp/" 1448 }, 1449 { 1450 "v": 0 1451 } 1452 ], 1453 [ 1454 { 1455 "bi": "/sensors/humid/" 1456 }, 1457 { 1458 "v": 0 1459 } 1460 ] 1461 ] 1463 Figure 30: Group Delete 1465 9. Link extensions 1467 9.1. Actions 1469 Actions are hypermedia controls, indicated by a rel=action value in a 1470 link, used to construct transfer operations that change the state of 1471 resources. The use roughly follows the use of forms in HTML 1472 [RFC1866], with semantics more consistent with links. See 1473 Section 10.5 for more information. 1475 An example Action element is shown in Figure 31. 1477 { 1478 "rel": "action", 1479 "type": "st.on", 1480 "href": "switchcommand", 1481 "method": "create", 1482 "accept": "text/plain", 1483 "schema": {"type": "string", "enum": ["on"]} 1484 } 1486 { 1487 "rel": "action", 1488 "type": "st.off", 1489 "href": "switchcommand", 1490 "method": "create", 1491 "accept": "text/plain", 1492 "schema": {"enum": ["off"]} 1493 } 1495 Figure 31: Example Action Element 1497 These Action elements inform the client that to perform a type 1498 "st.on" or "st.off" action on the context resource, perform a CREATE 1499 method on the "switchcommand" URI relative to the context URI, using 1500 the text/plain content type, with a payload as defined by the 1501 "schema" parameter. This example uses a free-form fragment of JSON- 1502 Schema language to differentiate, by action payloads, the "st.on" and 1503 "st.off" actions, which are mapped to the same URI and method. 1505 9.2. Link Bindings and Monitors 1507 Link Bindings and Monitors are hypermedia controls, indicated by a 1508 rel=boundto or rel=monitor value in a link, used to construct 1509 transfer operations that consume or expose state changes of 1510 resources. A monitor invokes a state transfer operation from the 1511 link context to a target resource. A Link Binding follows the 1512 semantics defined in [I-D.groves-core-dynlink], and invokes a state 1513 transfer in the opposite direction, that is from the link target to 1514 the link context. 1516 Monitors use the IANA registered link relation "monitor", defined in 1517 [RFC5989]. Link Bindings use the link relation type "boundto", 1518 defined in [I-D.groves-core-dynlink]. 1520 Monitors have a set of accept parameters that indicate how the 1521 context resource is being observed, a set of filter parameters that 1522 indicate the conditions for generating a state change in the monitor, 1523 and a set of target parameters that indicate how state changes are to 1524 be applied to the monitor resource. See Section 10.6 for more 1525 information. 1527 An example Monitor element is shown in Figure 32. 1529 { 1530 "rel": "monitor", 1531 "href": "tank-level-events", 1532 "content-type": "application/senml+json", 1533 "transfer-method": "create", 1534 "pmin": 600, 1535 "pmax": 3600, 1536 "nbul": 20, 1537 "nbll": 80 1538 } 1540 Figure 32: Example Monitor Element 1542 This Monitor element defines a monitor resource at the "tank-level- 1543 events" URI relative to the context URI, which OBSERVEs the context 1544 URI, and updates the "tank-level-events" resource using the CREATE 1545 method to add JSON items to the collection, according to the given 1546 conditional parameters no more frequently than once every 600 1547 seconds, at least once every 3600 seconds, when the reading is in the 1548 notification band, which has a lower limit of 80 and wraps around 1549 zero to an upper limit of 20. This has the effect of defining a low 1550 level alert notification and high level alert notification. 1552 10. Reserved Identifiers 1554 This section defines the common reserved identifiers that are 1555 expected to be processed by implementations of HSML clients and 1556 servers. There are many more relation types and link parameters 1557 defined and registered with IANA. Implementations should not 1558 restrict processing to the keywords identified in this document; they 1559 should accept all IANA registered keywords as valid identifiers. 1561 Many of the keywords listed are defined in other RFCs and IETF 1562 documents. This document does not redefine any existing keywords. 1563 Where a definition exists, the existing definition will be used. 1564 Where multiple conflicting definitions exist, this document will 1565 indicate the required definition. 1567 New definitions are summarized in Section 11. 1569 10.1. Default namespace 1571 Identifiers in representations using the HSML media types are assumed 1572 to use the default namespace defined in Section 10 of this document. 1573 An identifier that does not containan explicit namespace identifier 1574 is assumed to be in the default namespace. 1576 For example, if the identifier "method" is encountered and it doesn't 1577 resolve to an IANA registered parameter (reg-parameter in [RFC5988]) 1578 resolution should be attempted using the definition of "method" in 1579 this document. 1581 10.2. URI Processing Parameters 1583 The following URI Parameters are used to filter representations 1584 according to specific processing rules and should not be used to 1585 attempt to match link parameters. 1587 "if" Interface type, used to select a partial representation of a 1588 collection 1590 "count" Indicates the number of items to be returned from the 1591 collection 1593 "start" Indicates the array index of the item in the collection to 1594 select as the first item to be returned 1596 "page" Page number, in units of count 1598 10.3. Link Keywords 1600 The following keywords are reserved for use in an HSML serialization 1601 to indicate elements of a web link 1603 "anchor" 1604 Overrides the default resource context of the link 1606 "rel" 1607 Link relation type as defined in [RFC5988] and [RFC6690] 1609 "href" 1610 Target of a link reference. This may be a relative path reference 1611 in the collection, e.g. "currentValue" or an absolute path 1612 reference on the server, "/sensors/temp/currentValue", or an 1613 absulute URI, for example "https://example.com/sensors/temp/ 1614 currentValue" 1616 10.3.1. Link Relation Types 1618 The following keywords are reserved for use in a HSML serialization 1619 to indicate types of link relations, and are used for values of 1620 "rel". 1622 "self" 1623 Refers to the collection that contains the link 1625 "item" 1626 The link points to an item in the collection, indicating 1627 eligibility for collective interaction using link embedding as 1628 described in Section 3.4 and Section 8.3.1. 1630 "grp" 1631 The item the link points to is available for collective 1632 interaction through the collection URI according to group 1633 semantics described in Section 8.5. 1635 10.3.2. Link Attribute Types 1637 The following keywords are reserved for use in a HSML serialization 1638 to indicate types of link attributes 1640 "rt" 1641 The resource type(s) of the item 1643 "u" 1644 Units of measure 1646 "ct" 1647 The CoAP content-format number(s) associated with the item 1649 "content-type" 1650 The media type string(s) associated with the item 1652 "obs" 1653 Presence of this attribute indicates that the associated resource 1654 is observable 1656 10.4. Item Keywords 1658 The following keywords are reserved for use in a HSML serialization 1659 to indicate elements within the serialization. Some of these are 1660 defined in [I-D.ietf-core-senml]. 1662 "bi" 1663 The base URI of the collection, relative to the service location 1664 e.g. "/sensors/temp/" Thi sis a new definition for HSML 1666 "bt" 1667 The base time that corresponds to the encapsulated state of the 1668 collection 1670 "t" 1671 The time stamp that corresponds to the encapsulated state of the 1672 item in the collection, relative to the base time "bt" 1674 "n" 1675 The name or URI of the resource, relative to the base name or base 1676 URI 1678 "u" 1679 Units of measure 1681 "v" 1682 Number value 1684 "vb" 1685 Boolean value 1687 "vs" 1688 String value 1690 10.5. Link Parameters used in Actions 1692 "anchor" 1693 May override the default context of an action 1695 "rel" 1696 Indicates that this control is an action when rel contains the 1697 value "action" 1699 "href" 1700 URI for mapping or invoking the action specified in the action 1701 control. 1703 "type" 1704 Additional indicator of the action being exposed, can be used with 1705 "rel" 1707 "method" 1708 Transfer method to use on a particular action 1710 "accept" 1711 The Content-Types or CoAP content-formats that are accepted on 1712 create and update methods 1714 "content-type" 1715 The media type string(s) that are exposed by retrieve and observe 1716 methods 1718 "ct" 1719 The CoAP content-format number(s) exposed 1721 "schema" 1722 Indicates the schema to use for constructing or interpreting 1723 transfer payloads, may be a literal value or a URI pointing to an 1724 instance of a schema 1726 10.6. Link Parameters used in Link Bindings and Monitors 1728 "anchor" 1729 May override the context URI of a link binding or monitor with any 1730 observable resource 1732 "rel" 1733 Indicates that this control is a monitor when rel contains the 1734 value "monitor" or a link binding when rel contains the value 1735 "boundto" 1737 "href" 1738 The URI of the resource used to monitor context URI, where 1739 transfer operations will be sent. 1741 "accept" 1742 The media type string or CoAP content-format to request from the 1743 observed resource 1745 "content-type" 1746 The media type string to use in the transfer operation 1748 "ct" 1749 the CoAP content-format number to use in the transfer operation 1751 "accept-method" 1752 (HSML extension) Transfer method to use in request from the 1753 observed resource, default is OBSERVE 1755 "transfer-method" 1756 (HSML extension) Transfer method to use for notifications, default 1757 is UPDATE 1759 "accept-schema" 1760 (HSML extension) Schema to use in interpreting the observed 1761 resource payload, required if transfer-schema is used. 1763 "transfer-schema" 1764 (HSML extension) Schema to use in constructing the notification 1765 transfer payload, default is to transfer the accepted payload 1766 unmodified to the target resource. 1768 10.7. Conditional Observe Parameters used in Monitors 1770 "pmin" 1771 Minimum time between notifications from a monitor 1773 "pmax" 1774 Maximum time between notifications from a monitor 1776 "gth" 1777 Value to match or exceed to determine notification condition 1779 "lth" 1780 Value to match or be less than to determine notification condition 1782 "st" 1783 Value change +/- from last report to determine notification 1784 condition 1786 "eq" 1787 Value to match, or change from, to determine notification 1788 condition 1790 "bmn" 1791 Defines a lower limit, at or above which notification is enabled 1793 "bmx" 1794 Defines an upper limit, at or below which notification is enabled 1796 "iv" 1797 Starts the notification state machine with an initial value 1799 10.8. Link Attribute Values 1801 The following keywords are reserved for use in a HSML serialization 1802 to indicate values of link attributes 1804 "create" 1805 Transfer layer CREATE operation, value of "method" or "target- 1806 method" 1808 "retrieve" 1809 Transfer layer RETRIEVE operation, value of "method" or "accept- 1810 method" 1812 "update" 1813 Transfer layer UPDATE operation, value of "method" or "target- 1814 method" 1816 "delete" 1817 Transfer layer DELETE operation, value of "method" or "target- 1818 method" 1820 "observe" 1821 Transfer layer OBSERVE operation, value of "method" or "accept- 1822 method" 1824 11. IANA Considerations 1826 11.1. Media Types 1828 Type 1830 o application 1832 Subtypes 1834 o hsml 1836 o hsml.collection 1838 o hsml.link 1840 o hsml.item 1842 Media type strings 1844 o application/hsml 1846 o application/hsml.collection 1848 o application/hsml.link 1850 o application/hsml.item 1852 o application/hsml+json 1854 o application/hsml.collection+json 1855 o application/hsml.link+json 1857 o application/hsml.item+json 1859 11.2. CoRE Parameters Content Formats 1861 (subject to Structured Syntax encoding rules TBD) 1863 o 22000 - application/hsml+json 1865 o 22001 - application/hsml.link+json 1867 o 22002 - application/hsml.item+json 1869 11.3. Link Parameters 1871 o method 1873 o schema 1875 o content-type 1877 o ct 1879 o accept-method 1881 o transfer-method 1883 o accept-schema 1885 o transfer-schema 1887 The following should be registered in the CoRE dynamic linking draft 1888 [I-D.groves-core-dynlink]. 1890 o pmin 1892 o pmax 1894 o bmn 1896 o bmx 1898 o iv 1900 o lth 1902 o gth 1903 o st 1905 o eq 1907 11.4. Link Relation Types 1909 o grp 1911 11.5. New CoRE Interface Types 1913 o hsml.collection 1915 o hsml.item 1917 o hsml.link 1919 11.6. Transfer Layer Methods 1921 These definitions may use the default namespace and do not need to be 1922 registered with IANA 1924 o create 1926 o retrieve 1928 o update 1930 o delete 1932 o observe 1934 12. Security Considerations 1936 12.1. Object Signing 1938 Collection representations are resource state encapsulations and may 1939 be transmitted and stored as signed objects in order to protect the 1940 integrity of data and metadata, including time and embedded access 1941 control information. 1943 12.2. Signed Embedded Time Stamps 1945 The collection may include time stamps (bt and t) that are signed 1946 with the object data and metadata. 1948 12.3. Signed Embedded Access Control 1950 The collection representation may include embedded access control 1951 information, also signed with the metadata, that can instruct the 1952 server to enforce a particular access policy for transfer requests. 1954 12.4. Secure State Updates 1956 Representations submitted to a server to update the state of a 1957 resource (UPDATE, CREATE, DELETE) may also contain embedded signed 1958 assertions which may be used by the server to decide whether to apply 1959 or reject the update. 1961 12.5. Object Signing and Encryption 1963 Object signing and encryption SHOULD use the mechanisms specified in 1964 IETF documents for secure JSON Objects [RFC7516] and CBOR Objects 1965 [I-D.ietf-cose-msg] [I-D.selander-ace-object-security]. 1967 13. Terminology 1969 Client 1970 Having a client role in a REST operation, transmitting a request 1971 and receiving one or more responses. 1973 Server 1974 Having a server role in a REST operation, the origin of data items 1975 or proxy for the origin. A server is also an authority for a URI 1976 namespace [RFC3986]. 1978 Resource 1979 Server endpoint for a REST operation, identified by a URI 1980 [RFC3986] 1982 Representation 1983 An encoded form of the state of a resource. The encoding rules 1984 may be specified in a media type or content type. Clients and 1985 servers exchange representations of resources in order to effect 1986 application state changes [REST]. 1988 URI 1989 Uniform Resource Identifier, used to identify a resource in a link 1990 or as a reference [RFC3986] 1992 Reference 1993 An identifier used to select or identify a particular resource. 1994 References are constructed by clients to identify resources when 1995 interacting with servers. Servers match references in client 1996 requests against URIs of hosted resources. 1998 Media Type, also Content-Format, Content-Type 1999 A set of rules for encoding, transfer, and prosessing resource 2000 representations 2002 Hypermedia 2003 Design style which uses metadata in the form of hyperlinks to 2004 structure resources in relation to each other 2006 Collection 2007 A composite resource that contains links and optionally data items 2009 Link, also Hyperlink 2010 A metadata element as described in [RFC5988] and [RFC6690] that 2011 contains a pointer to and description of some data element. 2013 Item 2014 A data item pointed to by one or more links in one or more 2015 collections. 2017 Context 2018 The context of a link is the subject of the link or the enclosing 2019 scope. In this document the collection is the default context for 2020 links in the collection. 2022 Target 2023 The target of a link is the resource being pointed to or 2024 described. Links in a collection point to and describe items as 2025 link targets. 2027 Transfer Layer 2028 A set of predefined message types used to implement state transfer 2029 semantics, for example REST. 2031 Request 2032 A message sent from a client to a server identifying the resource, 2033 representation, and method to use for the interaction with the 2034 server. 2036 Response 2037 A message sent from a server to a client in response to a request, 2038 which communicates the state of the identified resource. 2040 Operation or Method 2041 The state transition type requested by the client for the server 2042 to perform on the identified resource. Indicated by the transfer 2043 layer method, for example, RETRIEVE, UPDATE, CREATE, DELETE. 2045 Pubsub 2046 A transfer layer semantic interface based on the publish-subscribe 2047 paradigm, allowing for asynchronous messages to be routed on 2048 demand. 2050 14. Informative References 2052 [I-D.groves-core-dynlink] 2053 Shelby, Z., Vial, M., Koster, M., and C. Groves, "Dynamic 2054 Resource Linking for Constrained RESTful Environments", 2055 draft-groves-core-dynlink-00 (work in progress), July 2056 2016. 2058 [I-D.ietf-core-interfaces] 2059 Shelby, Z., Vial, M., Koster, M., and C. Groves, "Reusable 2060 Interface Definitions for Constrained RESTful 2061 Environments", draft-ietf-core-interfaces-08 (work in 2062 progress), February 2017. 2064 [I-D.ietf-core-links-json] 2065 Li, K., Rahman, A., and C. Bormann, "Representing CoRE 2066 Formats in JSON and CBOR", draft-ietf-core-links-json-06 2067 (work in progress), July 2016. 2069 [I-D.ietf-core-resource-directory] 2070 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 2071 Resource Directory", draft-ietf-core-resource-directory-09 2072 (work in progress), October 2016. 2074 [I-D.ietf-core-senml] 2075 Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. 2076 Bormann, "Media Types for Sensor Measurement Lists 2077 (SenML)", draft-ietf-core-senml-05 (work in progress), 2078 March 2017. 2080 [I-D.ietf-cose-msg] 2081 Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2082 draft-ietf-cose-msg-24 (work in progress), November 2016. 2084 [I-D.selander-ace-object-security] 2085 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 2086 "Object Security of CoAP (OSCOAP)", draft-selander-ace- 2087 object-security-06 (work in progress), October 2016. 2089 [REST] Fielding, R., "Architectural Styles and the Design of 2090 Network-based Software Architectures", Ph.D. Dissertation, 2091 University of California, Irvine, 2000, 2092 . 2095 [RFC1866] Berners-Lee, T. and D. Connolly, "Hypertext Markup 2096 Language - 2.0", RFC 1866, DOI 10.17487/RFC1866, November 2097 1995, . 2099 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2100 Resource Identifier (URI): Generic Syntax", STD 66, 2101 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2102 . 2104 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 2105 DOI 10.17487/RFC5988, October 2010, 2106 . 2108 [RFC5989] Roach, A., "A SIP Event Package for Subscribing to Changes 2109 to an HTTP Resource", RFC 5989, DOI 10.17487/RFC5989, 2110 October 2010, . 2112 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2113 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2114 . 2116 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2117 Application Protocol (CoAP)", RFC 7252, 2118 DOI 10.17487/RFC7252, June 2014, 2119 . 2121 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 2122 RFC 7516, DOI 10.17487/RFC7516, May 2015, 2123 . 2125 [T2TRG] IRTF, ., "IRTF Thing to Thing Research Group", 2016, 2126 . 2128 [W3C-WoT] WoT IG, ., "W3C Web of Things Interest Group", 2016, 2129 . 2131 Author's Address 2132 Michael Koster 2133 SmartThings 2134 1281 Lawrence Station Road 2135 Sunnyvale 94089 2136 USA 2138 Phone: +1-707-502-5136 2139 Email: michael.koster@smartthings.com