idnits 2.17.1 draft-ietf-core-link-format-05.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: When using a transfer protocol like the Constrained Application Protocol (CoAP) that supports multicast requests, special care is taken. A multicast request with a query string MUST not be responded to if filtering is not supported (to avoid a needless response storm). -- The document date (May 22, 2011) is 4695 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-06 ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 5785 (Obsoleted by RFC 8615) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Z. Shelby 3 Internet-Draft Sensinode 4 Intended status: Standards Track May 22, 2011 5 Expires: November 23, 2011 7 CoRE Link Format 8 draft-ietf-core-link-format-05 10 Abstract 12 This document defines Web Linking using a link format for use by 13 constrained web servers to describe hosted resources, their 14 attributes and other relationships between links. Based on the HTTP 15 Link Header format defined in RFC5988, the CoRE Link Format is 16 carried as a payload and is assigned an Internet media type. A well- 17 known URI is defined as a default entry-point for requesting the 18 links hosted by a server. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on November 23, 2011. 37 Copyright Notice 39 Copyright (c) 2011 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Web Linking in CoRE . . . . . . . . . . . . . . . . . . . 3 56 1.2. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.2.1. Discovery . . . . . . . . . . . . . . . . . . . . . . 4 58 1.2.2. Resource Collections . . . . . . . . . . . . . . . . . 5 59 1.2.3. Resource Directory . . . . . . . . . . . . . . . . . . 5 60 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 61 2. Link Format . . . . . . . . . . . . . . . . . . . . . . . . . 6 62 2.1. Target and context URIs . . . . . . . . . . . . . . . . . 7 63 2.2. Link relations . . . . . . . . . . . . . . . . . . . . . . 7 64 2.3. Use of anchors . . . . . . . . . . . . . . . . . . . . . . 8 65 3. CoRE link extensions . . . . . . . . . . . . . . . . . . . . . 8 66 3.1. Resource type 'rt' attribute . . . . . . . . . . . . . . . 8 67 3.2. Interface description 'if' attribute . . . . . . . . . . . 9 68 3.3. Content-type code 'ct' attribute . . . . . . . . . . . . . 9 69 3.4. Maximum size estimate 'sz' attribute . . . . . . . . . . . 9 70 4. Well-known Interface . . . . . . . . . . . . . . . . . . . . . 10 71 4.1. Query Filtering . . . . . . . . . . . . . . . . . . . . . 11 72 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 73 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 74 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 75 7.1. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 14 76 7.2. New 'hosts' relation type . . . . . . . . . . . . . . . . 14 77 7.3. New link-format Internet media type . . . . . . . . . . . 14 78 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 79 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 16 80 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 81 10.1. Normative References . . . . . . . . . . . . . . . . . . . 18 82 10.2. Informative References . . . . . . . . . . . . . . . . . . 18 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 19 85 1. Introduction 87 The Constrained RESTful Environments (CoRE) working group aims at 88 realizing the Representational State Transfer (REST) architecture 89 [REST] in a suitable form for the most constrained nodes (e.g. 8-bit 90 microcontrollers with limited memoryt) and networks (e.g. 6LoWPAN 91 [RFC4944]). CoRE is aimed at Machine-to-Machine (M2M) applications 92 such as smart energy and building automation. 94 The discovery of resources hosted by a constrained server is very 95 important in machine-to-machine applications where there are no 96 humans in the loop and static interfaces result in fragility. The 97 discovery of resources provided by an HTTP [RFC2616] Web Server is 98 typically called Web Discovery and the description of relations 99 between resources is called Web Linking [RFC5988]. In this document 100 we refer to the discovery of resources hosted by a constrained web 101 server, their attributes and other resource relations as CoRE 102 Resource Discovery. 104 The main function of such a discovery mechanism is to provide 105 Universal Resource Identifiers (URIs, called links) for the resources 106 hosted by the server, complemented by attributes about those 107 resources and possible further link relations. In CoRE this 108 collection of links is carried as a resource of its own (as opposed 109 to HTTP headers delivered with a specific resource). This document 110 specifies a link format for use in CoRE Resource Discovery by 111 extending the HTTP Link Header Format [RFC5988] to describe these 112 link descriptions. The CoRE Link Format is carried as a payload and 113 is assigned an Internet media type. A well-known URI "/.well-known/ 114 core" is defined as a default entry-point for requesting the list of 115 links about resources hosted by a server, and thus performing CoRE 116 Resource Discovery. 118 1.1. Web Linking in CoRE 120 What is the difference between the CoRE Link Format and [RFC5988]? 121 Technically the CoRE Link Format is a serialization of a typed link 122 as specified in [RFC5988], used to describe relationships between 123 resources, so-called "Web Linking". In this specification Web 124 Linking is extended with specific constrained M2M attributes, links 125 are carried as a message payload rather than in an HTTP Link Header, 126 and a default interface is defined to discover resources hosted by a 127 server. This specification also defines a new relation type "hosts", 128 which indicates that the resource is hosted by the server from which 129 the link document was requested. 131 Why not just use the HTTP Link Header? In HTTP, the Link Header can 132 be used to carry link information about a resource along with an HTTP 133 response. This works well for the typical use case for a web server 134 and browser, where further information about a particular resource is 135 useful after accessing it. In CoRE the main use case for Web Linking 136 is the discovery of which resources a server hosts in the first 137 place. Although some resources may have further links associated 138 with them, this is expected to be an exception. For that reason the 139 CoRE Link Format serialization is carried as a resource 140 representation of a well-known URI. The CoRE Link Format does re-use 141 the format of the HTTP Link Header serialization defined in 142 [RFC5988]. 144 1.2. Use Cases 146 Typical use cases for Web Linking on today's web include e.g. 147 describing the author of a web page, or describing relations between 148 web pages (next chapter, previous chapter etc.). Web Linking can 149 also be applied to M2M applications, where typed links are used to 150 assist a machine client in finding and understanding how to use 151 resources on a server. In this section a few use cases are described 152 for how the CoRE Link Format could be used in M2M applications. For 153 further technical examples see Section 5. As there are a large range 154 of M2M applications, these use cases are purposely generic. This 155 document assumes that different deployments or application domains 156 will define the appropraite REST interface descriptions along with 157 Resource Types to make discovery meaniningful. 159 1.2.1. Discovery 161 In M2M applications, for example home or building automation, there 162 is a need for local clients and servers to find and interact with 163 each other without human intervention. The CoRE Link Format can be 164 used by servers in such environments to enable Resource Discovery of 165 the resources hosted by the server. 167 Resource Discovery can be performed either unicast or multicast. 168 When a server's IP address is already known, either a priori or 169 resolved via the Domain Name System (DNS) [RFC1034][RFC1035], unicast 170 discovery is performed in order to locate the entry point to the 171 resource of interest. This is performed using a GET to /.well-known/ 172 core on the server, which returns a payload in the CoRE Link Format. 173 A client would then match the appropriate Resource Type, Interface 174 Description and possible Content-Type [RFC2045] for its application. 175 These attributes may also be included in the query string in order to 176 filter the number of links returned in a response. 178 Multicast resource discovery is useful when a client needs to locate 179 a resource within a limited scope, and that scope supports IP 180 multicast. A GET request to the appropriate multicast address is 181 made for /.well-known/core. In order to limit the number and size or 182 responses, a query string is recommended with the known attributes. 183 Typically a resource would be discovered based on its Resource Type 184 and/or Interface Description, along with possible application 185 specific attributes. 187 1.2.2. Resource Collections 189 RESTful designs of M2M interfaces often make use of collections of 190 resources. For example an index of temprature sensors on a data 191 collection node or a list of alarms on a home security controller. 192 The CoRE Link Format can be used to make it possible to find the 193 entry point to a collection and traverse its members. The entry 194 point of a collection would always be included in /.well-known/core 195 to enable its discovery. The members of the collection can be 196 defined either through the interface description of the resource 197 along with a parameter resource for the size of the collection, or by 198 using the link format to describe each resource in the collection. 199 These links could be located under /.well-known/core or hosted for 200 example in the root resource of the collection. 202 1.2.3. Resource Directory 204 In many deployment scenarios, for example constrained networks with 205 sleeping servers, or large M2M deployments with bandwidth limited 206 access networks, it makes sense to deploy resource directory entities 207 which store links to resources stored on other servers. Think of 208 this as a limited search engine for constrained M2M resources. 210 The CoRE Link Format can be used by a server to register resources 211 with a resource directory, or to allow a resource directory to poll 212 for resources. Resource polling uses the same process as unicast or 213 multicast discovery, however usually without filtering. Resource 214 registration can be achived by having each server POST their 215 resources to /.well-known/core on the resource directory. This in 216 turn adds links to the resource directory under an appropriate 217 resource. These links can then be discovered by any client by a 218 performing a GET on the resource directory using a query string 219 filter. 221 1.3. Terminology 223 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 224 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 225 document are to be interpreted as described in [RFC2119]. 227 This specification requires readers to be familiar with all the terms 228 and concepts that are discussed in [RFC5988]. This specification 229 makes use of the following terminology: 231 Web Linking 232 A framework for indicating the relationships between web 233 resources. 235 Link 236 Also called "typed links" in RFC5988. A link is a typed 237 connection between two resources identified by URIs. Made up of a 238 context URI, a link relation type, a target URI, and optional 239 target attributes. 241 Link Format 242 A particular serialisation of typed links. 244 CoRE Link Format 245 A particular serialization of typed links based the HTTP Link 246 Header serialization defined in Section 5 of RFC5988, but carried 247 as a resource representation with a MIME type. 249 Attribute 250 Properly called "Target Attribute" in RFC5988. A set of key/value 251 pairs that descibe the link or its target. 253 CoRE Resource Discovery 254 When a client discovers the list of resources hosted by a server, 255 their attributes and other link relations by accessing /.well- 256 known/core. 258 2. Link Format 260 The CoRE Link Format extends the HTTP Link Header format specified in 261 [RFC5988], which is specified in Augmented Backus-Naur Form (ABNF) 262 notation [RFC5234]. The format does not require special XML or 263 binary parsing, is fairly compact, and is extensible - all important 264 characteristics for CoRE. It should be noted that this link format 265 is just one serialization of typed links defined in [RFC5988], others 266 include HTML link, Atom feed links [RFC4287] or HTTP Link Headers. 267 It is expected that resources discovered in the CoRE Link Format may 268 also be made available in alternative formats on the greater 269 Internet. The CoRE Link Format is only expected to be supported in 270 constrained networks and M2M systems. 272 Section 5 of [RFC5988] did not require an Internet media type for the 273 defined link format, as it was defined to be carried in an HTTP 274 header. This specification thus defines a Internet media type for 275 the CoRE Link Format (see Section 7.3). 277 The CoRE link format uses the ABNF description and associated rules 278 in Section 5 of [RFC5988]. In addition, the pchar rule is taken from 279 [RFC3986]. The "Link:" text is omitted as that is part of the HTTP 280 Link Header. As in [RFC5988], multiple link descriptions are 281 separated by commas. Note that commas can also occur in quoted 282 strings and URIs but do not end a description. 284 2.1. Target and context URIs 286 Each link conveys one target URI as a URI-reference inside angle 287 brackets ("<>"). The context URI of a link (also called base URI in 288 [RFC3986]) conveyed in the CoRE Link Format is by default built from 289 the scheme and authority parts of the target URI. In the absence of 290 this information in the target URI, the context URI is built from the 291 scheme and authority that was used for referencing the resource 292 returning the set of links, replacing the path with an empty path. 293 Thus by default links can be thought of as describing a target 294 resource hosted by the server. Other relations can be expressed by 295 including an anchor parameter (which defines the context URI) along 296 with an explicit relation parameter. This is an important difference 297 to the way the HTTP Link Header format is used, as it is included in 298 the header of an HTTP response for some URI (this URI is by default 299 the context URI). Thus the HTTP Link Header is by default relating 300 the target URI to the URI that was requested. In comparison, the 301 CoRE link format includes one or more links, each describing a 302 resource hosted by a server by default. Other relations can be 303 expressed by using the anchor parameter. See Section 5 of [RFC3986] 304 for a description of how URIs are constructed from URI references. 306 2.2. Link relations 308 Since links in the CoRE Link Format are typically used to describe 309 resources hosted by a server, and thus in the absence of the relation 310 parameter the new relation type "hosts" is assumed (see Section 7.2). 311 The "hosts" relation type indicates that the target URI is a resource 312 hosted by the server given by the base URI, or, if present, the 313 anchor parameter. 315 To express other relations a links can make use of any registered 316 relation parameter or target attributes by including the relation 317 parameter. The context of a relation can be defined using the anchor 318 parameter. In this way, relations between resources hosted on a 319 server, or between hosted resources and external resources can be 320 expressed. 322 2.3. Use of anchors 324 As per Section 5.2 of [RFC5988] a link description MAY include an 325 "anchor" attribute, in which case the context is the URI included in 326 that attribute. This is used to describe a relationship between two 327 resources. A consuming implementation can however choose to ignore 328 such links. It is not expected that all implementations will be able 329 to derive useful information from explicitly anchored links. 331 3. CoRE link extensions 333 The following CoRE specific target attributes are defined in addition 334 to the ABNF rules in Section 5 of [RFC5988]. These attributes 335 describe information useful in accessing the target link of the 336 relation, and in some cases may be URIs. These URIs MUST be treated 337 as non resolvable identifiers (they are not meant to be retrieved). 338 When attributes are compared, they MUST be compared as strings. 339 Relationships to resources that are meant to be retrieved should be 340 expressed as separate links using the anchor attribute and the 341 appropriate relation type. 343 link-extension = 344 link-extension = ( "rt" "=" quoted-string ) 345 link-extension = ( "if" "=" quoted-string ) 346 link-extension = ( "ct" "=" cardinal ) ; Range of 0-65535 347 link-extension = ( "sz" "=" cardinal ) 348 cardinal = "0" / %x31-39 *DIGIT 350 3.1. Resource type 'rt' attribute 352 The resource type "rt" attribute is an opaque string used to assign a 353 semantically important type to a resource. One can think of this as 354 a noun describing the resource. In the case of a temperature 355 resource this could be e.g. an application-specific semantic type 356 like "OutdoorTemperature", a Universal Resource Name (URN) like 357 "urn:temperature:outdoor" or a URI referencing a specific concept in 358 an ontology like 359 "http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature". Multiple 360 resource type attributes MAY appear in a link. 362 The resource type attribute is not meant to used to assign a human 363 readable name to a resource. The "title" attribute defined in 364 [RFC5988] is meant for that purpose. 366 3.2. Interface description 'if' attribute 368 The interface description "if" attribute is an opaque string used to 369 provide a name, URI or URN indicating a specific interface definition 370 used to interact with the target resource. One can think of this as 371 describing verbs usable on a resource. The interface description 372 attribute is meant to describe the generic REST interface to interact 373 with a resource or a set of resources. It is expected that an 374 interface description will be re-used by different resource types. 375 For example the resource types "OutdoorTemperature", "DewPoint" and 376 "RelHumidity" could all be accessible using the interface description 377 "http://www.example.org/myapp.wadl#sensor". 379 The interface description could be for example the URI of a Web 380 Application Description Language (WADL) [WADL] definition of the 381 target resource "http://www.example.org/myapp.wadl#sensor", a URN 382 indicating the type of interface to the resource "urn:myapp:sensor", 383 or an application-specific name "Sensor". Multiple interface 384 description attributes MAY appear in a link. 386 3.3. Content-type code 'ct' attribute 388 The Content-type code "ct" attribute provides a hint about the 389 Internet media type this resource returns. Note that this is only a 390 hint, and does not override the Content-type Option of a CoAP 391 response obtained by actually following the link. The value is in 392 the CoAP identifier code format as a decimal ASCII integer 393 [I-D.ietf-core-coap] and MUST be in the range of 0-65535 (16-bit 394 unsigned integer). For example application/xml would be indicated as 395 "ct=41". If no Content-type code attribute is present then nothing 396 about the type can be assumed. The Content-type code attribute MUST 397 NOT appear more than once in a link. 399 Alternatively, the "type" attribute MAY be used to indicate an 400 Internet media type as a quoted-string [RFC5988]. It is not however 401 expected that constrained implementations are able to parse quoted- 402 string Content-type values. A link MAY include either a ct attribute 403 or a type attribute, but MUST NOT include both. 405 3.4. Maximum size estimate 'sz' attribute 407 The maximum size estimate attribute "sz" gives an indication of the 408 maximum size of the resource indicated by the target URI. This 409 attribute is not expected to be included for small resources that can 410 comfortably by carried in a single Maxiumum Transmission Unit (MTU), 411 but SHOULD be included for resources larger than that. The maximum 412 size estimate attribute MUST NOT appear more than once in a link. 414 Note that there is no defined upper limit to the value of the sz 415 attributes. Implementations MUST be prepared to accept large values. 416 One implementation strategy is to convert any value larger than a 417 reasonable size limit for this implementation to a special value 418 "Big", which in further processing would indicate that a size value 419 was given that was so big that it cannot be processed by this 420 implementation. 422 4. Well-known Interface 424 Resource discovery in CoRE is accomplished through the use of a well- 425 known resource URI which returns a list of links about resources 426 hosted by that server and other link relations. Well-known resources 427 have a path component that begins with "/.well-known/" as specified 428 in [RFC5785]. This document defines a new well-known resource for 429 CoRE Resource Discovery "/.well-known/core". 431 A server implementing this specification MUST support this resource 432 on the default port appropriate for the protocol for the purpose of 433 resource discovery. It is however up to the application which links 434 are included and how they are organized. The resource /.well-known/ 435 core is meant to be used to return links to the entry points of 436 resource interfaces on a server. More sophisticated link 437 organization can be achieved by including links to CoRE Link Format 438 resources located elsewhere on the server, for example to achieve an 439 index. In the absence of any links, a zero-length payload is 440 returned. The resource representation of this resource MUST be the 441 CoRE Link Format described in Section 2. 443 The CoRE resource discovery interface supports the following 444 interactions: 446 o Performing a GET on /.well-known/core to the default port returns 447 a set of links available from the server (if any) in the CoRE Link 448 Format. These links might describe resources hosted on that 449 server, on other servers, or express other kinds of link relations 450 as described in Section 2. 452 o Filtering may be performed on any of the link format attributes 453 using a query string as specified in Section 4.1. For example 454 [GET /.well-known/core?n=TemperatureC] would request resources 455 with the name TemperatureC. A server is not however required to 456 support filtering. 458 o More capable servers such as proxies could support a resource 459 directory by requesting the resource descriptions of other end- 460 points or allowing servers to POST requests to /.well-known/core. 462 The details of such resource directory functionality is however 463 out of scope for this document, and is expected to be specified 464 separately. 466 4.1. Query Filtering 468 A server implementing this document MAY recognize the query part of a 469 resource discovery URI as a filter on the resources to be returned. 470 The query part should conform to the following syntax. Note that 471 this only defines querying for a single parameter at a time. 473 filter-query = resource-param "=" query-pattern 474 resource-param = "uri" | parmname 475 query-pattern = 1*pchar [ "*" ] 477 The resource-param "uri" refers to the URI-reference between the "<" 478 and ">" characters of a link. Other resource-param values refer to 479 the link attribute they name. Filtering is performed by comparing 480 the query-pattern against the value of the attribute identified by 481 the resource-param for each link-value in the collection of resources 482 identified by the URI path. 484 If the decoded query-pattern does not end with "*", a link value 485 matches the query only if the value of the attribute or URI-reference 486 denoted by the resource-param is bytewise identical to the query- 487 pattern. If the decoded query-pattern ends with "*", it is 488 sufficient that the remainder of the query-pattern be a prefix of the 489 value denoted by the resource-param. A query-pattern of "*" will 490 match that resource-param with an empty string value. It is not 491 expected that very constrained nodes support filtering. 492 Implementations not supporting filtering MUST simply ignore the query 493 string and return the whole resource for unicast requests. 495 When using a transfer protocol like the Constrained Application 496 Protocol (CoAP) that supports multicast requests, special care is 497 taken. A multicast request with a query string MUST not be responded 498 to if filtering is not supported (to avoid a needless response 499 storm). 501 5. Examples 503 A few examples of typical link descriptions in this format follows. 504 Multiple resource descriptions in a representation are separated by 505 commas. Linefeeds never occur in the actual format, but are shown in 506 these examples for readability. Although the following examples use 507 CoAP response codes, the examples are applicable to HTTP as well (the 508 corresponding response code would be 200 OK). 510 This example includes links to two different sensors sharing the same 511 interface description. 513 REQ: GET /.well-known/core 515 RES: 2.05 "Content" 516 ;ct=41;rt="TemperatureC";if="sensor", 517 ;ct=41;rt="LightLux";if="sensor" 519 Without the linefeeds included for readability, the format actually 520 looks as follows. 522 ;ct=41;rt="TemperatureC";if="sensor",; 523 ct=41;rt="LightLux";if="sensor" 525 This example arranges link descriptions hierarchically, with the 526 entry point including a link to a sub-resource containing links about 527 the sensors. 529 REQ: GET /.well-known/core 531 RES: 2.05 "Content" 532 ;rt="index";ct=40 534 REQ: GET /sensors 536 RES: 2.05 "Content" 537 ;ct=41;rt="TemperatureC";if="sensor", 538 ;ct=41;rt="LightLux";if="sensor" 540 An example query filter may look like: 542 REQ: GET /.well-known/core?rt=LightLux 544 RES: 2.05 "Content" 545 ;ct=41;rt="LightLux";if="sensor" 547 This example shows the use of an anchor attribute to relate the 548 temperature sensor resource to an external description and to an 549 alternative URL. 551 REQ: GET /.well-known/core 553 RES: 2.05 "Content" 554 ;ct=40;rt="index";rt="Sensor Index", 555 ;rt="TemperatureC";if="sensor", 556 ;ct=41;rt="LightLux";if="sensor", 557 ;anchor="/sensors/temp" 558 ;rel="describedby", 559 ;anchor="/sensors/temp";rel="alternate" 561 If a client is interested to find relations about a particular 562 resource, it can perform a query on the anchor parameter: 564 REQ: GET /.well-known/core?anchor=/sensors/temp 566 RES: 2.05 "Content" 567 ;anchor="/sensors/temp" 568 ;rel="describedby", 569 ;anchor="/sensors/temp";rel="alternate" 571 The following example shows a large firmware resource with a size 572 attribute. The consumer of this link would use the sz attribute to 573 determine if the resource representation is too large and if block 574 transfer would be required to request it. In this case a client with 575 only a 64 KiB flash might only support a 16-bit integer for storing 576 the sz attibute. Thus a special flag or value should be used to 577 indicate "Big" (larger than 64 KiB). 579 REQ: GET /.well-known/core?rt=firmware 581 RES: 2.05 "Content" 582 ;rt="firmware";sz=262144 584 6. Security Considerations 586 This document needs the same security considerations as described in 587 Section 7 of [RFC5988]. The /.well-known/core resource may be 588 protected e.g. using DTLS when hosted on a CoAP server as per 589 [I-D.ietf-core-coap] Section 10.2. 591 Multicast requests using CoAP for the well-known link-format 592 resources could be used to perform denial of service on a constrained 593 network. A multicast request SHOULD only be accepted if the request 594 is sufficiently authenticated and secured using e.g. IPsec or an 595 appropriate object security mechanism. 597 CoRE link format parsers should be aware that a link description may 598 be cyclical, i.e., contain a link to itself. These cyclical links 599 could be direct or indirect (i.e., through referenced link 600 resources). Care should be taken when parsing link descriptions and 601 accessing cyclical links. 603 7. IANA Considerations 605 7.1. Well-known 'core' URI 607 This memo registers the "core" well-known URI in the Well-Known URI 608 Registry as defined by [RFC5785]. 610 URI suffix: core 612 Change controller: IETF 614 Specification document(s): [[ this document ]] 616 Related information: None 618 7.2. New 'hosts' relation type 620 This memo registers the new "hosts" Web Linking relation type as per 621 [RFC5988]. 623 Relation Name: hosts 625 Description: Refers to a resource hosted by the server indicated by 626 the link context. 628 Reference: [[ this document ]] 630 Notes: This relation is used in CoRE where links are retrieved as a 631 /.well-known/core resource representation, and by default the context 632 of the links is the server at coap://authority from which /.well- 633 known/core was requested. 635 Application Data: None 637 7.3. New link-format Internet media type 639 This memo registers the a new Internet media type for the CoRE link 640 format, application/link-format. 642 Type name: application 644 Subtype name: link-format 646 Required parameters: None 648 Optional parameters: None 650 Encoding considerations: Binary data 652 Security considerations: 654 Multicast requests using CoAP for the well-known link-format 655 resources could be used to perform denial of service on a constrained 656 network. A multicast request SHOULD only be accepted if the request 657 is sufficiently authenticated and secured using e.g. IPsec or an 658 appropriate object security mechanism. 660 CoRE link format parsers should be aware that a link description may 661 be cyclical, i.e., contain a link to itself. These cyclical links 662 could be direct or indirect (i.e., through referenced link 663 resources). Care should be taken when parsing link descriptions and 664 accessing cyclical links. 666 Interoperability considerations: 668 Published specification: [[ this document ]] 670 Applications that use this media type: CoAP server and client 671 implementations for resource discovery and HTTP applications that use 672 the link-format as a payload. 674 Additional information: 676 Magic number(s): 678 File extension(s): *.wlnk 680 Macintosh file type code(s): 682 Intended usage: COMMON 684 Restrictions on usage: None 686 Author: CoRE WG 688 Change controller: IETF 690 8. Acknowledgments 692 Special thanks to Peter Bigot, who has made a considerable number 693 reviews and text contributions that greatly improved the document. 694 In particular, Peter is responsible for the ABNF descriptions and the 695 idea for a new "hosts" relation type. 697 Thanks to Mark Nottingham and Eran Hammer-Lahav for the discussions 698 and ideas that led to this draft, and to Carsten Bormann, Martin 699 Thomson, Alexey Melnikov and Peter Saint-Andre for extensive comments 700 and contributions that improved the text. 702 Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido 703 Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey 704 Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin, 705 Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed 706 Beroset, Gilman Tolle, Robby Simpson, Colin O'Flynn and David Ryan 707 for helpful comments and discussions that have shaped the document. 709 9. Changelog 711 Changes from ietf-04 to ietf-05: 713 o Removed mention of UTF-8 as this is already defined by RFC5988 714 (#158) 716 o Changed encoding considerations to "Binary data" (#157) 718 o Updated ABNF to dissallow leading zeros in intergers (#159) 720 o Updated examples and reference for coap-06 (#152) 722 o Removed the applcation/link-format CoAP code registration, now 723 included in the CoAP specification directly (#160) 725 Changes from ietf-03 to ietf-04: 727 o Removed the attribute registry (#145). 729 o Requested a CoAP media type for application/link-format (#144). 731 o Editorial and reference improvements from AD review (#146). 733 o Added a range limitation for ct attribute. 735 o Added security considerations and file extension for 736 application/link-format registration. 738 Changes from ietf-02 to ietf-03: 740 o Removed 'obs' attribute definition, now defined in the CoAP 741 Observation spec (#99). 743 o Changed Resource name (n=) to Resource type (rt=) and d= to if= 744 (#121). 746 o Hierarchical organization of links under /.well-known/core 747 removed (#95). 749 o Bug in Section 3.1 on byte-wise query matching fixed (#91). 751 o Explanatory text added about alternative Web link formats (#92). 753 o Fixed a bug in Section 2.2.4 (#93). 755 o Added use case examples (#89). 757 o Clarified how the CoRE link format is used and how it differs 758 from RFC5988 (#90, #98). 760 o Changed the Interface definition format to quoted-string to 761 match the resource type. 763 o Added an IANA registry for CoRE Link Format attributes (#100). 765 Changes from ietf-01 to ietf-02: 767 o Added references to RFC5988 (#41). 769 o Removed sh and id link-extensions (#42). 771 o Defined the use of UTF-8 (#84). 773 o Changed query filter definition for any parameter (#70). 775 o Added more example, now as a separate section (#43). 777 o Mentioned cyclical links in the security section (#57). 779 o Removed the sh and id attributes, added obs and sz attributes 780 (#42). 782 o Improved the context and relation description wrt RFC5988 and 783 requested a new "hosts" default relation type (#85). 785 Changes from ietf-00 to ietf-01: 787 o Editorial changes to correct references. 789 o Formal definition for filter query string. 791 o Removed URI-reference option from "n" and "id". 793 o Added security text about multicast requests. 795 Changes from shelby-00 to ietf-00: 797 o Fixed the ABNF link-extension definitions (quotes around URIs, 798 integer definition). 800 o Clarified that filtering is optional, and the query string is to 801 be ignored if not supported (and the URL path processed as 802 normally). 804 o Required support of wildcard * processing if filtering is 805 supported. 807 o Removed the aussumption of a default content-type assumption. 809 10. References 811 10.1. Normative References 813 [I-D.ietf-core-coap] 814 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 815 "Constrained Application Protocol (CoAP)", 816 draft-ietf-core-coap-06 (work in progress), May 2011. 818 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 819 Requirement Levels", BCP 14, RFC 2119, March 1997. 821 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 822 Resource Identifier (URI): Generic Syntax", STD 66, 823 RFC 3986, January 2005. 825 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 826 Specifications: ABNF", STD 68, RFC 5234, January 2008. 828 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 830 10.2. Informative References 832 [REST] Fielding, R., "Architectural Styles and the Design of 833 Network-based Software Architectures", 2000, . 836 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 837 STD 13, RFC 1034, November 1987. 839 [RFC1035] Mockapetris, P., "Domain names - implementation and 840 specification", STD 13, RFC 1035, November 1987. 842 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 843 Extensions (MIME) Part One: Format of Internet Message 844 Bodies", RFC 2045, November 1996. 846 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 847 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 848 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 850 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 851 Syndication Format", RFC 4287, December 2005. 853 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 854 "Transmission of IPv6 Packets over IEEE 802.15.4 855 Networks", RFC 4944, September 2007. 857 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 858 Uniform Resource Identifiers (URIs)", RFC 5785, 859 April 2010. 861 [WADL] Hadley, M., "Web Application Description Language (WADL)", 862 2009, . 865 Author's Address 867 Zach Shelby 868 Sensinode 869 Kidekuja 2 870 Vuokatti 88600 871 FINLAND 873 Phone: +358407796297 874 Email: zach@sensinode.com