idnits 2.17.1 draft-ietf-core-link-format-03.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 (March 14, 2011) is 4785 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) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-04 -- 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 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 5785 (Obsoleted by RFC 8615) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 4 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 March 14, 2011 5 Expires: September 15, 2011 7 CoRE Link Format 8 draft-ietf-core-link-format-03 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 September 15, 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 . . . . . . . . . . . . . . . . . . . . . 10 72 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 73 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 74 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 75 7.1. Attribute Registry . . . . . . . . . . . . . . . . . . . . 13 76 7.2. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 14 77 7.3. New 'hosts' relation type . . . . . . . . . . . . . . . . 14 78 7.4. New link-format Internet media type . . . . . . . . . . . 15 79 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15 80 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 16 81 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 82 10.1. Normative References . . . . . . . . . . . . . . . . . . . 18 83 10.2. Informative References . . . . . . . . . . . . . . . . . . 18 84 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 19 86 1. Introduction 88 The Constrained RESTful Environments (CoRE) working group aims at 89 realizing the Representational State Transfer (REST) architecture 90 [REST] in a suitable form for the most constrained nodes (e.g. 8-bit 91 microcontrollers with limited memoryt) and networks (e.g. 6LoWPAN 92 [RFC4944]). 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 this document 101 we refer to the discovery of resources hosted by a constrained web 102 server, their attributes and other resource relations as CoRE 103 Resource Discovery. 105 The main function of such a discovery mechanism is to provide 106 Universal Resource Indicators (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 URI "/.well-known/ 115 core" is defined as a default entry-point for requesting the list of 116 links about resources hosted by a server, and thus performing CoRE 117 Resource Discovery. 119 1.1. Web Linking in CoRE 121 What is the difference between the CoRE Link Format and [RFC5988]? 122 Technically the CoRE Link Format is a serialization of a typed link 123 as specified in [RFC5988], used to describe relationships between 124 resources, so-called "Web Linking". In this specification Web 125 Linking is extended with specific constrained M2M attributes, links 126 are carried as a message payload rather than in an HTTP Link Header, 127 and a default interface is defined to discover resources hosted by a 128 server. This specification also defines a new relation type "hosts", 129 which indicates that the resource is hosted by the server from which 130 the link document was requested. 132 Why not just use the HTTP Link Header? In HTTP, the Link Header can 133 be used to carry link information about a resource along with an HTTP 134 response. This works well for the typical use case for a web server 135 and browser, where further information about a particular resource is 136 useful after accessing it. In CoRE the main use case for Web Linking 137 is the discovery of which resources a server hosts in the first 138 place. Although some resources may have further links associated 139 with them, this is expected to be an exception. For that reason the 140 CoRE Link Format serialization is carried as a resource 141 representation of a well-known URI. The CoRE Link Format does re-use 142 the format of the HTTP Link Header serialization defined in 143 [RFC5988]. 145 1.2. Use Cases 147 Typical use cases for Web Linking on today's web include e.g. 148 describing the author of a web page, or describing relations between 149 web pages (next chapter, previous chapter etc.). Web Linking can 150 also be applied to M2M applications, where typed links are used to 151 assist a machine client in finding and understanding how to use 152 resources on a server. In this section a few use cases are described 153 for how the CoRE Link Format could be used in M2M applications. For 154 further technical examples see Section 5. As there are a large range 155 of M2M applications, these use cases are purposely generic. This 156 document assumes that different deployments or application domains 157 will define the appropraite REST interface descriptions along with 158 Resource Types to make discovery meaniningful. 160 1.2.1. Discovery 162 In M2M application, for example home or building automation, there is 163 a need for local clients and servers to find and interact with each 164 other without human intervention. The CoRE Link Format can be used 165 by servers in such environments to enable Resource Discovery of the 166 resources hosted by the server. 168 Resource Discovery can be performed either unicast or multicast. 169 When a server's IP address is already known, either a priori or 170 resolved via the Domain Name System (DNS), unicast disovery is 171 performed in order to locate the entry point to the resource of 172 interest. This is performed using a GET to /.well-known/core on the 173 server, which returns a payload in the CoRE Link Format. A client 174 would then match the appropriate Resource Type, Interface Description 175 and possible Content-Type for its application. These attributes may 176 also be included in the query string in order to filter the number of 177 links returned in a response. 179 Multicast resource discovery is useful when a client needs to locate 180 a resource within a limited scope, and that scope supports IP 181 multicast. A GET request to the appropriate multicast address is 182 made for /.well-known/core. In order to limit the number and size or 183 responses, a query string is recommended with the known attributes. 184 Typically a resource would be discovered based on its Resource Type 185 and/or Interface Description, along with possible application 186 specific attributes. 188 1.2.2. Resource Collections 190 RESTful designs of M2M interfaces often make use of collections of 191 resources. For example an index of temprature sensors on a data 192 collection node or a list of alarms on a home security controller. 193 The CoRE Link Format can be used to make it possible to find the 194 entry point to a collection and traverse its members. The entry 195 point of a collection would always be included in /.well-known/core 196 to enable its discovery. The members of the collection can be 197 defined either through the interface description of the resource 198 along with a parameter resource for the size of the collection, or by 199 using the link format to describe each resource in the collection. 200 These links could be located under /.well-known/core or hosted for 201 example in the root resource of the collection. 203 1.2.3. Resource Directory 205 In many deployment scenarios, for example constrained networks with 206 sleeping servers, or large M2M deployments with bandwidth limited 207 access networks, it makes sense to deploy resource directory entities 208 which store links to resources stored on other servers. Think of 209 this as a limited search engine for constrained M2M resources. 211 The CoRE Link Format can be used by a server to register resources 212 with a resource directory, or to allow a resource directory to poll 213 for resources. Resource polling uses the same process as unicast or 214 multicast discovery, however usually without filtering. Resource 215 registration can be achived by having each server POST their 216 resources to /.well-known/core on the resource directory. This in 217 turn adds links to the resource directory under an appropriate 218 resource. These links can then be discovered by any client by a 219 performing a GET on the resource directory using a query string 220 filter. 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 document are to be interpreted as described in [RFC2119]. 228 This specification requires readers to be familiar with all the terms 229 and concepts that are discussed in [RFC5988]. This specification 230 makes use of the following terminology: 232 Web Linking 233 A framework for indicating the relationships between web 234 resources. 236 Link 237 Also called "typed links" in RFC5988. A link is a typed 238 connection between two resources identified by URIs. Made up of a 239 context URI, a link relation type, a tarfet URI, and optional 240 target attributes. 242 Link Format 243 A particular serialisation of typed links. 245 CoRE Link Format 246 A particular serialization of typed links based the HTTP Link 247 Header serialization defined in Section 5 of RFC5988, but carried 248 as a resource representation with a MIME type. 250 Attribute 251 Properly called "Target Attribute" in RFC5988. A set of key/value 252 pairs that descibe the link or its target. 254 CoRE Resource Discovery 255 When a client discovers the list of resources hosted by a server, 256 their attributes and other link relations by accessing /.well- 257 known/core. 259 2. Link Format 261 The CoRE Link Format extends the HTTP Link Header format specified in 262 [RFC5988], which is specified in Augmented Backus-Naur Form (ABNF) 263 notation [RFC5234]. The format does not require special XML or 264 binary parsing, is fairly compact, and is extensible - all important 265 characteristics for CoRE. It should be noted that this link format 266 is just one serialization of typed links defined in [RFC5988], others 267 include HTML link, Atom feed links [RFC4287] or HTTP Link Headers. 268 It is expected that resources discovered in the CoRE Link Format may 269 also be made available in alternative formats on the greater 270 Internet. The CoRE Link Format is only expected to be supported in 271 constrained networks and M2M systems. 273 Section 5 of [RFC5988] did not require an Internet media type for the 274 defined link format, as it was defined to be carried in an HTTP 275 header. This specification thus defines a Internet media type for 276 the CoRE Link Format (see Section 7.4). 278 The CoRE link format uses the ABNF description and associated rules 279 in Section 5 of [RFC5988]. In addition, the pchar rule is taken from 280 [RFC3986]. The "Link:" text is omitted as that is part of the HTTP 281 Link Header. As in [RFC5988], multiple link descriptions are 282 separated by commas. Note that commas can also occur in quoted 283 strings and URIs but do not end a description. The CoRE link format 284 MUST use UTF-8 encoding, which SHOULD be in NFC (Unicode 285 Normalization Form C). See Section 3 of [RFC5198], which explains 286 why it useful to represent Unicode in a single unique form. 288 2.1. Target and context URIs 290 Each link conveys one target URI as a URI-reference inside angle 291 brackets ("<>"). The context URI of a link (also called base URI in 292 [RFC3986]) conveyed in the CoRE Link Format is by default built from 293 the scheme and authority parts of the target URI. In the absence of 294 this information in the target URI, the context URI is built from the 295 scheme and authority that was used for referencing the resource 296 returning the set of links, replacing the path with an empty path. 297 Thus by default links can be thought of as describing a target 298 resource hosted by the server. Other relations can be expressed by 299 including an anchor parameter (which defines the context URI) along 300 with an explicit relation parameter. This is an important difference 301 to the way the HTTP Link Header format is used, as it is included in 302 the header of an HTTP response for some URI (this URI is by default 303 the context URI). Thus the HTTP Link Header is by default relating 304 the target URI to the URI that was requested. In comparison, the 305 CoRE link format includes one or more links, each describing a 306 resource hosted by a server by default. Other relations can be 307 expressed by using the anchor parameter. See Section 5 of [RFC3986] 308 for a description of how URIs are constructed from URI references. 310 2.2. Link relations 312 Since links in the CoRE Link Format are typically used to describe 313 resources hosted by a server, and thus in the absence of the relation 314 parameter the new relation type "hosts" is assumed (see Section 7.3). 315 The "hosts" relation type indicates that the target URI is a resource 316 hosted by the server given by the base URI, or, if present, the 317 anchor parameter. 319 To express other relations a links can make use of any registered 320 relation parameter or target attributes by including the relation 321 parameter. The context of a relation can be defined using the anchor 322 parameter. In this way, relations between resources hosted on a 323 server, or between hosted resources and external resources can be 324 expressed. 326 2.3. Use of anchors 328 As per Section 5.2 of [RFC5988] a link description MAY include an 329 "anchor" attribute, in which case the context is the URI included in 330 that attribute. This is used to describe a relationship between two 331 resources. A consuming implementation can however choose to ignore 332 such links. It is not expected that all implementations will be able 333 to derive useful information from explicitly anchored links. 335 3. CoRE link extensions 337 The following CoRE specific target attributes are defined. These 338 attributes describe information useful in accessing the target link 339 of the relation, and in some cases may be URIs. These URIs MUST be 340 treated as indicators, and are not meant to be actually retrieved 341 like a URL. When attributes are compared, they MUST be compared as 342 strings. Relationships to resources that are meant to be retrieved 343 should be expressed as separate links using the anchor attribute and 344 the appropriate relation type. 346 link-extension = ( "rt" "=" quoted-string ) 347 link-extension = ( "if" "=" quoted-string ) 348 link-extension = ( "ct" "=" integer ) 349 link-extension = ( "sz" "=" integer ) 350 integer = 1*DIGIT 352 3.1. Resource type 'rt' attribute 354 The resource type "rt" attribute is used to assign a semantically 355 important type to a resource. One can think of this as a noun 356 describing the resource. In the case of a temperature resource this 357 could be an application-specific semantic type like 358 "OutdoorTemperature", a Universal Resource Name (URN) like 359 "urn:temperature:outdoor" or a URI referencing a specific concept in 360 an ontology like 361 "http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature". Multiple 362 resource type attributes MAY appear in a link. 364 The resource type attribute is not meant to used to assign a human 365 readable name to a resource. The "title" attribute defined in 366 [RFC5988] is meant for that purpose. 368 3.2. Interface description 'if' attribute 370 The interface description "if" attribute is used to provide a name, 371 URI or URN indicating a specific interface definition used to 372 interact with the target resource. One can think of this as 373 describing verbs usable on a resource. The interface description 374 attribute is meant to describe the generic REST interface to interact 375 with a resource or a set of resources. It is expected that an 376 interface description will be re-used by different resource types. 377 For example the resource types "OutdoorTemperature", "DewPoint" and 378 "RelHumidity" could all be accessible using the interface description 379 "http://www.example.org/myapp.wadl#sensor". 381 The interface description could be for example the URI of a Web 382 Application Description Language (WADL) definition of the target 383 resource "http://www.example.org/myapp.wadl#sensor", a URN indicating 384 the type of interface to the resource "urn:myapp:sensor", or an 385 application-specific name "Sensor". Multiple interface description 386 attributes MAY appear in a link. 388 3.3. Content-type code 'ct' attribute 390 The Content-type code "ct" attribute provides a hint about the 391 Internet media type this resource returns. Note that this is only a 392 hint, and does not override the Content-type Option of a CoAP 393 response obtained by actually following the link. The value is in 394 the CoAP identifier code format as a decimal ASCII integer 395 [I-D.ietf-core-coap]. For example application/xml would be indicated 396 as "ct=41". If no Content-type code attribute is present then 397 nothing about the type can be assumed. The Content-type code 398 attribute MUST NOT appear more than once in a link. 400 Alternatively, the "type" attribute MAY be used to indicate an 401 Internet media type as a quoted-string [RFC5988]. It is not however 402 expected that constrained implementations are able to parse quoted- 403 string Content-type values. A link MAY include either a ct attribute 404 or a type attribute, but MUST NOT include both. 406 3.4. Maximum size estimate 'sz' attribute 408 The maximum size estimate attribute "sz" gives an indication of the 409 maximum size of the resource indicated by the target URI. This 410 attribute is not expected to be included for small resources that can 411 comfortably by carried in a single Maxiumum Transmission Unit (MTU), 412 but SHOULD be included for resources larger than that. The maximum 413 size estimate attribute MUST NOT appear more than once in a link. 415 4. Well-known Interface 417 Resource discovery in CoRE is accomplished through the use of a well- 418 known resource URI which returns a list of links about resources 419 hosted by that server and other link relations. Well-known resources 420 have a path component that begins with "/.well-known/" as specified 421 in [RFC5785]. This document defines a new well-known resource for 422 CoRE Resource Discovery "/.well-known/core". 424 A server implementing this specification MUST support this resource 425 on the default port appropriate for the protocol for the purpose of 426 resource discovery. It is however up to the application which links 427 are included and how they are organized. The resource /.well-known/ 428 core is meant to be used to return links to the entry points of 429 resource interfaces on a server. More sophisticated link 430 organization can be achieved by including links to CoRE Link Format 431 resources located elsewhere on the server, for example to achieve an 432 index. In the absence of any links, a zero-length payload is 433 returned. The resource representation of this resource MUST be the 434 CoRE Link Format described in Section 2. 436 The CoRE resource discovery interface supports the following 437 interactions: 439 o Performing a GET on /.well-known/core to the default port returns 440 a set of links available from the server (if any) in the CoRE Link 441 Format. These links might describe resources hosted on that 442 server, on other servers, or express other kinds of link relations 443 as described in Section 2. 445 o Filtering may be performed on any of the link format attributes 446 using a query string as specified in Section 4.1. For example 447 [GET /.well-known/core?n=TemperatureC] would request resources 448 with the name TemperatureC. A server is not however required to 449 support filtering. 451 o More capable servers such as proxies could support a resource 452 directory by requesting the resource descriptions of other end- 453 points or allowing servers to POST requests to /.well-known/core. 454 The details of such resource directory functionality is however 455 out of scope for this document, and is expected to be specified 456 separately. 458 4.1. Query Filtering 460 A server implementing this document MAY recognize the query part of a 461 resource discovery URI as a filter on the resources to be returned. 462 The query part should conform to the following syntax. Note that 463 this only defines querying for a single parameter at a time. 465 filter-query = resource-param "=" query-pattern 466 resource-param = "uri" | parmname 467 query-pattern = 1*pchar [ "*" ] 469 The resource-param "uri" refers to the URI-reference between the "<" 470 and ">" characters of a link. Other resource-param values refer to 471 the link attribute they name. Filtering is performed by comparing 472 the query-pattern against the value of the attribute identified by 473 the resource-param for each link-value in the collection of resources 474 identified by the URI path. 476 If the decoded query-pattern does not end with "*", a link value 477 matches the query only if the value of the attribute or URI-reference 478 denoted by the resource-param is bytewise identical to the query- 479 pattern. If the decoded query-pattern ends with "*", it is 480 sufficient that the remainder of the query-pattern be a prefix of the 481 value denoted by the resource-param. It is not expected that very 482 constrained nodes support filtering. Implementations not supporting 483 filtering MUST simply ignore the query string and return the whole 484 resource for unicast requests. 486 When using a transfer protocol like the Constrained Application 487 Protocol (CoAP) that supports multicast requests, special care is 488 taken. A multicast request with a query string MUST not be responded 489 to if filtering is not supported (to avoid a needless response 490 storm). 492 5. Examples 494 A few examples of typical link descriptions in this format follows. 495 Multiple resource descriptions in a representation are separated by 496 commas. Linefeeds never occur in the actual format, but are shown in 497 the example for readability. 499 This example includes links to two different sensors sharing the same 500 interface description. 502 REQ: GET /.well-known/core 504 RES: 200 OK 505 ;ct=41;rt="TemperatureC";if="sensor", 506 ;ct=41;rt="LightLux";if="sensor" 507 This example arranges link descriptions hierarchically, with the 508 entry point including a link to a sub-resource containing links about 509 the sensors. 511 REQ: GET /.well-known/core 513 RES: 200 OK 514 ;rt="index";ct=40 516 REQ: GET /sensors 518 RES: 200 OK 519 ;ct=41;rt="TemperatureC";if="sensor", 520 ;ct=41;rt="LightLux";if="sensor" 522 An example query filter may look like: 524 REQ: GET /.well-known/core?rt=LightLux 526 RES: 200 OK 527 ;ct=41;rt="LightLux";if="sensor" 529 This example shows the use of an anchor attribute to relate the 530 temperature sensor resource to an external description and to an 531 alternative URL. 533 REQ: GET /.well-known/core 535 RES: 200 OK 536 ;ct=40;rt="index";rt="Sensor Index", 537 ;rt="TemperatureC";if="sensor", 538 ;ct=41;rt="LightLux";if="sensor", 539 ;anchor="/sensors/temp" 540 ;rel="describedby", 541 ;anchor="/sensors/temp";rel="alternate" 543 If a client is interested to find relations about a particular 544 resource, it can perform a query on the anchor parameter: 546 REQ: GET /.well-known/core?anchor=/sensors/temp 548 RES: 200 OK 549 ;anchor="/sensors/temp" 550 ;rel="describedby", 551 ;anchor="/sensors/temp";rel="alternate" 553 6. Security Considerations 555 This document needs the same security considerations as described in 556 Section 7 of [RFC5988]. The /.well-known/core resource may be 557 protected e.g. using DTLS when hosted on a CoAP server as per 558 [I-D.ietf-core-coap] Section 10.2. 560 Multicast requests using CoAP for the well-known link-format 561 resources could be used to perform denial of service on a constrained 562 network. A multicast request SHOULD only be accepted if the request 563 is sufficiently authenticated and secured. 565 CoRE link format parsers should be aware that a link description may 566 be cyclical, i.e., contain a link to itself. These cyclical links 567 could be direct or indirect (i.e., through referenced link 568 resources). Care should be taken when parsing link descriptions and 569 accessing cyclical links. 571 7. IANA Considerations 573 7.1. Attribute Registry 575 This document defines a registry for the link extension attributes 576 defined for use with the CoRE Link Format. The name of the registry 577 is "CoRE Link Format Attributes". 579 Each entry in the registry must include the attribute name, the 580 attribute, the format of the attribute and a reference to the 581 attribute's documentation. 583 Initial entries in this registry are as follows: 585 +-----------------------+-----------+---------------+-----------+ 586 | Name | Attribute | Type | Reference | 587 +-----------------------+-----------+---------------+-----------+ 588 | Resource Type | rt | Quoted String | &SELF; | 589 | Interface Description | if | Quoted String | &SELF; | 590 | Content-Type | ct | Integer | &SELF; | 591 | Maximum Size Estimate | sz | Integer | &SELF; | 592 +-----------------------+-----------+---------------+-----------+ 594 Table 1: CoAP Option Numbers 596 New attributes defined for the CoRE Link Format MUST NOT collide with 597 existing attributes defined in [RFC5988]. 599 The IANA policy for future additions to this registry is "IETF 600 Review" as described in [RFC5226]. 602 The documentation of an attribute should specify the semantics of the 603 attribute, including the following properties: 605 o The meaning of the attribute. 607 o The format of the attribute's value. 609 o Whether the attribute can occur multiple times. 611 o The default value, if any. 613 7.2. Well-known 'core' URI 615 This memo registers the "core" well-known URI in the Well-Known URI 616 Registry as defined by [RFC5785]. 618 URI suffix: core 620 Change controller: IETF 622 Specification document(s): [[ this document ]] 624 Related information: None 626 7.3. New 'hosts' relation type 628 This memo registers the new "hosts" Web Linking relation type as per 629 [RFC5988]. 631 Relation Name: hosts 633 Description: Refers to a resource hosted by the server indicated by 634 the link context. 636 Reference: [[ this document ]] 638 Notes: This relation is used in CoRE where links are retrieved as a 639 /.well-known/core resource representation, and by default the context 640 of the links is the server at coap://authority from which /.well- 641 known/core was requested. 643 Application Data: None 645 7.4. New link-format Internet media type 647 This memo registers the a new Internet media type for the CoRE link 648 format, application/link-format. 650 Type name: application 652 Subtype name: link-format 654 Required parameters: None 656 Optional parameters: The query string may contain uri= to match the 657 URI, or any other attribute defined for the link format to match that 658 attribute as defined in this document. 660 Encoding considerations: UTF-8 (NFC) 662 Security considerations: None 664 Interoperability considerations: 666 Published specification: [[ this document ]] 668 Applications that use this media type: CoAP server and client 669 implementations for resource discovery and HTTP applications that use 670 the link-format as a payload. 672 Additional information: 674 Magic number(s): 676 File extension(s): 678 Macintosh file type code(s): 680 Intended usage: COMMON 682 Restrictions on usage: None 684 Author: CoRE WG 686 Change controller: IETF 688 8. Acknowledgments 690 Special thanks to Peter Bigot, who has made a considerable number 691 reviews and text contributions that greatly improved the document. 693 In particular, Peter is responsible for the ABNF descriptions and the 694 idea for a new "hosts" relation type. 696 Thanks to Mark Nottingham and Eran Hammer-Lahav for the discussions 697 and ideas that led to this draft, and to Carsten Bormann, Martin 698 Thomson and Peter Saint-Andre for extensive comments and 699 contributions that improved the text. 701 Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido 702 Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey 703 Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin, 704 Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed 705 Beroset, Gilman Tolle, Robby Simpson, Colin O'Flynn and David Ryan 706 for helpful comments and discussions that have shaped the document. 708 9. Changelog 710 Changes from ietf-02 to ietf-03: 712 o Removed 'obs' attribute definition, now defined in the CoAP 713 Observation spec (#99). 715 o Changed Resource name (n=) to Resource type (rt=) and d= to if= 716 (#121). 718 o Hierarchical organization of links under /.well-known/core 719 removed (#95). 721 o Bug in Section 3.1 on byte-wise query matching fixed (#91). 723 o Explanatory text added about alternative Web link formats (#92). 725 o Fixed a bug in Section 2.2.4 (#93). 727 o Added use case examples (#89). 729 o Clarified how the CoRE link format is used and how it differs 730 from RFC5988 (#90, #98). 732 o Changed the Interface definition format to quoted-string to 733 match the resource type. 735 o Added an IANA registry for CoRE Link Format attributes (#100). 737 Changes from ietf-01 to ietf-02: 739 o Added references to RFC5988 (#41). 741 o Removed sh and id link-extensions (#42). 743 o Defined the use of UTF-8 (#84). 745 o Changed query filter definition for any parameter (#70). 747 o Added more example, now as a separate section (#43). 749 o Mentioned cyclical links in the security section (#57). 751 o Removed the sh and id attributes, added obs and sz attributes 752 (#42). 754 o Improved the context and relation description wrt RFC5988 and 755 requested a new "hosts" default relation type (#85). 757 Changes from ietf-00 to ietf-01: 759 o Editorial changes to correct references. 761 o Formal definition for filter query string. 763 o Removed URI-reference option from "n" and "id". 765 o Added security text about multicast requests. 767 Changes from shelby-00 to ietf-00: 769 o Fixed the ABNF link-extension definitions (quotes around URIs, 770 integer definition). 772 o Clarified that filtering is optional, and the query string is to 773 be ignored if not supported (and the URL path processed as 774 normally). 776 o Required support of wildcard * processing if filtering is 777 supported. 779 o Removed the aussumption of a default content-type assumption. 781 10. References 782 10.1. Normative References 784 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 785 Requirement Levels", BCP 14, RFC 2119, March 1997. 787 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 788 Resource Identifier (URI): Generic Syntax", STD 66, 789 RFC 3986, January 2005. 791 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 792 Specifications: ABNF", STD 68, RFC 5234, January 2008. 794 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 796 10.2. Informative References 798 [I-D.ietf-core-coap] 799 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 800 "Constrained Application Protocol (CoAP)", 801 draft-ietf-core-coap-04 (work in progress), January 2011. 803 [REST] Fielding, "Architectural Styles and the Design of Network- 804 based Software Architectures", , 2000, . 807 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 808 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 809 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 811 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 812 Syndication Format", RFC 4287, December 2005. 814 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 815 "Transmission of IPv6 Packets over IEEE 802.15.4 816 Networks", RFC 4944, September 2007. 818 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 819 Interchange", RFC 5198, March 2008. 821 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 822 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 823 May 2008. 825 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 826 Uniform Resource Identifiers (URIs)", RFC 5785, 827 April 2010. 829 Author's Address 831 Zach Shelby 832 Sensinode 833 Kidekuja 2 834 Vuokatti 88600 835 FINLAND 837 Phone: +358407796297 838 Email: zach@sensinode.com