idnits 2.17.1 draft-shelby-core-link-format-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) 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 137: '...commas. The CoRE link format MUST use...' RFC 2119 keyword, line 164: '... description MAY include an "anchor"...' RFC 2119 keyword, line 187: '...ption attributes MAY appear in a link ...' RFC 2119 keyword, line 193: '...t URI attributes MAY appear in a link ...' RFC 2119 keyword, line 203: '... name attributes MAY appear in a link ...' (9 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 28, 2010) is 4959 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-01 Summary: 3 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 September 28, 2010 5 Expires: April 1, 2011 7 CoRE Link Format 8 draft-shelby-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 to IETF 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), its areas, and its working groups. Note that 26 other groups may also distribute working documents as Internet- 27 Drafts. 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 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt. 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html. 40 This Internet-Draft will expire on April 1, 2011. 42 Copyright Notice 44 Copyright (c) 2010 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 2. Link Format . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2.1. Target and context IRIs . . . . . . . . . . . . . . . . . 4 62 2.2. Link relation 'rel' usage . . . . . . . . . . . . . . . . 4 63 2.3. Description 'd' usage . . . . . . . . . . . . . . . . . . 5 64 2.4. Alternative URI 'sh' usage . . . . . . . . . . . . . . . . 5 65 2.5. Resource name 'n' usage . . . . . . . . . . . . . . . . . 5 66 2.6. Content-type code 'ct' usage . . . . . . . . . . . . . . . 5 67 2.7. Resource identifier 'id' usage . . . . . . . . . . . . . . 6 68 2.8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 69 3. Well-known Interface . . . . . . . . . . . . . . . . . . . . . 6 70 3.1. Query Filtering . . . . . . . . . . . . . . . . . . . . . 7 71 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 72 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 73 5.1. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 8 74 5.2. New link-format Internet media type . . . . . . . . . . . 8 75 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 76 7. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 9 77 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 78 8.1. Normative References . . . . . . . . . . . . . . . . . . . 10 79 8.2. Informative References . . . . . . . . . . . . . . . . . . 10 80 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10 82 1. Introduction 84 The Constrained RESTful Environments (CoRE) working group aims at 85 realizing the REST architecture in a suitable form for the most 86 constrained nodes (e.g. 8-bit microcontrollers with limited RAM and 87 ROM) and networks (e.g. 6LoWPAN). CoRE is aimed at machine-to- 88 machine (M2M) applications such as smart energy and building 89 automation [I-D.shelby-core-coap-req]. 91 The discovery of resources offered by a constrained server is very 92 important in machine-to-machine applications where there are no 93 humans in the loop and static interfaces result in fragility. The 94 discovery of resources provided by an HTTP Web Server is typically 95 called Web Discovery. In this document we refer to the discovery of 96 resources offered by a CoAP server as resource discovery. 98 The core function of such a discovery mechanism is to provide URIs 99 ("links") for the resources offered, complemented by information 100 describing the relationship between the resource description and each 101 resource as well as other attributes. When such a collection of 102 attributed resource references (links) is offered as a resource of 103 its own (as opposed to as HTTP headers delivered with a different 104 resource), we speak of its representation as a link-format. 106 This document specifies a link-format for use in CoRE resource 107 discovery by extending the HTTP Link Header Format 108 [I-D.nottingham-http-link-header] to describe resources hosted by a 109 constrained server. The CoRE link-format is carried as a payload and 110 is assigned an Internet media type. A well-known URI "/.well-known/ 111 core" is defined as a default entry-point for requesting the list of 112 links to resources hosted by a server. 114 2. Link Format 116 CoRE resource discovery extends the HTTP Link Header format specified 117 in [I-D.nottingham-http-link-header] which is specified in Augmented 118 Backus-Naur Form (ABNF) notation [RFC5234]. The format does not 119 require special XML or binary parsing, and is extensible. 121 This link format is used for a similar purpose to that described in 122 [I-D.nottingham-http-link-header], to describe one or more 123 relationships between resources. However in this specification the 124 link format is extended with specific constrained M2M link 125 parameters, links are carried as a payload rather than in a message 126 header, and a default interface is defined to discover resources 127 described by these links. 129 [I-D.nottingham-http-link-header] did not require an Internet media 130 type for this link format, as it assumes to be carried in an HTTP 131 header. This specification thus requests a Internet media type for 132 this format (see Section 5.2). 134 The CoRE link format uses the ABNF description and associated rules 135 in Section 5 of [I-D.nottingham-http-link-header]. The "Link:" text 136 is omitted as that is part of the HTTP Link Header. Multiple link 137 descriptions are separated by commas. The CoRE link format MUST use 138 the US-ASCII character set (support for RFC2231 encoding of non-ASCII 139 content TBD). The following CoRE specific link-extension parameters 140 to the format are defined: 142 link-extension = ( "d" "=" URI ) 143 link-extension = ( "sh" "=" URI-Reference ) 144 link-extension = ( "n" "=" ( quoted-string | URI ) ) 145 link-extension = ( "ct" "=" integer ) 146 link-extension = ( "id" "=" ( quoted-string | URI ) ) 148 2.1. Target and context IRIs 150 Each link description conveys one target URI as a URI-Reference 151 inside angle brackets ("<>"). The context of a link conveyed in the 152 description is by default the URI of the resource that returned the 153 link-format representation (usually ./well-known/core). Thus each 154 link can be thought of as describing a target resource hosted by the 155 server in the absence of further relation information. This is an 156 important difference to the way the HTTP Link Header format is used, 157 as it is included in the header of an HTTP response for some URI 158 (this URI is by default the context). Thus the HTTP Link Header is 159 by default relating the target URI to the URI that was requested. In 160 comparison, the CoRE link format includes one or more link entries, 161 each describing a resource hosted by a server. 163 As per Section 5.2 of [I-D.nottingham-http-link-header] a link 164 description MAY include an "anchor" attribute, in which case the 165 context is the URI included in that attribute. This can be used to 166 describe a relationship between two resources. A consuming 167 implementation can however choose to ignore such links. It is not 168 expected that most implementations will be able to derive useful from 169 explicitly anchored links. 171 2.2. Link relation 'rel' usage 173 Link descriptions in CoRE are typically used to describe entry points 174 to services hosted by the server, and thus in the absence of the rel 175 attribute the registered "service" relation type is assumed. In the 176 CoRE link format the service relation type indicates that the link is 177 a service hosted by the server (in the absence of the anchor 178 attribute). A description can make use of any registered relation 179 type or extension types in the form of a URI by including the rel 180 attribute. 182 2.3. Description 'd' usage 184 The description "d" attribute can provide a URI to a specific 185 interface definition used to access the target resource. This could 186 be for example a URI to the WADL definition of the target resource. 187 Multiple description attributes MAY appear in a link description. 189 2.4. Alternative URI 'sh' usage 191 This attribute can be included to define an alternative short URI 192 which can also be used to access the target resource. Multiple 193 alternative short URI attributes MAY appear in a link description. 195 2.5. Resource name 'n' usage 197 The resource name "n" attribute is used to assign eith a human 198 readable or a semantically important name to a resource. In the case 199 of a temperature sensor resource the name could be something like 200 "Temperature in Centigrade", a URI to an ontology like 201 "http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature" or an 202 application-specific semantic name like "TemperatureC". Multiple 203 name attributes MAY appear in a link description. 205 2.6. Content-type code 'ct' usage 207 The Content-type code "ct" attribute provides a hint about the 208 Internet media type this resource returns. The value is in the CoAP 209 identifier code format as a decimal ASCII integer 210 [I-D.ietf-core-coap]. For example application/xml would be indicated 211 as "ct=41". If no Content-type code attribute is present then text/ 212 plain is assumed. The Content-type code attribute MUST NOT appear 213 more than once in a link description. 215 Alternatively, the "type" attribute MAY be used to indicate an 216 Internet media type as a quoted-string. It is not however expected 217 that constrained implementations are able to parse quoted-string 218 Content-type values. 220 2.7. Resource identifier 'id' usage 222 The resource identifier "id" field is a unique identifier (e.g. 223 UUID) for this resource for use in e.g. resource or search 224 directories. This attribute may be in quoted-string format (e.g. in 225 the case of a UUID or XRI) or in URI format (e.g. in the case of a 226 URN). The resource identifier attribute MUST NOT appear more than 227 once in a link description. 229 2.8. Examples 231 A few examples of typical link descriptions in this format follows. 232 Multiple resource descriptions in a representation are separated by 233 commas. Commas can also occur in quoted strings and URIs but do not 234 end a description. Linefeeds never occur in the actual format, but 235 are shown in the example for readability. 237 This example includes link descriptions for an index to sensors 238 hosted by a server, along with links two two different sensors. 240 GET /.well-known/core 242 ;rel="index";n="Sensor Index", 243 ;sh="/t";n="TemperatureC", 244 ;sh="/l";ct=41;n="LightLux" 246 This example arranges link descriptions hierarchically, with the 247 entry point including a link description to a sub-resource containing 248 link descriptions about the sensors. 250 GET /.well-known/core 252 ;rel="section" 253 ;type="application/link-format" 255 GET /.well-known/core/sensors 257 ;sh="/t";n="TemperatureC", 258 ;sh="/l";ct=41;n="LightLux" 260 3. Well-known Interface 262 Resource discovery in CoRE is accomplished through the use of a well- 263 known resource URI which returns a list of links (resource 264 descriptions) offered by that constrained server. Well-known 265 resources have a reserved base URI "/.well-known/" as specified in 267 [RFC5785]. This document defines a new well-known URI for CoRE 268 discovery "/.well-known/core" Section 5.1. A server implementing 269 this specification MUST support this URI on the default port 270 appropriate for the protocol, for the purpose of resource discovery. 271 It is however up to the application which link descriptions are 272 included and how they are organized. In the absense of any links, a 273 zero-length payload is returned. The resource representation of this 274 resource is described in Section 2. 276 The CoRE resource discovery interface supports the following 277 interactions: 279 o Performing a GET on /.well-known/core to the default port returns 280 a list of link descriptions available from a CoAP server (if any). 282 o Filtering may be performed on any of the link format attributes 283 using a query string as specified in Section 3.1. For example 284 [GET /.well-known/core?n=TemperatureC] would request resources 285 with the name TemperatureC. A server is not however required to 286 support filtering. 288 o More capable servers such as proxies could support a resource 289 directory by requesting the resource descriptions of other end- 290 points or accepting [POST /.well-known/core messages] from other 291 servers. This adds the resources of other end-points as a sub- 292 resource in which absolute URIs are included for the link-values. 293 The details of such resource directory functionality is however 294 out of scope for this document. 296 End-points with a large number of resources SHOULD include resource 297 descriptions only for important services or collections and organize 298 their resource descriptions into a hierarchy of link resources. This 299 is done by including links in the /.well-known/core list which point 300 to other resource lists, e.g. . Such a 301 hierarchy SHOULD be under the /.well-known/core path but could be 302 located elsewhere. 304 3.1. Query Filtering 306 A server implementing this document MAY support the query string 307 /.well-known/core? with uri= corresponding to the link-value or any 308 of the resource description attributes for the purpose of filtering a 309 discovery. It is not expected that simple implementations support 310 filtering, but instead will just ignore the query string. Wildcard * 311 endings MAY be supported. An exact match is performed on the query 312 string, and a 200 OK response is returned with link descriptions that 313 contains the matching entries (if any). If resource descriptions are 314 organized hierarchically, a query on the root resource /.well-known/ 315 core SHOULD return all matching resource descriptions from the entire 316 hierarchy. An example query on the example link descriptions from 317 Section 2 may look like: 319 GET /.well-known/core?n=LightLux 321 ;sh="/l";ct=41;n="LightLux" 323 4. Security Considerations 325 This document needs the same security considerations as described in 326 Section 7 of [I-D.nottingham-http-link-header]. The /.well-known/ 327 core resource may be protected e.g. using DTLS when hosted on a CoAP 328 server. 330 5. IANA Considerations 332 5.1. Well-known 'core' URI 334 This memo registers the "core" well-known URI in the Well-Known URI 335 Registry as defined by [RFC5785]. 337 URI suffix: core 339 Change controller: IETF 341 Specification document(s): [[ this document ]] 343 Related information: None 345 5.2. New link-format Internet media type 347 This memo registers the a new Internet media type for the CoRE link 348 format, application/link-format. 350 Type name: application 352 Subtype name: link-format 354 Required parameters: None 356 Optional parameters: The query string may contain uri= to match the 357 URI, or any other attribute defined for the link format to match that 358 attribute. 360 Encoding considerations: US-ASCII 361 Security considerations: None 363 Interoperability considerations: 365 Published specification: [[ this document ]] 367 Applications that use this media type: CoAP server and client 368 implementations. 370 Additional information: 372 Magic number(s): 374 File extension(s): 376 Macintosh file type code(s): 378 Intended usage: COMMON 380 Restrictions on usage: None 382 Author: CoRE WG 384 Change controller: IETF 386 6. Acknowledgments 388 Special thanks to Mark Nottingham and Eran Hammer-Lahav for 389 discussions and ideas that led to this draft, and to Carsten Bormann 390 for extensive comments and contributions that improved the text. 392 Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido 393 Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey 394 Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin, 395 Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed 396 Beroset, Gilman Tolle, Robby Simpson, Peter Bigot, Colin O'Flynn and 397 David Ryan for helpful comments and discussions that have shaped the 398 document. 400 7. Changelog 402 8. References 403 8.1. Normative References 405 [I-D.ietf-core-coap] 406 Shelby, Z., Frank, B., and D. Sturek, "Constrained 407 Application Protocol (CoAP)", draft-ietf-core-coap-02 408 (work in progress), September 2010. 410 [I-D.nottingham-http-link-header] 411 Nottingham, M., "Web Linking", 412 draft-nottingham-http-link-header-10 (work in progress), 413 May 2010. 415 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 416 Specifications: ABNF", STD 68, RFC 5234, January 2008. 418 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 419 Uniform Resource Identifiers (URIs)", RFC 5785, 420 April 2010. 422 8.2. Informative References 424 [I-D.shelby-core-coap-req] 425 Shelby, Z., Stuber, M., Sturek, D., Frank, B., and R. 426 Kelsey, "CoAP Requirements and Features", 427 draft-shelby-core-coap-req-01 (work in progress), 428 April 2010. 430 Author's Address 432 Zach Shelby 433 Sensinode 434 Kidekuja 2 435 Vuokatti 88600 436 FINLAND 438 Phone: +358407796297 439 Email: zach@sensinode.com