idnits 2.17.1 draft-ietf-core-link-format-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 131: '...commas. The CoRE link format MUST use...' RFC 2119 keyword, line 159: '... description MAY include an "anchor"...' RFC 2119 keyword, line 182: '...ption attributes MAY appear in a link ...' RFC 2119 keyword, line 188: '...t URI attributes MAY appear in a link ...' RFC 2119 keyword, line 198: '... name attributes MAY appear in a link ...' (10 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 18, 2010) is 4932 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-02 ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) == Outdated reference: A later version (-04) exists of draft-shelby-core-coap-req-02 Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). 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 October 18, 2010 5 Expires: April 21, 2011 7 CoRE Link Format 8 draft-ietf-core-link-format-00 10 Abstract 12 This document defines a link format for use by constrained CoAP web 13 servers to describe URIs of resources offered along with other 14 attributes. Based on the HTTP Link Header format, the CoRE link 15 format is carried as a payload and is assigned an Internet media 16 type. A well-known URI is defined as a default entry-point for 17 requesting the list of links to resources hosted by a server. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on April 21, 2011. 36 Copyright Notice 38 Copyright (c) 2010 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Link Format . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2.1. Target and context IRIs . . . . . . . . . . . . . . . . . 4 56 2.2. Link relation 'rel' usage . . . . . . . . . . . . . . . . 5 57 2.3. Description 'd' usage . . . . . . . . . . . . . . . . . . 5 58 2.4. Alternative URI 'sh' usage . . . . . . . . . . . . . . . . 5 59 2.5. Resource name 'n' usage . . . . . . . . . . . . . . . . . 5 60 2.6. Content-type code 'ct' usage . . . . . . . . . . . . . . . 5 61 2.7. Resource identifier 'id' usage . . . . . . . . . . . . . . 6 62 2.8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 3. Well-known Interface . . . . . . . . . . . . . . . . . . . . . 6 64 3.1. Query Filtering . . . . . . . . . . . . . . . . . . . . . 7 65 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 66 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 67 5.1. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 8 68 5.2. New link-format Internet media type . . . . . . . . . . . 8 69 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 70 7. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 9 71 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 72 8.1. Normative References . . . . . . . . . . . . . . . . . . . 10 73 8.2. Informative References . . . . . . . . . . . . . . . . . . 10 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10 76 1. Introduction 78 The Constrained RESTful Environments (CoRE) working group aims at 79 realizing the REST architecture in a suitable form for the most 80 constrained nodes (e.g. 8-bit microcontrollers with limited RAM and 81 ROM) and networks (e.g. 6LoWPAN). CoRE is aimed at machine-to- 82 machine (M2M) applications such as smart energy and building 83 automation [I-D.shelby-core-coap-req]. 85 The discovery of resources offered by a constrained server is very 86 important in machine-to-machine applications where there are no 87 humans in the loop and static interfaces result in fragility. The 88 discovery of resources provided by an HTTP Web Server is typically 89 called Web Discovery. In this document we refer to the discovery of 90 resources offered by a CoAP server as resource discovery. 92 The core function of such a discovery mechanism is to provide URIs 93 ("links") for the resources offered, complemented by information 94 describing the relationship between the resource description and each 95 resource as well as other attributes. When such a collection of 96 attributed resource references (links) is offered as a resource of 97 its own (as opposed to as HTTP headers delivered with a different 98 resource), we speak of its representation as a link-format. 100 This document specifies a link-format for use in CoRE resource 101 discovery by extending the HTTP Link Header Format 102 [I-D.nottingham-http-link-header] to describe resources hosted by a 103 constrained server. The CoRE link-format is carried as a payload and 104 is assigned an Internet media type. A well-known URI "/.well-known/ 105 core" is defined as a default entry-point for requesting the list of 106 links to resources hosted by a server. 108 2. Link Format 110 CoRE resource discovery extends the HTTP Link Header format specified 111 in [I-D.nottingham-http-link-header] which is specified in Augmented 112 Backus-Naur Form (ABNF) notation [RFC5234]. The format does not 113 require special XML or binary parsing, and is extensible. 115 This link format is used for a similar purpose to that described in 116 [I-D.nottingham-http-link-header], to describe one or more 117 relationships between resources. However in this specification the 118 link format is extended with specific constrained M2M link 119 parameters, links are carried as a payload rather than in a message 120 header, and a default interface is defined to discover resources 121 described by these links. 123 [I-D.nottingham-http-link-header] did not require an Internet media 124 type for this link format, as it assumes to be carried in an HTTP 125 header. This specification thus requests a Internet media type for 126 this format (see Section 5.2). 128 The CoRE link format uses the ABNF description and associated rules 129 in Section 5 of [I-D.nottingham-http-link-header]. The "Link:" text 130 is omitted as that is part of the HTTP Link Header. Multiple link 131 descriptions are separated by commas. The CoRE link format MUST use 132 the US-ASCII character set (support for RFC2231 encoding of non-ASCII 133 content TBD). The following CoRE specific link-extension parameters 134 to the format are defined: 136 link-extension = ( "d" "=" <"> URI <">) 137 link-extension = ( "sh" "=" <"> URI-Reference <">) 138 link-extension = ( "n" "=" ( quoted-string | URI ) ) 139 link-extension = ( "ct" "=" integer ) 140 link-extension = ( "id" "=" ( quoted-string | URI ) ) 141 integer = 1*DIGIT 143 2.1. Target and context IRIs 145 Each link description conveys one target URI as a URI-Reference 146 inside angle brackets ("<>"). The context of a link conveyed in the 147 description is by default the URI of the resource that returned the 148 link-format representation (usually ./well-known/core). Thus each 149 link can be thought of as describing a target resource hosted by the 150 server in the absence of further relation information. This is an 151 important difference to the way the HTTP Link Header format is used, 152 as it is included in the header of an HTTP response for some URI 153 (this URI is by default the context). Thus the HTTP Link Header is 154 by default relating the target URI to the URI that was requested. In 155 comparison, the CoRE link format includes one or more link entries, 156 each describing a resource hosted by a server. 158 As per Section 5.2 of [I-D.nottingham-http-link-header] a link 159 description MAY include an "anchor" attribute, in which case the 160 context is the URI included in that attribute. This can be used to 161 describe a relationship between two resources. A consuming 162 implementation can however choose to ignore such links. It is not 163 expected that most implementations will be able to derive useful from 164 explicitly anchored links. 166 2.2. Link relation 'rel' usage 168 Link descriptions in CoRE are typically used to describe entry points 169 to services hosted by the server, and thus in the absence of the rel 170 attribute the registered "service" relation type is assumed. In the 171 CoRE link format the service relation type indicates that the link is 172 a service hosted by the server (in the absence of the anchor 173 attribute). A description can make use of any registered relation 174 type or extension types in the form of a URI by including the rel 175 attribute. 177 2.3. Description 'd' usage 179 The description "d" attribute can provide a URI to a specific 180 interface definition used to access the target resource. This could 181 be for example a URI to the WADL definition of the target resource. 182 Multiple description attributes MAY appear in a link description. 184 2.4. Alternative URI 'sh' usage 186 This attribute can be included to define an alternative short URI 187 which can also be used to access the target resource. Multiple 188 alternative short URI attributes MAY appear in a link description. 190 2.5. Resource name 'n' usage 192 The resource name "n" attribute is used to assign eith a human 193 readable or a semantically important name to a resource. In the case 194 of a temperature sensor resource the name could be something like 195 "Temperature in Centigrade", a URI to an ontology like 196 "http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature" or an 197 application-specific semantic name like "TemperatureC". Multiple 198 name attributes MAY appear in a link description. 200 2.6. Content-type code 'ct' usage 202 The Content-type code "ct" attribute provides a hint about the 203 Internet media type this resource returns. The value is in the CoAP 204 identifier code format as a decimal ASCII integer 205 [I-D.ietf-core-coap]. For example application/xml would be indicated 206 as "ct=41". If no Content-type code attribute is present then 207 nothing about the type can be assumed. The Content-type code 208 attribute MUST NOT appear more than once in a link description. 210 Alternatively, the "type" attribute MAY be used to indicate an 211 Internet media type as a quoted-string. It is not however expected 212 that constrained implementations are able to parse quoted-string 213 Content-type values. 215 2.7. Resource identifier 'id' usage 217 The resource identifier "id" field is a unique identifier (e.g. UUID 218 or XRI) for this resource for use in e.g. resource or search 219 directories. The resource identifier attribute MUST NOT appear more 220 than once in a link description. 222 2.8. Examples 224 A few examples of typical link descriptions in this format follows. 225 Multiple resource descriptions in a representation are separated by 226 commas. Commas can also occur in quoted strings and URIs but do not 227 end a description. Linefeeds never occur in the actual format, but 228 are shown in the example for readability. 230 This example includes link descriptions for an index to sensors 231 hosted by a server, along with links two two different sensors. 233 GET /.well-known/core 235 ;rel="index";n="Sensor Index", 236 ;sh="/t";n="TemperatureC", 237 ;sh="/l";ct=41;n="LightLux" 239 This example arranges link descriptions hierarchically, with the 240 entry point including a link description to a sub-resource containing 241 link descriptions about the sensors. 243 GET /.well-known/core 245 ;rel="section" 246 ;type="application/link-format" 248 GET /.well-known/core/sensors 250 ;sh="/t";n="TemperatureC", 251 ;sh="/l";ct=41;n="LightLux" 253 3. Well-known Interface 255 Resource discovery in CoRE is accomplished through the use of a well- 256 known resource URI which returns a list of links (resource 257 descriptions) offered by that constrained server. Well-known 258 resources have a reserved base URI "/.well-known/" as specified in 259 [RFC5785]. This document defines a new well-known URI for CoRE 260 discovery "/.well-known/core" Section 5.1. A server implementing 261 this specification MUST support this URI on the default port 262 appropriate for the protocol for the purpose of resource discovery. 263 It is however up to the application which link descriptions are 264 included and how they are organized. In the absense of any links, a 265 zero-length payload is returned. The resource representation of this 266 resource is described in Section 2. 268 The CoRE resource discovery interface supports the following 269 interactions: 271 o Performing a GET on /.well-known/core to the default port returns 272 a list of link descriptions available from a CoAP server (if any). 274 o Filtering may be performed on any of the link format attributes 275 using a query string as specified in Section 3.1. For example 276 [GET /.well-known/core?n=TemperatureC] would request resources 277 with the name TemperatureC. A server is not however required to 278 support filtering. 280 o More capable servers such as proxies could support a resource 281 directory by requesting the resource descriptions of other end- 282 points or accepting [POST /.well-known/core messages] from other 283 servers. This adds the resources of other end-points as a sub- 284 resource in which absolute URIs are included for the link-values. 285 The details of such resource directory functionality is however 286 out of scope for this document. 288 End-points with a large number of resources SHOULD include resource 289 descriptions only for important services or collections and organize 290 their resource descriptions into a hierarchy of link resources. This 291 is done by including links in the /.well-known/core list which point 292 to other resource lists, e.g. . Such a 293 hierarchy SHOULD be under the /.well-known/core path but could be 294 located elsewhere. 296 3.1. Query Filtering 298 A server implementing this document MAY support the query string 299 /.well-known/core? with uri= corresponding to the link-value or any 300 of the resource description attributes for the purpose of filtering a 301 discovery. It is not expected that very constrained nodes support 302 filtering. Implementations not supporting filtering MUST simply 303 ignore the query string and return the whole resource. An exact 304 match is performed on the query string, and a 200 OK response is 305 returned with link descriptions that contains the matching entries 306 (if any). Implementations supporting filtering MUST also support 307 wildcard * endings. If resource descriptions are organized 308 hierarchically, a query on the root resource /.well-known/core SHOULD 309 return all matching resource descriptions from the entire hierarchy. 310 An example query on the link descriptions from Section 2 may look 311 like: 313 GET /.well-known/core?n=LightLux 315 ;sh="/l";ct=41;n="LightLux" 317 4. Security Considerations 319 This document needs the same security considerations as described in 320 Section 7 of [I-D.nottingham-http-link-header]. The /.well-known/ 321 core resource may be protected e.g. using DTLS when hosted on a CoAP 322 server as per [I-D.ietf-core-coap] Section 10.2. 324 5. IANA Considerations 326 5.1. Well-known 'core' URI 328 This memo registers the "core" well-known URI in the Well-Known URI 329 Registry as defined by [RFC5785]. 331 URI suffix: core 333 Change controller: IETF 335 Specification document(s): [[ this document ]] 337 Related information: None 339 5.2. New link-format Internet media type 341 This memo registers the a new Internet media type for the CoRE link 342 format, application/link-format. 344 Type name: application 346 Subtype name: link-format 348 Required parameters: None 350 Optional parameters: The query string may contain uri= to match the 351 URI, or any other attribute defined for the link format to match that 352 attribute. 354 Encoding considerations: US-ASCII 355 Security considerations: None 357 Interoperability considerations: 359 Published specification: [[ this document ]] 361 Applications that use this media type: CoAP server and client 362 implementations. 364 Additional information: 366 Magic number(s): 368 File extension(s): 370 Macintosh file type code(s): 372 Intended usage: COMMON 374 Restrictions on usage: None 376 Author: CoRE WG 378 Change controller: IETF 380 6. Acknowledgments 382 Special thanks to Mark Nottingham and Eran Hammer-Lahav for 383 discussions and ideas that led to this draft, and to Carsten Bormann 384 for extensive comments and contributions that improved the text. 386 Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido 387 Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey 388 Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin, 389 Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed 390 Beroset, Gilman Tolle, Robby Simpson, Peter Bigot, Colin O'Flynn and 391 David Ryan for helpful comments and discussions that have shaped the 392 document. 394 7. Changelog 396 Changes from shelby-00 to ietf-00: 398 o Fixed the ABNF link-extension definitions (quotes around URIs, 399 integer definition). 401 o Clarified that filtering is optional, and the query string is to 402 be ignored if not supported (and the URL path processed as 403 normally). 405 o Required support of wildcard * processing if filtering is 406 supported. 408 o Removed the aussumption of a default content-type assumption. 410 8. References 412 8.1. Normative References 414 [I-D.ietf-core-coap] 415 Shelby, Z., Frank, B., and D. Sturek, "Constrained 416 Application Protocol (CoAP)", draft-ietf-core-coap-02 417 (work in progress), September 2010. 419 [I-D.nottingham-http-link-header] 420 Nottingham, M., "Web Linking", 421 draft-nottingham-http-link-header-10 (work in progress), 422 May 2010. 424 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 425 Specifications: ABNF", STD 68, RFC 5234, January 2008. 427 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 428 Uniform Resource Identifiers (URIs)", RFC 5785, 429 April 2010. 431 8.2. Informative References 433 [I-D.shelby-core-coap-req] 434 Shelby, Z., Stuber, M., Sturek, D., Frank, B., and R. 435 Kelsey, "CoAP Requirements and Features", 436 draft-shelby-core-coap-req-02 (work in progress), 437 October 2010. 439 Author's Address 441 Zach Shelby 442 Sensinode 443 Kidekuja 2 444 Vuokatti 88600 445 FINLAND 447 Phone: +358407796297 448 Email: zach@sensinode.com