One document matched: draft-ietf-core-link-format-01.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!-- This template is for creating an Internet Draft using xml2rfc,
which is available here: http://xml.resource.org. -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC0792 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.0792.xml">
<!ENTITY RFC2045 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2045.xml">
<!ENTITY RFC2046 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2046.xml">
<!ENTITY RFC2616 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml">
<!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC4288 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4288.xml">
<!ENTITY RFC4346 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4346.xml">
<!ENTITY RFC4347 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4347.xml">
<!ENTITY RFC4944 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4944.xml">
<!ENTITY RFC5234 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml">
<!ENTITY RFC5785 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5785.xml">
<!ENTITY I-D.bormann-6lowpan-6lowapp-problem SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.bormann-6lowpan-6lowapp-problem.xml">
<!ENTITY I-D.shelby-6lowapp-encoding SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.shelby-6lowapp-encoding.xml">
<!ENTITY I-D.frank-6lowapp-chopan SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.frank-6lowapp-chopan.xml">
<!ENTITY I-D.gold-6lowapp-sensei SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-gold-6lowapp-sensei-00.xml">
<!ENTITY I-D.martocci-6lowapp-building-applications SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-martocci-6lowapp-building-applications-00.xml">
<!ENTITY I-D.sturek-6lowapp-smartenergy SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-sturek-6lowapp-smartenergy-00.xml">
<!ENTITY I-D.moritz-6lowapp-dpws-enhancements SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-moritz-6lowapp-dpws-enhancements-00.xml">
<!ENTITY I-D.shelby-core-coap-req SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-shelby-core-coap-req-02.xml">
<!ENTITY I-D.nottingham-http-link-header SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-nottingham-http-link-header-10.xml">
<!ENTITY I-D.eggert-core-congestion-control SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-eggert-core-congestion-control-00.xml">
<!ENTITY I-D.hartke-coap-observe SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-hartke-coap-observe-02.xml">
<!ENTITY I-D.ietf-core-coap SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-core-coap-02.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!-- For a complete list and description of processing instructions (PIs),
please see http://xml.resource.org/authoring/README.html. -->
<!-- Below are generally applicable Processing Instructions (PIs) that most I-Ds might want to use.
(Here they are set differently than their defaults in xml2rfc v1.32) -->
<?rfc strict="yes" ?>
<!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc tocdepth="3"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<!-- control vertical white space
(using these PIs as follows is recommended by the RFC Editor) -->
<?rfc compact="yes" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?>
<!-- keep one blank line between list items -->
<!-- end of list of popular I-D processing instructions -->
<rfc category="std" ipr="trust200902" docName="draft-ietf-core-link-format-01">
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no" ?>
<?rfc strict="yes" ?>
<front>
<title>CoRE Link Format</title>
<author initials="Z" surname="Shelby" fullname="Zach Shelby">
<organization>
Sensinode
</organization>
<address>
<postal>
<street>Kidekuja 2</street>
<city>Vuokatti</city>
<code>88600</code>
<country>FINLAND</country>
</postal>
<phone>+358407796297</phone>
<email>zach@sensinode.com</email>
</address>
</author>
<!--
<author initials="M" surname="Nottingham" fullname="Mark Nottingham">
<organization>
</organization>
<address>
<postal>
<street></street>
<city></city>
<code></code>
<country></country>
</postal>
<phone></phone>
<email>mnot@mnot.net</email>
</address>
</author>
-->
<date year="2010"/>
<area>Internet</area>
<workgroup>CoRE</workgroup>
<keyword>CoRE, Link Format, HTTP Link Header Format, Resource Discovery</keyword>
<abstract>
<t>
This document defines a link format for use by constrained CoAP web servers to describe URIs of resources offered along with other attributes. Based on the HTTP Link Header format, the CoRE link format is carried as a payload and is assigned an Internet media type. A well-known URI is defined as a default entry-point for requesting the list of links to resources hosted by a server.
</t>
</abstract>
</front>
<middle>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor='introduction' title="Introduction">
<t>
The Constrained RESTful Environments (CoRE) working group aims at realizing the REST architecture in a suitable form for the most constrained nodes (e.g. 8-bit microcontrollers with limited RAM and ROM) and networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M) applications such as smart energy and building automation <xref target="I-D.shelby-core-coap-req"/>.
</t>
<t>
The discovery of resources offered 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 Web Server is typically called Web Discovery. In this document we refer to the discovery of resources offered by a CoAP server as resource discovery.
</t>
<t>
The core function of such a discovery mechanism is to provide URIs ("links") for the resources offered, complemented by information describing the relationship between the resource description and each resource as well as other attributes. When such a collection of attributed resource references (links) is offered as a resource of its own (as opposed to as HTTP headers delivered with a different resource), we speak of its representation as a link-format.
</t>
<t>
This document specifies a link-format for use in CoRE resource discovery by extending the HTTP Link Header Format <xref target="I-D.nottingham-http-link-header"/> to describe resources hosted by a constrained server. The CoRE link-format is carried as a payload and is assigned an Internet media type. A well-known URI "/.well-known/core" is defined as a default entry-point for requesting the list of links to resources hosted by a server.
</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor='format' title="Link Format">
<t>
CoRE resource discovery extends the HTTP Link Header format specified in <xref target="I-D.nottingham-http-link-header"/> which is specified in Augmented Backus-Naur Form (ABNF) notation <xref target="RFC2616"/>. The format does not require special XML or binary parsing, and is extensible.
</t>
<t>
This link format is used for a similar purpose to that described in <xref target="I-D.nottingham-http-link-header"/>, to describe one or more relationships between resources. However in this specification the link format is extended with specific constrained M2M link parameters, links are carried as a payload rather than in a message header, and a default interface is defined to discover resources described by these links.
</t>
<t>
<xref target="I-D.nottingham-http-link-header"/> did not require an Internet media type for this link format, as it assumes to be carried in an HTTP header. This specification thus requests a Internet media type for this format (see <xref target="iana-mime"/>).
</t>
<t>
The CoRE link format uses the ABNF description and associated rules in Section 5 of <xref target="I-D.nottingham-http-link-header"/>. In addition, the URI, URI-reference and pchar rules are taken from <xref target="RFC3986"/>. The "Link:" text is omitted as that is part of the HTTP Link Header.
Multiple link descriptions are separated by commas. The CoRE link format MUST use the US-ASCII character set (support for RFC2231 encoding of non-ASCII content TBD). The following CoRE specific link-extension parameters to the format are defined:
</t>
<figure>
<artwork><![CDATA[
link-extension = ( "d" "=" <"> URI-reference <">)
link-extension = ( "sh" "=" <"> URI-reference <">)
link-extension = ( "n" "=" quoted-string )
link-extension = ( "ct" "=" integer )
link-extension = ( "id" "=" quoted-string )
integer = 1*DIGIT
]]></artwork>
</figure>
<section title="Target and context URIs">
<t>
Each link description conveys one target URI as a URI-reference inside angle brackets ("<>"). The context URI of a link (also called base URI in <xref target="RFC3986"/>) conveyed in the description is by default the URI of the resource that returned the link-format representation. Thus each link can be thought of as describing a target resource hosted by the server in the absence of further relation information. This is an important difference to the way the HTTP Link Header format is used, as it is included in the header of an HTTP response for some URI (this URI is by default the context). Thus the HTTP Link Header is by default relating the target URI to the URI that was requested. In comparison, the CoRE link format includes one or more link entries, each describing a resource hosted by a server. See Section 5 of <xref target="RFC3986"/> for a description of how URIs are constructed from URI references.
</t>
<t>
As per Section 5.2 of <xref target="I-D.nottingham-http-link-header"/> a link description MAY include an "anchor" attribute, in which case the context is the URI included in that attribute. This can be used to describe a relationship between two resources. A consuming implementation can however choose to ignore such links. It is not expected that most implementations will be able to derive useful information from explicitly anchored links.
</t>
</section>
<section title="Link relation 'rel' usage">
<t>
Link descriptions in CoRE are typically used to describe entry points to services hosted by the server, and thus in the absence of the rel attribute the registered "service" relation type is assumed. In the CoRE link format the service relation type indicates that the link is a service hosted by the server (in the absence of the anchor attribute). A description can make use of any registered relation type or extension types in the form of a URI by including the rel attribute. </t>
</section>
<section title="Description 'd' usage">
<t>
The description "d" attribute can provide a URI to a specific interface definition used to access the target resource. This could be for example a URI to the WADL definition of the target resource. Multiple description attributes MAY appear in a link description.
</t>
</section>
<section title="Alternative URI 'sh' usage">
<t>
This attribute can be included to define an alternative short URI which can also be used to access the target resource. Multiple alternative short URI attributes MAY appear in a link description.
</t>
</section>
<section title="Resource name 'n' usage">
<t>
The resource name "n" attribute is used to assign either a human readable or a semantically important name to a resource. In the case of a temperature sensor resource the name could be something like "Temperature in Centigrade", a URI to an ontology like "http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature" or an application-specific semantic name like "TemperatureC". Multiple name attributes MAY appear in a link description.
</t>
</section>
<section title="Content-type code 'ct' usage">
<t>
The Content-type code "ct" attribute provides a hint about the Internet media type this resource returns. The value is in the CoAP identifier code format as a decimal ASCII integer <xref target="I-D.ietf-core-coap"/>. For example application/xml would be indicated as "ct=41". If no Content-type code attribute is present then nothing about the type can be assumed. The Content-type code attribute MUST NOT appear more than once in a link description.
</t>
<t>
Alternatively, the "type" attribute MAY be used to indicate an Internet media type as a quoted-string. It is not however expected that constrained implementations are able to parse quoted-string Content-type values.
</t>
</section>
<section title="Resource identifier 'id' usage">
<t>
The resource identifier "id" field is a unique identifier (e.g. UUID or XRI) for this resource for use in e.g. resource or search directories. The resource identifier attribute MUST NOT appear more than once in a link description.
</t>
</section>
<section anchor='examples' title="Examples">
<t>
A few examples of typical link descriptions in this format follows. Multiple resource descriptions in a representation are separated by commas. Commas can also occur in quoted strings and URIs but do not end a description. Linefeeds never occur in the actual format, but are shown in the example for readability. </t>
<t>This example includes link descriptions for an index to sensors hosted by a server, along with links two two different sensors.</t>
<figure>
<artwork><![CDATA[
GET /.well-known/core
</sensors>;rel="index";n="Sensor Index",
</sensors/temp>;sh="/t";n="TemperatureC",
</sensors/light>;sh="/l";ct=41;n="LightLux"
]]></artwork>
</figure>
<t>This example arranges link descriptions hierarchically, with the entry point including a link description to a sub-resource containing link descriptions about the sensors.</t>
<figure>
<artwork><![CDATA[
GET /.well-known/core
</.well-known/core/sensors>;rel="section"
;type="application/link-format"
GET /.well-known/core/sensors
</sensors/temp>;sh="/t";n="TemperatureC",
</sensors/light>;sh="/l";ct=41;n="LightLux"
]]></artwork>
</figure>
<!--
<t>This example shows the use of an anchor atttribute to relate the temperature sensor resource to an external description.</t>
<figure>
<artwork><![CDATA[
GET /.well-known/core
</sensors>;rel="index",n="Sensor Index",
</sensors/temp>;sh="/t";n="TemperatureC",
</sensors/light>;sh="/l";ct=41;n="LightLux",
<http://www.example.com/sensors/temp123>;anchor="/sensors/temp"
;rel=describedby,
]]></artwork>
</figure>
-->
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor='well-known' title="Well-known Interface">
<t>
Resource discovery in CoRE is accomplished through the use of a well-known resource URI which returns a list of links (resource descriptions) offered by that constrained server. Well-known resources have a path component that begins with "/.well-known/" as specified in [RFC5785]. This document defines a new well-known path prefix for CoRE discovery "/.well-known/core" [Section 5.1]. A server implementing this specification MUST support this path prefix on the default port appropriate for the protocol for the purpose of resource discovery. It is however up to the application which link descriptions are included and how they are organized. In the absense of any links, a zero-length payload is returned. The resource representation of this resource is described in <xref target="format"/>.
</t>
<t>
The CoRE resource discovery interface supports the following interactions:
<list style="symbols">
<t>Performing a GET on /.well-known/core to the default port returns a list of link descriptions available from a CoAP server (if any). </t>
<t>Filtering may be performed on any of the link format attributes using a query string as specified in <xref target="filtering"/>. For example [GET /.well-known/core?n=TemperatureC] would request resources with the name TemperatureC. A server is not however required to support filtering.
</t>
<t>More capable servers such as proxies could support a resource directory by requesting the resource descriptions of other end-points or accepting [POST /.well-known/core messages] from other servers. This adds the resources of other end-points as a sub-resource in which absolute URIs are included for the link-values. The details of such resource directory functionality is however out of scope for this document.</t>
</list>
</t>
<t>
End-points with a large number of resources SHOULD include resource descriptions only for important services or collections and organize their resource descriptions into a hierarchy of link resources. This is done by including links in the /.well-known/core list which point to other resource lists, e.g. <![CDATA[</.well-known/core/sensors>]]>. Such a hierarchy SHOULD be under the /.well-known/core path but could be located elsewhere.
</t>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor='filtering' title="Query Filtering">
<t>
A server implementing this document MAY recognize the query part of a resource-discovery URI as a filter on the resources to be returned. The query part should conform to the following syntax:
</t>
<figure>
<artwork><![CDATA[
filter-query = resource-param "=" query-pattern
resource-param = "uri" | "d" | "sh" | "n" | "id"
query-pattern = 1*pchar [ "*" ]
]]></artwork>
</figure>
<t>
The resource-param "uri" refers to the URI-reference between the <![CDATA["<" and ">"]]> characters of a link-value. Other resource-param values refer to the link attribute they name. (TBD: Do we want to add the resource description attributes that I excluded, or the standard link-param attributes from I-D.nottingham-http-link-header?) Filtering is performed by comparing the query-pattern against the value of the attribute identified by the resource-param for each link-value in the collection of resources identified by the URI path.</t>
<t>
If the decoded query-pattern does not end with "*", a link value matches the query only if the value of the attribute or URI-reference denoted by the resource-param is bytewise identical to the query-pattern. If the decoded query-pattern ends with "*", it is sufficient that the remainder of the query-pattern be a prefix of the value denoted by the resource-param.
</t>
<t>
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. An exact match is performed on the query string, and a 200 OK response is returned with link descriptions that contains the matching entries (if any). In contrast, a multicast request with a query string MUST not be responded to if filtering is not supported (to avoid a needless response storm). If resource descriptions are organized hierarchically, a query on the root resource /.well-known/core SHOULD return all matching resource descriptions from the entire hierarchy. An example query on the link descriptions from <xref target="format"/> may look like:
</t>
<figure>
<artwork><![CDATA[
GET /.well-known/core?n=LightLux
</sensors/light>;sh="/l";ct=41;n="LightLux"
]]></artwork>
</figure>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Security Considerations">
<t>
This document needs the same security considerations as described in Section 7 of <xref target="I-D.nottingham-http-link-header"/>. The /.well-known/core resource may be protected e.g. using DTLS when hosted on a CoAP server as per <xref target="I-D.ietf-core-coap"/> Section 10.2.
</t>
<t>
Great care must be taken when processing multicast requests using CoAP for the well-known link-format resources, as this 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.
</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="IANA Considerations">
<section anchor='iana-well-known' title="Well-known 'core' URI">
<t>This memo registers the "core" well-known URI in the Well-Known
URI Registry as defined by [RFC5785].</t>
<t>URI suffix: core</t>
<t>Change controller: IETF</t>
<t>Specification document(s): [[ this document ]]</t>
<t>Related information: None</t>
</section>
<section anchor='iana-mime' title="New link-format Internet media type">
<t>This memo registers the a new Internet media type for the CoRE link format, application/link-format. </t>
<t>Type name: application </t>
<t>Subtype name: link-format </t>
<t>Required parameters: None </t>
<t>Optional parameters: The query string may contain uri= to match the URI, or any other attribute defined for the link format to match that attribute. </t>
<t>Encoding considerations: US-ASCII </t>
<t>Security considerations: None </t>
<t>Interoperability considerations: </t>
<t>Published specification: [[ this document ]] </t>
<t>Applications that use this media type: CoAP server and client implementations. </t>
<t>Additional information: </t>
<t>Magic number(s): </t>
<t>File extension(s): </t>
<t>Macintosh file type code(s): </t>
<t>Intended usage: COMMON </t>
<t>Restrictions on usage: None </t>
<t>Author: CoRE WG </t>
<t>Change controller: IETF </t>
</section>
</section>
<!------------------------------------------------------>
<!-- SECTION: ACKNOWLEDGMENTS -->
<!------------------------------------------------------>
<section title="Acknowledgments">
<t>Special thanks to Mark Nottingham and Eran Hammer-Lahav for discussions and ideas that led to this draft, and to Carsten Bormann and Peter Bigot for extensive comments and contributions that improved the text.</t>
<t>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, Peter Bigot, Colin O'Flynn and David Ryan for helpful comments and discussions that have shaped the document.</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Changelog">
<t>Changes from ietf-00 to ietf-01:
<list>
<t>o Editorial changes to correct references. </t>
<t>o Formal definition for filter query string.</t>
<t>o Removed URI-reference option from "n" and "id". </t>
<t>o Added security text about multicast requests. </t>
</list>
</t>
<t>Changes from shelby-00 to ietf-00:
<list>
<t>o Fixed the ABNF link-extension definitions (quotes around URIs, integer definition). </t>
<t>o Clarified that filtering is optional, and the query string is to be ignored if not supported (and the URL path processed as normally). </t>
<t>o Required support of wildcard * processing if filtering is supported.</t>
<t>o Removed the aussumption of a default content-type assumption.</t>
</list>
</t>
</section>
</middle>
<back>
<references title='Normative References'>
&RFC2616;
&RFC3986;
<!-- &RFC5234;
&RFC5785; -->
&I-D.nottingham-http-link-header;
&I-D.ietf-core-coap;
</references>
<references title='Informative References'>
&I-D.shelby-core-coap-req;
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 02:58:55 |