summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc6690.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc6690.txt')
-rw-r--r--doc/rfc/rfc6690.txt1235
1 files changed, 1235 insertions, 0 deletions
diff --git a/doc/rfc/rfc6690.txt b/doc/rfc/rfc6690.txt
new file mode 100644
index 0000000..37209df
--- /dev/null
+++ b/doc/rfc/rfc6690.txt
@@ -0,0 +1,1235 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) Z. Shelby
+Request for Comments: 6690 Sensinode
+Category: Standards Track August 2012
+ISSN: 2070-1721
+
+
+ Constrained RESTful Environments (CoRE) Link Format
+
+Abstract
+
+ This specification defines Web Linking using a link format for use by
+ constrained web servers to describe hosted resources, their
+ attributes, and other relationships between links. Based on the HTTP
+ Link Header field defined in RFC 5988, the Constrained RESTful
+ Environments (CoRE) Link Format is carried as a payload and is
+ assigned an Internet media type. "RESTful" refers to the
+ Representational State Transfer (REST) architecture. A well-known
+ URI is defined as a default entry point for requesting the links
+ hosted by a server.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc6690.
+
+Copyright Notice
+
+ Copyright (c) 2012 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+
+
+Shelby Standards Track [Page 1]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+Table of Contents
+
+ 1. Introduction ....................................................3
+ 1.1. Web Linking in CoRE ........................................3
+ 1.2. Use Cases ..................................................4
+ 1.2.1. Discovery ...........................................4
+ 1.2.2. Resource Collections ................................5
+ 1.2.3. Resource Directory ..................................5
+ 1.3. Terminology ................................................6
+ 2. Link Format .....................................................6
+ 2.1. Target and Context URIs ....................................8
+ 2.2. Link Relations .............................................8
+ 2.3. Use of Anchors .............................................9
+ 3. CoRE Link Attributes ............................................9
+ 3.1. Resource Type 'rt' Attribute ...............................9
+ 3.2. Interface Description 'if' Attribute ......................10
+ 3.3. Maximum Size Estimate 'sz' Attribute ......................10
+ 4. Well-Known Interface ...........................................10
+ 4.1. Query Filtering ...........................................12
+ 5. Examples .......................................................13
+ 6. Security Considerations ........................................15
+ 7. IANA Considerations ............................................16
+ 7.1. Well-Known 'core' URI .....................................16
+ 7.2. New 'hosts' Relation Type .................................16
+ 7.3. New 'link-format' Internet Media Type .....................17
+ 7.4. Constrained RESTful Environments (CoRE) Parameters
+ Registry ..................................................18
+ 8. Acknowledgments ................................................19
+ 9. References .....................................................20
+ 9.1. Normative References ......................................20
+ 9.2. Informative References ....................................20
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Shelby Standards Track [Page 2]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+1. Introduction
+
+ The Constrained RESTful Environments (CoRE) realizes the
+ Representational State Transfer (REST) architecture [REST] in a
+ suitable form for the most constrained nodes (e.g., 8-bit
+ microcontrollers with limited memory) and networks (e.g., IPv6 over
+ Low-Power Wireless Personal Area Networks (6LoWPANs) [RFC4919]).
+ CoRE is aimed at Machine-to-Machine (M2M) applications such as smart
+ energy and building automation.
+
+ The discovery of resources hosted by a constrained server is very
+ important in machine-to-machine applications where there are no
+ humans in the loop and static interfaces result in fragility. The
+ discovery of resources provided by an HTTP [RFC2616] web server is
+ typically called "Web Discovery" and the description of relations
+ between resources is called "Web Linking" [RFC5988]. In the present
+ specification, we refer to the discovery of resources hosted by a
+ constrained web server, their attributes, and other resource
+ relations as CoRE Resource Discovery.
+
+ The main function of such a discovery mechanism is to provide
+ Universal Resource Identifiers (URIs, called links) for the resources
+ hosted by the server, complemented by attributes about those
+ resources and possible further link relations. In CoRE, this
+ collection of links is carried as a resource of its own (as opposed
+ to HTTP headers delivered with a specific resource). This document
+ specifies a link format for use in CoRE Resource Discovery by
+ extending the HTTP Link Header format [RFC5988] to describe these
+ link descriptions. The CoRE Link Format is carried as a payload and
+ is assigned an Internet media type. A well-known relative URI
+ "/.well-known/core" is defined as a default entry point for
+ requesting the list of links about resources hosted by a server and
+ thus performing CoRE Resource Discovery. This specification is
+ applicable for use with Constrained Application Protocol (CoAP)
+ [COAP], HTTP, or any other suitable web transfer protocol. The link
+ format can also be saved in file format.
+
+1.1. Web Linking in CoRE
+
+ Technically, the CoRE Link Format is a serialization of a typed link
+ as specified in [RFC5988], used to describe relationships between
+ resources, so-called "Web Linking". In this specification, Web
+ Linking is extended with specific constrained M2M attributes; links
+ are carried as a message payload rather than in an HTTP Link Header
+ field, and a default interface is defined to discover resources
+ hosted by a server. This specification also defines a new relation
+
+
+
+
+
+Shelby Standards Track [Page 3]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+ type "hosts" (from the verb "to host"), which indicates that the
+ resource is hosted by the server from which the link document was
+ requested.
+
+ In HTTP, the Link Header can be used to carry link information about
+ a resource along with an HTTP response. This works well for the
+ typical use case for a web server and browser, where further
+ information about a particular resource is useful after accessing it.
+ In CoRE, the main use case for Web Linking is the discovery of which
+ resources a server hosts in the first place. Although some resources
+ may have further links associated with them, this is expected to be
+ an exception. For that reason, the CoRE Link Format serialization is
+ carried as a resource representation of a well-known URI. The CoRE
+ Link Format does reuse the format of the HTTP Link Header
+ serialization defined in [RFC5988].
+
+1.2. Use Cases
+
+ Typical use cases for Web Linking on today's web include, e.g.,
+ describing the author of a web page or describing relations between
+ web pages (next chapter, previous chapter, etc.). Web Linking can
+ also be applied to M2M applications, where typed links are used to
+ assist a machine client in finding and understanding how to use
+ resources on a server. In this section a few use cases are described
+ for how the CoRE Link Format could be used in M2M applications. For
+ further technical examples, see Section 5. As there is a large range
+ of M2M applications, these use cases are purposely generic. This
+ specification assumes that different deployments or application
+ domains will define the appropriate REST Interface Descriptions along
+ with Resource Types to make discovery meaningful.
+
+1.2.1. Discovery
+
+ In M2M applications, for example, home or building automation, there
+ is a need for local clients and servers to find and interact with
+ each other without human intervention. The CoRE Link Format can be
+ used by servers in such environments to enable Resource Discovery of
+ the resources hosted by the server.
+
+ Resource Discovery can be performed either unicast or multicast.
+ When a server's IP address is already known, either a priori or
+ resolved via the Domain Name System (DNS) [RFC1034][RFC1035], unicast
+ discovery is performed in order to locate the entry point to the
+ resource of interest. In this specification, this is performed using
+ a GET to "/.well-known/core" on the server, which returns a payload
+ in the CoRE Link Format. A client would then match the appropriate
+ Resource Type, Interface Description, and possible media type
+
+
+
+
+Shelby Standards Track [Page 4]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+ [RFC2045] for its application. These attributes may also be included
+ in the query string in order to filter the number of links returned
+ in a response.
+
+ Multicast Resource Discovery is useful when a client needs to locate
+ a resource within a limited scope, and that scope supports IP
+ multicast. A GET request to the appropriate multicast address is
+ made for "/.well-known/core". In order to limit the number and size
+ of responses, a query string is recommended with the known
+ attributes. Typically, a resource would be discovered based on its
+ Resource Type and/or Interface Description, along with possible
+ application-specific attributes.
+
+1.2.2. Resource Collections
+
+ RESTful designs of M2M interfaces often make use of collections of
+ resources. For example, an index of temperature sensors on a data
+ collection node or a list of alarms on a home security controller.
+ The CoRE Link Format can be used to make it possible to find the
+ entry point to a collection and traverse its members. The entry
+ point of a collection would always be included in "/.well-known/core"
+ to enable its discovery. The members of the collection can be
+ defined either through the Interface Description of the resource
+ along with a parameter resource for the size of the collection or by
+ using the link format to describe each resource in the collection.
+ These links could be located under "/.well-known/core" or hosted, for
+ example, in the root resource of the collection.
+
+1.2.3. Resource Directory
+
+ In many deployment scenarios, for example, constrained networks with
+ sleeping servers or large M2M deployments with bandwidth limited
+ access networks, it makes sense to deploy resource directory entities
+ that store links to resources stored on other servers. Think of this
+ as a limited search engine for constrained M2M resources.
+
+ The CoRE Link Format can be used by a server to register resources
+ with a resource directory or to allow a resource directory to poll
+ for resources. Resource registration can be achieved by having each
+ server POST their resources to "/.well-known/core" on the resource
+ directory. This, in turn, adds links to the resource directory under
+ an appropriate resource. These links can then be discovered by any
+ client by making a request to a resource directory lookup interface.
+
+
+
+
+
+
+
+
+Shelby Standards Track [Page 5]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+1.3. Terminology
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ specification are to be interpreted as described in [RFC2119].
+
+ This specification makes use of the Augmented Backus-Naur Form (ABNF)
+ [RFC5234] notation, including the core rules defined in Appendix B of
+ that document.
+
+ This specification requires readers to be familiar with all the terms
+ and concepts that are discussed in [RFC5988] and [RFC6454]. In
+ addition, this specification makes use of the following terminology:
+
+ Web Linking
+ A framework for indicating the relationships between web
+ resources.
+
+ Link
+ Also called "typed links" in [RFC5988]. A link is a typed
+ connection between two resources identified by URI and is made up
+ of a context URI, a link relation type, a target URI, and optional
+ target attributes.
+
+ Link Format
+ A particular serialization of typed links.
+
+ CoRE Link Format
+ A particular serialization of typed links based on the HTTP Link
+ Header field serialization defined in Section 5 of [RFC5988] but
+ carried as a resource representation with a media type.
+
+ Attribute
+ Properly called "Target Attribute" in [RFC5988]. A key/value pair
+ that describes the link or its target.
+
+ CoRE Resource Discovery
+ When a client discovers the list of resources hosted by a server,
+ their attributes, and other link relations by accessing
+ "/.well-known/core".
+
+2. Link Format
+
+ The CoRE Link Format extends the HTTP Link Header field specified in
+ [RFC5988]. The format does not require special XML or binary
+ parsing, is fairly compact, and is extensible -- all important
+ characteristics for CoRE. It should be noted that this link format
+ is just one serialization of typed links defined in [RFC5988]; others
+
+
+
+Shelby Standards Track [Page 6]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+ include HTML links, Atom feed links [RFC4287], or HTTP Link Header
+ fields. It is expected that resources discovered in the CoRE Link
+ Format may also be made available in alternative formats on the
+ greater Internet. The CoRE Link Format is only expected to be
+ supported in constrained networks and M2M systems.
+
+ Section 5 of [RFC5988] did not require an Internet media type for the
+ defined link format, as it was defined to be carried in an HTTP
+ header. This specification thus defines the Internet media type
+ 'application/link-format' for the CoRE Link Format (see Section 7.3).
+ Whereas the HTTP Link Header field depends on [RFC2616] for its
+ encoding, the CoRE Link Format is encoded as UTF-8 [RFC3629]. A
+ decoder of the format is not expected to validate UTF-8 encoding (but
+ is not prohibited from doing so) and doesn't need to perform any
+ UTF-8 normalization. UTF-8 data can be compared bitwise, which
+ allows values to contain UTF-8 data without any added complexity for
+ constrained nodes.
+
+ The CoRE Link Format is equivalent to the [RFC5988] link format;
+ however, the ABNF in the present specification is repeated with
+ improvements to be compliant with [RFC5234] and includes new link
+ parameters. The link parameter "href" is reserved for use as a query
+ parameter for filtering in this specification (see Section 4.1) and
+ MUST NOT be defined as a link parameter. As in [RFC5988], multiple
+ link descriptions are separated by commas. Note that commas can also
+ occur in quoted strings and URIs but do not end a description. In
+ order to convert an HTTP Link Header field to this link format, first
+ the "Link:" HTTP header is removed, any linear whitespace (LWS) is
+ removed, the header value is converted to UTF-8, and any percent-
+ encodings are decoded.
+
+ Link = link-value-list
+ link-value-list = [ link-value *[ "," link-value ]]
+ link-value = "<" URI-Reference ">" *( ";" link-param )
+ link-param = ( ( "rel" "=" relation-types )
+ / ( "anchor" "=" DQUOTE URI-Reference DQUOTE )
+ / ( "rev" "=" relation-types )
+ / ( "hreflang" "=" Language-Tag )
+ / ( "media" "=" ( MediaDesc
+ / ( DQUOTE MediaDesc DQUOTE ) ) )
+ / ( "title" "=" quoted-string )
+ / ( "title*" "=" ext-value )
+ / ( "type" "=" ( media-type / quoted-mt ) )
+ / ( "rt" "=" relation-types )
+ / ( "if" "=" relation-types )
+ / ( "sz" "=" cardinal )
+ / ( link-extension ) )
+ link-extension = ( parmname [ "=" ( ptoken / quoted-string ) ] )
+
+
+
+Shelby Standards Track [Page 7]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+ / ( ext-name-star "=" ext-value )
+ ext-name-star = parmname "*" ; reserved for RFC-2231-profiled
+ ; extensions. Whitespace NOT
+ ; allowed in between.
+ ptoken = 1*ptokenchar
+ ptokenchar = "!" / "#" / "$" / "%" / "&" / "'" / "("
+ / ")" / "*" / "+" / "-" / "." / "/" / DIGIT
+ / ":" / "<" / "=" / ">" / "?" / "@" / ALPHA
+ / "[" / "]" / "^" / "_" / "`" / "{" / "|"
+ / "}" / "~"
+ media-type = type-name "/" subtype-name
+ quoted-mt = DQUOTE media-type DQUOTE
+ relation-types = relation-type
+ / DQUOTE relation-type *( 1*SP relation-type ) DQUOTE
+ relation-type = reg-rel-type / ext-rel-type
+ reg-rel-type = LOALPHA *( LOALPHA / DIGIT / "." / "-" )
+ ext-rel-type = URI
+ cardinal = "0" / ( %x31-39 *DIGIT )
+ LOALPHA = %x61-7A ; a-z
+ quoted-string = <defined in [RFC2616]>
+ URI = <defined in [RFC3986]>
+ URI-Reference = <defined in [RFC3986]>
+ type-name = <defined in [RFC4288]>
+ subtype-name = <defined in [RFC4288]>
+ MediaDesc = <defined in [W3C.HTML.4.01]>
+ Language-Tag = <defined in [RFC5646]>
+ ext-value = <defined in [RFC5987]>
+ parmname = <defined in [RFC5987]>
+
+2.1. Target and Context URIs
+
+ Each link conveys one target URI as a URI-reference inside angle
+ brackets ("<>"). The context URI of a link (also called the base URI
+ in [RFC3986]) is determined by the following rules in this
+ specification:
+
+ (a) The context URI is set to the anchor parameter, when specified.
+
+ (b) Origin of the target URI, when specified.
+
+ (c) Origin of the link format resource's base URI.
+
+2.2. Link Relations
+
+ Since links in the CoRE Link Format are typically used to describe
+ resources hosted by a server, the new relation type "hosts" is
+ assumed in the absence of the relation parameter (see Section 7.2).
+ The "hosts" relation type (from the verb "to host") indicates that
+
+
+
+Shelby Standards Track [Page 8]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+ the target URI is a resource hosted by the server (i.e., server hosts
+ resource) indicated by the context URI. The target URI MUST be a
+ relative URI of the context URI for this relation type.
+
+ To express other relations, links can make use of any registered
+ relation by including the relation parameter. The context of a
+ relation can be defined using the anchor parameter. In this way,
+ relations between resources hosted on a server or between hosted
+ resources and external resources can be expressed.
+
+2.3. Use of Anchors
+
+ As per Section 5.2 of [RFC5988], a link description MAY include an
+ "anchor" parameter, in which case the context is the URI included in
+ that attribute. This is used to describe a relationship between two
+ resources. A consuming implementation can, however, choose to ignore
+ such links. It is not expected that all implementations will be able
+ to derive useful information from explicitly anchored links.
+
+3. CoRE Link Attributes
+
+ The following CoRE-specific target attributes are defined in addition
+ to those already defined in [RFC5988]. These attributes describe
+ information useful in accessing the target link of the relation and,
+ in some cases, can use the syntactical form of a URI. Such a URI MAY
+ be dereferenced (for instance, to obtain a description of the link
+ relation), but that is not part of the protocol and MUST NOT be done
+ automatically on link evaluation. When the values of attributes are
+ compared, they MUST be compared as strings.
+
+3.1. Resource Type 'rt' Attribute
+
+ The Resource Type 'rt' attribute is an opaque string used to assign
+ an application-specific semantic type to a resource. One can think
+ of this as a noun describing the resource. In the case of a
+ temperature resource, this could be, e.g., an application-specific
+ semantic type like "outdoor-temperature" or a URI referencing a
+ specific concept in an ontology like
+ "http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature". Multiple
+ Resource Types MAY be included in the value of this parameter, each
+ separated by a space, similar to the relation attribute. The
+ registry for Resource Type values is defined in Section 7.4.
+
+ The Resource Type attribute is not meant to be used to assign a
+ human-readable name to a resource. The "title" attribute defined in
+ [RFC5988] is meant for that purpose. The Resource Type attribute
+ MUST NOT appear more than once in a link.
+
+
+
+
+Shelby Standards Track [Page 9]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+3.2. Interface Description 'if' Attribute
+
+ The Interface Description 'if' attribute is an opaque string used to
+ provide a name or URI indicating a specific interface definition used
+ to interact with the target resource. One can think of this as
+ describing verbs usable on a resource. The Interface Description
+ attribute is meant to describe the generic REST interface to interact
+ with a resource or a set of resources. It is expected that an
+ Interface Description will be reused by different Resource Types.
+ For example, the Resource Types "outdoor-temperature", "dew-point",
+ and "rel-humidity" could all be accessible using the Interface
+ Description "http://www.example.org/myapp.wadl#sensor". Multiple
+ Interface Descriptions MAY be included in the value of this
+ parameter, each separated by a space, similar to the relation
+ attribute. The registry for Interface Description values is defined
+ in Section 7.4.
+
+ The Interface Description could be, for example, the URI of a Web
+ Application Description Language (WADL) [WADL] definition of the
+ target resource "http://www.example.org/myapp.wadl#sensor", a URN
+ indicating the type of interface to the resource "urn:myapp:sensor",
+ or an application-specific name "sensor". The Interface Description
+ attribute MUST NOT appear more than once in a link.
+
+3.3. Maximum Size Estimate 'sz' Attribute
+
+ The maximum size estimate attribute 'sz' gives an indication of the
+ maximum size of the resource representation returned by performing a
+ GET on the target URI. For links to CoAP resources, this attribute
+ is not expected to be included for small resources that can
+ comfortably be carried in a single Maximum Transmission Unit (MTU)
+ but SHOULD be included for resources larger than that. The maximum
+ size estimate attribute MUST NOT appear more than once in a link.
+
+ Note that there is no defined upper limit to the value of the 'sz'
+ attributes. Implementations MUST be prepared to accept large values.
+ One implementation strategy is to convert any value larger than a
+ reasonable size limit for this implementation to a special value
+ "Big", which in further processing would indicate that a size value
+ was given that was so big that it cannot be processed by this
+ implementation.
+
+4. Well-Known Interface
+
+ Resource discovery in CoRE is accomplished through the use of a well-
+ known resource URI that returns a list of links about resources
+ hosted by that server and other link relations. Well-known resources
+
+
+
+
+Shelby Standards Track [Page 10]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+ have a path component that begins with "/.well-known/" as specified
+ in [RFC5785]. This specification defines a new well-known resource
+ for CoRE Resource Discovery: "/.well-known/core".
+
+ A server implementing this specification MUST support this resource
+ on the default port appropriate for the protocol for the purpose of
+ resource discovery. It is, however, up to the application which
+ links are included and how they are organized. The resource
+ "/.well-known/core" is meant to be used to return links to the entry
+ points of resource interfaces on a server. More sophisticated link
+ organization can be achieved by including links to CoRE Link Format
+ resources located elsewhere on the server, for example, to achieve an
+ index. In the absence of any links, a zero-length payload is
+ returned. The resource representation of this resource MUST be the
+ CoRE Link Format described in Section 2.
+
+ The CoRE resource discovery interface supports the following
+ interactions:
+
+ o Performing a GET on "/.well-known/core" to the default port
+ returns a set of links available from the server (if any) in the
+ CoRE Link Format. These links might describe resources hosted on
+ that server or on other servers or express other kinds of link
+ relations as described in Section 2.
+
+ o Filtering may be performed on any of the link format attributes
+ using a query string as specified in Section 4.1. For example,
+ [GET /.well-known/core?rt=temperature-c] would request resources
+ with the Resource Type temperature-c. A server is not, however,
+ required to support filtering.
+
+ o More capable servers such as proxies could support a resource
+ directory by requesting the resource descriptions of other end-
+ points or allowing servers to POST requests to "/.well-known/
+ core". The details of such resource directory functionality is,
+ however, out of the scope of this specification and is expected to
+ be specified separately.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Shelby Standards Track [Page 11]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+4.1. Query Filtering
+
+ A server implementing this specification MAY recognize the query part
+ of a resource discovery URI as a filter on the resources to be
+ returned. The path and query components together should conform to
+ the following level-4 URI Template [RFC6570]:
+
+ /.well-known/core{?search*}
+
+ where the variable "search" is a 1-element list that has a single
+ name/value pair, where
+
+ o name is either "href", a link-param name defined in this
+ specification, or any other link-extension name, and
+
+ o value is either a Complete Value String that does not end in an
+ "*" (%2A), or a Prefix Value String followed by an "*" (%2A).
+
+ The search name "href" refers to the URI-reference between the "<"
+ and ">" characters of a link. Both Value Strings match a target
+ attribute only if it exists. Value Strings are percent-decoded
+ ([RFC3986], Section 2.1) before matching; similarly, any target
+ attributes notated as quoted-string are interpreted as defined in
+ Section 2.2 of [RFC2616]. After these steps, a Complete Value String
+ matches a target attribute if it is bitwise identical. A Prefix
+ Value String matches a target attribute if it is a bitwise prefix of
+ the target attribute (where any string is a prefix of itself). Empty
+ Prefix Value Strings are allowed; by the definition above, they match
+ any target attribute that does exist. Note that relation-type target
+ attributes can contain multiple values, and each value MUST be
+ treated as a separate target attribute when matching.
+
+ It is not expected that very constrained nodes support filtering.
+ Implementations not supporting filtering MUST simply ignore the query
+ string and return the whole resource for unicast requests.
+
+ When using a transfer protocol like the Constrained Application
+ Protocol (CoAP) that supports multicast requests, special care needs
+ to be taken. A multicast request with a query string SHOULD NOT be
+ responded to if filtering is not supported or if the filter does not
+ match (to avoid a needless response storm). The exception is in
+ cases where the IP stack interface is not able to indicate that the
+ destination address was multicast.
+
+
+
+
+
+
+
+
+Shelby Standards Track [Page 12]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+ The following are examples of valid query URIs:
+
+ o ?href=/foo matches a link-value that is anchored at /foo
+
+ o ?href=/foo* matches a link-value that is anchored at a URI that
+ starts with /foo
+
+ o ?foo=bar matches a link-value that has a target attribute named
+ foo with the exact value bar
+
+ o ?foo=bar* matches a link-value that has a target attribute named
+ foo, the value of which starts with bar, e.g., bar or barley
+
+ o ?foo=* matches a link-value that has a target attribute named foo
+
+5. Examples
+
+ A few examples of typical link descriptions in this format follows.
+ Multiple resource descriptions in a representation are separated by
+ commas. Linefeeds are also included in these examples for
+ readability. Although the following examples use CoAP response
+ codes, the examples are applicable to HTTP as well (the corresponding
+ response code would be 200 OK).
+
+ This example includes links to two different sensors sharing the same
+ Interface Description. Note that the default relation type for this
+ link format is "hosts" in links with no rel= target attribute. Thus,
+ the links in this example tell that the Origin server from which
+ /.well-known/core was requested (the context) hosts the resources
+ /sensors/temp and /sensors/light (each a target).
+
+ REQ: GET /.well-known/core
+
+ RES: 2.05 Content
+ </sensors/temp>;if="sensor",
+ </sensors/light>;if="sensor"
+
+ Without the linefeeds inserted here for readability, the format
+ actually looks as follows.
+
+ </sensors/temp>;if="sensor",</sensors/light>;if="sensor"
+
+ This example arranges link descriptions hierarchically, with the
+ entry point including a link to a sub-resource containing links about
+ the sensors.
+
+
+
+
+
+
+Shelby Standards Track [Page 13]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+ REQ: GET /.well-known/core
+
+ RES: 2.05 Content
+ </sensors>;ct=40
+
+ REQ: GET /sensors
+
+ RES: 2.05 Content
+ </sensors/temp>;rt="temperature-c";if="sensor",
+ </sensors/light>;rt="light-lux";if="sensor"
+
+ An example query filter may look like:
+
+ REQ: GET /.well-known/core?rt=light-lux
+
+ RES: 2.05 Content
+ </sensors/light>;rt="light-lux";if="sensor"
+
+ Note that relation-type attributes like 'rt', 'if', and 'rel' can
+ have multiple values separated by spaces. A query filter parameter
+ can match any one of those values, as in this example:
+
+ REQ: GET /.well-known/core?rt=light-lux
+
+ RES: 2.05 Content
+ </sensors/light>;rt="light-lux core.sen-light";if="sensor"
+
+ This example shows the use of an "anchor" attribute to relate the
+ temperature sensor resource to an external description and to an
+ alternative URI.
+
+ REQ: GET /.well-known/core
+
+ RES: 2.05 Content
+ </sensors>;ct=40;title="Sensor Index",
+ </sensors/temp>;rt="temperature-c";if="sensor",
+ </sensors/light>;rt="light-lux";if="sensor",
+ <http://www.example.com/sensors/t123>;anchor="/sensors/temp"
+ ;rel="describedby",
+ </t>;anchor="/sensors/temp";rel="alternate"
+
+
+
+
+
+
+
+
+
+
+
+Shelby Standards Track [Page 14]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+ If a client is interested in finding relations about a particular
+ resource, it can perform a query on the anchor parameter:
+
+ REQ: GET /.well-known/core?anchor=/sensors/temp
+
+ RES: 2.05 Content
+ <http://www.example.com/sensors/temp123>;anchor="/sensors/temp"
+ ;rel="describedby",
+ </t>;anchor="/sensors/temp";rel="alternate"
+
+ The following example shows a large firmware resource with a size
+ attribute. The consumer of this link would use the 'sz' attribute to
+ determine if the resource representation is too large and if block
+ transfer would be required to request it. In this case, a client
+ with only a 64 KiB flash might only support a 16-bit integer for
+ storing the 'sz' attribute. Thus, a special flag or value should be
+ used to indicate "Big" (larger than 64 KiB).
+
+ REQ: GET /.well-known/core?rt=firmware
+
+ RES: 2.05 Content
+ </firmware/v2.1>;rt="firmware";sz=262144
+
+6. Security Considerations
+
+ This specification has the same security considerations as described
+ in Section 7 of [RFC5988]. The "/.well-known/core" resource MAY be
+ protected, e.g., using Datagram Transport Layer Security (DTLS) when
+ hosted on a CoAP server as per [COAP], Section 9.1.
+
+ Some servers might provide resource discovery services to a mix of
+ clients that are trusted to different levels. For example, a
+ lighting control system might allow any client to read state
+ variables, but only certain clients to write state (turn lights on or
+ off). Servers that have authentication and authorization features
+ SHOULD support authentication features of the underlying transport
+ protocols (HTTP or DTLS/TLS) and allow servers to return different
+ lists of links based on a client's identity and authorization. While
+ such servers might not return all links to all requesters, not
+ providing the link does not, by itself, control access to the
+ relevant resource -- a bad actor could know or guess the right URIs.
+ Servers can also lie about the resources available. If it is
+ important for a client to only get information from a known source,
+ then that source needs to be authenticated.
+
+
+
+
+
+
+
+Shelby Standards Track [Page 15]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+ Multicast requests using CoAP for the well-known link-format
+ resources could be used to perform denial of service on a constrained
+ network. A multicast request SHOULD only be accepted if the request
+ is sufficiently authenticated and secured using, e.g., IPsec or an
+ appropriate object security mechanism.
+
+ CoRE Link Format parsers should be aware that a link description may
+ be cyclical, i.e., contain a link to itself. These cyclical links
+ could be direct or indirect (i.e., through referenced link
+ resources). Care should be taken when parsing link descriptions and
+ accessing cyclical links.
+
+7. IANA Considerations
+
+7.1. Well-Known 'core' URI
+
+ This memo registers the 'core' well-known URI in the Well-Known URIs
+ registry as defined by [RFC5785].
+
+ URI suffix: core
+
+ Change controller: IETF
+
+ Specification document(s): RFC 6690
+
+ Related information: None
+
+7.2. New 'hosts' Relation Type
+
+ This memo registers the new "hosts" Web Linking relation type as per
+ [RFC5988].
+
+ Relation Name: hosts
+
+ Description: Refers to a resource hosted by the server indicated by
+ the link context.
+
+ Reference: RFC 6690
+
+ Notes: This relation is used in CoRE where links are retrieved as a
+ "/.well-known/core" resource representation and is the default
+ relation type in the CoRE Link Format.
+
+ Application Data: None
+
+
+
+
+
+
+
+Shelby Standards Track [Page 16]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+7.3. New 'link-format' Internet Media Type
+
+ This memo registers the a new Internet media type for the CoRE Link
+ Format, 'application/link-format'.
+
+ Type name: application
+
+ Subtype name: link-format
+
+ Required parameters: None
+
+ Optional parameters: None
+
+ Encoding considerations: Binary data (UTF-8)
+
+ Security considerations:
+
+ Multicast requests using CoAP for the well-known link-format
+ resources could be used to perform denial of service on a constrained
+ network. A multicast request SHOULD only be accepted if the request
+ is sufficiently authenticated and secured using, e.g., IPsec or an
+ appropriate object security mechanism.
+
+ CoRE Link Format parsers should be aware that a link description may
+ be cyclical, i.e., contain a link to itself. These cyclical links
+ could be direct or indirect (i.e., through referenced link
+ resources). Care should be taken when parsing link descriptions and
+ accessing cyclical links.
+
+ Interoperability considerations: None
+
+ Published specification: RFC 6690
+
+ Applications that use this media type: CoAP server and client
+ implementations for resource discovery and HTTP applications that use
+ the link-format as a payload.
+
+ Additional information:
+
+ Magic number(s):
+
+ File extension(s): *.wlnk
+
+ Macintosh file type code(s):
+
+ Intended usage: COMMON
+
+ Restrictions on usage: None
+
+
+
+Shelby Standards Track [Page 17]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+ Author: CoRE WG
+
+ Change controller: IETF
+
+7.4. Constrained RESTful Environments (CoRE) Parameters Registry
+
+ This specification establishes a new Constrained RESTful Environments
+ (CoRE) Parameters registry, which contains two new sub-registries of
+ Link Target Attribute values (defined in [RFC5988]), one for Resource
+ Type (rt=) Link Target Attribute values and the other for Interface
+ Description (if=) Link Target Attribute values. No initial entries
+ are defined by this specification for either sub-registry.
+
+ For both sub-registries, values starting with the characters "core"
+ are registered using the IETF Review registration policy [RFC5226].
+ All other values are registered using the Specification Required
+ policy, which requires review by a designated expert appointed by the
+ IESG or their delegate.
+
+ The designated expert will enforce the following requirements:
+
+ o Registration values MUST be related to the intended purpose of
+ these attributes as described in Section 3.
+
+ o Registered values MUST conform to the ABNF reg-rel-type definition
+ of Section 2, meaning that the value starts with a lowercase
+ alphabetic character, followed by a sequence of lowercase
+ alphabetic, numeric, ".", or "-" characters, and contains no white
+ space.
+
+ o It is recommended that the period "." character be used for
+ dividing name segments and that the dash "-" character be used for
+ making a segment more readable. Example Interface Description
+ values might be "core.batch" and "core.link-batch".
+
+ o URIs are reserved for free use as extension values for these
+ attributes and MUST NOT be registered.
+
+ Registration requests consist of the completed registration template
+ below, with the reference pointing to the required specification. To
+ allow for the allocation of values prior to publication, the
+ designated expert may approve registration once they are satisfied
+ that a specification will be published.
+
+ Note that Link Target Attribute Values can be registered by third
+ parties if the Designated Expert determines that an unregistered Link
+ Target Attribute Value is widely deployed and not likely to be
+ registered in a timely manner.
+
+
+
+Shelby Standards Track [Page 18]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+ The registration template for both sub-registries is:
+
+ o Attribute Value:
+
+ o Description:
+
+ o Reference:
+
+ o Notes: [optional]
+
+ Registration requests should be sent to the core-parameters@ietf.org
+ mailing list, marked clearly in the subject line (e.g., "NEW RESOURCE
+ TYPE - example" to register an "example" relation type or "NEW
+ INTERFACE DESCRIPTION - example" to register an "example" Interface
+ Description).
+
+ Within at most 14 days of the request, the Designated Expert(s) will
+ either approve or deny the registration request, communicating this
+ decision to the review list and IANA. Denials should include an
+ explanation and, if applicable, suggestions as to how to make the
+ request successful.
+
+ Decisions (or lack thereof) made by the Designated Expert can be
+ first appealed to Application Area Directors (contactable using the
+ app-ads@tools.ietf.org email address or directly by looking up their
+ email addresses on http://www.iesg.org/ website) and, if the
+ appellant is not satisfied with the response, to the full IESG (using
+ the iesg@ietf.org mailing list).
+
+8. Acknowledgments
+
+ Special thanks to Peter Bigot, who has made a considerable number of
+ reviews and text contributions that greatly improved the document.
+ In particular, Peter is responsible for early improvements to the
+ ABNF descriptions and the idea for a new 'hosts' relation type.
+
+ Thanks to Mark Nottingham and Eran Hammer-Lahav for the discussions
+ and ideas that led to this document, and to Carsten Bormann, Martin
+ Thomson, Alexey Melnikov, Julian Reschke, Joel Halpern, Richard
+ Barnes, Barry Leiba, and Peter Saint-Andre for extensive comments and
+ contributions that improved the text.
+
+ Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido
+ Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey
+ Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin,
+ Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed
+ Beroset, Gilman Tolle, Robby Simpson, Colin O'Flynn, and David Ryan
+ for helpful comments and discussions that have shaped the document.
+
+
+
+Shelby Standards Track [Page 19]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+9. References
+
+9.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
+ Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
+ Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
+
+ [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
+ 10646", STD 63, RFC 3629, November 2003.
+
+ [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
+ Resource Identifier (URI): Generic Syntax", STD 66,
+ RFC 3986, January 2005.
+
+ [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and
+ Registration Procedures", BCP 13, RFC 4288, December 2005.
+
+ [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
+ IANA Considerations Section in RFCs", BCP 26, RFC 5226,
+ May 2008.
+
+ [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", STD 68, RFC 5234, January 2008.
+
+ [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying
+ Languages", BCP 47, RFC 5646, September 2009.
+
+ [RFC5987] Reschke, J., "Character Set and Language Encoding for
+ Hypertext Transfer Protocol (HTTP) Header Field
+ Parameters", RFC 5987, August 2010.
+
+ [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
+
+ [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
+ and D. Orchard, "URI Template", RFC 6570, March 2012.
+
+9.2. Informative References
+
+ [COAP] Shelby, Z., Hartke, K., Bormann, C., and B. Frank,
+ "Constrained Application Protocol (CoAP)", Work in
+ Progress, July 2012.
+
+
+
+
+
+
+Shelby Standards Track [Page 20]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+ [REST] Fielding, R., "Architectural Styles and the Design of
+ Network-based Software Architectures", 2000,
+ <http://www.ics.uci.edu/~fielding/pubs/dissertation/
+ top.htm>.
+
+ [RFC1034] Mockapetris, P., "Domain names - concepts and facilities",
+ STD 13, RFC 1034, November 1987.
+
+ [RFC1035] Mockapetris, P., "Domain names - implementation and
+ specification", STD 13, RFC 1035, November 1987.
+
+ [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) Part One: Format of Internet Message
+ Bodies", RFC 2045, November 1996.
+
+ [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded
+ Word Extensions: Character Sets, Languages, and
+ Continuations", RFC 2231, November 1997.
+
+ [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom
+ Syndication Format", RFC 4287, December 2005.
+
+ [RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6
+ over Low-Power Wireless Personal Area Networks (6LoWPANs):
+ Overview, Assumptions, Problem Statement, and Goals",
+ RFC 4919, August 2007.
+
+ [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
+ Uniform Resource Identifiers (URIs)", RFC 5785,
+ April 2010.
+
+ [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454,
+ December 2011.
+
+ [W3C.HTML.4.01]
+ Raggett, D., Le Hors, A., and I. Jacobs, "HTML 4.01
+ Specification", World Wide Web Consortium
+ Recommendation REC-html401-19991224, December 1999,
+ <http://www.w3.org/TR/1999/REC-html401-19991224>.
+
+ [WADL] Hadley, M., "Web Application Description Language (WADL)",
+ 2009, <http://java.net/projects/wadl/sources/svn/content/
+ trunk/www/wadl20090202.pdf>.
+
+
+
+
+
+
+
+
+Shelby Standards Track [Page 21]
+
+RFC 6690 CoRE Link Format August 2012
+
+
+Author's Address
+
+ Zach Shelby
+ Sensinode
+ Kidekuja 2
+ Vuokatti 88600
+ Finland
+
+ Phone: +358407796297
+ EMail: zach@sensinode.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Shelby Standards Track [Page 22]
+