RFC 6690

Constrained RESTful Environments (CoRE) Link Format

📅 published August 2012, from ietf
  • Internet Engineering Task Force (IETF) 🌸
  • Request for Comments: 6690 💖
  • Author: Z. Shelby, Sensinode ✨
  • Category: Standards Track 👑
  • Date: August 2012 📅
  • ISSN: 2070-1721 🦋

Abstract ✨

okay so this spec is all about Web Linking 💅 It defines a link format that tiny constrained web servers can use to describe the resources they host, the attributes of those resources, and how the links relate to each other 🔗 It's built on the HTTP Link Header field from RFC 5988, and the CoRE Link Format travels as a payload and gets its own Internet media type 🎀 ("RESTful" just refers to the Representational State Transfer (REST) architecture, obviously 🙈) There's also a well-known URI that acts as the default entry point for asking a server for its list of links 🧚

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, received public review, and got approved for publication by the Internet Engineering Steering Group (IESG) 💅 If you want more on Internet Standards, check out Section 2 of RFC 5741 📚

for info on the current status, any errata, and how to give feedback, go to http://www.rfc-editor.org/info/rfc6690 💖

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, because 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 they are provided without warranty as described in the Simplified BSD License 🫶

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

1. Introduction ✨

the Constrained RESTful Environments (CoRE) takes the Representational State Transfer (REST) architecture [REST] and makes it work for the most constrained nodes (think 8-bit microcontrollers with limited memory) and networks (like IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) [RFC4919]) 🤖 CoRE is aimed at Machine-to-Machine (M2M) apps like smart energy and building automation 🏠⚡

finding resources on a constrained server is a huge deal in M2M land 😭 There are no humans in the loop, and static interfaces make everything super fragile 💀 Discovering resources on an HTTP [RFC2616] web server is usually called "Web Discovery," and describing relations between resources is called "Web Linking" [RFC5988] In this spec, we call it CoRE Resource Discovery when we're finding resources on a constrained web server, looking at their attributes, and checking out other resource relations 🎀

the main job of a discovery mechanism is handing out Universal Resource Identifiers (URIs, called links) for the server's resources, plus attributes about those resources and any extra link relations 🔗 In CoRE, this list of links is its own resource (instead of HTTP headers that come along with one specific resource) 🧚 This document sets up a link format for CoRE Resource Discovery by extending the HTTP Link Header format [RFC5988] to describe these links 💅 The CoRE Link Format travels as a payload and gets an Internet media type 🎀 The well-known relative URI /.well-known/core is the default entry point for asking a server for its list of links, which is how you do CoRE Resource Discovery 🦋 This spec works with the Constrained Application Protocol (CoAP) [COAP], HTTP, or any other suitable web transfer protocol 🌈 The link format can also be saved as a file 📁

1.1. Web Linking in CoRE 🔗

technically, the CoRE Link Format is a serialization of a typed link from [RFC5988], used to describe relationships between resources (that's "Web Linking") 💖 Here, Web Linking gets extended with specific constrained M2M attributes 🤖 The links ride in a message payload instead of an HTTP Link Header field, and there's a default interface for discovering a server's resources 🎀 This spec also introduces a new relation type, "hosts" (from the verb "to host") 🌸 It says the resource is hosted by the server the link document came from 🏠

in HTTP, the Link Header can carry link info about a resource along with an HTTP response 🌷 That's perfect for a web server and browser, where you want more info about a resource after you've already accessed it 👀 In CoRE, the big use case for Web Linking is figuring out which resources a server hosts in the first place 🔍 Some resources might have more links attached, but that's supposed to be the exception 🙈 So the CoRE Link Format is carried as a resource representation of a well-known URI 🧚 It still reuses the HTTP Link Header serialization format defined in [RFC5988] 💅

1.2. Use Cases 💡

Web Linking is everywhere on today's web, like describing the author of a page or linking pages together (next chapter, previous chapter, that kind of thing) 📖 It also works for M2M apps, where typed links help a machine client find resources on a server and figure out how to use them 🤖 This section covers a few ways the CoRE Link Format could be used in M2M apps, and for more technical examples you can jump to Section 5 🦋 M2M apps are super varied, so these use cases stay generic on purpose 🌈 This spec assumes that different deployments or application domains will define the right REST Interface Descriptions along with Resource Types, so discovery actually means something 💜

1.2.1. Discovery 🔎

in M2M apps like home or building automation, local clients and servers need to find and talk to each other with no human involved 🏡 The CoRE Link Format lets servers in those environments make their resources discoverable 💖

Resource Discovery can happen unicast or multicast 🌸 If you already know a server's IP address (either a priori or resolved through the Domain Name System (DNS) [RFC1034][RFC1035]), unicast discovery finds the entry point to the resource you want 🎯 Here you send a GET to /.well-known/core on the server, and it sends back a payload in the CoRE Link Format 🎁 The client then matches the right Resource Type, Interface Description, and possibly media type [RFC2045] for its app 🧩 You can also put these attributes in the query string to filter how many links come back in the response ✨

Multicast Resource Discovery is handy when a client needs to find a resource within a limited scope that supports IP multicast 📡 You make a GET request to the right multicast address for /.well-known/core 📣 To keep the number and size of responses in check, a query string is recommended with the known attributes 🫶 Usually a resource gets discovered by its Resource Type and/or Interface Description, plus any app-specific attributes 🦋

1.2.2. Resource Collections 🗃️

RESTful M2M interfaces love collections of resources 🍓 Think of an index of temperature sensors on a data collection node, or a list of alarms on a home security controller 🚨 The CoRE Link Format helps you find the entry point to a collection and walk through its members 🚶‍♀️ The entry point of a collection should always be included in /.well-known/core so it can be discovered 🔑 The members can be defined either through the Interface Description of the resource plus a parameter resource for the collection's size, or by using the link format to describe each resource in the collection 📋 Those links could live under /.well-known/core, or be hosted in the collection's root resource, for example 🌳

1.2.3. Resource Directory 📚

in lots of deployments, like constrained networks with sleeping servers or big M2M setups with bandwidth-limited access networks, it makes total sense to set up resource directory entities 🧠 These store links to resources that live on other servers 💅 Think of it as a limited search engine for constrained M2M resources 🔍✨

the CoRE Link Format lets a server register its resources with a resource directory, or lets a resource directory poll for resources 🫶 Registration works by having each server POST its resources to /.well-known/core on the resource directory 📮 The directory then adds those links under an appropriate resource 🎀 Any client can find these links by making a request to a resource directory lookup interface 🦋

1.3. Terminology 🎀

okay so 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]. these are the official vibe-check words 💅

this spec uses ABNF (Augmented Backus-Naur Form) [RFC5234] notation, including the core rules from Appendix B of that doc 🧚

you need to already know all the terms and concepts covered in [RFC5988] and [RFC6454] 📚 on top of that, this spec has its own little glossary:

  • 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 it's 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]. it's 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" 🦋

okay so the CoRE Link Format is basically a glow-up of the HTTP Link Header field from [RFC5988] 💅 it doesn't need special XML or binary parsing, it's pretty compact, and it's extensible, which are all the things CoRE needs 🫶 it's worth noting that this link format is just one serialization of typed links from [RFC5988]. others include HTML links, Atom feed links [RFC4287], or HTTP Link Header fields. resources found in the CoRE Link Format may also show up in other formats out on the greater Internet. the CoRE Link Format is only expected to be supported in constrained networks and M2M systems 🤖

Section 5 of [RFC5988] didn't require an Internet media type for the link format, since it was meant to ride along in an HTTP header. so this spec defines the Internet media type application/link-format for the CoRE Link Format (see Section 7.3) 🎀 the HTTP Link Header field depends on [RFC2616] for its encoding, but the CoRE Link Format is encoded as UTF-8 [RFC3629]. a decoder isn't expected to validate the UTF-8 encoding (but it's not prohibited from doing so), and it doesn't need to do any UTF-8 normalization. UTF-8 data can be compared bitwise, which lets values hold UTF-8 data with zero extra complexity for constrained nodes 🌈

the CoRE Link Format is equivalent to the [RFC5988] link format. the ABNF in this spec is repeated with improvements so it's compliant with [RFC5234], and it adds 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 it MUST NOT be defined as a link parameter 🙅‍♀️ like in [RFC5988], multiple link descriptions are separated by commas. commas can also show up in quoted strings and URIs, but they don't end a description 🧐 to convert an HTTP Link Header field into this link format, first you remove the Link: HTTP header, remove any linear whitespace (LWS), convert the header value to UTF-8, and then decode any percent-encodings 🧹

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 ) ] )

               / ( 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 carries one target URI as a URI-reference inside angle brackets (<>). the context URI of a link (also called the base URI in [RFC3986]) gets decided by these rules in this spec:

  • (a) the context URI is set to the anchor parameter, when it's specified.
  • (b) origin of the target URI, when it's specified.
  • (c) origin of the link format resource's base URI.

since links in the CoRE Link Format are usually describing resources hosted by a server, the new relation type hosts is assumed when there's no relation parameter (see Section 7.2) 🏠 the hosts relation type (from the verb "to host") says the target URI is a resource hosted by the server (aka the server hosts the resource) that's indicated by the context URI. the target URI MUST be a relative URI of the context URI for this relation type 🫶

wanna express other relations? no problem, links can use any registered relation by including the relation parameter 🌸 the context of a relation can be defined with the anchor parameter. that way you can express relations between resources hosted on a server, or between hosted resources and external resources 🦋

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 still choose to ignore these links, though. it's not expected that all implementations will be able to get useful info out of explicitly anchored links 🙈

these CoRE-specific target attributes are defined on top of the ones already defined in [RFC5988]. they describe info that's useful for accessing the target link of the relation, and sometimes they can use the syntactical form of a URI 🌈 such a URI MAY be dereferenced (like, to get a description of the link relation), but that's not part of the protocol, and it MUST NOT be done automatically on link evaluation 🙅‍♀️ when attribute values get compared, they MUST be compared as strings 🔍

3.1. Resource Type 'rt' Attribute 🍓

the Resource Type 'rt' attribute is an opaque string used to give a resource an application-specific semantic type. think of it as a noun describing the resource 🧁 for a temperature resource, this could be something like an application-specific semantic type outdoor-temperature, or a URI pointing at 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 isn't meant for giving a resource a human-readable name, bestie 🙅‍♀️ that's what the title attribute from [RFC5988] is for. the Resource Type attribute MUST NOT appear more than once in a link 💀

3.2. Interface Description 'if' Attribute 🦋

the Interface Description 'if' attribute is an opaque string used to give a name or URI that points at a specific interface definition for interacting with the target resource 💅 think of it as describing the verbs you can use on a resource. this attribute is meant to describe the generic REST interface for interacting with a resource or a set of resources ✨ it's expected that an Interface Description gets 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.

an 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 you get back from doing a GET on the target URI 🌸 for links to CoAP resources, this attribute isn't expected for small resources that can comfortably fit in a single Maximum Transmission Unit (MTU), but it SHOULD be included for resources larger than that 📦 the maximum size estimate attribute MUST NOT appear more than once in a link.

no defined upper limit to the value of the 'sz' attributes, so implementations MUST be prepared to accept large values 😭 one implementation strategy is to convert any value bigger than a reasonable size limit for that implementation into a special value Big. later on, processing can read Big as "this size was so huge that this implementation can't process it" 🫠

4. Well-Known Interface ✨

Okay so resource discovery in CoRE happens through a well-known resource URI 🔗 that hands back a list of links about the resources hosted on that server, plus other link relations. Well-known resources have a path that starts with /.well-known/, as specified in [RFC5785] 🧚. This spec creates one brand-new well-known resource for CoRE Resource Discovery: /.well-known/core 💖.

A server implementing this specification MUST support this resource on the default port for the protocol, for the purpose of resource discovery 🫶. Honestly, the application gets to decide which links show up and how they're organized 💅. The /.well-known/core resource is meant to return links to the entry points of a server's resource interfaces 🌸. If you want fancier organization, you can include links to CoRE Link Format resources located elsewhere on the server, like an index 📚. If there are no links at all, you get a zero-length payload back 🫧. And the representation of this resource MUST be the CoRE Link Format described in Section 2 🎀.

The CoRE resource discovery interface supports these interactions:

  • 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 they might express other kinds of link relations as described in Section 2 ✨.
  • 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 🙈.
  • More capable servers, such as proxies, could support a resource directory by requesting the resource descriptions of other endpoints, or by allowing servers to POST requests to /.well-known/core 🧚‍♀️. The details of that resource directory functionality are, however, out of the scope of this specification and are expected to be specified separately 📝.

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*}

The variable search is a 1-element list with a single name/value pair, where:

  • name is either href, a link-param name defined in this specification, or any other link-extension name, and
  • 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 that attribute 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, and 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 that don't support filtering MUST simply ignore the query string and return the whole resource for unicast requests 🫶.

When you're using a transfer protocol like the Constrained Application Protocol (CoAP) that supports multicast requests, you have to be extra careful 🚨. A multicast request with a query string SHOULD NOT be responded to if filtering is not supported or if the filter does not match, which avoids a needless response storm 🌪️. The exception is when the IP stack interface can't indicate that the destination address was multicast 🤷‍♀️.

Here are some examples of valid query URIs 💅:

  • ?href=/foo matches a link-value that is anchored at /foo
  • ?href=/foo* matches a link-value that is anchored at a URI that starts with /foo
  • ?foo=bar matches a link-value that has a target attribute named foo with the exact value bar
  • ?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 🌾
  • ?foo=* matches a link-value that has a target attribute named foo 💖

5. Examples

Here are a few examples of typical link descriptions in this format 📖. Multiple resource descriptions in a representation are separated by commas 🍬. Linefeeds are also included in these examples for readability 👀. Even though these examples use CoAP response codes, they apply to HTTP as well, where the matching response code would be 200 OK 🌐.

This first example includes links to two sensors that share the same Interface Description 🌡️. Note that the default relation type for this link format is "hosts" in links with no rel= target attribute 🫶. So these links tell us that the Origin server we asked for /.well-known/core (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 for readability, the format actually looks like this 🤓:

</sensors/temp>;if="sensor",</sensors/light>;if="sensor"

This next example arranges link descriptions hierarchically, with the entry point linking to a sub-resource that contains links about the sensors 🪜.

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"

Here's what an example query filter might 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 how an "anchor" attribute relates 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"

If a client wants to find relations about a particular resource, it can run 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 last example shows a large firmware resource with a size attribute 📦. The consumer of this link would use the 'sz' attribute to figure out if the resource representation is too big and whether block transfer would be needed 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 💾. So 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 let any client read state variables, but only certain clients can write state (turn lights on or off) 💡. Servers that have authentication and authorization features SHOULD support the authentication features of the underlying transport protocols (HTTP or DTLS/TLS), and they should be able 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, leaving a link out doesn't, 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 🤥. So if it's important for a client to only get information from a known source, that source needs to be authenticated 🔑.

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., it may 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] 📝. The registration details are:

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] 🔗. The registration details are:

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

okay so this memo registers a brand new Internet media type for the CoRE Link Format, called application/link-format 🎀 here's the registration form:

Type name: application

Subtype name: link-format

Required parameters: None

Optional parameters: None

Encoding considerations: Binary data (UTF-8)

Security considerations:

bestie, this part is serious 😭 multicast requests using CoAP for the well-known link-format resources could be used to perform denial of service on a constrained network 💀 so a multicast request SHOULD only be accepted if it's sufficiently authenticated and secured, using something like IPsec or an appropriate object security mechanism 🔐

also, CoRE Link Format parsers should be aware that a link description may be cyclical, meaning it can contain a link to itself 🌀 those cyclical links could be direct or indirect (like going through referenced link resources). so take care when you parse link descriptions and access cyclical links, or you'll be stuck in a loop forever 🙈

Here's the rest of the form:

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
Author: CoRE WG

Change controller: IETF

7.4. Constrained RESTful Environments (CoRE) Parameters Registry ✨

this section sets up a new Constrained RESTful Environments (CoRE) Parameters registry 🧚 it holds two new sub-registries of Link Target Attribute values (defined in [RFC5988]): one for Resource Type (rt=) values and one for Interface Description (if=) values. no initial entries are defined by this specification for either sub-registry, so it's a clean slate 🌸

For both sub-registries, values starting with the characters "core" are registered using the IETF Review registration policy [RFC5226]. Everything else gets the Specification Required policy, which means a designated expert appointed by the IESG (or their delegate) has to review it 👑

The designated expert is going to enforce these requirements:

  • Registration values MUST be related to the intended purpose of these attributes as described in Section 3.
  • Registered values MUST conform to the ABNF reg-rel-type definition of Section 2. In normal words, that means the value starts with a lowercase alphabetic character, followed by a sequence of lowercase alphabetic, numeric, ".", or "-" characters, and contains no white space 💅
  • 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" 🦋
  • URIs are reserved for free use as extension values for these attributes and MUST NOT be registered. (URIs are off-limits for registration, periodt 🙅‍♀️)

Registration requests consist of the completed registration template below, with the reference pointing to the required specification. To allow values to be allocated before publication, the designated expert may approve a registration once they're 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. ✨

The registration template for both sub-registries is:

Attribute Value:

Description:

Reference:

Notes: [optional]

Registration requests should be sent to the core-parameters@ietf.org mailing list, with the subject line clearly marked. For example, "NEW RESOURCE TYPE - example" registers an "example" relation type, and "NEW INTERFACE DESCRIPTION - example" registers an "example" Interface Description 💌

Within at most 14 days of the request, the Designated Expert(s) will either approve or deny it, and tell both the review list and IANA what they decided 🗓️ if it's a denial, they should include an explanation and, where it applies, suggestions for how to make the request work next time 🫶

Decisions (or the lack of one) made by the Designated Expert can be appealed first to the Application Area Directors (you can reach them at the app-ads@tools.ietf.org email address, or by finding their email addresses directly on the http://www.iesg.org/ website). If the appellant still isn't happy with the response, they can take it to the full IESG, using the iesg@ietf.org mailing list 📣

8. Acknowledgments 🫶

Special thanks to Peter Bigot, who wrote a huge pile of reviews and text contributions that made the document so much better 🌟 Peter was responsible for early improvements to the ABNF descriptions, and also came up with the idea for the new 'hosts' relation type 🍓

Thanks to Mark Nottingham and Eran Hammer-Lahav for the discussions and ideas that led to this document 💜 Also a big thank you to Carsten Bormann, Martin Thomson, Alexey Melnikov, Julian Reschke, Joel Halpern, Richard Barnes, Barry Leiba, and Peter Saint-Andre for their 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 the helpful comments and discussions that shaped the document 🌈

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.

[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>.

Author's Address 🌸

Zach Shelby
Sensinode
Kidekuja 2
Vuokatti  88600
Finland

Phone: +358407796297
EMail: zach@sensinode.com
📦 where this page comes from