idnits 2.17.1 draft-ietf-core-link-format-14.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 == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (June 1, 2012) is 4346 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) == Unused Reference: 'RFC4288' is defined on line 1064, but no explicit reference was found in the text == Unused Reference: 'RFC5646' is defined on line 1074, but no explicit reference was found in the text == Unused Reference: 'RFC5987' is defined on line 1077, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5987 (Obsoleted by RFC 8187) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-09 -- Obsolete informational reference (is this intentional?): RFC 5785 (Obsoleted by RFC 8615) Summary: 5 errors (**), 0 flaws (~~), 6 warnings (==), 2 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 June 1, 2012 5 Expires: December 3, 2012 7 CoRE Link Format 8 draft-ietf-core-link-format-14 10 Abstract 12 This specification 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 field defined in RFC5988, the CoRE Link Format is carried 16 as a payload and is assigned an Internet media type. A well-known 17 URI is defined as a default entry-point for requesting the links 18 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 December 3, 2012. 37 Copyright Notice 39 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . 9 63 2.2. Link relations . . . . . . . . . . . . . . . . . . . . . . 9 64 2.3. Use of anchors . . . . . . . . . . . . . . . . . . . . . . 9 65 3. CoRE link attributes . . . . . . . . . . . . . . . . . . . . . 9 66 3.1. Resource type 'rt' attribute . . . . . . . . . . . . . . . 10 67 3.2. Interface description 'if' attribute . . . . . . . . . . . 10 68 3.3. Maximum size estimate 'sz' attribute . . . . . . . . . . . 11 69 4. Well-known Interface . . . . . . . . . . . . . . . . . . . . . 11 70 4.1. Query Filtering . . . . . . . . . . . . . . . . . . . . . 12 71 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 72 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15 73 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 74 7.1. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 16 75 7.2. New 'hosts' relation type . . . . . . . . . . . . . . . . 16 76 7.3. New link-format Internet media type . . . . . . . . . . . 17 77 7.4. Constrained RESTful Environments (CORE) Parameters 78 Registry . . . . . . . . . . . . . . . . . . . . . . . . . 18 79 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 80 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 20 81 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24 82 10.1. Normative References . . . . . . . . . . . . . . . . . . . 24 83 10.2. Informative References . . . . . . . . . . . . . . . . . . 24 84 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 25 86 1. Introduction 88 The Constrained RESTful Environments (CoRE) realizes the 89 Representational State Transfer (REST) architecture [REST] in a 90 suitable form for the most constrained nodes (e.g. 8-bit 91 microcontrollers with limited memory) and networks (e.g. 6LoWPAN 92 [RFC4919]). CoRE is aimed at Machine-to-Machine (M2M) applications 93 such as smart energy and building automation. 95 The discovery of resources hosted by a constrained server is very 96 important in machine-to-machine applications where there are no 97 humans in the loop and static interfaces result in fragility. The 98 discovery of resources provided by an HTTP [RFC2616] Web Server is 99 typically called Web Discovery and the description of relations 100 between resources is called Web Linking [RFC5988]. In the present 101 specification we refer to the discovery of resources hosted by a 102 constrained web server, their attributes and other resource relations 103 as CoRE Resource Discovery. 105 The main function of such a discovery mechanism is to provide 106 Universal Resource Identifiers (URIs, called links) for the resources 107 hosted by the server, complemented by attributes about those 108 resources and possible further link relations. In CoRE this 109 collection of links is carried as a resource of its own (as opposed 110 to HTTP headers delivered with a specific resource). This document 111 specifies a link format for use in CoRE Resource Discovery by 112 extending the HTTP Link Header format [RFC5988] to describe these 113 link descriptions. The CoRE Link Format is carried as a payload and 114 is assigned an Internet media type. A well-known relative URI 115 "/.well-known/core" is defined as a default entry-point for 116 requesting the list of links about resources hosted by a server, and 117 thus performing CoRE Resource Discovery. This specification is 118 applicable for use with Constrained Application Protocol (CoAP) 119 [I-D.ietf-core-coap], HTTP or any other suitable web transfer 120 protocol. The link format can also be saved in file format. 122 1.1. Web Linking in CoRE 124 Technically the CoRE Link Format is a serialization of a typed link 125 as specified in [RFC5988], used to describe relationships between 126 resources, so-called "Web Linking". In this specification Web 127 Linking is extended with specific constrained M2M attributes, links 128 are carried as a message payload rather than in an HTTP Link Header 129 field, and a default interface is defined to discover resources 130 hosted by a server. This specification also defines a new relation 131 type "hosts" (from the verb "to host"), which indicates that the 132 resource is hosted by the server from which the link document was 133 requested. 135 In HTTP, the Link Header can be used to carry link information about 136 a resource along with an HTTP response. This works well for the 137 typical use case for a web server and browser, where further 138 information about a particular resource is useful after accessing it. 139 In CoRE the main use case for Web Linking is the discovery of which 140 resources a server hosts in the first place. Although some resources 141 may have further links associated with them, this is expected to be 142 an exception. For that reason the CoRE Link Format serialization is 143 carried as a resource representation of a well-known URI. The CoRE 144 Link Format does re-use the format of the HTTP Link Header 145 serialization defined in [RFC5988]. 147 1.2. Use Cases 149 Typical use cases for Web Linking on today's web include e.g. 150 describing the author of a web page or describing relations between 151 web pages (next chapter, previous chapter etc.). Web Linking can 152 also be applied to M2M applications, where typed links are used to 153 assist a machine client in finding and understanding how to use 154 resources on a server. In this section a few use cases are described 155 for how the CoRE Link Format could be used in M2M applications. For 156 further technical examples see Section 5. As there are a large range 157 of M2M applications, these use cases are purposely generic. This 158 specification assumes that different deployments or application 159 domains will define the appropriate REST Interface Descriptions along 160 with Resource Types to make discovery meaningful. 162 1.2.1. Discovery 164 In M2M applications, for example home or building automation, there 165 is a need for local clients and servers to find and interact with 166 each other without human intervention. The CoRE Link Format can be 167 used by servers in such environments to enable Resource Discovery of 168 the resources hosted by the server. 170 Resource Discovery can be performed either unicast or multicast. 171 When a server's IP address is already known, either a priori or 172 resolved via the Domain Name System (DNS) [RFC1034][RFC1035], unicast 173 discovery is performed in order to locate the entry point to the 174 resource of interest. In this specification, this is performed using 175 a GET to "/.well-known/core" on the server, which returns a payload 176 in the CoRE Link Format. A client would then match the appropriate 177 Resource Type, Interface Description and possible Media type 178 [RFC2045] for its application. These attributes may also be included 179 in the query string in order to filter the number of links returned 180 in a response. 182 Multicast resource discovery is useful when a client needs to locate 183 a resource within a limited scope, and that scope supports IP 184 multicast. A GET request to the appropriate multicast address is 185 made for "/.well-known/core". In order to limit the number and size 186 or responses, a query string is recommended with the known 187 attributes. Typically a resource would be discovered based on its 188 Resource Type and/or Interface Description, along with possible 189 application specific attributes. 191 1.2.2. Resource Collections 193 RESTful designs of M2M interfaces often make use of collections of 194 resources. For example an index of temperature sensors on a data 195 collection node or a list of alarms on a home security controller. 196 The CoRE Link Format can be used to make it possible to find the 197 entry point to a collection and traverse its members. The entry 198 point of a collection would always be included in "/.well-known/core" 199 to enable its discovery. The members of the collection can be 200 defined either through the Interface Description of the resource 201 along with a parameter resource for the size of the collection, or by 202 using the link format to describe each resource in the collection. 203 These links could be located under "/.well-known/core" or hosted for 204 example in the root resource of the collection. 206 1.2.3. Resource Directory 208 In many deployment scenarios, for example constrained networks with 209 sleeping servers, or large M2M deployments with bandwidth limited 210 access networks, it makes sense to deploy resource directory entities 211 which store links to resources stored on other servers. Think of 212 this as a limited search engine for constrained M2M resources. 214 The CoRE Link Format can be used by a server to register resources 215 with a resource directory, or to allow a resource directory to poll 216 for resources. Resource registration can be achieved by having each 217 server POST their resources to "/.well-known/core" on the resource 218 directory. This in turn adds links to the resource directory under 219 an appropriate resource. These links can then be discovered by any 220 client by making a request to a resource directory lookup interface. 222 1.3. Terminology 224 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 225 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 226 specification are to be interpreted as described in [RFC2119]. 228 This specification makes use of the Augmented Backus-Naur Form (ABNF) 229 [RFC5234] notation, including the core rules defined in Appendix A of 230 that document. 232 This specification requires readers to be familiar with all the terms 233 and concepts that are discussed in [RFC5988] and [RFC6454]. In 234 addition, this specification makes use of the following terminology: 236 Web Linking 237 A framework for indicating the relationships between web 238 resources. 240 Link 241 Also called "typed links" in RFC5988. A link is a typed 242 connection between two resources identified by URIs. Made up of a 243 context URI, a link relation type, a target URI, and optional 244 target attributes. 246 Link Format 247 A particular serialization of typed links. 249 CoRE Link Format 250 A particular serialization of typed links based on the HTTP Link 251 Header field serialization defined in Section 5 of RFC5988, but 252 carried as a resource representation with a media type. 254 Attribute 255 Properly called "Target Attribute" in RFC5988. A key/value pair 256 that describes the link or its target. 258 CoRE Resource Discovery 259 When a client discovers the list of resources hosted by a server, 260 their attributes and other link relations by accessing "/.well- 261 known/core". 263 2. Link Format 265 The CoRE Link Format extends the HTTP Link Header field specified in 266 [RFC5988]. The format does not require special XML or binary 267 parsing, is fairly compact, and is extensible - all important 268 characteristics for CoRE. It should be noted that this link format 269 is just one serialization of typed links defined in [RFC5988], others 270 include HTML link, Atom feed links [RFC4287] or HTTP Link Header 271 fields. It is expected that resources discovered in the CoRE Link 272 Format may also be made available in alternative formats on the 273 greater Internet. The CoRE Link Format is only expected to be 274 supported in constrained networks and M2M systems. 276 Section 5 of [RFC5988] did not require an Internet media type for the 277 defined link format, as it was defined to be carried in an HTTP 278 header. This specification thus defines the Internet media type 279 "application/link-format" for the CoRE Link Format (see Section 7.3). 280 Whereas the HTTP Link Header field depends on [RFC2616] for its 281 encoding, the CoRE Link Format is encoded as UTF-8 [RFC3629]. A 282 decoder of the format is not expected to (but not prohibited from) 283 validate UTF-8 encoding and doesn't need to perform any UTF-8 284 normalization. UTF-8 data can be compared bit-wise, which allows 285 values to contain UTF-8 data without any added complexity for 286 constrained nodes. 288 The CoRE link format is equivalent to the [RFC5988] link format, 289 however the ABNF in the present specification is repeated with 290 improvements to be compliant with [RFC5234] and includes new link 291 parameters. The link parameter "href" is reserved for use as a query 292 parameter for filtering in this specification (see Section 4.1), and 293 MUST NOT be defined as a link parameter. As in [RFC5988], multiple 294 link descriptions are separated by commas. Note that commas can also 295 occur in quoted strings and URIs but do not end a description. In 296 order to convert an HTTP Link Header field to this link format, first 297 the "Link:" HTTP header is removed, any LWS is removed, the header 298 value is converted to UTF-8 and any percent-encodings decoded. 300 Link = link-value-list 301 link-value-list = [ link-value *[ "," link-value ]] 302 link-value = "<" URI-Reference ">" *( ";" link-param ) 303 link-param = ( ( "rel" "=" relation-types ) 304 / ( "anchor" "=" DQUOTE URI-Reference DQUOTE ) 305 / ( "rev" "=" relation-types ) 306 / ( "hreflang" "=" Language-Tag ) 307 / ( "media" "=" ( MediaDesc 308 / ( DQUOTE MediaDesc DQUOTE ) ) ) 309 / ( "title" "=" quoted-string ) 310 / ( "title*" "=" ext-value ) 311 / ( "type" "=" ( media-type / quoted-mt ) ) 312 / ( "rt" "=" relation-types ) 313 / ( "if" "=" relation-types ) 314 / ( "sz" "=" cardinal ) 315 / ( link-extension ) ) 316 link-extension = ( parmname [ "=" ( ptoken / quoted-string ) ] ) 317 / ( ext-name-star "=" ext-value ) 318 ext-name-star = parmname "*" ; reserved for RFC2231-profiled 319 ; extensions. Whitespace NOT 320 ; allowed in between. 321 ptoken = 1*ptokenchar 322 ptokenchar = "!" / "#" / "$" / "%" / "&" / "'" / "(" 323 / ")" / "*" / "+" / "-" / "." / "/" / DIGIT 324 / ":" / "<" / "=" / ">" / "?" / "@" / ALPHA 325 / "[" / "]" / "^" / "_" / "`" / "{" / "|" 326 / "}" / "~" 327 media-type = type-name "/" subtype-name 328 quoted-mt = DQUOTE media-type DQUOTE 329 relation-types = relation-type 330 / DQUOTE relation-type *( 1*SP relation-type ) DQUOTE 331 relation-type = reg-rel-type / ext-rel-type 332 reg-rel-type = LOALPHA *( LOALPHA / DIGIT / "." / "-" ) 333 ext-rel-type = URI 334 cardinal = "0" / ( %x31-39 *DIGIT ) 335 LOALPHA = %x61-7A ; a-z 336 quoted-string = 337 URI = 338 URI-Reference = 339 type-name = 340 subtype-name = 341 MediaDesc = 342 Language-Tag = 343 ext-value = 344 parmname = 346 2.1. Target and context URIs 348 Each link conveys one target URI as a URI-reference inside angle 349 brackets ("<>"). The context URI of a link (also called base URI in 350 [RFC3986]) is determined by the following rules in this 351 specification: 353 (a) The context URI is set to the anchor parameter, when specified, 354 or 356 (b) Origin of the target URI, when specified 358 (c) Origin of the link format resource's base URI. 360 2.2. Link relations 362 Since links in the CoRE Link Format are typically used to describe 363 resources hosted by a server, and thus in the absence of the relation 364 parameter the new relation type "hosts" is assumed (see Section 7.2). 365 The "hosts" relation type (from the verb "to host") indicates that 366 the target URI is a resource hosted by the server (i.e. server hosts 367 resource) indicated by the context URI. The target URI MUST be a 368 relative URI of the context URI for this relation type. 370 To express other relations, links can make use of any registered 371 relation by including the relation parameter. The context of a 372 relation can be defined using the anchor parameter. In this way, 373 relations between resources hosted on a server, or between hosted 374 resources and external resources can be expressed. 376 2.3. Use of anchors 378 As per Section 5.2 of [RFC5988] a link description MAY include an 379 "anchor" attribute, in which case the context is the URI included in 380 that attribute. This is used to describe a relationship between two 381 resources. A consuming implementation can however choose to ignore 382 such links. It is not expected that all implementations will be able 383 to derive useful information from explicitly anchored links. 385 3. CoRE link attributes 387 The following CoRE specific target attributes are defined in addition 388 to those already defined in [RFC5988]. These attributes describe 389 information useful in accessing the target link of the relation, and 390 in some cases can use the syntactical form of a URI. Such a URI MAY 391 be dereferenced (for instance to obtain a description of the link 392 relation), but that this is not part of the protocol and MUST NOT be 393 done automatically on link evaluation. When attributes values are 394 compared, they MUST be compared as strings. 396 3.1. Resource type 'rt' attribute 398 The resource type "rt" attribute is an opaque string used to assign 399 an application specific semantic type to a resource. One can think 400 of this as a noun describing the resource. In the case of a 401 temperature resource this could be e.g. an application-specific 402 semantic type like "outdoor-temperature" or a URI referencing a 403 specific concept in an ontology like 404 "http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature". Multiple 405 resource types MAY be included in the value of this parameter, each 406 separated by a space, similar to the relation attribute. The 407 registry for Resource Type values is defined in Section 7.4. 409 The resource type attribute is not meant to used to assign a human 410 readable name to a resource. The "title" attribute defined in 411 [RFC5988] is meant for that purpose. The resource type attribute 412 MUST NOT appear more than once in a link. 414 3.2. Interface description 'if' attribute 416 The Interface Description "if" attribute is an opaque string used to 417 provide a name or URI indicating a specific interface definition used 418 to interact with the target resource. One can think of this as 419 describing verbs usable on a resource. The Interface Description 420 attribute is meant to describe the generic REST interface to interact 421 with a resource or a set of resources. It is expected that an 422 Interface Description will be re-used by different resource types. 423 For example the resource types "outdoor-temperature", "dew-point" and 424 "rel-humidity" could all be accessible using the interface 425 description "http://www.example.org/myapp.wadl#sensor". Multiple 426 interface descriptions MAY be included in the value of this 427 parameter, each separated by a space, similar to the relation 428 attribute. The registry for Interface Description values is defined 429 in Section 7.4. 431 The Interface Description could be for example the URI of a Web 432 Application Description Language (WADL) [WADL] definition of the 433 target resource "http://www.example.org/myapp.wadl#sensor", a URN 434 indicating the type of interface to the resource "urn:myapp:sensor", 435 or an application-specific name "Sensor". The Interface Description 436 attribute MUST NOT appear more than once in a link. 438 3.3. Maximum size estimate 'sz' attribute 440 The maximum size estimate attribute "sz" gives an indication of the 441 maximum size of the resource representation returned by performing a 442 GET on the target URI. For links to CoAP resources this attribute is 443 not expected to be included for small resources that can comfortably 444 be carried in a single Maximum Transmission Unit (MTU), but SHOULD be 445 included for resources larger than that. The maximum size estimate 446 attribute MUST NOT appear more than once in a link. 448 Note that there is no defined upper limit to the value of the sz 449 attributes. Implementations MUST be prepared to accept large values. 450 One implementation strategy is to convert any value larger than a 451 reasonable size limit for this implementation to a special value 452 "Big", which in further processing would indicate that a size value 453 was given that was so big that it cannot be processed by this 454 implementation. 456 4. Well-known Interface 458 Resource discovery in CoRE is accomplished through the use of a well- 459 known resource URI which returns a list of links about resources 460 hosted by that server and other link relations. Well-known resources 461 have a path component that begins with "/.well-known/" as specified 462 in [RFC5785]. This specification defines a new well-known resource 463 for CoRE Resource Discovery "/.well-known/core". 465 A server implementing this specification MUST support this resource 466 on the default port appropriate for the protocol for the purpose of 467 resource discovery. It is however up to the application which links 468 are included and how they are organized. The resource "/.well-known/ 469 core" is meant to be used to return links to the entry points of 470 resource interfaces on a server. More sophisticated link 471 organization can be achieved by including links to CoRE Link Format 472 resources located elsewhere on the server, for example to achieve an 473 index. In the absence of any links, a zero-length payload is 474 returned. The resource representation of this resource MUST be the 475 CoRE Link Format described in Section 2. 477 The CoRE resource discovery interface supports the following 478 interactions: 480 o Performing a GET on "/.well-known/core" to the default port 481 returns a set of links available from the server (if any) in the 482 CoRE Link Format. These links might describe resources hosted on 483 that server, on other servers, or express other kinds of link 484 relations as described in Section 2. 486 o Filtering may be performed on any of the link format attributes 487 using a query string as specified in Section 4.1. For example 488 [GET /.well-known/core?rt=temperature-c] would request resources 489 with the resource type TemperatureC. A server is not however 490 required to support filtering. 492 o More capable servers such as proxies could support a resource 493 directory by requesting the resource descriptions of other end- 494 points or allowing servers to POST requests to "/.well-known/ 495 core". The details of such resource directory functionality is 496 however out of scope for this specification, and is expected to be 497 specified separately. 499 4.1. Query Filtering 501 A server implementing this specification MAY recognize the query part 502 of a resource discovery URI as a filter on the resources to be 503 returned. The path and query components together should conform to 504 the following level-4 URI Template [RFC6570] 506 /.well-known/core{?search*} 508 where the variable "search" is a 1-element list that has a single 509 name/value pair, where 511 o name is either "href", a link-param name defined in this 512 specification, or any other link-extension name, and 514 o value is either a Complete Value String that does not end in a "*" 515 (%2A), or a Prefix Value String followed by a "*" (%2A). 517 The search name "href" refers to the URI-reference between the "<" 518 and ">" characters of a link. Both Value Strings match a target 519 attribute only if it exists. Value Strings are percent-decoded 520 ([RFC3986] section 2.1) before matching; similarly, any target 521 attributes notated as quoted-string are interpreted as defined in 522 section 2.2 of [RFC2616]. After these steps, a Complete Value String 523 matches a target attribute if it is bitwise identical. A Prefix 524 Value String matches a target attribute if is is a bitwise prefix of 525 the target attribute (where any string is a prefix of itself). Empty 526 prefix value strings are allowed, by the definition above they match 527 any target attribute that does exist. Note that relation-type target 528 attributes can contain multiple values, and each value MUST be 529 treated as a separate target attribute when matching. 531 It is not expected that very constrained nodes support filtering. 533 Implementations not supporting filtering MUST simply ignore the query 534 string and return the whole resource for unicast requests. 536 When using a transfer protocol like the Constrained Application 537 Protocol (CoAP) that supports multicast requests, special care needs 538 to be taken. A multicast request with a query string SHOULD NOT be 539 responded to if filtering is not supported or if the filter does not 540 match (to avoid a needless response storm). The exception is in 541 cases where the IP stack interface is not able to indicate that the 542 destination address was multicast. 544 The following are examples of valid query URIs: 546 o ?href=/foo matches a link-value that is anchored at /foo 548 o ?href=/foo* matches a link-value that is anchored at a URI that 549 starts with /foo 551 o ?foo=bar matches a link value that has a target attribute named 552 foo with the exact value bar 554 o ?foo=bar* matches a link value that has a target attribute named 555 foo the value of which starts with bar, e.g., bar or barley 557 o ?foo=* matches a link value that has a target attribute named foo 559 5. Examples 561 A few examples of typical link descriptions in this format follows. 562 Multiple resource descriptions in a representation are separated by 563 commas. Linefeeds are also included in these examples for 564 readability. Although the following examples use CoAP response 565 codes, the examples are applicable to HTTP as well (the corresponding 566 response code would be 200 OK). 568 This example includes links to two different sensors sharing the same 569 Interface Description. Note that the default relation type for this 570 link format is "hosts" in links with no rel= target attribute. Thus 571 the links in this example tell that the Origin server /.well-known/ 572 core was requested from (the context) hosts the resources /sensors/ 573 temp and /sensors/light (each a target). 575 REQ: GET /.well-known/core 577 RES: 2.05 Content 578 ;if="sensor", 579 ;if="sensor" 580 Without the linefeeds inserted here for readability, the format 581 actually looks as follows. 583 ;if="sensor",;if="sensor" 585 This example arranges link descriptions hierarchically, with the 586 entry point including a link to a sub-resource containing links about 587 the sensors. 589 REQ: GET /.well-known/core 591 RES: 2.05 Content 592 ;ct=40 594 REQ: GET /sensors 596 RES: 2.05 Content 597 ;rt="temperature-c";if="sensor", 598 ;rt="light-lux";if="sensor" 600 An example query filter may look like: 602 REQ: GET /.well-known/core?rt=light-lux 604 RES: 2.05 Content 605 ;rt="light-lux";if="sensor" 607 Note that relation-type attributes like rt=, if= and rel= can have 608 multiple values separated by spaces. A query filter parameter can 609 match any one of those values, as in this example: 611 REQ: GET /.well-known/core?rt=light-lux 613 RES: 2.05 Content 614 ;rt="light-lux core.sen-light";if="sensor" 616 This example shows the use of an anchor attribute to relate the 617 temperature sensor resource to an external description and to an 618 alternative URI. 620 REQ: GET /.well-known/core 622 RES: 2.05 Content 623 ;ct=40;title="Sensor Index", 624 ;rt="temperature-c";if="sensor", 625 ;rt="light-lux";if="sensor", 626 ;anchor="/sensors/temp" 627 ;rel="describedby", 628 ;anchor="/sensors/temp";rel="alternate" 630 If a client is interested to find relations about a particular 631 resource, it can perform a query on the anchor parameter: 633 REQ: GET /.well-known/core?anchor=/sensors/temp 635 RES: 2.05 Content 636 ;anchor="/sensors/temp" 637 ;rel="describedby", 638 ;anchor="/sensors/temp";rel="alternate" 640 The following example shows a large firmware resource with a size 641 attribute. The consumer of this link would use the sz attribute to 642 determine if the resource representation is too large and if block 643 transfer would be required to request it. In this case a client with 644 only a 64 KiB flash might only support a 16-bit integer for storing 645 the sz attribute. Thus a special flag or value should be used to 646 indicate "Big" (larger than 64 KiB). 648 REQ: GET /.well-known/core?rt=firmware 650 RES: 2.05 Content 651 ;rt="firmware";sz=262144 653 6. Security Considerations 655 This specification has the same security considerations as described 656 in Section 7 of [RFC5988]. The "/.well-known/core" resource MAY be 657 protected e.g. using DTLS when hosted on a CoAP server as per 658 [I-D.ietf-core-coap] Section 10.2. 660 Some servers might provide resource discovery services to a mix of 661 clients that are trusted to different levels. For example, a 662 lighting control system might allow any client to read state 663 variables, but only certain clients to write state (turn lights on or 664 off). Servers that have authentication and authorization features 665 SHOULD support authentication features of the underlying transport 666 protocols (HTTP or DTLS/TLS) and allow servers to return different 667 lists of links based on a client's identity and authorization. While 668 such servers might not return all links to all requesters, not 669 providing the link does not, by itsef, control access to the relevant 670 resource - a bad actor could know or guess the right URIs. Servers 671 can also lie about the resources available. If it is important for a 672 client to only get information from a known source, then that source 673 needs to be authenticated. 675 Multicast requests using CoAP for the well-known link-format 676 resources could be used to perform denial of service on a constrained 677 network. A multicast request SHOULD only be accepted if the request 678 is sufficiently authenticated and secured using e.g. IPsec or an 679 appropriate object security mechanism. 681 CoRE link format parsers should be aware that a link description may 682 be cyclical, i.e., contain a link to itself. These cyclical links 683 could be direct or indirect (i.e., through referenced link 684 resources). Care should be taken when parsing link descriptions and 685 accessing cyclical links. 687 7. IANA Considerations 689 7.1. Well-known 'core' URI 691 This memo registers the "core" well-known URI in the Well-Known URI 692 Registry as defined by [RFC5785]. 694 URI suffix: core 696 Change controller: IETF 698 Specification document(s): [[ this document ]] 700 Related information: None 702 7.2. New 'hosts' relation type 704 This memo registers the new "hosts" Web Linking relation type as per 705 [RFC5988]. 707 Relation Name: hosts 709 Description: Refers to a resource hosted by the server indicated by 710 the link context. 712 Reference: [[ this document ]] 714 Notes: This relation is used in CoRE where links are retrieved as a 715 "/.well-known/core" resource representation, and is the default 716 relation type in the CoRE Link Format. 718 Application Data: None 720 7.3. New link-format Internet media type 722 This memo registers the a new Internet media type for the CoRE link 723 format, application/link-format. 725 Type name: application 727 Subtype name: link-format 729 Required parameters: None 731 Optional parameters: None 733 Encoding considerations: Binary data (UTF-8) 735 Security considerations: 737 Multicast requests using CoAP for the well-known link-format 738 resources could be used to perform denial of service on a constrained 739 network. A multicast request SHOULD only be accepted if the request 740 is sufficiently authenticated and secured using e.g. IPsec or an 741 appropriate object security mechanism. 743 CoRE link format parsers should be aware that a link description may 744 be cyclical, i.e., contain a link to itself. These cyclical links 745 could be direct or indirect (i.e., through referenced link 746 resources). Care should be taken when parsing link descriptions and 747 accessing cyclical links. 749 Interoperability considerations: 751 Published specification: [[ this document ]] 753 Applications that use this media type: CoAP server and client 754 implementations for resource discovery and HTTP applications that use 755 the link-format as a payload. 757 Additional information: 759 Magic number(s): 761 File extension(s): *.wlnk 763 Macintosh file type code(s): 765 Intended usage: COMMON 767 Restrictions on usage: None 769 Author: CoRE WG 771 Change controller: IETF 773 7.4. Constrained RESTful Environments (CORE) Parameters Registry 775 This specification establishes a new Constrained RESTful Environments 776 (CORE) Parameters registry, which contains two new sub-registries of 777 Link Target Attribute values (defined in [RFC5988]), one for Resource 778 Type (rt=) Link Target Attribute values and the other for Interface 779 Description (if=) Link Target Attribute values. No initial entries 780 are defined by this specification for either sub-registry. 782 For both sub-registries, values starting with the characters "core" 783 are registered using the IETF Review registration policy [RFC5226]. 784 All other values are registered using the Specification Required 785 policy, which requires review by a designated expert appointed by the 786 IESG or their delegate. 788 The designated expert will enforce the following requirements: 790 o Registration values MUST be related to the intended purpose of 791 these attributes as described in Section 3. 793 o Registered values MUST conform to the ABNF reg-rel-type definition 794 of Section 2, meaning that the value starts with a lower case 795 alphabetic character, followed by a sequence of lower case 796 alphabetic, numeric, "." or "-" characters, and contains no white 797 space. 799 o It is recommended that the period "." character be used for 800 dividing name segments, and that the dash "-" character be used 801 for making a segment more readable. Example Interface Description 802 values might be "core.batch" and "core.link-batch". 804 o URIs are reserved for free use as extension values for these 805 attributes, and MUST NOT be registered. 807 Registration requests consist of the completed registration template 808 below, with the reference pointing to the required specification. To 809 allow for the allocation of values prior to publication, the 810 designated expert may approve registration once they are satisfied 811 that a specification will be published. 813 Note that link target attribute values can be registered by third 814 parties, if the Designated Expert determines that an unregistered 815 link target attribute values is widely deployed and not likely to be 816 registered in a timely manner. 818 The registration template for both sub-registries is: 820 o Attribute Value: 822 o Description: 824 o Reference: 826 o Notes: [optional] 828 Registration requests should be sent to the core-parameters@ietf.org 829 mailing list, marked clearly in the subject line (e.g., "NEW RESOURCE 830 TYPE - example" to register an "example" relation type, or "NEW 831 INTERFACE DESCRIPTION - example" to register an "example" interface 832 description). 834 Within at most 14 days of the request, the Designated Expert(s) will 835 either approve or deny the registration request, communicating this 836 decision to the review list and IANA. Denials should include an 837 explanation and, if applicable, suggestions as to how to make the 838 request successful. 840 Decisions (or lack thereof) made by the Designated Expert can be 841 first appealed to Application Area Directors (contactable using 842 app-ads@tools.ietf.org email address or directly by looking up their 843 email addresses on http://www.iesg.org/ website) and, if the 844 appellant is not satisfied with the response, to the full IESG (using 845 the iesg@iesg.org mailing list). 847 8. Acknowledgments 849 Special thanks to Peter Bigot, who has made a considerable number 850 reviews and text contributions that greatly improved the document. 851 In particular, Peter is responsible for early improvements to the 852 ABNF descriptions and the idea for a new "hosts" relation type. 854 Thanks to Mark Nottingham and Eran Hammer-Lahav for the discussions 855 and ideas that led to this draft, and to Carsten Bormann, Martin 856 Thomson, Alexey Melnikov, Julian Reschke, Joel Halpern, Richard 857 Barnes, Barry Leiba and Peter Saint-Andre for extensive comments and 858 contributions that improved the text. 860 Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido 861 Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey 862 Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin, 863 Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed 864 Beroset, Gilman Tolle, Robby Simpson, Colin O'Flynn and David Ryan 865 for helpful comments and discussions that have shaped the document. 867 9. Changelog 869 Changes from ietf-13 to ietf-14: 871 o Editorial clarifications. 873 o Examples and explanation for filtering when a target attribute 874 of relation-type contains multiple values. 876 Changes from ietf-12 to ietf-13: 878 o Improvements to the new CoRE Parameters registry 880 o Replaced the Section 4.1 ABNF Query Filter definition with a URI 881 Template (#240) 883 o Aligned examples with rt= and if= value rules 885 o Clarified that "href" can not be a link parameter 887 Changes from ietf-11 to ietf-12: 889 o Changed "uri" to "href" in the filter query (#200) 891 o Upgraded all ABNF to RFC5234 (#197) 893 o Put multiple rt= and if= values in a single attribute (as in 894 rel=) (#199) 896 o Use the Origin definition (#191) 898 o Clarified URI fetching rules (#196) 900 o Added access control and other security consideration 901 improvements (#189) 902 o Fixed normalization for query pattern matching (#192) 904 o Added an anchor restriction for hosts (#193) 906 o New rules for determining link context (#194) 908 o Described how to convert from HTTP Link Header (#190) 910 o Created a registry for rt= and if= values (#195) 912 o Integration of all other IETF LC and IESG comments. 914 Changes from ietf-10 to ietf-11: 916 o Fixed editorial nits. 918 Changes from ietf-09 to ietf-10: 920 o Changed to SHOULD NOT for multiple relation types (#178). 922 o Changed to SHOULD NOT for multicast response repression (#179). 924 o Updated ABNF for queries (#179). 926 o Editorial improvements from WGLC comments. 928 Changes from ietf-08 to ietf-09: 930 o Corrected ABNF and editorial nits. 932 o Elided empty responses to multicast request. 934 Changes from ietf-07 to ietf-08: 936 o IESG submission nits. 938 Changes from ietf-06 to ietf-07: 940 o Moved the Content-type attribute (ct=) to the base CoAP 941 specification. 943 Changes from ietf-05 to ietf-06: 945 o Added improved text about the encoding of the format as UTF-8, 946 but treating it as binary data without normalization. 948 Changes from ietf-04 to ietf-05: 950 o Removed mention of UTF-8 as this is already defined by RFC5988 951 (#158) 953 o Changed encoding considerations to "Binary data" (#157) 955 o Updated ABNF to disallow leading zeros in integers (#159) 957 o Updated examples and reference for coap-06 (#152) 959 o Removed the application/link-format CoAP code registration, now 960 included in the CoAP specification directly (#160) 962 Changes from ietf-03 to ietf-04: 964 o Removed the attribute registry (#145). 966 o Requested a CoAP media type for application/link-format (#144). 968 o Editorial and reference improvements from AD review (#146). 970 o Added a range limitation for ct attribute. 972 o Added security considerations and file extension for 973 application/link-format registration. 975 Changes from ietf-02 to ietf-03: 977 o Removed 'obs' attribute definition, now defined in the CoAP 978 Observation spec (#99). 980 o Changed Resource name (n=) to Resource type (rt=) and d= to if= 981 (#121). 983 o Hierarchical organization of links under /.well-known/core 984 removed (#95). 986 o Bug in Section 3.1 on byte-wise query matching fixed (#91). 988 o Explanatory text added about alternative Web link formats (#92). 990 o Fixed a bug in Section 2.2.4 (#93). 992 o Added use case examples (#89). 994 o Clarified how the CoRE link format is used and how it differs 995 from RFC5988 (#90, #98). 997 o Changed the Interface definition format to quoted-string to 998 match the resource type. 1000 o Added an IANA registry for CoRE Link Format attributes (#100). 1002 Changes from ietf-01 to ietf-02: 1004 o Added references to RFC5988 (#41). 1006 o Removed sh and id link-extensions (#42). 1008 o Defined the use of UTF-8 (#84). 1010 o Changed query filter definition for any parameter (#70). 1012 o Added more example, now as a separate section (#43). 1014 o Mentioned cyclical links in the security section (#57). 1016 o Removed the sh and id attributes, added obs and sz attributes 1017 (#42). 1019 o Improved the context and relation description wrt RFC5988 and 1020 requested a new "hosts" default relation type (#85). 1022 Changes from ietf-00 to ietf-01: 1024 o Editorial changes to correct references. 1026 o Formal definition for filter query string. 1028 o Removed URI-reference option from "n" and "id". 1030 o Added security text about multicast requests. 1032 Changes from shelby-00 to ietf-00: 1034 o Fixed the ABNF link-extension definitions (quotes around URIs, 1035 integer definition). 1037 o Clarified that filtering is optional, and the query string is to 1038 be ignored if not supported (and the URI path processed as 1039 normally). 1041 o Required support of wildcard * processing if filtering is 1042 supported. 1044 o Removed the assumption of a default content-type. 1046 10. References 1048 10.1. Normative References 1050 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1051 Requirement Levels", BCP 14, RFC 2119, March 1997. 1053 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1054 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1055 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1057 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1058 10646", STD 63, RFC 3629, November 2003. 1060 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1061 Resource Identifier (URI): Generic Syntax", STD 66, 1062 RFC 3986, January 2005. 1064 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 1065 Registration Procedures", BCP 13, RFC 4288, December 2005. 1067 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1068 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1069 May 2008. 1071 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1072 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1074 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1075 Languages", BCP 47, RFC 5646, September 2009. 1077 [RFC5987] Reschke, J., "Character Set and Language Encoding for 1078 Hypertext Transfer Protocol (HTTP) Header Field 1079 Parameters", RFC 5987, August 2010. 1081 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1083 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1084 and D. Orchard, "URI Template", RFC 6570, March 2012. 1086 10.2. Informative References 1088 [I-D.ietf-core-coap] 1089 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 1090 "Constrained Application Protocol (CoAP)", 1091 draft-ietf-core-coap-09 (work in progress), March 2012. 1093 [REST] Fielding, R., "Architectural Styles and the Design of 1094 Network-based Software Architectures", 2000, . 1097 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 1098 STD 13, RFC 1034, November 1987. 1100 [RFC1035] Mockapetris, P., "Domain names - implementation and 1101 specification", STD 13, RFC 1035, November 1987. 1103 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1104 Extensions (MIME) Part One: Format of Internet Message 1105 Bodies", RFC 2045, November 1996. 1107 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1108 Syndication Format", RFC 4287, December 2005. 1110 [RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6 1111 over Low-Power Wireless Personal Area Networks (6LoWPANs): 1112 Overview, Assumptions, Problem Statement, and Goals", 1113 RFC 4919, August 2007. 1115 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1116 Uniform Resource Identifiers (URIs)", RFC 5785, 1117 April 2010. 1119 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1120 December 2011. 1122 [WADL] Hadley, M., "Web Application Description Language (WADL)", 1123 2009, . 1126 Author's Address 1128 Zach Shelby 1129 Sensinode 1130 Kidekuja 2 1131 Vuokatti 88600 1132 FINLAND 1134 Phone: +358407796297 1135 Email: zach@sensinode.com