Thing-to-Thing Research Group K. Hartke
Internet-Draft Ericsson
Intended status: Experimental October 22, 2018
Expires: April 25, 2019
The Constrained RESTful Application Language (CoRAL)
draft-hartke-t2trg-coral-06
Abstract
The Constrained RESTful Application Language (CoRAL) defines a data
model and interaction model as well as two specialized serialization
formats for the description of typed connections between resources on
the Web ("links"), possible operations on such resources ("forms"),
as well as simple resource metadata.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 25, 2019.
Copyright Notice
Copyright (c) 2018 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
(https://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.
Hartke Expires April 25, 2019 [Page 1]
Internet-Draft Constrained RESTful Application Language October 2018
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 4
2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Web Linking . . . . . . . . . . . . . . . . . . . . . . . 4
2.2. Links, Forms, and Metadata . . . . . . . . . . . . . . . 5
3. Data and Interaction Model . . . . . . . . . . . . . . . . . 6
3.1. Browsing Context . . . . . . . . . . . . . . . . . . . . 7
3.2. Documents . . . . . . . . . . . . . . . . . . . . . . . . 7
3.3. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.4. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.5. Form Data . . . . . . . . . . . . . . . . . . . . . . . . 9
3.6. Embedded Representations . . . . . . . . . . . . . . . . 9
3.7. Navigation . . . . . . . . . . . . . . . . . . . . . . . 10
3.8. History Traversal . . . . . . . . . . . . . . . . . . . . 11
4. Binary Format . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1. Data Structure . . . . . . . . . . . . . . . . . . . . . 11
4.1.1. Documents . . . . . . . . . . . . . . . . . . . . . . 12
4.1.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 12
4.1.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.4. Embedded Representations . . . . . . . . . . . . . . 15
4.1.5. Directives . . . . . . . . . . . . . . . . . . . . . 15
5. Textual Format . . . . . . . . . . . . . . . . . . . . . . . 16
5.1. Lexical Structure . . . . . . . . . . . . . . . . . . . . 16
5.1.1. Line Terminators . . . . . . . . . . . . . . . . . . 16
5.1.2. White Space . . . . . . . . . . . . . . . . . . . . . 16
5.1.3. Comments . . . . . . . . . . . . . . . . . . . . . . 16
5.1.4. Identifiers . . . . . . . . . . . . . . . . . . . . . 17
5.1.5. IRI References . . . . . . . . . . . . . . . . . . . 17
5.1.6. Literals . . . . . . . . . . . . . . . . . . . . . . 17
5.1.7. Punctuators . . . . . . . . . . . . . . . . . . . . . 21
5.2. Syntactic Structure . . . . . . . . . . . . . . . . . . . 21
5.2.1. Documents . . . . . . . . . . . . . . . . . . . . . . 21
5.2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 22
5.2.4. Embedded Representations . . . . . . . . . . . . . . 23
5.2.5. Directives . . . . . . . . . . . . . . . . . . . . . 24
6. Usage Considerations . . . . . . . . . . . . . . . . . . . . 25
6.1. Specifying CoRAL-based Applications . . . . . . . . . . . 25
6.1.1. Naming Resources . . . . . . . . . . . . . . . . . . 26
6.1.2. Implementation Limits . . . . . . . . . . . . . . . . 26
6.2. Minting New Relation Types . . . . . . . . . . . . . . . 27
6.3. Registering Relation Types . . . . . . . . . . . . . . . 27
6.4. Expressing Link Target Attributes . . . . . . . . . . . . 29
6.5. Embedding CoRAL in CBOR Structures . . . . . . . . . . . 29
7. Security Considerations . . . . . . . . . . . . . . . . . . . 30
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31
Hartke Expires April 25, 2019 [Page 2]
Internet-Draft Constrained RESTful Application Language October 2018
8.1. Media Type "application/coral+cbor" . . . . . . . . . . . 31
8.2. Media Type "text/coral" . . . . . . . . . . . . . . . . . 32
8.3. CoAP Content Formats . . . . . . . . . . . . . . . . . . 33
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 34
9.1. Normative References . . . . . . . . . . . . . . . . . . 34
9.2. Informative References . . . . . . . . . . . . . . . . . 36
Appendix A. Core Vocabulary . . . . . . . . . . . . . . . . . . 37
A.1. Link Relation Types . . . . . . . . . . . . . . . . . . . 38
A.2. Form Relation Types . . . . . . . . . . . . . . . . . . . 38
A.3. Form Field Names . . . . . . . . . . . . . . . . . . . . 39
Appendix B. Default Profile . . . . . . . . . . . . . . . . . . 39
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 39
1. Introduction
The Constrained RESTful Application Language (CoRAL) is a language
for the description of typed connections between resources on the Web
("links"), possible operations on such resources ("forms"), as well
as simple resource metadata.
CoRAL is intended for driving automated software agents that navigate
a Web application based on a standardized vocabulary of link and form
relation types. It is designed to be used in conjunction with a Web
transfer protocol such as the Hypertext Transfer Protocol (HTTP)
[RFC7230] or the Constrained Application Protocol (CoAP) [RFC7252].
This document defines the CoRAL data and interaction model, as well
as two specialized CoRAL serialization formats:
The CoRAL data and interaction model is a superset of the Web Linking
model of RFC 8288 [RFC8288]. The CoRAL data model consists of two
elements: _links_ that describe the relationships between pairs of
resources and the type of those relationships, and _forms_ that
describe possible operations on resources and the type of those
operations. Additionally, the data model can describe simple
resource metadata in a way similar to the Resource Description
Framework (RDF) [W3C.REC-rdf11-concepts-20140225]. In contrast to
RDF, the focus of CoRAL is on the interaction with resources, not
just the relationships between them. The CoRAL interaction model
derives from HTML 5 [W3C.REC-html52-20171214] and specifies how an
automated software agent can navigate between resources by following
links and perform operations on resources by submitting forms.
The primary CoRAL serialization format is a compact, binary encoding
of links and forms in Concise Binary Object Representation (CBOR)
[RFC7049]. It is intended for environments with constraints on
power, memory, and processing resources [RFC7228] and shares many
similarities with the message format of the Constrained Application
Hartke Expires April 25, 2019 [Page 3]
Internet-Draft Constrained RESTful Application Language October 2018
Protocol (CoAP) [RFC7252]. For example, it uses numeric identifiers
instead of verbose strings for link and form relation types, and pre-
parses URIs into (what CoAP considers to be) their components, which
greatly simplifies URI processing. As a result, link serializations
are often much more compact than equivalent serializations in CoRE
Link Format [RFC6690] [I-D.ietf-core-links-json].
The secondary CoRAL serialization format is a lightweight, textual
encoding of links and forms that is intended to be easy to read and
write for humans. The format is loosely inspired by the syntax of
Turtle [W3C.REC-turtle-20140225] and is used throughout the document
for examples.
1.1. Requirements Notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
2. Examples
2.1. Web Linking
At its core, CoRAL is just yet another serialization format for Web
links. For example, if an HTTP client sends the following request:
GET /TheBook/chapter3 HTTP/1.1
Host: example.com
and receives the following response:
HTTP/1.1 200 OK
Content-Type: text/coral
#using
next <./chapter4>
icon
license
then the representation contains the following three links:
o one link of type "http://www.iana.org/assignments/relation/next"
from to
,
Hartke Expires April 25, 2019 [Page 4]
Internet-Draft Constrained RESTful Application Language October 2018
o one link of type "http://www.iana.org/assignments/relation/icon"
from to , and
o one link of type "http://www.iana.org/assignments/relation/
license" from to
.
This representation is equivalent to the following Link header field
[RFC8288]:
Link: <./chapter4>; rel="next",
; rel="icon",
; rel="license"
and the following HTML 5 [W3C.REC-html52-20171214] link elements:
2.2. Links, Forms, and Metadata
In its entirety, CoRAL is an expressive language for describing Web
links between resources, possible operations on these resources, and
simple resource metadata. For example, if an HTTP client sends the
following request:
GET /tasks HTTP/1.1
Host: example.com
and receives the following response:
Hartke Expires April 25, 2019 [Page 5]
Internet-Draft Constrained RESTful Application Language October 2018
HTTP/1.1 200 OK
Content-Type: text/coral
#using
#using coral =
task {
description "Pick up the kids"
}
task {
description "Return the books to the library"
coral:delete -> DELETE
}
coral:create -> POST [coral:accept "example/task"]
then the representation contains the following six elements:
o one link of type "http://example.org/vocabulary#task" from
to ,
o one link of type "http://example.org/vocabulary#description" from
to "Pick up the kids",
o one link of type "http://example.org/vocabulary#task" from
to ,
o one link of type "http://example.org/vocabulary#description" from
to "Return the books to the library",
o one form of type "urn:TBD#delete" that can be used to delete
by making a DELETE request to
, and
o one form of type "urn:TBD#create" that can be used to create a new
item in by making a POST request to
with an "example/task" payload.
3. Data and Interaction Model
The Constrained RESTful Application Language (CoRAL) is designed for
building Web-based applications [W3C.REC-webarch-20041215] in which
automated software agents navigate between resources by following
links and perform operations on resources by submitting forms.
Hartke Expires April 25, 2019 [Page 6]
Internet-Draft Constrained RESTful Application Language October 2018
3.1. Browsing Context
Borrowing from HTML 5 [W3C.REC-html52-20171214], each such agent
maintains a _browsing context_ in which the representations of Web
resources are processed. (In HTML 5, the browsing context typically
corresponds to a tab or window in a Web browser.)
A browsing context has a _session history_ that lists the resource
representations that the agent has processed, is processing, or will
process. At any time, one representation in each browsing context is
designated the _active_ representation.
A session history consists of a flat list of session history entries.
Each _session history entry_ consists of a resource representation
and the Internationalized Resource Identifier (IRI) [RFC3987] that
was used to retrieve the representation. An entry may additionally
have other information associated with it. New entries are added to
the session history as the agent navigates from resource to resource.
3.2. Documents
A resource representation in one of the CoRAL serialization formats
is called a CoRAL _document_. The IRI that was used to retrieve such
a document is called the document's _retrieval context_.
A CoRAL document consists of a list of zero or more links, forms, and
embedded resource representations, collectively called _elements_.
CoRAL serialization formats may define additional types of elements
for efficiency or convenience, such as base IRIs for relative IRI
references.
3.3. Links
A _link_ describes a relationship between two resources on the Web
[RFC8288]. As defined in RFC 8288, it consists of a _link context_,
a _link relation type_, and a _link target_. In CoRAL, a link can
additionally have a nested list of zero or more elements, which take
the place of link target attributes.
A link can be viewed as a statement of the form "{link context} has a
{link relation type} resource at {link target}" where the link target
may be further described by nested elements.
The link relation type identifies the semantics of a link. In HTML 5
and the RFC 8288 Link header field, link relation types are typically
denoted by an IANA-registered name, such as "stylesheet" or "icon".
In CoRAL, in contrast, link relation types are denoted by an IRI or
an unsigned integer. IRIs on the one hand allow for the creation of
Hartke Expires April 25, 2019 [Page 7]
Internet-Draft Constrained RESTful Application Language October 2018
new, unique relation types in a decentralized fashion, but can incur
a high overhead in terms of message size. Small, unsigned integers
on the other hand minimize the overhead of link relation types in
constrained environments, but require the assignment of values by a
registry to avoid collisions.
The link context and the link target are both resources on the Web.
Resources are denoted in CoRAL either by an IRI reference [RFC3987]
or (similarly to RDF) a literal. If the IRI scheme indicates a Web
transfer protocol such as HTTP or CoAP, then an agent can dereference
the IRI and navigate the browsing context to the referenced resource;
this is called _following the link_. A literal directly identifies a
value, which in CoRAL can be a Boolean value, an integer, a floating-
point number, a byte string, or a text string.
A link can occur as a top-level element in a document or as a nested
element within a link. When a link occurs as a top-level element,
the link context is implicitly the document's retrieval context.
When a link occurs nested within a link, the link context of the
inner link is the link target of the outer link.
There are no restrictions on the cardinality of links; there can be
multiple links to and from a particular target, and multiple links of
the same or different types between a given link context and target.
However, the CoRAL data model constrains the description of a
resource graph to a tree: Links between linked resources can only be
described by further nesting links.
3.4. Forms
A _form_ provides instructions to an agent for performing an
operation on a Web resource. It consists of a _form context_, a
_form relation type_, a _request method_, and a _submission IRI_.
Additionally, a form may be accompanied by _form data_.
A form can be viewed as an instruction of the form "To perform a
{form relation type} operation on {form context}, make a {request
method} request to {submission IRI}" where the payload of the request
may be further described by form data.
The form relation type identifies the semantics of the operation.
Like link relation types, form relation types are denoted by an IRI
or an unsigned integer.
The form context is the resource on which an operation is ultimately
performed. To perform the operation, an agent needs to construct a
request with the specified request method and submission IRI. The
submission IRI typically refers to the form context, but MAY refer to
Hartke Expires April 25, 2019 [Page 8]
Internet-Draft Constrained RESTful Application Language October 2018
another resource. Constructing and sending the request is called
_submitting the form_.
If a form is accompanied by form data (Section 3.5), then the agent
MUST also construct a payload that matches the specifications of the
form data and include that in the request.
A form can occur as a top-level element in a document or as a nested
element within a link. When a form occurs as a top-level element,
the form context is implicitly the document's retrieval context.
When a form occurs nested within a link, the form context is the link
target of the enclosing link.
3.5. Form Data
Form data provides instructions for agents to construct a request
payload. It consists of a list of zero or more _form fields_. Each
form field consists of a _form field name_ and a _form field value_.
Form fields can either directly identify data items that need to be
included in the request payload or reference another resource (such
as a schema) that describes the data items. Form fields may also
provide other information, such as acceptable representation formats.
The form field name identifies the semantics of the form field. Like
link and form relation types, form field names are denoted by an IRI
or an unsigned integer.
The form field value can be an IRI, a Boolean value, an integer, a
floating-point number, a byte string, or a text string.
3.6. Embedded Representations
When a document contains links to many resources and an agent needs a
representation of each link target, it may be inefficient to retrieve
each of these representations individually. To alleviate this,
documents can directly embed representations of resources.
An _embedded representation_ consists of a sequence of bytes, plus
_representation metadata_ to describe those bytes.
An embedded representation may be a full, partial, or inconsistent
version of the representation served from the IRI of the represented
resource.
An embedded representation can occur as a top-level element in a
document or as a nested element within a link. When it occurs as a
top-level element, it provides an alternate representation of the
Hartke Expires April 25, 2019 [Page 9]
Internet-Draft Constrained RESTful Application Language October 2018
document's retrieval context. When it occurs nested within a link,
it provides a representation of link target of the enclosing link.
3.7. Navigation
An agent begins interacting with an application by performing a GET
request on an _entry point IRI_. The entry point IRI is the only IRI
an agent is expected to know before interacting with an application.
From there, the agent is expected to make all requests by following
links and submitting forms provided by the server in responses. The
entry point IRI can be obtained by manual configuration or through
some discovery process.
If dereferencing the entry point IRI yields a CoRAL document or any
other representation that implements the CoRAL data and interaction
model, then the agent proceeds as follows:
1. The first step for the agent is to decide what to do next, i.e.,
which type of link to follow or form to submit, based on the link
relation types and form relation types it understands.
2. The agent finds the link(s) or form(s) with the respective
relation type in the active representation. This may yield one
or more candidates, from which the agent must select the most
appropriate one in the next step. The set of candidates may be
empty, for example, when a transition is not supported or not
allowed.
3. The agent selects one of the candidates based on the metadata
associated with the link(s) or form(s). Metadata typically
includes the media type of the target resource representation,
the IRI scheme, the request method, and other information that is
provided as nested elements in a link and form data in a form.
If the selected candidate contains an embedded representation,
then the agent MAY skip the following steps and immediately
proceed with step 8.
4. The agent resolves the IRI reference in the link or form
(Section 5 of RFC 3986 [RFC3986]) to obtain the _request IRI_.
Fragment identifiers are not part of the request IRI and MUST be
separated from the rest of the IRI prior to a dereference. The
request IRI may need to be converted to a URI (Section 3.1 of RFC
3987 [RFC3987]) for protocols that do not support IRIs.
5. The agent constructs a new request with the request IRI. If the
agent follows a link, the request method MUST be GET. If the
agent submits a form, the request method MUST be the one
Hartke Expires April 25, 2019 [Page 10]
Internet-Draft Constrained RESTful Application Language October 2018
specified in the form. The agent SHOULD set HTTP header fields
and CoAP request options according to provided metadata (e.g.,
set the HTTP Accept header field or the CoAP Accept option when
the media type of the target resource is provided). In case of a
form with form data, the agent MUST also include a request
payload that matches the specifications of the form data.
6. The agent sends the request and receives the response.
7. If a fragment identifier was separated from the request IRI, the
agent dereferences the fragment identifier within the received
representation.
8. The agent _updates the session history_: It removes all the
entries in the browsing context's session history after the
current entry. Then it appends a new entry at the end of the
history representing the new resource and makes that entry the
active representation.
9. Finally, the agent processes the representation. In case of a
CoRAL document or any other representation that implements the
CoRAL data and interaction model, this means the agent decides
again what to do next -- and the cycle repeats.
3.8. History Traversal
An agent can navigate a browsing context also by traversing the
browsing context's session history. An agent can _traverse the
session history_ by updating the active representation to the that
entry.
4. Binary Format
This section defines the encoding of documents in the CoRAL binary
format.
A document in the binary format is a data item in Concise Binary
Object Representation (CBOR) [RFC7049]. The structure of this data
item is presented in the Concise Data Definition Language (CDDL)
[I-D.ietf-cbor-cddl]. The media type is "application/coral+cbor".
4.1. Data Structure
The data structure of a document in the binary format is made up of
four kinds of elements: links, forms, embedded representations, and
(as an extension to the CoRAL data model) base IRI directives. Base
IRI directives provide a way to encode IRI references with a common
base more efficiently.
Hartke Expires April 25, 2019 [Page 11]
Internet-Draft Constrained RESTful Application Language October 2018
Elements are processed in the order they appear in the document.
Document processors need to maintain an _environment_ while iterating
an array of elements. The environment consists of three variables: a
_current context IRI_, a _current base IRI_, and a _current relation
type_. The current context IRI and current base IRI are initially
both set to the document's retrieval context. The current relation
type is initially set to the unsigned integer zero.
4.1.1. Documents
The body of a document in the binary format is encoded as an array of
zero or more links, forms, embedded representations, and directives.
body = [*(link / form / representation / directive)]
4.1.2. Links
A link is encoded as an array that consists of the unsigned integer
2, followed by the link relation type and the link target, optionally
followed by a link body that contains nested elements.
link = [link: 2, relation, target, ?body]
The link relation type is encoded either as a text string containing
an absolute IRI reference or as an (unsigned or negative) integer
representing the difference to the current relation type. A link is
processed by updating the current relation type to the result of
adding the specified integer (or zero in the case of a text string)
to the current relation type. It is an error if the current relation
type becomes negative.
relation = text / int
The link target is denoted by an IRI reference or represented by a
literal value. The IRI reference MAY be relative or absolute, and
MUST be resolved against the current base IRI. The encoding of IRI
references in the binary format is described in RFC XXXX
[I-D.hartke-t2trg-ciri]. The link target MAY be null, which
indicates that the link target is an unidentified resource.
target = ciri / literal / null
literal = bool / int / float / bytes / text
The array of elements in the link body, if any, MUST be processed in
a fresh environment. The current context IRI and current base IRI in
the new environment are initially both set to the link target of the
Hartke Expires April 25, 2019 [Page 12]
Internet-Draft Constrained RESTful Application Language October 2018
enclosing link. The current relation type in the new environment is
initially set to the current relation type.
4.1.3. Forms
A form is encoded as an array that consists of the unsigned integer
3, followed by the form relation type, the submission method, and a
submission IRI reference, optionally followed by form data.
form = [form: 3, relation, method, ciri, ?form-data]
The form relation type is encoded and processed in the same way as a
link relation type (Section 4.1.2).
The method MUST refer to one of the request methods defined by the
Web transfer protocol identified by the scheme of the submission IRI.
It is encoded either as a text string or an unsigned integer.
method = text / uint
For HTTP [RFC7230], the method MUST be encoded as a text string in
the format defined in Section 4.1 of RFC 7231 [RFC7231]; the set of
possible values is maintained in the IANA HTTP Method Registry. For
CoAP [RFC7252], the method MUST be encoded as an unsigned integer
(e.g., the unsigned integer 2 for the POST method); the set of
possible values is maintained in the IANA CoAP Method Codes Registry.
The submission IRI reference MAY be relative or absolute, and MUST be
resolved against the current base IRI. The encoding of IRI
references in the binary format is described in RFC XXXX
[I-D.hartke-t2trg-ciri].
4.1.3.1. Form Data
Form data is encoded as an array of zero or more name-value pairs.
form-data = [*(form-field-name, form-field-value)]
Form data, if any, MUST be processed in a fresh environment. The
current context IRI and current base IRI in the new environment are
initially both set to the submission IRI of the enclosing form. The
current relation type in the new environment is initially set to the
current relation type.
A form field name is encoded and processed in the same way as a link
relation type (Section 4.1.2).
form-field-name = text / uint
Hartke Expires April 25, 2019 [Page 13]
Internet-Draft Constrained RESTful Application Language October 2018
A form field value can be an IRI reference, a Boolean value, an
integer, a floating-point number, a byte string, a text string, or
null. An IRI reference MAY be relative or absolute, and MUST be
resolved against the current base IRI. The encoding of IRI
references in the binary format is described in RFC XXXX
[I-D.hartke-t2trg-ciri].
form-field-value = ciri / bool / int / float / bytes / text / null
4.1.3.2. Short Forms
Forms in certain shapes can be encoded in a more efficient manner
using short forms. The following short forms are available:
form /= [form.create: 4, ?accept: uint .size 2]
form /= [form.update: 5, ?accept: uint .size 2]
form /= [form.delete: 6]
form /= [form.search: 7, ?accept: uint .size 2]
If the scheme of the submission IRI indicates HTTP, the short forms
expand as follows:
[4] -> [3, "urn:TBD#create", "POST", []]
[4, x] -> [3, "urn:TBD#create", "POST", [],
["urn:TBD#accept", x]]
[5] -> [3, "urn:TBD#update", "PUT", []]
[5, x] -> [3, "urn:TBD#update", "PUT", [],
["urn:TBD#accept", x]]
[6] -> [3, "urn:TBD#delete", "DELETE", []]
[7] -> [3, "urn:TBD#search", "POST", []]
[7, x] -> [3, "urn:TBD#search", "POST", [],
["urn:TBD#accept", x]]
If the scheme of the submission IRI indicates CoAP, the short forms
expand as follows (the only difference being the request methods):
Hartke Expires April 25, 2019 [Page 14]
Internet-Draft Constrained RESTful Application Language October 2018
[4] -> [3, "urn:TBD#create", 2, []]
[4, x] -> [3, "urn:TBD#create", 2, [],
["urn:TBD#accept", x]]
[5] -> [3, "urn:TBD#update", 3, []]
[5, x] -> [3, "urn:TBD#update", 3, [],
["urn:TBD#accept", x]]
[6] -> [3, "urn:TBD#delete", 4, []]
[7] -> [3, "urn:TBD#search", 5, []]
[7, x] -> [3, "urn:TBD#search", 5, [],
["urn:TBD#accept", x]]
The form relation types and form field names used in these expansions
are defined in Appendix A.
4.1.4. Embedded Representations
An embedded representation is encoded as an array that consists of
the unsigned integer 0, followed by the HTTP content type or CoAP
content format of the representation and a byte string containing the
representation data.
representation = [representation: 0, text / uint, bytes]
For HTTP, the content type MUST be specified as a text string in the
format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the set of
possible values is maintained in the IANA Media Types Registry. For
CoAP, the content format MUST be specified as an unsigned integer;
the set of possible values is maintained in the IANA CoAP Content-
Formats Registry.
4.1.5. Directives
Directives provide the ability to manipulate the environment when
processing a list of elements. There is one directive available: the
Base IRI directive.
directive = base-directive
4.1.5.1. Base IRI Directives
A Base IRI directive is encoded as an array that consists of the
negative integer -1, followed by an IRI reference.
base-directive = [base: -1, ciri]
The IRI reference MAY be relative or absolute, and MUST be resolved
against the current context IRI. The encoding of IRI references in
the binary format is described in RFC XXXX [I-D.hartke-t2trg-ciri].
Hartke Expires April 25, 2019 [Page 15]
Internet-Draft Constrained RESTful Application Language October 2018
The directive is processed by resolving the IRI reference against the
current context IRI and assigning the result to the current base IRI.
5. Textual Format
This section defines the syntax of documents in the CoRAL textual
format using two grammars: The lexical grammar defines how Unicode
characters are combined to form line terminators, white space,
comments, and tokens. The syntactic grammar defines how the tokens
are combined to form documents. Both grammars are presented in
Augmented Backus-Naur Form (ABNF) [RFC5234].
A document in the textual format is a Unicode string in a Unicode
encoding form [UNICODE]. The media type for such documents is "text/
coral". The "charset" parameter is not used; charset information is
transported inside the document in the form of an OPTIONAL Byte Order
Mark (BOM). The use of the UTF-8 encoding scheme [RFC3629], without
a BOM, is RECOMMENDED.
5.1. Lexical Structure
The lexical structure of a document in the textual format is made up
of four basic elements: line terminators, white space, comments, and
tokens. Of these, only tokens are significant in the syntactic
grammar. There are four kinds of tokens: identifiers, IRI
references, literals, and punctuators.
When several lexical grammar rules match a sequence of characters in
a document, the longest match takes priority.
5.1.1. Line Terminators
Line terminators divide text into lines. A line terminator is any
Unicode character with Line_Break class BK, CR, LF, or NL. However,
any CR character that immediately precedes a LF character is ignored.
(This affects only the numbering of lines in error messages.)
5.1.2. White Space
White space is a sequence of one or more white space characters. A
white space character is any Unicode character with the White_Space
property.
5.1.3. Comments
Comments are sequences of characters that are ignored when parsing
text into tokens. Single-line comments begin with the characters
"//" and extend to the end of the line. Delimited comments begin
Hartke Expires April 25, 2019 [Page 16]
Internet-Draft Constrained RESTful Application Language October 2018
with the characters "/*" and end with the characters "*/". Delimited
comments can occupy a portion of a line, a single line, or multiple
lines.
Comments do not nest. The character sequences "/*" and "*/" have no
special meaning within a single-line comment; the character sequences
"//" and "/*" have no special meaning within a delimited comment.
5.1.4. Identifiers
An identifier tokens is a user-defined symbolic name. The rules for
identifiers correspond to those recommended by the Unicode Standard
Annex #31 [UNICODE-UAX31] using the following profile:
identifier = start *continue *(medial 1*continue)
start =
continue =
medial = "-" / "." / "~" / %xB7 / %x58A / %xF0B
medial =/ %x2010 / %x2027 / %x30A0 / %x30FB
All identifiers MUST be converted into Unicode Normalization Form C
(NFC), as defined by the Unicode Standard Annex #15 [UNICODE-UAX15].
Comparison of identifiers is based on NFC and is case-sensitive
(unless otherwise noted).
5.1.5. IRI References
An IRI reference is a Unicode string that conforms to the syntax
defined in RFC 3987 [RFC3987]. An IRI reference can be absolute or
relative, and can contain a fragment identifier. IRI references are
enclosed in angle brackets ("<" and ">").
iri = "<" IRI-reference ">"
IRI-reference =
5.1.6. Literals
A literal is a textual representation of a value. There are six
types of literals: Boolean, integer, floating-point, byte string,
text string, and null.
Hartke Expires April 25, 2019 [Page 17]
Internet-Draft Constrained RESTful Application Language October 2018
5.1.6.1. Boolean Literals
The case-insensitive tokens "true" and "false" denote the Boolean
values true and false, respectively.
boolean = "true" / "false"
5.1.6.2. Integer Literals
Integer literals denote integer values of unspecified precision. By
default, integer literals are expressed in decimal, but they can also
be specified in an alternate base using a prefix. Binary literals
begin with "0b", octal literals begin with "0o", and hexadecimal
literals begin with "0x".
Decimal literals contain the digits "0" through "9". Binary literals
contain "0" and "1", octal literals contain "0" through "7", and
hexadecimal literals contain "0" through "9" as well as "A" through
"F" in upper- or lowercase.
Negative integers are expressed by prepending a minus sign ("-").
integer = ["+" / "-"] (decimal / binary / octal / hexadecimal)
decimal = 1*DIGIT
binary = %x30 (%x42 / %x62) 1*BINDIG
octal = %x30 (%x4F / %x6F) 1*OCTDIG
hexadecimal = %x30 (%x58 / %x78) 1*HEXDIG
DIGIT = %x30-39
BINDIG = %x30-31
OCTDIG = %x30-37
HEXDIG = %x30-39 / %x41-46 / %x61-66
5.1.6.3. Floating-point Literals
Floating-point literals denote floating-point numbers of unspecified
precision.
Floating-point literals consist of a sequence of decimal digits
followed by a fraction, an exponent, or both. The fraction consists
of a decimal point (".") followed by a sequence of decimal digits.
Hartke Expires April 25, 2019 [Page 18]
Internet-Draft Constrained RESTful Application Language October 2018
The exponent consists of the letter "e" in upper- or lowercase,
followed by an optional sign and a sequence of decimal digits that
indicate a power of 10 by which the value preceding the "e" is
multiplied.
Negative floating-point values are expressed by prepending a minus
sign ("-").
floating-point = ["+" / "-"] 1*DIGIT [fraction] [exponent]
fraction = "." 1*DIGIT
exponent = (%x45 / %x65) ["+" / "-"] 1*DIGIT
Floating-point literals can additionally denote the special "Not-
a-Number" (NaN) value, positive infinity, and negative infinity. The
NaN value is produced by the case-insensitive token "NaN". The two
infinite values are produced by the case-insensitive tokens
"+Infinity" (or simply "Infinity") and "-Infinity".
floating-point =/ "NaN"
floating-point =/ ["+" / "-"] "Infinity"
5.1.6.4. Byte String Literals
A byte string literal consists of a prefix and zero or more bytes
encoded in Base16, Base32, or Base64 [RFC4648] and enclosed in single
quotes. Byte string literals encoded in Base16 begin with "h" or
"b16", byte string literals encoded in Base32 begin with "b32", and
byte string literals encoded in Base64 begin with "b64".
bytes = base16 / base32 / base64
base16 = (%x68 / %x62.31.36) SQUOTE SQUOTE
base32 = %x62.33.32 SQUOTE SQUOTE
base64 = %x62.36.34 SQUOTE SQUOTE
SQUOTE = %x27
5.1.6.5. Text String Literals
A text string literal consists of zero or more Unicode characters
enclosed in double quotes. It can include simple escape sequences
(such as \t for the tab character) as well as hexadecimal and Unicode
escape sequences.
Hartke Expires April 25, 2019 [Page 19]
Internet-Draft Constrained RESTful Application Language October 2018
text = DQUOTE *(char / %x5C escape) DQUOTE
char =
escape = simple-escape / hexadecimal-escape / unicode-escape
simple-escape = %x30 / %x62 / %x74 / %x6E / %x76
simple-escape =/ %x66 / %x72 / %x22 / %x27 / %x5C
hexadecimal-escape = (%x78 / %x58) 2HEXDIG
unicode-escape = %x75 4HEXDIG / %x55 8HEXDIG
DQUOTE = %x22
An escape sequence denotes a single Unicode code point. For
hexadecimal and Unicode escape sequences, the code point is expressed
by the hexadecimal number following the "\x", "\X", "\u", or "\U"
prefix. Simple escape sequences indicate the code points listed in
Table 1.
+-----------------+------------+----------------------+
| Escape Sequence | Code Point | Character Name |
+-----------------+------------+----------------------+
| \0 | U+0000 | Null |
| \b | U+0008 | Backspace |
| \t | U+0009 | Character Tabulation |
| \n | U+000A | Line Feed |
| \v | U+000B | Line Tabulation |
| \f | U+000C | Form Feed |
| \r | U+000D | Carriage Return |
| \" | U+0022 | Quotation Mark |
| \' | U+0027 | Apostrophe |
| \\ | U+005C | Reverse Solidus |
+-----------------+------------+----------------------+
Table 1: Simple Escape Sequences
5.1.6.6. Null Literal
The case-insensitive tokens "null" and "_" denote the intentional
absence of any value.
null = "null" / "_"
Hartke Expires April 25, 2019 [Page 20]
Internet-Draft Constrained RESTful Application Language October 2018
5.1.7. Punctuators
Punctuator tokens are used for grouping and separating.
punctuator = "#" | ":" | "*" | "[" | "]" | "{" | "}" | "=" | "->"
5.2. Syntactic Structure
The syntactic structure of a document in the textual format is made
up of four kinds of elements: links, forms, embedded representations,
and (as an extension to the CoRAL data model) directives. Directives
provide a way to make documents easier to read and write by defining
base IRIs for relative IRI references and introducing shorthands for
IRIs.
Elements are processed in the order they appear in the document.
Document processors need to maintain an _environment_ while iterating
a list of elements. The environment consists of three variables: a
_current context IRI_, a _current base IRI_, and a _current mapping
from identifiers to IRIs_. The current context IRI and current base
IRI are initially both set to the document's retrieval context. The
current mapping from identifiers to IRIs is initially empty.
5.2.1. Documents
The body of a document in the textual format consists of zero or more
links, forms, and directives.
body = *(link / form / representation / directive)
5.2.2. Links
A link consists of the link relation type, followed by the link
target, optionally followed by a link body enclosed in curly brackets
("{" and "}").
link = relation target ["{" body "}"]
The link relation type is denoted either by an absolute IRI
reference, a simple name, a qualified name, or an integer.
relation = iri / simple-name / qualified-name / integer
A simple name consists of an identifier. It is resolved to an IRI by
looking up the empty string in the current mapping from identifiers
to IRIs and appending the specified identifier to the result. It is
an error if the empty string is not present in the mapping.
Hartke Expires April 25, 2019 [Page 21]
Internet-Draft Constrained RESTful Application Language October 2018
simple-name = identifier
A qualified name consists of two identifiers separated by a colon
(":"). It is resolved to an IRI by looking up the identifier on the
left hand side in the current mapping from identifiers to IRIs and
appending the identifier on the right hand side to the result. It is
an error if the identifier on the left hand side is not present in
the mapping.
qualified-name = identifier ":" identifier
The link target is denoted by an IRI reference or represented by a
value literal. The IRI reference MAY be relative or absolute, and
MUST be resolved against the current base IRI. If the link target is
null, the link target is an unidentified resource.
target = iri / literal / null
literal = boolean / integer / floating-point / bytes / text
The list of elements in the link body, if any, MUST be processed in a
fresh environment. The current context IRI and current base IRI in
this environment are initially both set to the link target of the
enclosing link. The mapping from identifiers to IRIs is initially
set to a copy of the mapping from identifiers to IRIs in the current
environment.
5.2.3. Forms
A form consists of the form relation type, followed by a "->" token,
a method identifier, and a submission IRI reference, optionally
followed by form data enclosed in square brackets ("[" and "]").
form = relation "->" method iri ["[" form-data "]"]
The form relation type is denoted in the same way as a link relation
type (Section 5.2.2).
The method identifier refers to one of the request methods defined by
the Web transfer protocol identified by the scheme of the submission
IRI. Method identifiers are case-insensitive and constrained to
Unicode characters in the Basic Latin block.
method = identifier
For HTTP [RFC7230], the set of possible method identifiers is
maintained in the IANA HTTP Method Registry. For CoAP [RFC7252], the
Hartke Expires April 25, 2019 [Page 22]
Internet-Draft Constrained RESTful Application Language October 2018
set of possible method identifiers is maintained in the IANA CoAP
Method Codes Registry.
The submission IRI reference MAY be relative or absolute, and MUST be
resolved against the current base IRI.
5.2.3.1. Form Data
Form data consists of zero or more name-value pairs.
form-data = *(form-field-name form-field-value)
Form data, if any, MUST be processed in a fresh environment. The
current context IRI and current base IRI in this environment are
initially both set to the submission IRI of the enclosing form. The
mapping from identifiers to IRIs is initially set to a copy of the
mapping from identifiers to IRIs in the current environment.
The form field name is denoted in the same way as a link relation
type (Section 5.2.2).
form-field-name = iri / simple-name / qualified-name / integer
The form field value can be an IRI reference, Boolean literal,
integer literal, floating-point literal, byte string literal, text
string literal, or null. An IRI reference MAY be relative or
absolute, and MUST be resolved against the current base IRI.
form-field-value = iri / boolean / integer
form-field-value =/ floating-point / bytes / text / null
5.2.4. Embedded Representations
An embedded representation consists of a "*" token, followed by the
representation data, optionally followed by representation metadata
enclosed in square brackets ("[" and "]").
representation = "*" bytes ["[" representation-metadata "]"]
Representation metadata consists of zero or more name-value pairs.
representation-metadata = *(metadata-name metadata-value)
This document specifies only one kind of metadata item, labeled with
the name "type": the HTTP content type or CoAP content format of the
representation.
Hartke Expires April 25, 2019 [Page 23]
Internet-Draft Constrained RESTful Application Language October 2018
metadata-name = "type"
metadata-value = text / integer
For HTTP, the content type MUST be specified as a text string in the
format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the set of
possible values is maintained in the IANA Media Types Registry. For
CoAP, the content format MUST be specified as an integer; the set of
possible values is maintained in the IANA CoAP Content-Formats
Registry.
A metadata item with the name "type" MUST NOT occur more than once.
If absent, its value defaults to content type "application/octet-
stream" or content format 42.
5.2.5. Directives
Directives provide the ability to manipulate the environment when
processing a list of elements. All directives start with a number
sign ("#") followed by a directive identifier. Directive identifiers
are case-insensitive and constrained to Unicode characters in the
Basic Latin block.
The following directives are available: Base IRI directives and Using
directives.
directive = base-directive / using-directive
5.2.5.1. Base IRI Directives
A Base IRI directive consists of a number sign ("#"), followed by the
case-insensitive identifier "base", followed by an IRI reference.
base-directive = "#" "base" iri
The IRI reference MAY be relative or absolute, and MUST be resolved
against the current context IRI.
The directive is processed by resolving the IRI reference against the
current context IRI and assigning the result to the current base IRI.
5.2.5.2. Using Directives
A Using directive consists of a number sign ("#"), followed by the
case-insensitive identifier "using", optionally followed by an
identifier and an equals sign ("="), finally followed by an absolute
IRI reference. If the identifier is not specified, it is assumed to
be the empty string.
Hartke Expires April 25, 2019 [Page 24]
Internet-Draft Constrained RESTful Application Language October 2018
using-directive = "#" "using" [identifier "="] iri
The IRI reference MUST be absolute.
The directive is processed by adding the specified identifier and IRI
to the current mapping from identifiers to IRIs. It is an error if
the identifier is already present in the mapping.
6. Usage Considerations
This section discusses some considerations in creating CoRAL-based
applications and managing link and form relation types.
6.1. Specifying CoRAL-based Applications
CoRAL-based applications naturally implement the Web architecture
[W3C.REC-webarch-20041215] and thus are centered around orthogonal
specifications for identification, interaction, and representation:
o Resources are identified by IRIs or represented by value literals.
o Interactions are based on the hypermedia interaction model of the
Web and the methods provided by the Web transfer protocol. The
semantics of possible interactions are identified by link and form
relation types.
o Representations are CoRAL documents encoded in the binary format
defined in Section 4 or the textual format defined in Section 5.
Depending on the application, additional representation formats
may be used.
Specifications for CoRAL-based applications need to list the specific
components used in the application and their identifiers. This
SHOULD include at least the following items:
o IRI schemes that identify the Web transfer protocol(s) used in the
application.
o Internet media types that identify the representation format(s)
used in the application, including the media type(s) of the CoRAL
serialization format(s).
o Link relation types that identify the semantics of links.
o Form relation types that identify the semantics of forms.
Additionally, for each form relation type, the permissible request
method(s).
Hartke Expires April 25, 2019 [Page 25]
Internet-Draft Constrained RESTful Application Language October 2018
o Form field names that identify the semantics of form fields.
Additionally, for each form field name, the permissible form field
value(s) or type(s).
6.1.1. Naming Resources
Resource names -- URIs [RFC3986] and IRIs [RFC3987] -- are a
cornerstone of Web-based applications. They enable the uniform
identification of resources and are used every time a client
interacts with a server or a resource representation needs to refer
to another resource.
URIs and IRIs often include structured application data in the path
and query components, such as paths in a filesystem or keys in a
database. It is a common practice in many HTTP-based applications to
make this part of the application specification, i.e., to prescribe
fixed URI templates that are hard-coded in implementations. There
are, however, a number of problems with this practice [RFC7320].
In CoRAL-based applications, resource names are not part of the
application specification; they are an implementation detail. The
specification of a CoRAL-based application MUST NOT mandate any
particular form of resource name structure. BCP 190 [RFC7320]
describes the problematic practice of fixed URI structures in more
detail and provides some acceptable alternatives.
6.1.2. Implementation Limits
This document places no restrictions on the number of elements in a
CoRAL document or the depth of nested elements. Applications using
CoRAL (in particular those running in constrained environments) MAY
wish to limit these numbers and specify implementation limits that an
application implementation must at least support to be interoperable.
Applications MAY also mandate the following and other restrictions:
o use of only either the binary format or the text format;
o use of only either HTTP or CoAP as supported Web transfer
protocol;
o use of only either IRIs or unsigned integers to denote link
relation types, form relation types, and form field names;
o use of only either short forms or long forms in the binary format;
o use of only either HTTP content types or CoAP content formats;
Hartke Expires April 25, 2019 [Page 26]
Internet-Draft Constrained RESTful Application Language October 2018
o use of IRI references only up to a specific length;
o use of CBOR in a canonical format (Section 3.9 of RFC 7049
[RFC7049]).
6.2. Minting New Relation Types
New link relation types, form relation types, and form field names
can be minted by defining an IRI [RFC3987] that uniquely identifies
the item. Although the IRI can point to a resource that contains a
definition of the semantics of the relation type, clients SHOULD NOT
automatically access that resource to avoid overburdening its server.
The IRI SHOULD be under the control of the person or party defining
it, or be delegated to them.
Link relation types registered in the IANA Link Relations Registry,
such as "collection" [RFC6573] or "icon" [W3C.REC-html52-20171214],
can be used in CoRAL by appending the registered name to the IRI
:
#using iana =
iana:collection
iana:icon
A good source for link relation types for resource metadata are RDF
predicates [W3C.REC-rdf11-concepts-20140225]. An RDF statement says
that some relationship, indicated by a predicate, holds between two
resources. RDF predicates and link relation types can therefore
often be used interchangeably. For example, a CoRAL document could
describe its creator by using the FOAF vocabulary [FOAF]:
#using iana =
#using foaf =
foaf:maker _ {
iana:type
foaf:familyName "Hartke"
foaf:givenName "Klaus"
foaf:mbox
}
6.3. Registering Relation Types
IRIs that identify link relation types, form relation types, and form
field names do not need to be registered. The inclusion of DNS names
in IRIs allows for the decentralized creation of new IRIs without the
risk of collisions.
Hartke Expires April 25, 2019 [Page 27]
Internet-Draft Constrained RESTful Application Language October 2018
However, IRIs can be relatively verbose and impose a high overhead on
representations. This can be a problem in constrained environments
[RFC7228]. Therefore, CoRAL alternatively allows the use of unsigned
integers to identify link relation types, form relation types, and
form field names. These impose a much smaller overhead but instead
need to be assigned by a registry to avoid collisions.
This document does not create a registry for such integers. Instead,
the media types for CoRAL documents in the binary and textual format
are defined to have a "profile" parameter [RFC6906] that determines
the registry in use. The registry is identified by a URI [RFC3986].
For example, a CoRAL document that uses the registry identified by
the URI can use the following media
type:
application/coral+cbor; profile="http://example.com/registry"
The URI serves only as an identifier; it does not necessarily have to
be dereferencable (or even use a dereferencable URI scheme). It is
permissible, though, to use a dereferencable URI and to serve a
representation that provides information about the registry in a
human- or machine-readable way. (The format of such a representation
is outside the scope of this document.)
For simplicity, a CoRAL document can use unsigned integers from only
one registry. The "profile" parameter of the CoRAL media types MUST
contain a single URI, not a white space separated list of URIs as
recommended by RFC 6906 [RFC6906]. If the "profile" parameter is
absent, the default profile specified in Appendix B of this document
is assumed.
A CoRAL registry SHOULD map each unsigned integer to a full IRI that
identifies a link relation type, form relation type, or form field
name. Once an integer has been assigned, the assignment MUST NOT be
changed or removed. A registry MAY provide additional information
about an assignment that MAY change over time.
In CoAP [RFC7252], media types (including specific values for their
parameters) are encoded as an unsigned integer called the _content
format_. For use with CoAP, each CoRAL registry needs to register a
new content format in the IANA CoAP Content-Formats Registry. Each
such registered content format MUST specify a CoRAL media type with a
"profile" parameter that contains the registry URI.
Hartke Expires April 25, 2019 [Page 28]
Internet-Draft Constrained RESTful Application Language October 2018
6.4. Expressing Link Target Attributes
Link target attributes defined for use with CoRE Link Format
[RFC6690] (such as "type", "hreflang", "media", "ct", "rt", "if",
"sz", and "obs") can be expressed in CoRAL by nesting links under the
respective link and specifying the attribute name appended to the IRI
as the link relation type.
If the expressed link target attribute has a value, the target of the
nested link MUST be a text string; otherwise, the target MUST be the
Boolean value "true":
#using iana =
#using attr =
iana:item {
attr:type "application/json-patch+json"
attr:ct "51"
attr:sz "247"
attr:obs true
}
[[NOTE TO RFC EDITOR: Please replace all occurrences of "http://TBD/"
in this document with an IETF-controlled IRI, such as "urn:ietf:..."
or "http://...ietf.org/...".]]
Link target attributes that do not actually describe the link target
but the link itself (such as "rel", "anchor", "rev", "title", and
"title*") are excluded from this provision and MUST NOT occur in a
CoRAL document.
6.5. Embedding CoRAL in CBOR Structures
Data items in the CoRAL binary format (Section 4) MAY be embedded in
other CBOR [RFC7049] data structures. Specifications using CDDL
[I-D.ietf-cbor-cddl] SHOULD reference the following CDDL definitions
for this purpose:
CoRAL-Body = body
CoRAL-Link = link
CoRAL-Form = form
Hartke Expires April 25, 2019 [Page 29]
Internet-Draft Constrained RESTful Application Language October 2018
7. Security Considerations
Parsers of CoRAL documents must operate on input that is assumed to
be untrusted. This means that parsers MUST fail gracefully in the
face of malicious inputs. Additionally, parsers MUST be prepared to
deal with resource exhaustion (e.g., resulting from the allocation of
big data items) or exhaustion of the call stack (stack overflow).
See Section 8 of RFC 7049 [RFC7049] for security considerations
relating to parsing CBOR.
Implementers of the CoRAL textual format need to consider the
security aspects of handling Unicode input. See the Unicode Standard
Annex #36 [UNICODE-UAX36] for security considerations relating to
visual spoofing and misuse of character encodings. See Section 10 of
RFC 3629 [RFC3629] for security considerations relating to UTF-8.
CoRAL makes extensive use of IRIs and URIs. See Section 8 of RFC
3987 [RFC3987] for security considerations relating to IRIs. See
Section 7 of RFC 3986 [RFC3986] for security considerations relating
to URIs.
The security of applications using CoRAL can depend on the proper
preparation and comparison of internationalized strings. For
example, such strings can be used to make authentication and
authorization decisions, and the security of an application could be
compromised if an entity providing a given string is connected to the
wrong account or online resource based on different interpretations
of the string. See RFC 6943 [RFC6943] for security considerations
relating to identifiers in IRIs and other locations.
CoRAL is intended to be used in conjunction with a Web transfer
protocol like HTTP or CoAP. See Section 9 of RFC 7320 [RFC7230],
Section 9 of RFC 7231 [RFC7231], etc., for security considerations
relating to HTTP. See Section 11 of RFC 7252 [RFC7252] for security
considerations relating to CoAP.
CoRAL does not define any specific mechanisms for protecting the
confidentiality and integrity of CoRAL documents. It relies on
application layer or transport layer mechanisms for this, such as
Transport Layer Security (TLS) [RFC8446].
CoRAL documents and the structure of a web of resources revealed from
automatically following links can disclose personal information and
other sensitive information. Implementations need to prevent the
unintentional disclosure of such information. See Section of 9 of
RFC 7231 [RFC7231] for additional considerations.
Hartke Expires April 25, 2019 [Page 30]
Internet-Draft Constrained RESTful Application Language October 2018
Applications using CoRAL ought to consider the attack vectors opened
by automatically following, trusting, or otherwise using links and
forms in CoRAL documents. In particular, a server that is
authoritative for the CoRAL representation of a resource may not
necessarily be authoritative for elements nested inside the top level
links in the document.
8. IANA Considerations
8.1. Media Type "application/coral+cbor"
This document registers the media type "application/coral+cbor"
according to the procedures of BCP 13 [RFC6838].
Type name:
application
Subtype name:
coral+cbor
Required parameters:
N/A
Optional parameters:
profile - See Section 6.3 of [I-D.hartke-t2trg-coral].
Encoding considerations:
binary - See Section 4 of [I-D.hartke-t2trg-coral].
Security considerations:
See Section 7 of [I-D.hartke-t2trg-coral].
Interoperability considerations:
N/A
Published specification:
[I-D.hartke-t2trg-coral]
Applications that use this media type:
See Section 1 of [I-D.hartke-t2trg-coral].
Fragment identifier considerations:
As specified for "application/cbor".
Additional information:
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): N/A
Hartke Expires April 25, 2019 [Page 31]
Internet-Draft Constrained RESTful Application Language October 2018
Macintosh file type code(s): N/A
Person & email address to contact for further information:
See the Author's Address section of [I-D.hartke-t2trg-coral].
Intended usage:
COMMON
Restrictions on usage:
N/A
Author:
See the Author's Address section of [I-D.hartke-t2trg-coral].
Change controller:
IESG
Provisional registration?
No
8.2. Media Type "text/coral"
This document registers the media type "text/coral" according to the
procedures of BCP 13 [RFC6838] and guidelines in RFC 6657 [RFC6657].
Type name:
text
Subtype name:
coral
Required parameters:
N/A
Optional parameters:
profile - See Section 6.3 of [I-D.hartke-t2trg-coral].
Encoding considerations:
binary - See Section 5 of [I-D.hartke-t2trg-coral].
Security considerations:
See Section 7 of [I-D.hartke-t2trg-coral].
Interoperability considerations:
N/A
Published specification:
[I-D.hartke-t2trg-coral]
Hartke Expires April 25, 2019 [Page 32]
Internet-Draft Constrained RESTful Application Language October 2018
Applications that use this media type:
See Section 1 of [I-D.hartke-t2trg-coral].
Fragment identifier considerations:
N/A
Additional information:
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): .coral
Macintosh file type code(s): TEXT
Person & email address to contact for further information:
See the Author's Address section of [I-D.hartke-t2trg-coral].
Intended usage:
COMMON
Restrictions on usage:
N/A
Author:
See the Author's Address section of [I-D.hartke-t2trg-coral].
Change controller:
IESG
Provisional registration?
No
8.3. CoAP Content Formats
This document registers CoAP content formats for the media types
"application/coral+cbor" and "text/coral" according to the procedures
of RFC 7252 [RFC7252].
o Media Type: application/coral+cbor
Content Coding: identity
ID: TBD (maybe 63)
Reference: [I-D.hartke-t2trg-coral]
o Media Type: text/coral
Content Coding: identity
ID: TBD (maybe 10063)
Reference: [I-D.hartke-t2trg-coral]
Hartke Expires April 25, 2019 [Page 33]
Internet-Draft Constrained RESTful Application Language October 2018
9. References
9.1. Normative References
[I-D.hartke-t2trg-ciri]
Hartke, K., "Constrained Internationalized Resource
Identifiers", draft-hartke-t2trg-ciri-00 (work in
progress), October 2018.
[I-D.ietf-cbor-cddl]
Birkholz, H., Vigano, C., and C. Bormann, "Concise data
definition language (CDDL): a notational convention to
express CBOR and JSON data structures", draft-ietf-cbor-
cddl-05 (work in progress), August 2018.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, .
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
.
[RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987,
January 2005, .
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
.
[RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding
"charset" Parameter Handling in Textual Media Types",
RFC 6657, DOI 10.17487/RFC6657, July 2012,
.
Hartke Expires April 25, 2019 [Page 34]
Internet-Draft Constrained RESTful Application Language October 2018
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013,
.
[RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for
Security Purposes", RFC 6943, DOI 10.17487/RFC6943, May
2013, .
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, .
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, .
[RFC8288] Nottingham, M., "Web Linking", RFC 8288,
DOI 10.17487/RFC8288, October 2017,
.
[UNICODE] The Unicode Consortium, "The Unicode Standard",
.
Note that this reference is to the latest version of
Unicode, rather than to a specific release. It is not
expected that future changes in the Unicode specification
will have any impact on this document.
[UNICODE-UAX15]
The Unicode Consortium, "Unicode Standard Annex #15:
Unicode Normalization Forms",
.
[UNICODE-UAX31]
The Unicode Consortium, "Unicode Standard Annex #31:
Unicode Identifier and Pattern Syntax",
.
[UNICODE-UAX36]
The Unicode Consortium, "Unicode Standard Annex #36:
Unicode Security Considerations",
.
Hartke Expires April 25, 2019 [Page 35]
Internet-Draft Constrained RESTful Application Language October 2018
9.2. Informative References
[FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification
0.99", January 2014,
.
[I-D.ietf-core-links-json]
Li, K., Rahman, A., and C. Bormann, "Representing
Constrained RESTful Environments (CoRE) Link Format in
JSON and CBOR", draft-ietf-core-links-json-10 (work in
progress), February 2018.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, DOI 10.17487/RFC5789, March 2010,
.
[RFC6573] Amundsen, M., "The Item and Collection Link Relations",
RFC 6573, DOI 10.17487/RFC6573, April 2012,
.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
.
[RFC6903] Snell, J., "Additional Link Relation Types", RFC 6903,
DOI 10.17487/RFC6903, March 2013,
.
[RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906,
DOI 10.17487/RFC6906, March 2013,
.
[RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for
Constrained-Node Networks", RFC 7228,
DOI 10.17487/RFC7228, May 2014,
.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014,
.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014,
.
Hartke Expires April 25, 2019 [Page 36]
Internet-Draft Constrained RESTful Application Language October 2018
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014,
.
[RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190,
RFC 7320, DOI 10.17487/RFC7320, July 2014,
.
[RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and
FETCH Methods for the Constrained Application Protocol
(CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017,
.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
.
[W3C.REC-html52-20171214]
Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and
S. Moon, "HTML 5.2", World Wide Web Consortium
Recommendation REC-html52-20171214, December 2017,
.
[W3C.REC-rdf11-concepts-20140225]
Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1
Concepts and Abstract Syntax", World Wide Web Consortium
Recommendation REC-rdf11-concepts-20140225, February 2014,
.
[W3C.REC-turtle-20140225]
Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle",
World Wide Web Consortium Recommendation REC-turtle-
20140225, February 2014,
.
[W3C.REC-webarch-20041215]
Jacobs, I. and N. Walsh, "Architecture of the World Wide
Web, Volume One", World Wide Web Consortium
Recommendation REC-webarch-20041215, December 2004,
.
Appendix A. Core Vocabulary
This section defines the core vocabulary for CoRAL. It is
RECOMMENDED that all CoRAL registries assign an unsigned integer to
each of these link relation types, form relation types, and form
field names.
Hartke Expires April 25, 2019 [Page 37]
Internet-Draft Constrained RESTful Application Language October 2018
[[NOTE TO RFC EDITOR: Please replace all occurrences of "urn:TBD" in
this document with an IETF-controlled IRI, such as "urn:ietf:..." or
"http://...ietf.org/...".]]
A.1. Link Relation Types
Indicates that the link's context is an instance of the type
specified as the link's target; see Section 6 of RFC 6903
[RFC6903].
This link relation type serves in CoRAL the same purpose as the
RDF predicate identified by the IRI .
Indicates that the link's context is a collection and that the
link's target is a member of that collection; see Section 2.1 of
RFC 6573 [RFC6573].
Indicates that the link's target is a collection and that the
link's context is a member of that collection; see Section 2.2 of
RFC 6573 [RFC6573].
A.2. Form Relation Types
Indicates that the form's context is a collection and that a new
item can be created in that collection by submitting a suitable
representation. This form relation type is typically used with
the POST method [RFC7231] [RFC7252].
Indicates that the form's context can be updated by submitting a
suitable representation. This form relation type is typically
used with the PUT method [RFC7231] [RFC7252], PATCH method
[RFC5789] [RFC8132], or iPATCH method [RFC8132].
Indicates that the form's context can be deleted. This form
relation type is typically used with the DELETE method [RFC7231]
[RFC7252].
Indicates that the form's context can be searched by submitting a
search query. This form relation type is typically used with the
POST method [RFC7231] [RFC7252] or FETCH method [RFC8132].
Hartke Expires April 25, 2019 [Page 38]
Internet-Draft Constrained RESTful Application Language October 2018
A.3. Form Field Names
Specifies an acceptable HTTP content type or CoAP content format
for the request payload. There MAY be multiple form fields with
this name. If a form does not include a form field with this
name, the server accepts any or no request payload, depending on
the form relation type.
For HTTP, the content type MUST be specified as a text string in
the format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the
set of possible values is maintained in the IANA Media Types
Registry. For CoAP, the content format MUST be specified as an
unsigned integer; the set of possible values is maintained in the
IANA CoAP Content-Formats Registry.
Appendix B. Default Profile
This section defines a default registry that is assumed when a CoRAL
media type without a "profile" parameter is used.
0 =
1 =
2 =
3 =
4 =
5 =
6 =
7 =
Author's Address
Klaus Hartke
Ericsson
Torshamnsgatan 23
Stockholm SE-16483
Sweden
Email: klaus.hartke@ericsson.com
Hartke Expires April 25, 2019 [Page 39]