draft-ietf-core-coral-02.txt   draft-ietf-core-coral-03.txt 
CoRE Working Group K. Hartke CoRE Working Group K. Hartke
Internet-Draft Ericsson Internet-Draft Ericsson
Intended status: Standards Track 8 January 2020 Intended status: Standards Track 9 March 2020
Expires: 11 July 2020 Expires: 10 September 2020
The Constrained RESTful Application Language (CoRAL) The Constrained RESTful Application Language (CoRAL)
draft-ietf-core-coral-02 draft-ietf-core-coral-03
Abstract Abstract
The Constrained RESTful Application Language (CoRAL) defines a data The Constrained RESTful Application Language (CoRAL) defines a data
model and interaction model as well as two specialized serialization model and interaction model as well as two specialized serialization
formats for the description of typed connections between resources on formats for the description of typed connections between resources on
the Web ("links"), possible operations on such resources ("forms"), the Web ("links"), possible operations on such resources ("forms"),
and simple resource metadata. and simple resource metadata.
Note to Readers Note to Readers
skipping to change at line 43 skipping to change at line 43
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on 11 July 2020. This Internet-Draft will expire on 10 September 2020.
Copyright Notice Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
skipping to change at line 84 skipping to change at line 84
3.1. Data Structure 3.1. Data Structure
3.1.1. Documents 3.1.1. Documents
3.1.2. Directives 3.1.2. Directives
3.1.3. IRIs 3.1.3. IRIs
3.1.4. Links 3.1.4. Links
3.1.5. Forms 3.1.5. Forms
3.1.6. Form Fields 3.1.6. Form Fields
3.2. Dictionary Compression 3.2. Dictionary Compression
3.2.1. Dictionary References 3.2.1. Dictionary References
3.2.2. Media Type Parameter 3.2.2. Media Type Parameter
3.3. Export Interface
4. Textual Format 4. Textual Format
4.1. Lexical Structure 4.1. Lexical Structure
4.1.1. Line Terminators 4.1.1. Line Terminators
4.1.2. White Space 4.1.2. White Space
4.1.3. Comments 4.1.3. Comments
4.1.4. Identifiers 4.1.4. Identifiers
4.1.5. Literals 4.1.5. Literals
4.1.6. Punctuators 4.1.6. Punctuators
4.2. Syntactic Structure 4.2. Syntactic Structure
4.2.1. Documents 4.2.1. Documents
skipping to change at line 117 skipping to change at line 118
6. Usage Considerations 6. Usage Considerations
6.1. Specifying CoRAL-based Applications 6.1. Specifying CoRAL-based Applications
6.1.1. Application Interfaces 6.1.1. Application Interfaces
6.1.2. Resource Identifiers 6.1.2. Resource Identifiers
6.1.3. Implementation Limits 6.1.3. Implementation Limits
6.2. Minting Vocabulary 6.2. Minting Vocabulary
6.3. Expressing Registered Link Relation Types 6.3. Expressing Registered Link Relation Types
6.4. Expressing Simple RDF Statements 6.4. Expressing Simple RDF Statements
6.5. Expressing Natural Language Texts 6.5. Expressing Natural Language Texts
6.6. Embedding Representations in CoRAL 6.6. Embedding Representations in CoRAL
6.7. Embedding CoRAL in CBOR Representations
7. Security Considerations 7. Security Considerations
8. IANA Considerations 8. IANA Considerations
8.1. Media Type "application/coral+cbor" 8.1. Media Type "application/coral+cbor"
8.2. Media Type "text/coral" 8.2. Media Type "text/coral"
8.3. CoAP Content Formats 8.3. CoAP Content Formats
8.4. CBOR Tag 8.4. CBOR Tag
9. References 9. References
9.1. Normative References 9.1. Normative References
9.2. Informative References 9.2. Informative References
Appendix A. Core Vocabulary Appendix A. Core Vocabulary
skipping to change at line 156 skipping to change at line 156
types and operation types. It is designed to be used in conjunction types and operation types. It is designed to be used in conjunction
with a Web transfer protocol, such as the Hypertext Transfer Protocol with a Web transfer protocol, such as the Hypertext Transfer Protocol
(HTTP) [RFC7230] or the Constrained Application Protocol (CoAP) (HTTP) [RFC7230] or the Constrained Application Protocol (CoAP)
[RFC7252]. [RFC7252].
This document defines the CoRAL data model and interaction model as This document defines the CoRAL data model and interaction model as
well as two specialized CoRAL serialization formats. well as two specialized CoRAL serialization formats.
1.1. Data and Interaction Model 1.1. Data and Interaction Model
The data model derives from the Web Linking model of RFC 8288 The data model derives from the Web Linking model of [RFC8288] and
[RFC8288] and primarily consists of two elements: "links" that consists primarily of two elements: "links" that describe the
describe the relationship between two resources and the type of that relationship between two resources and the type of that relationship;
relationship; and "forms" that describe a possible operation on a and "forms" that describe a possible operation on a resource and the
resource and the type of that operation. type of that operation.
Additionally, the data model can describe simple resource metadata in The data model can additionally make simple statements about
similarly to statements in the Resource Description Framework (RDF) resources in a way similar to the Resource Description Framework
[W3C.REC-rdf11-concepts-20140225]. In contrast to RDF, the focus of (RDF) [W3C.REC-rdf11-concepts-20140225]. In contrast to RDF,
CoRAL, however, is not on the description of a resource graph, but on however, the focus of CoRAL is not on the description of a graph of
the discovery of possible future application states of a software resources, but on the discovery of possible future application
agent. states.
The interaction model derives from HTML [W3C.REC-html52-20171214] and The interaction model derives from the processing model of HTML
specifies how an automated software agent can change the application [W3C.REC-html52-20171214] and specifies how an automated software
state, i.e., navigate between resources by following links and agent can change the application state by navigating between
perform operations on resources by submitting forms. resources following links and performing operations on resources
submitting forms.
1.2. Serialization Formats 1.2. Serialization Formats
The primary serialization format is a compact, binary encoding of The primary serialization format is a compact, binary encoding of
links and forms in Concise Binary Object Representation (CBOR) links and forms in Concise Binary Object Representation (CBOR)
[I-D.ietf-cbor-7049bis]. The format is intended for environments [RFC7049bis]. This format is intended for environments with
with constraints on power, memory, and processing resources [RFC7228] constraints on power, memory, and processing resources [RFC7228] and
and shares many similarities with the message format of the shares many similarities with the message format of CoAP: In place of
Constrained Application Protocol (CoAP) [RFC7252]. For example, it verbose strings, small numeric identifiers are used to encode link
uses numeric identifiers instead of verbose strings for link relation relation types and operation types. Uniform Resource Identifiers
types and operation types, and pre-parses Uniform Resource (URIs) [RFC3986] are pre-parsed into (what CoAP considers to be)
Identifiers (URIs) [RFC3986] into (what CoAP considers to be) their their components, which considerably simplifies URI processing for
components, which considerably simplifies URI processing for constrained nodes that already have a CoAP implementation. As a
constrained nodes that already implement CoAP. As a result, link result, link serializations in CoRAL are often much more compact and
serializations in CoRAL are often much more compact and easier to easier to process than equivalent serializations in CoRE Link Format
process than equivalent serializations in CoRE Link Format [RFC6690]. [RFC6690].
The secondary serialization format is a lightweight, textual encoding The secondary serialization format is a lightweight, textual encoding
of links and forms that is intended to be easy to read and to write of links and forms that is intended to be easy to read and to write
for humans. The format is loosely inspired by the syntax of Turtle for humans. The format is loosely inspired by the syntax of Turtle
[W3C.REC-turtle-20140225] and is mainly intended for giving examples [W3C.REC-turtle-20140225] and is mainly intended for giving examples
with precise semantics. in documentation and specifications with precise semantics.
1.3. Notational Conventions 1.3. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
Terms defined in this document appear in _cursive_ where they are Terms defined in this document appear in _cursive_ where they are
introduced. introduced (rendered in plain text as the new term surrounded by
underscores).
2. Data and Interaction Model 2. Data and Interaction Model
The Constrained RESTful Application Language (CoRAL) is designed for The Constrained RESTful Application Language (CoRAL) is designed for
building Web-based applications [W3C.REC-webarch-20041215] in which building Web-based applications [W3C.REC-webarch-20041215] in which
automated software agents navigate between resources by following automated software agents navigate between resources by following
links and perform operations on resources by submitting forms. links and perform operations on resources by submitting forms.
2.1. Browsing Context 2.1. Browsing Context
skipping to change at line 228 skipping to change at line 230
resources are processed. (In HTML, the browsing context typically resources are processed. (In HTML, the browsing context typically
corresponds to a tab or window in a Web browser.) corresponds to a tab or window in a Web browser.)
At any time, one representation in a browsing context is designated At any time, one representation in a browsing context is designated
the _active_ representation. the _active_ representation.
2.2. Documents 2.2. Documents
A resource representation in one of the CoRAL serialization formats A resource representation in one of the CoRAL serialization formats
is called a CoRAL _document_. The URI that was used to retrieve such is called a CoRAL _document_. The URI that was used to retrieve such
a document is called the document's _retrieval context_. a document is called the document's _retrieval context_. This URI is
also considered the base URI for relative URI references in the
document.
A CoRAL document consists of a list of zero or more links and forms, A CoRAL document consists of a list of zero or more links and forms,
collectively called _elements_. CoRAL serialization formats may collectively called _elements_. CoRAL serialization formats may
define additional types of elements for efficiency or convenience, define additional types of elements for efficiency or convenience,
such as a base for relative URI references. such as an embedded base URI that takes precedence over the
document's base URI.
2.3. Links 2.3. Links
A _link_ describes a relationship between two resources on the Web A _link_ describes a relationship between two resources on the Web.
[RFC8288]. As in RFC 8288, a link in CoRAL has a _link context_, a As in [RFC8288], a link in CoRAL has a _link context_, a _link
_link relation type_, and a _link target_. However, in CoRAL, links relation type_, and a _link target_. However, a link in CoRAL does
do not have target attributes. Instead, a link may have a list of not have target attributes. Instead, a link may have a list of zero
zero or more nested elements. These enable both the description of or more nested elements. These enable both the description of
resource metadata (which is done in RFC 8288 with target attributes) resource metadata and the chaining of links, which is done in
and the chaining of links (which can be done in RFC 8288 by setting [RFC8288] by setting the anchor of one link to the target of another.
the anchor of one link to the target of another).
A link can be viewed as a statement of the form "{link context} A link can be viewed as a statement of the form "{link context}
has a {link relation type} resource at {link target}" where the has a {link relation type} resource at {link target}" where the
link target may be further described by nested elements. link target may be further described by nested elements.
The link relation type identifies the semantics of a link. While in A link relation type identifies the semantics of a link. In HTML and
HTML and RFC 8288 these are typically denoted by an IANA-registered in [RFC8288], link relation types are typically denoted by an IANA-
name, such as "stylesheet" or "type", link relation types in CoRAL registered name, such as "stylesheet" or "type". In CoRAL, all link
are denoted by an Internationalized Resource Identifier (IRI) relation types are in contrast denoted by an Internationalized
[RFC3987], such as <http://www.iana.org/assignments/relation/ Resource Identifier (IRI) [RFC3987], such as
stylesheet> or <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>. <http://www.iana.org/assignments/relation/stylesheet> or
This allows for the creation of new link relation types without the <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>. This allows for
the decentralized creation of new link relation types without the
risk of collisions when from different organizations or domains of risk of collisions when from different organizations or domains of
knowledge. IRIs can also lead to documentation, schema, and other knowledge. IRIs can also lead to documentation, schema, and other
information about a link relation type. In CoRAL documents, these information about a link relation type. In CoRAL documents, these
IRIs are only used as identity tokens, though, and are compared with IRIs are only used as identity tokens, though, and are compared with
Simple String Comparison as specified in Section 5.3.1 of RFC 3987. Simple String Comparison as specified in Section 5.3.1 of [RFC3987].
The link context and the link target can be both either a URI, a Link contexts and link targets can both be either a URI, a literal
literal value, or an anonymous resource. If the scheme of a URI value, or an anonymous resource. If the link target is a URI and the
indicates a Web transfer protocol such as HTTP or CoAP, an agent can URI scheme indicates a Web transfer protocol like HTTP or CoAP, an
dereference the URI and navigate the browsing context to the link agent can dereference the URI and navigate the browsing context to
target; this is called _following the link_. A literal value can be its target resource; this is called _following the link_. Literal
either a Boolean value, an integer, a floating-point number, a date/ values are distinct and distinguishable from URIs and directly
time instant, a byte string, or a text string. An anonymous resource identify data by means of a literal representation. A literal value
is a resource which is not identified by a URI and is not a literal. can be either a Boolean value, an integer number, a floating-point
number, a date/time instant, a byte string, or a text string. An
anonymous resource is a resource that is neither identified by a URI
nor a literal representation.
A link can occur as a top-level element in a document or as a nested 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, element within a link. When a link occurs as a top-level element,
the link context implicitly is the document's retrieval context. the link context implicitly is the document's retrieval context.
When a link occurs nested within a link, the link context of the When a link occurs nested within a link, the link context of the
inner link is the same resource as the link target of the outer link. nested link is the link target of the enclosing link.
There are no restrictions on the cardinality of links; there can be There are no restrictions on the cardinality of links; there can be
multiple links to and from a particular target, and multiple links of multiple links to and from a particular target, and multiple links of
the same or different types between a given link context and target. the same or different types between a given link context and target.
However, the nested data structure constrains the description of a However, the nesting nature of the data model constrains the
resource graph to a tree: Links between linked resources can only be description of resource relations to a tree: Relations between linked
described by further nesting links. resources can only be described by further nesting links.
2.4. Forms 2.4. Forms
A _form_ provides instructions to an agent for performing an A _form_ provides instructions to an agent for performing an
operation on a Web resource. A form has a _form context_, an operation on a resource on the Web. A form has a _form context_, an
_operation type_, a _request method_, and a _submission target_. _operation type_, a _request method_, and a _submission target_.
Additionally, a form may be accompanied by a list of zero or more Additionally, a form may be accompanied by a list of zero or more
_form fields_. _form fields_.
A form can be viewed as an instruction of the form "To perform an A form can be viewed as an instruction of the form "To perform an
{operation type} operation on {form context}, make a {request {operation type} operation on {form context}, make a {request
method} request to {submission target}" where the request may be method} request to {submission target}" where the request may be
further described by form fields. further described by form fields.
The operation type identifies the semantics of the operation. An operation type identifies the semantics of the operation.
Operation types are denoted (like link relation types) by an IRI. Operation types are denoted (like link relation types) by an IRI.
Both the form context and the submission target are denoted by a URI. Form contexts and submission targets are both denoted by a URI. The
The form context is the resource on which an operation is ultimately form context is the resource on which the operation is ultimately
performed. To perform the operation, an agent needs to construct a performed. To perform the operation, an agent needs to construct a
request with the specified method and the specified submission target request with the specified method as the request method and the
as the request URI. Usually, the submission target is the same specified submission target as the request URI. Usually, the
resource as the form context, but it may be a different resource. submission target is the same resource as the form context, but may
Constructing and sending the request is called _submitting the form_. be a different resource. Constructing and sending the request is
called _submitting the form_.
A form can occur as a top-level element in a document or as a nested 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, element within a link. When a form occurs as a top-level element,
the form context implicitly is the document's retrieval context. the form context implicitly is the document's retrieval context.
When a form occurs nested within a link, the form context is the same When a form occurs nested within a link, the form context is the link
resource as the link target of the enclosing link. target of the enclosing link.
2.5. Form Fields 2.5. Form Fields
Form fields can be used to provide more detailed instructions to Form fields can be used to provide more detailed instructions to
agents for constructing the request when submitting a form. For agents for constructing the request when submitting a form. For
example, form fields can instruct the agent to include a certain example, a form field could instruct an agent to include a certain
payload or certain header fields in the request. Form fields might payload or header field in the request. A payload could, for
describe a payload by identifying acceptable media types, referencing instance, be described by form fields providing acceptable media
a schema, or listing a number of data items that need to be included. types, a reference to schema information, or a number of individual
Form fields can be specific to the Web transfer protocol that is used data items that the agents needs to supply. Form fields can be
for submitting the form. specific to the Web transfer protocol that is used for submitting the
form.
A form field is a pair of a _form field type_ and a _form field A form field is a pair of a _form field type_ and a _form field
value_. Additionally, a form field may have a list of zero or more value_. Additionally, a form field may have a list of zero or more
nested elements that further describe the form field value. nested elements that further describe the form field value.
The form field type identifies the semantics of the form field. Form A form field type identifies the semantics of the form field. Form
field types are denoted (like link relation types and operation field types are denoted (like link relation types and operation
types) by an IRI. types) by an IRI.
The form field value can be either a URI, a Boolean value, an Form field values can be either a URI, a Boolean value, an integer
integer, a floating-point number, a date/time instant, a byte string, number, a floating-point number, a date/time instant, a byte string,
a text string, or null. A null denotes the intentional absence of a text string, or null. A null indicates the intentional absence of
any form field value. any form field value.
2.6. Navigation 2.6. Navigation
An agent begins interacting with an application by performing a GET An agent begins the interaction with an application by performing a
request on an _entry point URI_. The entry point URI is the only URI GET request on an _entry point URI_. The entry point URI is the only
that the agent is expected to know before interacting with the URI that the agent is expected to know beforehand. From then on, the
application. From then on, the agent is expected to make all agent is expected to make all requests by following links and
requests by following links and submitting forms that are provided by submitting forms that are provided in the responses resulting from
servers in responses. The entry point URI can be obtained through the requests. The entry point URI could be obtained through some
some discovery process or manual configuration. discovery process or manual configuration.
If dereferencing the entry point URI yields a CoRAL document (or any If dereferencing the entry point URI yields a CoRAL document (or any
other representation that implements the CoRAL data and interaction other representation that implements the CoRAL data and interaction
model), then the agent makes this document the active representation model), the agent makes this document the active representation in
in the browsing context and proceeds as follows: the browsing context and proceeds as follows:
1. The first step for the agent is to decide what to do next, i.e., 1. The first step for the agent is to decide what to do next, i.e.,
which type of link to follow or type of form to submit, based on which type of link to follow or form to submit, based on the link
the link relation types and operation types it knows. relation types and operation types it understands.
An agent may follow a link without understanding the link
relation type, e.g., for the sake of pre-fetching or building a
search index. However, an agent MUST NOT submit a form without
understanding the operation type.
2. The agent then finds the link(s) or form(s) with the respective 2. The agent then finds the link(s) or form(s) with the respective
type in the active representation. This may yield one or more type in the active representation. This may yield one or more
candidates, from which the agent will have to select the most candidates, from which the agent will have to select the most
appropriate one. The set of candidates can be empty, for appropriate one. The set of candidates can be empty, for
example, when a transition is not supported or not allowed. example, when an application state transition is not supported or
not allowed.
3. The agent selects one of the candidates based on the order of 3. The agent selects one of the candidates based on the metadata
appearance in the document and the resource metadata associated associated them (in the form of form fields and nested elements)
with them in the form of nested elements and form fields. and their order of appearance in the document. Examples for
Examples for resource metadata include the indication of a relevant metadata could include the indication of a media type
content type for the target resource representation, the URI for the target resource representation, the URI scheme of a
scheme of a link target, or the request method of a form. target resource, or the request method of an operation.
4. The agent obtains the _request URI_ from the link target or 4. The agent obtains the _request URI_ from the link target or
submission target. Link targets and submission targets may be submission target. Link targets and submission targets can be
denoted by relative URI references, which need to be resolved to denoted by relative URI references, which need to be resolved
obtain the request URI. Fragment identifiers are not part of the against a base URI to obtain the request URI. Fragment
request URI and MUST be separated from the rest of the URI prior identifiers are not part of the request URI and MUST be separated
to the next step. from the rest of the URI prior to the next step.
5. The agent constructs a new request with the request URI. If the 5. The agent constructs a new request with the request URI. If the
agent is following a link, then the request method MUST be GET. agent is following a link, then the request method MUST be GET.
If the agent is submitting a form, then the request method MUST If the agent is submitting a form, then the request method MUST
be the one indicated by the form. An IRI may need to be be the one supplied by the form. An IRI may need to be converted
converted to a URI (Section 3.1 of RFC 3987) for protocols that to a URI (see Section 3.1 of [RFC3987]) for protocols that do not
do not support IRIs. support IRIs.
The agent should set HTTP header fields and CoAP request options The agent SHOULD set HTTP header fields and CoAP request options
according to the nested elements of a link or form fields of a according to the metadata (e.g., set the HTTP Accept header field
form (e.g., set the HTTP Accept header field or the CoAP Accept or the CoAP Accept option when a media type for the target
option when a media type for the target resource is provided). resource is provided). Depending on the operation type of a
Depending on the operation type of a form, the agent may also form, the agent may also have to include a request payload that
have to include a request payload that matches the specifications matches the specifications of some form fields.
of some form fields.
6. The agent sends the request and receives the response. 6. The agent sends the request and receives the response.
7. If a fragment identifier was separated from the request URI, the 7. If a fragment identifier was separated from the request URI, the
agent selects the fragment indicated by the fragment identifier agent selects the fragment indicated by the fragment identifier
within the received representation. within the received representation according to the semantics of
its media type.
8. The agent _updates the browsing context_ by making the (selected 8. The agent updates the browsing context by making the (selected
fragment of the) received representation the active fragment of the) received representation the active
representation. representation.
9. Finally, the agent processes the representation according to the 9. Finally, the agent processes the representation according to the
semantics of its content type. If the representation is a CoRAL semantics of its media type. If the representation is a CoRAL
document (or any other representation that implements the CoRAL document (or any other representation that implements the CoRAL
data and interaction model), the agent has the choice of what to data and interaction model), the agent again has the choice of
do next again -- and the cycle repeats. what to do next. Go to step 1.
2.7. History Traversal 2.7. History Traversal
Each browsing context has a _session history_ that lists the resource A browsing context has a _session history_, which lists the resource
representations that the agent has processed, is processing, or will representations that the agent has processed, is processing, or will
process. The maximum length of the session history is up for the process.
agent to decide and may be zero.
A session history consists of session history entries. The number of
session history entries may be limited and dependent on the agent.
An agent with severe constraints on memory size might only have
enough memory for the most recent entry.
An entry in the session history consists of a resource representation An entry in the session history consists of a resource representation
and the request URI that was used to retrieve the representation. and the representation's retrieval context. New entries are added to
New entries are added to the session history as the agent navigates the session history as the agent navigates from resource to resource,
from resource to resource. discarding entries that are no longer used.
In addition to following links and submitting forms, an agent can An agent can decide to navigate a browsing context (in addition to
decide tp navigate a browsing context by _traversing the session following links and submitting forms) by _traversing the session
history_. For example, when an agent receives a representation that history_. For example, when an agent receives a response with a
does not contain any further links or forms, it can set the active representation that does not contain any further links or forms, it
representation back to one it has visited earlier. can navigate back to a resource representation it has visited earlier
and make that the active representation.
Traversing the history should take advantage of caches to avoid new Traversing the history SHOULD take advantage of caches to avoid new
requests. An agent MAY reissue a safe request (e.g., a GET request) requests. An agent may reissue a safe request (e.g., a GET) when it
when it does not have a fresh representation in its cache. An agent does not have a fresh representation in its cache. An agent MUST NOT
MUST NOT reissue an unsafe request (e.g., a PUT or a POST request) reissue an unsafe request (e.g., a PUT or POST) unless it actually
unless it intends to perform that operation again. intends to perform that operation again.
3. Binary Format 3. Binary Format
This section defines the encoding of documents in the CoRAL binary This section defines the encoding of documents in the CoRAL binary
format. format.
A document in the binary format is encoded in Concise Binary Object A document in the binary format is encoded in Concise Binary Object
Representation (CBOR) [I-D.ietf-cbor-7049bis]. The encoding MUST Representation (CBOR) [RFC7049bis]. The encoding MUST satisfy the
satisfy the Core Deterministic Encoding Requirements specified in Core Deterministic Encoding Requirements specified in Section 4.2.1
Section XX of RFC XXXX [I-D.ietf-cbor-7049bis]. of [RFC7049bis].
The CBOR structure of a document is presented in the Concise Data The CBOR structure of a document is presented in the Concise Data
Definition Language (CDDL) [RFC8610]. All CDDL rules not defined in Definition Language (CDDL) [RFC8610]. All CDDL rules not defined in
this document are defined in Appendix D of RFC 8610 [RFC8610]. this document are defined in Appendix D of [RFC8610].
The media type of documents in the binary format is "application/ The media type of documents in the binary format is "application/
coral+cbor". coral+cbor".
3.1. Data Structure 3.1. Data Structure
The data structure of a document in the binary format is made up of The data structure of a document in the binary format is made up of
three kinds of elements: links, forms, and (as an extension to the three kinds of elements: links, forms, and (as an extension to the
CoRAL data model) directives. Directives provide a way to encode URI CoRAL data model) directives. Directives provide a way to encode URI
references with a common base more efficiently. references with a common base more efficiently.
skipping to change at line 470 skipping to change at line 491
contains zero or more elements. An element is either a link, a form, contains zero or more elements. An element is either a link, a form,
or a directive. or a directive.
document = [*element] document = [*element]
element = link / form / directive element = link / form / directive
The elements are processed in the order they appear in the document. The elements are processed in the order they appear in the document.
Document processors need to maintain an _environment_ while iterating Document processors need to maintain an _environment_ while iterating
an array of elements. The environment consists of two variables: the an array of elements. The environment consists of two variables: the
_current context_ and the _current base_. Both the current context _current context_ and the _current base_. The current context and
and the current base are initially set to the document's retrieval the current base are both initially set to the document's retrieval
context. context.
3.1.2. Directives 3.1.2. Directives
Directives provide the ability to manipulate the environment while Directives provide the ability to manipulate the environment while
processing elements. processing elements.
There is a single type of directives available: the Base directive. There is a single type of directives available: the Base directive.
directive = base-directive directive = base-directive
It is an error if a document processor encounters any other type of
directive.
3.1.2.1. Base Directives 3.1.2.1. Base Directives
A Base directive is encoded as a CBOR array that contains the A Base directive is encoded as a CBOR array that contains the
unsigned integer 1 and a base URI. unsigned integer 1 and a base URI.
base-directive = [1, baseURI] base-directive = [1, baseURI]
The base URI is denoted by a Constrained Resource Identifier (CoRI) The base URI is denoted by a Constrained Resource Identifier (CRI)
reference [I-D.ietf-core-href]. The CoRI reference MUST be resolved reference [I-D.ietf-core-href]. The CRI reference MUST be resolved
against the current context (not the current base). against the current context (not the current base).
baseURI = CoRI baseURI = CRI-Reference
CoRI = <Defined in Section XX of RFC XXXX> CRI-Reference = <Defined in Section XX of RFC XXXX>
The directive is processed by resolving the CoRI reference against The directive is processed by resolving the CRI reference against the
the current context and assigning the result to the current base. current context and assigning the result to the current base.
3.1.3. IRIs 3.1.3. IRIs
IRIs in links and forms are encoded as CoRI references. IRIs in links and forms are encoded as CRI references.
IRI = CoRI IRI = CRI-Reference
A CoRI reference is processed by resolving it to an IRI as specified A CRI reference is processed by resolving it to an IRI as specified
in Section XX of RFC XXXX [I-D.ietf-core-href] using the current in Section 5.2 of [I-D.ietf-core-href] using the current base.
base.
3.1.4. Links 3.1.4. Links
A link is encoded as a CBOR array that contains the unsigned integer A link is encoded as a CBOR array that contains the unsigned integer
2, the link relation type, the link target, and, optionally, an array 2, the link relation type, the link target, and, optionally, an array
of zero or more nested elements. of zero or more nested elements.
link = [2, relation-type, link-target, ?[*element]] link = [2, relation-type, link-target, ?[*element]]
The link relation type is encoded as a text string that conforms to The link relation type is an IRI.
the syntax of an IRI [RFC3987].
relation-type = text relation-type = IRI
The link target is either an IRI, a literal value, or null. The link target is either an IRI, a literal value, or null.
link-target = IRI / literal / null link-target = IRI / literal / null
literal = bool / int / float / time / bytes / text literal = bool / int / float / time / bytes / text
The nested elements, if any, MUST be processed in a fresh The nested elements, if any, MUST be processed in a fresh
environment. Both the current context and current base in this environment. The current context is set to the link target of the
environment are initially set to the link target of the enclosing enclosing link. The current base is initially set to the link
link. target, if the link target is an IRI; otherwise, it is set to the
current base of the current environment.
3.1.5. Forms 3.1.5. Forms
A form is encoded as a CBOR array that contains the unsigned integer A form is encoded as a CBOR array that contains the unsigned integer
3, the operation type, the submission target, and, optionally, an 3, the operation type, the submission target, and, optionally, an
array of zero or more form fields. array of zero or more form fields.
form = [3, operation-type, submission-target, ?[*form-field]] form = [3, operation-type, submission-target, ?[*form-field]]
The operation type is encoded as a text string that conforms to the The operation type is an IRI.
syntax of an IRI [RFC3987].
operation-type = text operation-type = IRI
The submission target is an IRI. The submission target is an IRI.
submission-target = IRI submission-target = IRI
The request method is either implied by the operation type or encoded The request method is either implied by the operation type or encoded
as a form field. If both are given, the form field takes precedence as a form field. If both are given, the form field takes precedence
over the operation type. Either way, the method MUST be applicable over the operation type. Either way, the method MUST be applicable
to the Web transfer protocol identified by the scheme of the to the Web transfer protocol identified by the scheme of the
submission target. submission target.
The form fields, if any, MUST be processed in a fresh environment. The form fields, if any, MUST be processed in a fresh environment.
Both the current context and the current base in this environment are The current context is set to an unspecified URI that represents the
initially set to the submission target of the enclosing form. enclosing form. The current base is initially set to the submission
target of the enclosing form.
3.1.6. Form Fields 3.1.6. Form Fields
A form field is encoded as a CBOR sequence that consists of a form A form field is encoded as a CBOR sequence that consists of a form
field type, a form field value, and, optionally, an array of zero or field type, a form field value, and, optionally, an array of zero or
more nested elements. more nested elements.
form-field = (form-field-type, form-field-value, ?[*element]) form-field = (form-field-type, form-field-value, ?[*element])
The form field type is encoded as a text string that conforms to the The form field type is an IRI.
syntax of an IRI [RFC3987].
form-field-type = text form-field-type = IRI
The form field value is either an IRI, a literal value, or null. The form field value is either an IRI, a literal value, or null.
form-field-value = IRI / literal / null form-field-value = IRI / literal / null
The nested elements, if any, MUST be processed in a fresh The nested elements, if any, MUST be processed in a fresh
environment. Both the current context and current base in this environment. The current context is set to the form field value of
environment are initially set to the form field value of the the enclosing form field. The current base is initially set to the
enclosing form field. form field value, if the form field value is an IRI; otherwise, it is
set to the current base of the current environment.
3.2. Dictionary Compression 3.2. Dictionary Compression
A document in the binary format can reference values from an external A document in the binary format MAY reference values from an external
dictionary to reduce representation size and processing cost. dictionary. This helps to reduce representation size and processing
Dictionary references can be used in place of link relation types, cost. Dictionary references can be used in place of link relation
link targets, operation types, submission targets, form field types, types, link targets, operation types, submission targets, form field
and form field values. types, and form field values.
3.2.1. Dictionary References 3.2.1. Dictionary References
A dictionary reference is encoded as an unsigned integer. Where a A dictionary reference is encoded as an unsigned integer. Where a
dictionary reference cannot be expressed unambiguously, the unsigned dictionary reference cannot be expressed unambiguously, the unsigned
integer is tagged with CBOR tag TBD6, as follows: integer is tagged with CBOR tag TBD6, as follows:
relation-type /= uint relation-type /= uint
link-target /= #6.TBD6(uint) link-target /= #6.TBD6(uint)
operation-type /= uint operation-type /= uint
submission-target /= #6.TBD6(uint) submission-target /= #6.TBD6(uint)
form-field-type /= uint form-field-type /= uint
form-field-value /= #6.TBD6(uint) form-field-value /= #6.TBD6(uint)
A dictionary reference MUST NOT refer to a dictionary value that is A dictionary reference MUST NOT refer to a dictionary value that
otherwise not allowed. For example, a dictionary reference that is would otherwise not be syntactically allowed in that position. For
used in place of a link relation type is not allowed to refer to a example, a dictionary reference in the position of a link relation
Boolean value. type cannot refer to a Boolean value; it can only refer to an IRI.
3.2.2. Media Type Parameter 3.2.2. Media Type Parameter
The "application/coral+cbor" media type for documents in the binary The "application/coral+cbor" media type for documents in the binary
format is defined to have a "dictionary" parameter that specifies the format is defined to have a "dictionary" parameter that specifies the
dictionary in use. The dictionary is identified by a URI [RFC3986]. dictionary in use. The dictionary is identified by a URI. For
For example, a CoRAL document that uses the dictionary identified by example, a CoRAL document that uses the dictionary identified by the
the URI <http://example.com/dictionary> can use the following content URI <http://example.com/dictionary> would have the following content
type: type:
application/coral+cbor;dictionary="http://example.com/dictionary" application/coral+cbor;dictionary="http://example.com/dictionary"
The URI serves only as an identifier; it does not necessarily have to The URI serves only as an identifier; it does not necessarily have to
be dereferencable (or even use a dereferencable URI scheme). It is be dereferencable (or even use a dereferencable URI scheme). It is
permissible, though, to use a dereferencable URI and to serve a permissible, though, to use a dereferencable URI and to serve a
representation that provides information about the dictionary in a representation that provides information about the dictionary in a
machine- or human-readable way. (The representation format and machine- or human-readable way. (The representation format and
security considerations of such a representation are outside the security considerations of such a representation are outside the
scope of this document.) scope of this document.)
For simplicity, a CoRAL document can reference values only from one For simplicity, a CoRAL document can reference values only from one
dictionary; the value of the "dictionary" parameter MUST be a single dictionary; the value of the "dictionary" parameter MUST be a single
URI. The "dictionary" parameter is OPTIONAL. If it is absent, the URI.
default dictionary specified in Appendix B of this document is
assumed. The "dictionary" parameter is OPTIONAL. If it is absent, the default
dictionary specified in Appendix B of this document is assumed.
Once a dictionary has made an assignment, the assignment MUST NOT be Once a dictionary has made an assignment, the assignment MUST NOT be
changed or removed. A dictionary, however, may contain additional changed or removed. A dictionary, however, may contain additional
information about an assignment, which may change over time. information about an assignment, which may change over time.
In CoAP [RFC7252], media types (including specific values for their In CoAP, media types (including specific values for their parameters,
parameters) are encoded as an unsigned integer called the "content plus an optional content coding) are encoded as an unsigned integer
format" of a representation. For use with CoAP, each new CoRAL called the "content format" of a representation. For use with CoAP,
dictionary therefore needs to have a new content format registered each new CoRAL dictionary therefore needs to have a new content
with IANA in the CoAP Content-Formats Registry. format registered in the CoAP Content Formats Registry
[CORE-PARAMETERS].
3.3. Export Interface
The definition of documents, links, and forms in the CoRAL binary
format can be reused in other CBOR-based protocols. Specifications
using CDDL should reference the following rules for this purpose:
CoRAL-Document = document
CoRAL-Link = link
CoRAL-Form = form
For each embedded document, link, and form, the CBOR-based protocol
needs to specify the document retrieval context, link context, and
form context, respectively.
4. Textual Format 4. Textual Format
This section defines the syntax of documents in the CoRAL textual This section defines the syntax of documents in the CoRAL textual
format using two grammars: The lexical grammar defines how Unicode format using two grammars: The lexical grammar defines how Unicode
characters are combined to form line terminators, white space, characters are combined to form line terminators, white space,
comments, and tokens. The syntactic grammar defines how tokens are comments, and tokens. The syntactic grammar defines how tokens are
combined to form documents. Both grammars are presented in Augmented combined to form documents. Both grammars are presented in Augmented
Backus-Naur Form (ABNF) [RFC5234]. Backus-Naur Form (ABNF) [RFC5234].
A document in the textual format is a Unicode string in a Unicode A document in the textual format is a Unicode string in a Unicode
encoding form [UNICODE]. The media type for such documents is "text/ encoding form [Unicode]. The media type for such documents is "text/
coral". The "charset" parameter of textual media types [RFC6657] is coral". The "charset" parameter of textual media types [RFC6657] is
not used; instead, charset information is transported inside the not used; instead, charset information is transported inside the
document in the form of an OPTIONAL Byte Order Mark (BOM). The use 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. of the UTF-8 encoding scheme [RFC3629] without a BOM is RECOMMENDED.
4.1. Lexical Structure 4.1. Lexical Structure
The lexical structure of a document in the textual format is made up The lexical structure of a document in the textual format is made up
of four basic elements: line terminators, white space, comments, and of four basic elements: line terminators, white space, comments, and
tokens. Of these, only tokens are significant in the syntactic tokens. Of these, only tokens are significant in the syntactic
grammar. There are three kinds of tokens: identifier tokens, literal grammar. There are three kinds of tokens: identifier tokens, literal
tokens, and punctuator tokens. tokens, and punctuator tokens.
token = identifier / IRIref / boolean / integer / float token = identifier / IRIref / boolean / integer / float
/ datetime / bytes / text / null / punctuator
token =/ datetime / bytes / text / null / punctuator
When several lexical grammar rules match a sequence of characters in When several lexical grammar rules match a sequence of characters in
a document, the longest match takes priority. a document, the longest match takes priority.
4.1.1. Line Terminators 4.1.1. Line Terminators
Line terminators divide text into lines. A line terminator is any Line terminators divide text into lines. A line terminator is any
Unicode character with Line_Break class BK, CR, LF, or NL. However, Unicode character with Line_Break class BK, CR, LF, or NL. However,
any CR character that immediately precedes a LF character is ignored. any CR character that immediately precedes a LF character is ignored.
(This affects only the numbering of lines in error messages.) (This affects only the numbering of lines in error messages.)
skipping to change at line 709 skipping to change at line 742
with the characters "/*" and end with the characters "*/". Delimited with the characters "/*" and end with the characters "*/". Delimited
comments can occupy a portion of a line, a single line, or multiple comments can occupy a portion of a line, a single line, or multiple
lines. lines.
Comments do not nest. The character sequences "/*" and "*/" have no Comments do not nest. The character sequences "/*" and "*/" have no
special meaning within a single-line comment; the character sequences special meaning within a single-line comment; the character sequences
"//" and "/*" have no special meaning within a delimited comment. "//" and "/*" have no special meaning within a delimited comment.
4.1.4. Identifiers 4.1.4. Identifiers
An identifier token is a user-defined symbolic name. The rules for An identifier token is a user-defined symbolic name. The syntax for
identifiers correspond to those recommended by the Unicode Standard identifiers corresponds to the Default Identifier Syntax in Unicode
Annex #31 [UAX31] with the following profile: Standard Annex #31 [UAX31] with the following profile:
identifier = START *CONTINUE *(MEDIAL 1*CONTINUE) identifier = START *CONTINUE *(MEDIAL 1*CONTINUE)
START = <Any character with the XID_Start property> START = <Any character with the XID_Start property>
CONTINUE = <Any character with the XID_Continue property> CONTINUE = <Any character with the XID_Continue property>
MEDIAL = <Any character from Table XX>
MEDIAL = "-" / "." / "~" / %x58A / %xF0B +-----------------------------------------+
| Code Point |
+=========================================+
| U+002D HYPHEN-MINUS |
+-----------------------------------------+
| U+002E FULL STOP |
+-----------------------------------------+
| U+007E TILDE |
+-----------------------------------------+
| U+058A ARMENIAN HYPHEN |
+-----------------------------------------+
| U+0F0B TIBETAN MARK INTERSYLLABIC TSHEG |
+-----------------------------------------+
| U+2010 HYPHEN |
+-----------------------------------------+
| U+2027 HYPHENATION POINT |
+-----------------------------------------+
| U+30A0 KATAKANA-HIRAGANA DOUBLE HYPHEN |
+-----------------------------------------+
| U+30FB KATAKANA MIDDLE DOT |
+-----------------------------------------+
MEDIAL =/ %x2010 / %x2027 / %x30A0 / %x30FB Table 1: Medial Characters
All identifiers MUST be converted into Unicode Normalization Form C All identifiers MUST be converted into Unicode Normalization Form C
(NFC), which is defined in Unicode Standard Annex #15 [UAX15]. (NFC) [Unicode]. Comparison of identifiers is based on NFC and case-
Comparison of identifiers is based on NFC and case-sensitive (unless sensitive (unless otherwise noted).
otherwise noted).
4.1.5. Literals 4.1.5. Literals
A literal token is a textual representation of a value. A literal token is a textual representation of a value.
4.1.5.1. IRI Reference Literals 4.1.5.1. IRI Reference Literals
IRI reference tokens denote references to resources on the Web. IRI reference tokens denote references to resources on the Web.
An IRI reference literal consists of a Unicode string that conforms An IRI reference literal consists of a Unicode string that conforms
to the syntax defined in RFC 3987 [RFC3987]. An IRI reference is to the syntax defined in [RFC3987]. An IRI reference is either an
either an IRI or a relative reference. IRI references are enclosed IRI or a relative reference. IRI references are enclosed in angle
in angle brackets ("<" and ">"). brackets ("<" and ">").
IRIref = "<" IRI-reference ">" IRIref = "<" IRI-reference ">"
IRI-reference = <Defined in Section 2.2 of RFC 3987> IRI-reference = <Defined in Section 2.2 of RFC 3987>
4.1.5.2. Boolean Literals 4.1.5.2. Boolean Literals
The case-insensitive tokens "true" and "false" denote the Boolean The case-insensitive tokens "true" and "false" denote the Boolean
values true and false, respectively. values true and false, respectively.
skipping to change at line 802 skipping to change at line 845
of a decimal point (".") followed by a sequence of decimal digits. of a decimal point (".") followed by a sequence of decimal digits.
The exponent consists of the letter "e" in upper- or lowercase, The exponent consists of the letter "e" in upper- or lowercase,
followed by an optional sign and a sequence of decimal digits that 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 indicate a power of 10 by which the value preceding the "e" is
multiplied. multiplied.
Negative floating-point values are expressed by prepending a minus Negative floating-point values are expressed by prepending a minus
sign ("-"). sign ("-").
float = ["+" / "-"] 1*DIGIT [fraction] [exponent] float = ["+" / "-"] 1*DIGIT [fraction] [exponent]
fraction = "." 1*DIGIT fraction = "." 1*DIGIT
exponent = (%x45 / %x65) ["+" / "-"] 1*DIGIT exponent = (%x45 / %x65) ["+" / "-"] 1*DIGIT
A floating-point literal can additionally denote either the special A floating-point literal can additionally denote either the special
"Not-a-Number" (NaN) value, positive infinity, or negative infinity. "Not-a-Number" (NaN) value, positive infinity, or negative infinity.
The NaN value is produced by the case-insensitive token "NaN". The The NaN value is produced by the case-insensitive token "NaN". The
two infinite values are produced by the case-insensitive tokens two infinite values are produced by the case-insensitive tokens
"+Infinity" (or simply "Infinity") and "-Infinity". "+Infinity" (or simply "Infinity") and "-Infinity".
float =/ "NaN" float =/ "NaN" / ["+" / "-"] "Infinity"
float =/ ["+" / "-"] "Infinity"
4.1.5.5. Date/Time Literals 4.1.5.5. Date/Time Literals
Date/time literal tokens denote an instant in time. Date/time literal tokens denote an instant in time.
A date/time literal consists of the prefix "dt" and a sequence of A date/time literal consists of the prefix "dt" and a sequence of
Unicode characters in Internet Date/Time Format [RFC3339], enclosed Unicode characters in Internet Date/Time Format [RFC3339], enclosed
in single quotes. in single quotes.
datetime = %x64.74 SQUOTE date-time SQUOTE datetime = %x64.74 SQUOTE date-time SQUOTE
skipping to change at line 859 skipping to change at line 893
4.1.5.7. Text String Literals 4.1.5.7. Text String Literals
Text string literal tokens denote a Unicode string. Text string literal tokens denote a Unicode string.
A text string literal consists of zero or more Unicode characters A text string literal consists of zero or more Unicode characters
enclosed in double quotes. It can include simple escape sequences enclosed in double quotes. It can include simple escape sequences
(such as \t for the tab character) as well as hexadecimal and Unicode (such as \t for the tab character) as well as hexadecimal and Unicode
escape sequences. escape sequences.
text = DQUOTE *(char / %x5C escape) DQUOTE text = DQUOTE *(char / %x5C escape) DQUOTE
char = <Any character except DQUOTE, %x5C, and line terminators> char = <Any character except DQUOTE, %x5C, and line terminators>
escape = simple-escape / hexadecimal-escape / unicode-escape escape = simple-escape / hexadecimal-escape / unicode-escape
simple-escape = %x30 / %x62 / %x74 / %x6E / %x76 simple-escape = %x30 / %x62 / %x74 / %x6E / %x76
/ %x66 / %x72 / %x22 / %x27 / %x5C
simple-escape =/ %x66 / %x72 / %x22 / %x27 / %x5C
hexadecimal-escape = (%x78 / %x58) 2HEXDIG hexadecimal-escape = (%x78 / %x58) 2HEXDIG
unicode-escape = %x75 4HEXDIG / %x55 8HEXDIG unicode-escape = %x75 4HEXDIG / %x55 8HEXDIG
DQUOTE = %x22 DQUOTE = %x22
An escape sequence denotes a single Unicode code point. For An escape sequence denotes a single Unicode code point. For
hexadecimal and Unicode escape sequences, the code point is expressed hexadecimal and Unicode escape sequences, the code point is expressed
by the hexadecimal number following the "\x", "\X", "\u", or "\U" by the hexadecimal number following the "\x", "\X", "\u", or "\U"
prefix. Simple escape sequences indicate the code points listed in prefix. Simple escape sequences indicate the code points listed in
Table 1. Table 2.
+-----------------+------------+----------------------+ +-----------------+------------------------------+
| Escape Sequence | Code Point | Character Name | | Escape Sequence | Code Point |
+=================+============+======================+ +=================+==============================+
| \0 | U+0000 | Null | | \0 | U+0000 NULL |
+-----------------+------------+----------------------+ +-----------------+------------------------------+
| \b | U+0008 | Backspace | | \b | U+0008 BACKSPACE |
+-----------------+------------+----------------------+ +-----------------+------------------------------+
| \t | U+0009 | Character Tabulation | | \t | U+0009 HORIZONTAL TABULATION |
+-----------------+------------+----------------------+ +-----------------+------------------------------+
| \n | U+000A | Line Feed | | \n | U+000A LINE FEED |
+-----------------+------------+----------------------+ +-----------------+------------------------------+
| \v | U+000B | Line Tabulation | | \v | U+000B VERTICAL TABULATION |
+-----------------+------------+----------------------+ +-----------------+------------------------------+
| \f | U+000C | Form Feed | | \f | U+000C FORM FEED |
+-----------------+------------+----------------------+ +-----------------+------------------------------+
| \r | U+000D | Carriage Return | | \r | U+000D CARRIAGE RETURN |
+-----------------+------------+----------------------+ +-----------------+------------------------------+
| \" | U+0022 | Quotation Mark | | \" | U+0022 QUOTATION MARK |
+-----------------+------------+----------------------+ +-----------------+------------------------------+
| \' | U+0027 | Apostrophe | | \' | U+0027 APOSTROPHE |
+-----------------+------------+----------------------+ +-----------------+------------------------------+
| \\ | U+005C | Reverse Solidus | | \\ | U+005C REVERSE SOLIDUS |
+-----------------+------------+----------------------+ +-----------------+------------------------------+
Table 1: Simple Escape Sequences Table 2: Simple Escape Sequences
4.1.5.8. Null Literal 4.1.5.8. Null Literal
The case-insensitive tokens "null" and "_" denote the intentional The case-insensitive tokens "null" and "_" denote the intentional
absence of any value. absence of any value.
null = "null" / "_" null = "null" / "_"
4.1.6. Punctuators 4.1.6. Punctuators
skipping to change at line 940 skipping to change at line 967
more elements. An element is either a link, a form, or a directive. more elements. An element is either a link, a form, or a directive.
document = *element document = *element
element = link / form / directive element = link / form / directive
The elements are processed in the order they appear in the document. The elements are processed in the order they appear in the document.
Document processors need to maintain an _environment_ while iterating Document processors need to maintain an _environment_ while iterating
a sequence of elements. The environment consists of three variables: a sequence of elements. The environment consists of three variables:
the _current context_, the _current base_, and the _current mapping the _current context_, the _current base_, and the _current mapping
from identifiers to IRIs_. Both the current context and the current from identifiers to IRIs_. The current context and the current base
base are initially set to the document's retrieval context. The are both initially set to the document's retrieval context. The
current mapping from identifiers to IRIs is initially empty. current mapping from identifiers to IRIs is initially empty.
4.2.2. Directives 4.2.2. Directives
Directives provide the ability to manipulate the environment while Directives provide the ability to manipulate the environment while
processing elements. processing elements.
All directives start with a number sign ("#") followed by an All directives start with a number sign ("#") followed by an
identifier. The identifier is case-insensitive and restricted to identifier. The identifier is case-insensitive and restricted to
Unicode characters in the Basic Latin block. Unicode characters in the Basic Latin block.
The following two types of directives are available: the Base The following two types of directives are available: the Base
directive and the Using directive. directive and the Using directive.
directive = base-directive / using-directive directive = base-directive / using-directive
It is an error if a document processor encounters any other type of
directive.
4.2.2.1. Base Directives 4.2.2.1. Base Directives
A Base directive consists of a number sign ("#"), followed by the A Base directive consists of a number sign ("#"), followed by the
case-insensitive token "base", followed by a base IRI. case-insensitive token "base", followed by a base IRI.
base-directive = "#" "base" baseIRI base-directive = "#" "base" baseIRI
The base IRI is denoted by an IRI reference. The IRI reference MUST The base IRI is denoted by an IRI reference. The IRI reference MUST
be resolved against the current context (not the current base). be resolved against the current context (not the current base).
skipping to change at line 990 skipping to change at line 1020
using-directive = "#" "using" [identifier "="] IRIref using-directive = "#" "using" [identifier "="] IRIref
The directive is processed by adding the specified identifier and IRI The directive is processed by adding the specified identifier and IRI
to the current mapping from identifiers to IRIs. It is an error if to the current mapping from identifiers to IRIs. It is an error if
the identifier is already present in the mapping or if the IRI is not the identifier is already present in the mapping or if the IRI is not
an IRI but a relative reference. an IRI but a relative reference.
4.2.3. IRIs 4.2.3. IRIs
IRIs in links and forms can be either denoted by an IRI reference or IRIs in links and forms can be either denoted by an IRI reference or
looked up from a mapping from identifiers to IRIs using names. There looked up in a mapping from identifiers to IRIs. Lookups can be done
are three kinds of names: simple names, qualified names, and in three ways: using a simple name, a qualified name, or a predefined
predefined names. name.
IRI = IRIref / simple-name / qualified-name / predefined-name IRI = IRIref / simple-name / qualified-name / predefined-name
Both IRI references and names are processed by resolving them to an All IRI references and names are processed by resolving them to an
IRI, as described in the following sub-sections. IRI, as described in the following sub-sections.
4.2.3.1. IRI References 4.2.3.1. IRI References
An IRI reference is resolved to an IRI as specified in Section 6.5 of An IRI reference is resolved to an IRI as specified in Section 6.5 of
RFC 3987 [RFC3987] using the current base. [RFC3987] using the current base as the base URI.
4.2.3.2. Simple Names 4.2.3.2. Simple Names
A simple name consists of an identifier. A simple name consists of an identifier.
simple-name = identifier simple-name = identifier
A simple name is resolved to an IRI by looking up the empty string in A simple name is resolved to an IRI by looking up the empty string in
the current mapping from identifiers to IRIs and appending the given the current mapping from identifiers to IRIs and appending the given
identifier to the result. It is an error if the empty string is not identifier to the result. It is an error if the empty string is not
skipping to change at line 1037 skipping to change at line 1067
4.2.3.4. Predefined Names 4.2.3.4. Predefined Names
A predefined name consists of a commercial at sign ("@") followed by A predefined name consists of a commercial at sign ("@") followed by
an identifier. The identifier is case-insensitive and restricted to an identifier. The identifier is case-insensitive and restricted to
Unicode characters in the Basic Latin block. Unicode characters in the Basic Latin block.
predefined-name = "@" identifier predefined-name = "@" identifier
A predefined name is resolved to an IRI by looking up the identifier A predefined name is resolved to an IRI by looking up the identifier
in Table 2. It is an error if the identifier is not present in the in Table 3. It is an error if the identifier is not present in the
table. table.
+------------+--------------------------------------+ +------------+--------------------------------------+
| Identifier | IRI | | Identifier | IRI |
+============+======================================+ +============+======================================+
| direction | <http://coreapps.org/base#direction> | | direction | <http://coreapps.org/base#direction> |
+------------+--------------------------------------+ +------------+--------------------------------------+
| language | <http://coreapps.org/base#language> | | language | <http://coreapps.org/base#language> |
+------------+--------------------------------------+ +------------+--------------------------------------+
Table 2: Predefined Names Table 3: Predefined Names
4.2.4. Links 4.2.4. Links
A link consists of the link relation type, followed by the link A link consists of the link relation type, followed by the link
target, optionally followed by a sequence of zero or more nested target, optionally followed by a sequence of zero or more nested
elements enclosed in curly brackets ("{" and "}"). elements enclosed in curly brackets ("{" and "}").
link = relation-type link-target ["{" *element "}"] link = relation-type link-target ["{" *element "}"]
The link relation type is an IRI. The link relation type is an IRI.
relation-type = IRI relation-type = IRI
The link target is either an IRI, a literal value, or null. The link target is either an IRI, a literal value, or null.
link-target = IRI / literal / null link-target = IRI / literal / null
literal = boolean / integer / float / datetime / bytes / text literal = boolean / integer / float / datetime / bytes / text
The nested elements, if any, MUST be processed in a fresh The nested elements, if any, MUST be processed in a fresh
environment. Both the current context and current base in this environment. The current context is set to the link target of the
environment are initially set to the link target of the enclosing enclosing link. The current base is initially set to the link
link. The mapping from identifiers to IRIs is initially set to a target, if the link target is an IRI; otherwise, it is set to the
copy of the mapping from identifiers to IRIs in the current current base of the current environment. The mapping from
environment. identifiers to IRIs is initially set to a copy of the mapping from
identifiers to IRIs in the current environment.
4.2.5. Forms 4.2.5. Forms
A form consists of the operation type, followed by a "->" token and A form consists of the operation type, followed by a "->" token and
the submission target, optionally followed by a sequence of zero or the submission target, optionally followed by a sequence of zero or
more form fields enclosed in square brackets ("[" and "]"). more form fields enclosed in square brackets ("[" and "]").
form = operation-type "->" submission-target ["[" *form-field "]"] form = operation-type "->" submission-target ["[" *form-field "]"]
The operation type is an IRI. The operation type is an IRI.
skipping to change at line 1098 skipping to change at line 1129
submission-target = IRI submission-target = IRI
The request method is either implied by the operation type or encoded The request method is either implied by the operation type or encoded
as a form field. If both are given, the form field takes precedence as a form field. If both are given, the form field takes precedence
over the operation type. Either way, the method MUST be applicable over the operation type. Either way, the method MUST be applicable
to the Web transfer protocol identified by the scheme of the to the Web transfer protocol identified by the scheme of the
submission target. submission target.
The form fields, if any, MUST be processed in a fresh environment. The form fields, if any, MUST be processed in a fresh environment.
Both the current context and the current base in this environment are The current context is set to an unspecified URI that represents the
initially set to the submission target of the enclosing form. The enclosing form. The current base is initially set to the submission
mapping from identifiers to IRIs is initially set to a copy of the target of the enclosing form. The mapping from identifiers to IRIs
mapping from identifiers to IRIs in the current environment. is initially set to a copy of the mapping from identifiers to IRIs in
the current environment.
4.2.6. Form Fields 4.2.6. Form Fields
A form field consists of a form field type, followed by a form field A form field consists of a form field type, followed by a form field
value, optionally followed by a sequence of zero or more nested value, optionally followed by a sequence of zero or more nested
elements enclosed in curly brackets ("{" and "}"). elements enclosed in curly brackets ("{" and "}").
form-field = form-field-type form-field-value ["{" *element "}"] form-field = form-field-type form-field-value ["{" *element "}"]
The form field type is an IRI. The form field type is an IRI.
form-field-type = IRI form-field-type = IRI
The form field value is either an IRI, a literal value, or null. The form field value is either an IRI, a literal value, or null.
form-field-value = IRI / literal / null form-field-value = IRI / literal / null
The nested elements, if any, MUST be processed in a fresh The nested elements, if any, MUST be processed in a fresh
environment. Both the current context and current base in this environment. The current context is set to the form field value of
environment are initially set to the form field value of the the enclosing form field. The current base is initially set to the
enclosing form field. The mapping from identifiers to IRIs is form field value, if the form field value is an IRI; otherwise, it is
initially set to a copy of the mapping from identifiers to IRIs in set to the current base of the current environment. The mapping from
the current environment. identifiers to IRIs is initially set to a copy of the mapping from
identifiers to IRIs in the current environment.
5. Document Semantics 5. Document Semantics
5.1. Submitting Documents 5.1. Submitting Documents
By default, a CoRAL document is a representation that captures the By default, a CoRAL document is a representation that captures the
current state of a resource. The meaning of a CoRAL document changes current state of a resource. The meaning of a CoRAL document changes
when it is submitted in a request. Depending on the request method, when it is submitted in a request. Depending on the request method,
the CoRAL document can capture the intended state of a resource (PUT) the CoRAL document can capture the intended state of a resource (PUT)
or be subject to application-specific processing (POST). or be subject to application-specific processing (POST).
skipping to change at line 1163 skipping to change at line 1196
The retrieval context and the base URI of a CoRAL document in a PUT The retrieval context and the base URI of a CoRAL document in a PUT
are the request URI of the request. are the request URI of the request.
5.1.2. POST Requests 5.1.2. POST Requests
A POST request with a CoRAL document enclosed in the request payload A POST request with a CoRAL document enclosed in the request payload
requests that the target resource process the CoRAL document requests that the target resource process the CoRAL document
according to the resource's own specific semantics. according to the resource's own specific semantics.
The retrieval context of a CoRAL document in a POST is defined by the The retrieval context of a CoRAL document in a POST is defined by the
target resource's processing semantics; it can be an unspecified URI. target resource's processing semantics; it may be an unspecified URI.
The base URI of the document is the request URI of the request. The base URI of the document is the request URI of the request.
5.2. Returning Documents 5.2. Returning Documents
In a response, the meaning of a CoRAL document changes depending on In a response, the meaning of a CoRAL document changes depending on
the request method and the response status code. For example, a the request method and the response status code. For example, a
CoRAL document in a successful response to a GET represents the CoRAL document in a successful response to a GET represents the
current state of the target resource, whereas a CoRAL document in a current state of the target resource, whereas a CoRAL document in a
successful response to a POST might represent either the processing successful response to a POST might represent either the processing
result or the new resource state. A CoRAL document in an error result or the new resource state. A CoRAL document in an error
skipping to change at line 1271 skipping to change at line 1304
* The link relation types used. * The link relation types used.
* The operation types used. Additionally, for each operation type, * The operation types used. Additionally, for each operation type,
the permissible request methods. the permissible request methods.
* The form field types used. Additionally, for each form field * The form field types used. Additionally, for each form field
type, the permissible form field values. type, the permissible form field values.
6.1.2. Resource Identifiers 6.1.2. Resource Identifiers
URIs [RFC3986] are a cornerstone of Web-based applications. They URIs are a cornerstone of Web-based applications. They enable the
enable the uniform identification of resources and are used every uniform identification of resources and are used every time a client
time a client interacts with a server or a resource representation interacts with a server or a resource representation needs to refer
needs to refer to another resource. to another resource.
URIs often include structured application data in the path and query URIs often include structured application data in the path and query
components, such as paths in a filesystem or keys in a database. It components, such as paths in a filesystem or keys in a database. It
is a common practice in HTTP-based application programming interfaces is a common practice in HTTP-based application programming interfaces
(APIs) to make this part of the application specification, i.e., to (APIs) to make this part of the application specification, i.e., to
prescribe fixed URI templates that are hard-coded in implementations. prescribe fixed URI templates that are hard-coded in implementations.
However, there are a number of problems with this practice However, there are a number of problems with this practice
[I-D.nottingham-rfc7320bis]. [RFC7320bis].
In CoRAL-based applications, resource names are therefore not part of In CoRAL-based applications, resource names are therefore not part of
the application specification -- they are an implementation detail. the application specification -- they are an implementation detail.
The specification of a CoRAL-based application MUST NOT mandate any The specification of a CoRAL-based application MUST NOT mandate any
particular form of resource name structure. particular form of resource name structure.
BCP 190 [I-D.nottingham-rfc7320bis] describes the problematic [RFC7320bis] describes the problematic practice of fixed URI
practice of fixed URI structures in more detail and provides some structures in more detail and provides some acceptable alternatives.
acceptable alternatives.
6.1.3. Implementation Limits 6.1.3. Implementation Limits
This document places no restrictions on the number of elements in a This document places no restrictions on the number of elements in a
CoRAL document or the depth of nested elements. Applications using CoRAL document or the depth of nested elements. Applications using
CoRAL (in particular those running in constrained environments) may CoRAL (in particular those running in constrained environments) may
limit these numbers and give specific implementation limits that an limit these numbers and define specific implementation limits that an
application implementation must at least support to be interoperable. implementation must support at least to be interoperable.
Applications may also mandate the following and other restrictions: Applications may also mandate the following and other restrictions:
* Use of only either the binary format or the text format. * Use of only either the binary format or the text format.
* Use of only either HTTP or CoAP as the supported Web transfer * Use of only either HTTP or CoAP as the supported Web transfer
protocol. protocol.
* Use of only dictionary references in the binary format for certain * Use of only dictionary references in the binary format for certain
vocabulary. vocabulary.
* Use of URI references and CoRI references only up to a specific * Use of URI references and CRI references only up to a specific
length. length.
6.2. Minting Vocabulary 6.2. Minting Vocabulary
New link relation types, operation types, and form field types can be New link relation types, operation types, and form field types can be
minted by defining an IRI [RFC3987] that uniquely identifies the minted by defining an IRI that uniquely identifies the item.
item. Although the IRI can point to a resource that contains a Although the IRI may point to a resource that contains a definition
definition of the semantics, clients SHOULD NOT automatically access of the semantics, clients SHOULD NOT automatically access that
that resource to avoid overburdening its server. The IRI SHOULD be resource to avoid overburdening its server. The IRI SHOULD be under
under the control of the person or party defining it, or be delegated the control of the person or party defining it, or be delegated to
to them. them.
To avoid interoperability problems, it is RECOMMENDED that only IRIs To avoid interoperability problems, it is RECOMMENDED that only IRIs
are minted that are normalized according to Section 5.3 of RFC 3987. are minted that are normalized according to Section 5.3 of [RFC3987].
Non-normalized forms that are best avoided include: Non-normalized forms that are best avoided include:
* Uppercase characters in scheme names and domain names * Uppercase characters in scheme names and domain names
* Percent-encoding of characters where it is not required by the IRI * Percent-encoding of characters where it is not required by the IRI
syntax syntax
* Explicitly stated HTTP default port (e.g., <http://example.com/> * Explicitly stated HTTP default port (e.g., <http://example.com/>
is preferable over <http://example.com:80/>) is preferable over <http://example.com:80/>)
* Completely empty path in HTTP IRIs (e.g., <http://example.com/> is * Completely empty path in HTTP IRIs (e.g., <http://example.com/> is
preferable over <http://example.com>) preferable over <http://example.com>)
* Dot segments ("/./" or "/../") in the path component of an IRI * Dot segments ("/./" or "/../") in the path component of an IRI
* Lowercase hexadecimal letters within percent-encoding triplets * Lowercase hexadecimal letters within percent-encoding triplets
(e.g., "%3F" is preferable over "%3f") (e.g., "%3F" is preferable over "%3f")
* Punycode-encoding of Internationalized Domain Names in IRIs * Punycode-encoding of Internationalized Domain Names in IRIs
* IRIs that are not in Unicode Normalization Form C [UAX15] * IRIs that are not in Unicode Normalization Form C
IRIs that identify vocabulary do not need to be registered. The IRIs that identify vocabulary do not need to be registered. The
inclusion of domain names in IRIs allows for the decentralized inclusion of domain names in IRIs allows for the decentralized
creation of new IRIs without the risk of collisions. creation of new IRIs without the risk of collisions.
However, IRIs can be relatively verbose and impose a high overhead on However, IRIs can be relatively verbose and impose a high overhead on
a representation. This can be a problem in constrained environments a representation. This can be a problem in constrained environments
[RFC7228]. Therefore, CoRAL alternatively allows the use of unsigned [RFC7228]. Therefore, CoRAL alternatively allows the use of unsigned
integers to reference CBOR data items from a dictionary, as specified integers to reference CBOR data items from a dictionary, as specified
in Section 3.2. These impose a much smaller overhead but instead in Section 3.2. These impose a much smaller overhead but instead
need to be assigned by an authority to avoid collisions. need to be assigned by an authority to avoid collisions.
6.3. Expressing Registered Link Relation Types 6.3. Expressing Registered Link Relation Types
Link relation types registered in the IANA Link Relations Registry, Link relation types registered in the Link Relations Registry
such as "collection" [RFC6573] or "icon" [W3C.REC-html52-20171214], [LINK-RELATIONS], such as "collection" [RFC6573] or "icon"
can be used in CoRAL by appending the registered name to the IRI [W3C.REC-html52-20171214], can be used in CoRAL by appending the
<http://www.iana.org/assignments/relation/>: registered name to the IRI <http://www.iana.org/assignments/
relation/>:
#using iana = <http://www.iana.org/assignments/relation/> #using iana = <http://www.iana.org/assignments/relation/>
iana:collection </items> iana:collection </items>
iana:icon </favicon.png> iana:icon </favicon.png>
The convention of appending the relation type name to the prefix The convention of appending the relation type name to the prefix
"http://www.iana.org/assignments/relation/" to form IRIs is adopted <http://www.iana.org/assignments/relation/> to form IRIs is adopted
from Atom [RFC4287]; see also Appendix A.2 of RFC 8288 [RFC8288]. from the Atom Syndication Format [RFC4287]; see also Appendix A.2 of
[RFC8288].
Note that registered relation type names are required to be lowercase Note that registered relation type names are required to be lowercase
ASCII letters (Section 3.3 of RFC 8288). ASCII letters (see Section 3.3 of [RFC8288]).
6.4. Expressing Simple RDF Statements 6.4. Expressing Simple RDF Statements
An RDF statement [W3C.REC-rdf11-concepts-20140225] says that some In RDF [W3C.REC-rdf11-concepts-20140225], a statement says that some
relationship, indicated by a predicate, holds between two resources. relationship, indicated by a predicate, holds between two resources.
Existing RDF vocabularies can therefore be good source for link Existing RDF vocabularies can therefore be a good source for link
relation types that describe resource metadata. For example, a CoRAL relation types that describe resource metadata. For example, a CoRAL
document could use the FOAF vocabulary [FOAF] to describe the person document could use the FOAF vocabulary [FOAF] to describe the person
or software that made it: or software that made it:
#using rdf = <http://www.w3.org/1999/02/22-rdf-syntax-ns#> #using rdf = <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
#using foaf = <http://xmlns.com/foaf/0.1/> #using foaf = <http://xmlns.com/foaf/0.1/>
foaf:maker null { foaf:maker null {
rdf:type <http://xmlns.com/foaf/0.1/Person> rdf:type <http://xmlns.com/foaf/0.1/Person>
foaf:familyName "Hartke" foaf:familyName "Hartke"
foaf:givenName "Klaus" foaf:givenName "Klaus"
foaf:mbox <mailto:klaus.hartke@ericsson.com> foaf:mbox <mailto:klaus.hartke@ericsson.com>
} }
6.5. Expressing Natural Language Texts 6.5. Expressing Natural Language Texts
Text strings that are the target of a link can be associated with a Text strings can be associated with a Language Tag [RFC5646] and a
language tag [RFC5646] and a base text direction (i.e., right-to-left base text direction (right-to-left or left-to-right) by nesting links
or left-to-right) by nesting links of type <http://coreapps.org/ of types <http://coreapps.org/base#language> and
base#language> and <http://coreapps.org/base#direction> under that <http://coreapps.org/base#direction>, respectively:
link, respectively:
#using <http://coreapps.org/base#> #using base = <http://coreapps.org/base#>
#using iana = <http://www.iana.org/assignments/relation/> #using iana = <http://www.iana.org/assignments/relation/>
iana:terms-of-service </tos> { iana:terms-of-service </tos> {
title "Nutzungsbedingungen" { base:title "Nutzungsbedingungen" {
language "de" @language "de"
direction "ltr" @direction "ltr"
} }
title "Terms of use" { base:title "Terms of use" {
language "en-US" @language "en-US"
direction "ltr" @direction "ltr"
} }
} }
The link relation types <http://coreapps.org/base#language> and The link relation types <http://coreapps.org/base#language> and
<http://coreapps.org/base#direction> are defined in Appendix A. <http://coreapps.org/base#direction> are defined in Appendix A.
6.6. Embedding Representations in CoRAL 6.6. Embedding Representations in CoRAL
When a document links to many Web resources and an agent needs a When a document links to many Web resources and an agent needs a
representation of each of them, it can be inefficient to retrieve representation of each of them, it can be inefficient to retrieve
each representations individually. To minimize round-trips, each representations individually. To minimize round-trips,
documents can embed representations of resources. documents can embed representations of resources.
A representation can be embedded in a document by including a link of A representation can be embedded in a document by including a link of
type <http://coreapps.org/base#representation>: type <http://coreapps.org/base#representation>:
#using <http://coreapps.org/base#> #using base = <http://coreapps.org/base#>
#using http = <http://coreapps.org/http#> #using http = <http://coreapps.org/http#>
#using iana = <http://www.iana.org/assignments/relation/> #using iana = <http://www.iana.org/assignments/relation/>
iana:icon </favicon.gif> { iana:icon </favicon.gif> {
representation base:representation
b64'R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAIAOw==' { b64'R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAIAOw==' {
http:type "image/gif" http:type "image/gif"
} }
} }
An embedded representation should have a nested link of type An embedded representation SHOULD have a nested link of type
<http://coreapps.org/http#type> or <http://coreapps.org/coap#type> <http://coreapps.org/http#type> or <http://coreapps.org/coap#type>
that indicates the content type of the representation. that indicates the content type of the representation.
The link relation types <http://coreapps.org/base#representation>, The link relation types <http://coreapps.org/base#representation>,
<http://coreapps.org/http#type>, and <http://coreapps.org/coap#type> <http://coreapps.org/http#type>, and <http://coreapps.org/coap#type>
are defined in Appendix A. are defined in Appendix A.
6.7. Embedding CoRAL in CBOR Representations
Data items in the CoRAL binary format (Section 3) may be embedded in
other CBOR structures [I-D.ietf-cbor-7049bis]. Specifications using
CDDL [RFC8610] can reference the following CDDL definitions for this
purpose:
CoRAL-Document = document
CoRAL-Link = link
CoRAL-Form = form
For each embedded document, link, and form, the specification for the
embedding CBOR structure needs to specify the document retrieval
context, the link context, and the form context, respectively.
7. Security Considerations 7. Security Considerations
CoRAL document processors need to be fully prepared for all types of CoRAL document processors need to be fully prepared for all types of
hostile input that may be designed to corrupt, overrun, or achieve hostile input that may be designed to corrupt, overrun, or achieve
control of the agent processing the document. For example, hostile control of the agent processing the document. For example, hostile
input may be constructed to overrun buffers, allocate very big data input may be constructed to overrun buffers, allocate very big data
structures, or exhaust the stack depth by setting up deeply nested structures, or exhaust the stack depth by setting up deeply nested
elements. Processors need to have appropriate resource management to elements. Processors need to have appropriate resource management to
mitigate these attacks. mitigate these attacks.
CoRAL serialization formats intentionally do not feature the CoRAL serialization formats intentionally do not feature the
equivalent of XML entity references so as to preclude the entire equivalent of XML entity references so as to preclude the entire
class of attacks relating to them, such as exponential XML entity class of attacks relating to them, such as exponential XML entity
expansion ("billion laughs") [CAPEC-197] and malicious XML entity expansion ("billion laughs") [CAPEC-197] and malicious XML entity
linking [CAPEC-201]. linking [CAPEC-201].
Implementers of the CoRAL binary format need to consider the security Implementers of the CoRAL binary format need to consider the security
aspects of decoding CBOR. See Section XX of RFC XXXX aspects of decoding CBOR. See Section 10 of [RFC7049bis] for
[I-D.ietf-cbor-7049bis] for security considerations relating to CBOR. security considerations relating to CBOR. In particular, different
In particular, different number encodings for the same numeric value number encodings for the same numeric value are not equivalent in
are not equivalent in CoRAL (e.g., a floating-point value of 0.0 is CoRAL (e.g., a floating-point value of 0.0 is not the same as the
not the same as the integer 0). integer 0).
Implementers of the CoRAL textual format need to consider the Implementers of the CoRAL textual format need to consider the
security aspects of handling Unicode input. See Unicode Technical security aspects of handling Unicode input. See Unicode Technical
Report #36 [UTR36] for security considerations relating to visual Report #36 [UTR36] for security considerations relating to visual
spoofing and misuse of character encodings. See Section 10 of RFC spoofing and misuse of character encodings. See Section 10 of
3629 [RFC3629] for security considerations relating to UTF-8. See [RFC3629] for security considerations relating to UTF-8. See Unicode
Unicode Technical Standard #39 [UTS39] for security mechanisms that Technical Standard #39 [UTS39] for security mechanisms that can be
can be used to detect possible security problems relating to Unicode. used to detect possible security problems relating to Unicode.
CoRAL makes extensive use of resource identifiers. See Section 7 of CoRAL makes extensive use of resource identifiers. See Section 7 of
RFC 3986 [RFC3986] for security considerations relating to URIs. See [RFC3986] for security considerations relating to URIs. See
Section 8 of RFC 3987 [RFC3987] for security considerations relating Section 8 of [RFC3987] for security considerations relating to IRIs.
to IRIs. See Section XX of RFC XXXX [I-D.ietf-core-href] for See Section 7 of [I-D.ietf-core-href] for security considerations
security considerations relating to CoRIs. relating to CRIs.
The security of applications using CoRAL can depend on the proper The security of applications using CoRAL can depend on the proper
preparation and comparison of internationalized strings. For preparation and comparison of internationalized strings. For
example, such strings can be used to make authentication and example, such strings can be used to make authentication and
authorization decisions, and the security of an application could be authorization decisions, and the security of an application could be
compromised if an entity providing a given string is connected to the compromised if an entity providing a given string is connected to the
wrong account or online resource based on different interpretations wrong account or online resource based on different interpretations
of the string. See RFC 6943 [RFC6943] for security considerations of the string. See [RFC6943] for security considerations relating to
relating to identifiers in IRIs and other strings. identifiers in IRIs and other strings.
CoRAL is intended to be used in conjunction with a Web transfer CoRAL is intended to be used in conjunction with a Web transfer
protocol like HTTP or CoAP. See Section 9 of RFC 7230 [RFC7230], protocol like HTTP or CoAP. See Section 9 of [RFC7230], Section 9 of
Section 9 of RFC 7231 [RFC7231], etc., for security considerations [RFC7231], etc., for security considerations relating to HTTP. See
relating to HTTP. See Section 11 of RFC 7252 [RFC7252] for security Section 11 of [RFC7252] for security considerations relating to CoAP.
considerations relating to CoAP.
CoRAL does not define any specific mechanisms for protecting the CoRAL does not define any specific mechanisms for protecting the
confidentiality and integrity of CoRAL documents. It relies on confidentiality and integrity of CoRAL documents. It relies on
security mechanisms on the application layer or transport layer for security mechanisms on the application layer or transport layer for
this, such as Transport Layer Security (TLS) [RFC8446]. this, such as Transport Layer Security (TLS) [RFC8446].
CoRAL documents and the structure of a web of resources revealed from CoRAL documents and the structure of a web of resources revealed from
automatically following links can disclose personal information and automatically following links can disclose personal information and
other sensitive information. Implementations need to prevent the other sensitive information. Implementations need to prevent the
unintentional disclosure of such information. See Section 9 of RFC unintentional disclosure of such information. See Section 9 of
7231 [RFC7231] for additional considerations. [RFC7231] for additional considerations.
Applications using CoRAL ought to consider the attack vectors opened Applications using CoRAL ought to consider the attack vectors opened
by automatically following, trusting, or otherwise using links and by automatically following, trusting, or otherwise using links and
forms in CoRAL documents. See Section 5 of RFC 8288 [RFC8288] for forms in CoRAL documents. See Section 5 of [RFC8288] for related
related considerations. considerations.
In particular, when a CoRAL document is the representation of a In particular, when a CoRAL document is the representation of a
resource, the server that is authoritative for that resource may not resource, the server that is authoritative for that resource may not
necessarily be authoritative for nested elements in the document. In necessarily be authoritative for nested elements in the document. In
this case, unless an application defines specific rules, any link or this case, unless an application defines specific rules, any link or
form where the link/form context and the document's retrieval context form where the link/form context and the document's retrieval context
do not share the same Web origin [RFC6454] should be discarded do not share the same Web Origin [RFC6454] should be discarded
("same-origin policy"). ("same-origin policy").
8. IANA Considerations 8. IANA Considerations
8.1. Media Type "application/coral+cbor" 8.1. Media Type "application/coral+cbor"
This document registers the media type "application/coral+cbor" This document registers the media type "application/coral+cbor"
according to the procedures of BCP 13 [RFC6838]. according to the procedures of [RFC6838].
Type name: Type name:
application application
Subtype name: Subtype name:
coral+cbor coral+cbor
Required parameters: Required parameters:
N/A N/A
skipping to change at line 1611 skipping to change at line 1626
Change controller: Change controller:
IESG IESG
Provisional registration? Provisional registration?
No No
8.2. Media Type "text/coral" 8.2. Media Type "text/coral"
This document registers the media type "text/coral" according to the This document registers the media type "text/coral" according to the
procedures of BCP 13 [RFC6838] and guidelines of RFC 6657 [RFC6657]. procedures of [RFC6838] and guidelines of [RFC6657].
Type name: Type name:
text text
Subtype name: Subtype name:
coral coral
Required parameters: Required parameters:
N/A N/A
skipping to change at line 1674 skipping to change at line 1689
Change controller: Change controller:
IESG IESG
Provisional registration? Provisional registration?
No No
8.3. CoAP Content Formats 8.3. CoAP Content Formats
This document registers CoAP content formats for the content types This document registers CoAP content formats for the content types
"application/coral+cbor" and "text/coral" according to the procedures "application/coral+cbor" and "text/coral" according to the procedures
of RFC 7252 [RFC7252]. of [RFC7252].
* Content Type: application/coral+cbor * Content Type: application/coral+cbor
Content Coding: identity Content Coding: identity
ID: TBD3 ID: TBD3
Reference: [I-D.ietf-core-coral] Reference: [I-D.ietf-core-coral]
* Content Type: text/coral * Content Type: text/coral
Content Coding: identity Content Coding: identity
ID: TBD4 ID: TBD4
Reference: [I-D.ietf-core-coral] Reference: [I-D.ietf-core-coral]
[[NOTE TO RFC EDITOR: Please replace all occurrences of "TBD3" and [[NOTE TO RFC EDITOR: Please replace all occurrences of TBD3 and TBD4
"TBD4" in this document with the code points assigned by IANA.]] in this document with the code points assigned by IANA.]]
[[NOTE TO IMPLEMENTERS: Experimental implementations can use content [[NOTE TO IMPLEMENTERS: Experimental implementations may use content
format ID 65087 for "application/coral+cbor" and content format ID format ID 65087 for "application/coral+cbor" and content format ID
65343 for "text/coral" until IANA has assigned code points.]] 65343 for "text/coral" until IANA has assigned code points.]]
8.4. CBOR Tag 8.4. CBOR Tag
This document registers a CBOR tag for dictionary references This document registers a CBOR tag for dictionary references
according to the procedures of RFC XXXX [I-D.ietf-cbor-7049bis]. according to the procedures of [RFC7049bis].
* Tag: TBD6 * Tag: TBD6
Data Item: unsigned integer Data Item: unsigned integer
Semantics: Dictionary reference Semantics: Dictionary reference
Reference: [I-D.ietf-core-coral] Reference: [I-D.ietf-core-coral]
[[NOTE TO RFC EDITOR: Please replace all occurrences of "TBD6" in [[NOTE TO RFC EDITOR: Please replace all occurrences of TBD6 in this
this document with the code point assigned by IANA.]] document with the code point assigned by IANA.]]
9. References 9. References
9.1. Normative References 9.1. Normative References
[I-D.ietf-cbor-7049bis]
Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", Work in Progress, Internet-Draft,
draft-ietf-cbor-7049bis-12, 18 December 2019,
<https://tools.ietf.org/html/draft-ietf-cbor-7049bis-12>.
[I-D.ietf-core-href] [I-D.ietf-core-href]
Hartke, K., "Constrained Resource Identifiers", Work in Hartke, K., "Constrained Resource Identifiers", Work in
Progress, Internet-Draft, draft-ietf-core-href-02, 8 Progress, Internet-Draft, draft-ietf-core-href-03, 9 March
January 2020, 2020,
<https://tools.ietf.org/html/draft-ietf-core-href-02>. <https://tools.ietf.org/html/draft-ietf-core-href-03>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>. <https://www.rfc-editor.org/info/rfc3339>.
skipping to change at line 1771 skipping to change at line 1780
[RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding [RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding
"charset" Parameter Handling in Textual Media Types", "charset" Parameter Handling in Textual Media Types",
RFC 6657, DOI 10.17487/RFC6657, July 2012, RFC 6657, DOI 10.17487/RFC6657, July 2012,
<https://www.rfc-editor.org/info/rfc6657>. <https://www.rfc-editor.org/info/rfc6657>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13, Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013, RFC 6838, DOI 10.17487/RFC6838, January 2013,
<https://www.rfc-editor.org/info/rfc6838>. <https://www.rfc-editor.org/info/rfc6838>.
[RFC7049bis]
Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", Work in Progress, Internet-Draft,
draft-ietf-cbor-7049bis-13, 8 March 2020,
<https://tools.ietf.org/html/draft-ietf-cbor-7049bis-13>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
Definition Language (CDDL): A Notational Convention to Definition Language (CDDL): A Notational Convention to
Express Concise Binary Object Representation (CBOR) and Express Concise Binary Object Representation (CBOR) and
JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
June 2019, <https://www.rfc-editor.org/info/rfc8610>. June 2019, <https://www.rfc-editor.org/info/rfc8610>.
[UAX15] The Unicode Consortium, "Unicode Standard Annex #15: [Unicode] The Unicode Consortium, "The Unicode Standard, Version
Unicode Normalization Forms", 12.1.0", ISBN 978-1-936213-25-2, May 2019,
<http://unicode.org/reports/tr15/>. <http://www.unicode.org/versions/Unicode12.1.0/>.
[UAX31] The Unicode Consortium, "Unicode Standard Annex #31:
Unicode Identifier and Pattern Syntax",
<http://unicode.org/reports/tr31/>.
[UNICODE] The Unicode Consortium, "The Unicode Standard",
<http://www.unicode.org/versions/latest/>. 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.
9.2. Informative References 9.2. Informative References
[CAPEC-197] [CAPEC-197]
MITRE, "CAPEC-197: XML Entity Expansion", 30 September MITRE, "CAPEC-197: XML Entity Expansion", 30 September
2019, <https://capec.mitre.org/data/definitions/197.html>. 2019, <https://capec.mitre.org/data/definitions/197.html>.
[CAPEC-201] [CAPEC-201]
MITRE, "CAPEC-201: XML Entity Linking", 30 September 2019, MITRE, "CAPEC-201: XML Entity Linking", 30 September 2019,
<https://capec.mitre.org/data/definitions/201.html>. <https://capec.mitre.org/data/definitions/201.html>.
[CORE-PARAMETERS]
IANA, "Constrained RESTful Environments (CoRE)
Parameters",
<http://www.iana.org/assignments/core-parameters>.
[FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification
0.99", 14 January 2014, 0.99", 14 January 2014,
<http://xmlns.com/foaf/spec/20140114.html>. <http://xmlns.com/foaf/spec/20140114.html>.
[HAL] Kelly, M., "JSON Hypertext Application Language", Work in [HAL] Kelly, M., "JSON Hypertext Application Language", Work in
Progress, Internet-Draft, draft-kelly-json-hal-08, 12 May Progress, Internet-Draft, draft-kelly-json-hal-08, 12 May
2016, 2016,
<https://tools.ietf.org/html/draft-kelly-json-hal-08>. <https://tools.ietf.org/html/draft-kelly-json-hal-08>.
[I-D.nottingham-rfc7320bis] [HTTP-METHODS]
Nottingham, M., "URI Design and Ownership", Work in IANA, "Hypertext Transfer Protocol (HTTP) Method
Progress, Internet-Draft, draft-nottingham-rfc7320bis-03, Registry", <http://www.iana.org/assignments/http-methods>.
5 January 2020, <https://tools.ietf.org/html/draft-
nottingham-rfc7320bis-03>. [LINK-RELATIONS]
IANA, "Link Relations",
<http://www.iana.org/assignments/link-relations>.
[MEDIA-TYPES]
IANA, "Media Types",
<http://www.iana.org/assignments/media-types>.
[RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom
Syndication Format", RFC 4287, DOI 10.17487/RFC4287, Syndication Format", RFC 4287, DOI 10.17487/RFC4287,
December 2005, <https://www.rfc-editor.org/info/rfc4287>. December 2005, <https://www.rfc-editor.org/info/rfc4287>.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, DOI 10.17487/RFC5789, March 2010, RFC 5789, DOI 10.17487/RFC5789, March 2010,
<https://www.rfc-editor.org/info/rfc5789>. <https://www.rfc-editor.org/info/rfc5789>.
[RFC6573] Amundsen, M., "The Item and Collection Link Relations", [RFC6573] Amundsen, M., "The Item and Collection Link Relations",
skipping to change at line 1861 skipping to change at line 1876
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231, Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014, DOI 10.17487/RFC7231, June 2014,
<https://www.rfc-editor.org/info/rfc7231>. <https://www.rfc-editor.org/info/rfc7231>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014, DOI 10.17487/RFC7252, June 2014,
<https://www.rfc-editor.org/info/rfc7252>. <https://www.rfc-editor.org/info/rfc7252>.
[RFC7320bis]
Nottingham, M., "URI Design and Ownership", Work in
Progress, Internet-Draft, draft-nottingham-rfc7320bis-03,
5 January 2020, <https://tools.ietf.org/html/draft-
nottingham-rfc7320bis-03>.
[RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and
FETCH Methods for the Constrained Application Protocol FETCH Methods for the Constrained Application Protocol
(CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017,
<https://www.rfc-editor.org/info/rfc8132>. <https://www.rfc-editor.org/info/rfc8132>.
[RFC8288] Nottingham, M., "Web Linking", RFC 8288, [RFC8288] Nottingham, M., "Web Linking", RFC 8288,
DOI 10.17487/RFC8288, October 2017, DOI 10.17487/RFC8288, October 2017,
<https://www.rfc-editor.org/info/rfc8288>. <https://www.rfc-editor.org/info/rfc8288>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>. <https://www.rfc-editor.org/info/rfc8446>.
[UAX31] The Unicode Consortium, "Unicode Standard Annex #31:
Unicode Identifier and Pattern Syntax", Revision 31,
February 2019,
<http://www.unicode.org/reports/tr31/tr31-31.html>.
[UTR36] The Unicode Consortium, "Unicode Technical Report #36: [UTR36] The Unicode Consortium, "Unicode Technical Report #36:
Unicode Security Considerations", Unicode Security Considerations", Revision 15, September
<http://unicode.org/reports/tr36/>. 2014, <http://www.unicode.org/reports/tr36/tr36-15.html>.
[UTS39] The Unicode Consortium, "Unicode Technical Standard #39: [UTS39] The Unicode Consortium, "Unicode Technical Standard #39:
Unicode Security Mechanisms", Unicode Security Mechanisms", Revision 20, May 2019,
<http://unicode.org/reports/tr39/>. <http://www.unicode.org/reports/tr39/tr39-20.html>.
[W3C.REC-html52-20171214] [W3C.REC-html52-20171214]
Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and
S. Moon, "HTML 5.2", World Wide Web Consortium S. Moon, "HTML 5.2", World Wide Web Consortium
Recommendation REC-html52-20171214, 14 December 2017, Recommendation REC-html52-20171214, 14 December 2017,
<https://www.w3.org/TR/2017/REC-html52-20171214>. <https://www.w3.org/TR/2017/REC-html52-20171214>.
[W3C.REC-rdf-schema-20140225] [W3C.REC-rdf-schema-20140225]
Brickley, D. and R. Guha, "RDF Schema 1.1", World Wide Web Brickley, D. and R. Guha, "RDF Schema 1.1", World Wide Web
Consortium Recommendation REC-rdf-schema-20140225, 25 Consortium Recommendation REC-rdf-schema-20140225, 25
skipping to change at line 1937 skipping to change at line 1963
<http://coreapps.org/base#title> <http://coreapps.org/base#title>
Indicates that the link target is a human-readable label (e.g., a Indicates that the link target is a human-readable label (e.g., a
menu entry). menu entry).
The link target MUST be a text string. The text string SHOULD be The link target MUST be a text string. The text string SHOULD be
annotated with a language and text direction using nested links of annotated with a language and text direction using nested links of
type <http://coreapps.org/base#language> and <http://coreapps.org/ type <http://coreapps.org/base#language> and <http://coreapps.org/
base#direction>, respectively. base#direction>, respectively.
<http://coreapps.org/base#language> <http://coreapps.org/base#language>
Indicates that the link target is a language tag [RFC5646] that Indicates that the link target is a Language Tag [RFC5646] that
specifies the language of the link context. specifies the language of the link context.
The link target MUST be a text string in the format specified in The link target MUST be a text string in the format specified in
Section 2.1 of RFC 5646 [RFC5646]. Section 2.1 of [RFC5646].
<http://coreapps.org/base#direction> <http://coreapps.org/base#direction>
Indicates that the link target is a base text direction (right-to- Indicates that the link target is a base text direction (right-to-
left or left-to-right) that specifies the text directionality of left or left-to-right) that specifies the text directionality of
the link context. the link context.
The link target MUST be either the text string "rtl" or the text The link target MUST be either the text string "rtl" or the text
string "ltr". string "ltr".
<http://coreapps.org/base#representation> <http://coreapps.org/base#representation>
Indicates that the link target is a representation of the link Indicates that the link target is a representation of the link
context. context.
The link target MUST be a byte string. The link target MUST be a byte string.
The representation may be a full, partial, or inconsistent version The representation may be a full, partial, or inconsistent version
of the representation served from the URI of the resource. of the representation served from the URI of the resource.
A link with link relation type can occur as a top-level element in A link with this link relation type can occur as a top-level
a document or as a nested element within a link. When it occurs element in a document or as a nested element within a link. When
as a top-level element, it provides an alternate representation of it occurs as a top-level element, it provides an alternate
the document's retrieval context. When it occurs nested within a representation of the document's retrieval context. When it
link, it provides a representation of link target of the enclosing occurs nested within a link, it provides a representation of link
link. target of the enclosing link.
Operation Types: Operation Types:
<http://coreapps.org/base#update> <http://coreapps.org/base#update>
Indicates that the state of the form's context can be replaced Indicates that the state of the form's context can be replaced
with the state described by a representation submitted to the with the state described by a representation submitted to the
server. server.
This operation type defaults to the PUT method [RFC7231] [RFC7252] This operation type defaults to the PUT method [RFC7231] [RFC7252]
for both HTTP and CoAP. Typical overrides by a form field include for both HTTP and CoAP. Typical overrides by a form field include
skipping to change at line 1994 skipping to change at line 2020
and the FETCH method [RFC8132] for CoAP. Typical overrides by a and the FETCH method [RFC8132] for CoAP. Typical overrides by a
form field include the POST method [RFC7252] for CoAP. form field include the POST method [RFC7252] for CoAP.
A.2. Collections A.2. Collections
Link Relation Types: Link Relation Types:
<http://www.iana.org/assignments/relation/item> <http://www.iana.org/assignments/relation/item>
Indicates that the link's context is a collection and that the Indicates that the link's context is a collection and that the
link's target is a member of that collection, as defined in link's target is a member of that collection, as defined in
Section 2.1 of RFC 6573 [RFC6573]. Section 2.1 of [RFC6573].
<http://www.iana.org/assignments/relation/collection> <http://www.iana.org/assignments/relation/collection>
Indicates that the link's target is a collection and that the Indicates that the link's target is a collection and that the
link's context is a member of that collection, as defined in link's context is a member of that collection, as defined in
Section 2.2 of RFC 6573 [RFC6573]. Section 2.2 of [RFC6573].
Operation Types: Operation Types:
<http://coreapps.org/collections#create> <http://coreapps.org/collections#create>
Indicates that the form's context is a collection and that a new Indicates that the form's context is a collection and that a new
item can be created in that collection with the state defined by a item can be created in that collection with the state defined by a
representation submitted to the server. representation submitted to the server.
This operation type defaults to the POST method [RFC7231] This operation type defaults to the POST method [RFC7231]
[RFC7252] for both HTTP and CoAP. [RFC7252] for both HTTP and CoAP.
skipping to change at line 2026 skipping to change at line 2052
[RFC7252] for both HTTP and CoAP. [RFC7252] for both HTTP and CoAP.
A.3. HTTP A.3. HTTP
Form Field Types: Form Field Types:
<http://coreapps.org/http#method> <http://coreapps.org/http#method>
Specifies the HTTP method for the request. Specifies the HTTP method for the request.
The form field value MUST be a text string in the format defined The form field value MUST be a text string in the format defined
in Section 4.1 of RFC 7231 [RFC7231]. The set of possible values in Section 4.1 of [RFC7231]. The possible set of values is
is maintained in the IANA HTTP Method Registry. maintained in the HTTP Methods Registry [HTTP-METHODS].
A form field of this type MUST NOT occur more than once in a form. A form field of this type MUST NOT occur more than once in a form.
If absent, it defaults to the request method implied by the form's If absent, it defaults to the request method implied by the form's
operation type. operation type.
<http://coreapps.org/http#accept> <http://coreapps.org/http#accept>
Specifies an acceptable HTTP content type for the request payload. Specifies an acceptable HTTP content type for the request payload.
There may be multiple form fields of this type. If a form does There may be multiple form fields of this type. If a form does
not include a form field of this type, the server accepts any or not include a form field of this type, the server accepts any or
no request payload, depending on the operation type. no request payload, depending on the operation type.
The form field value MUST be a text string in the format defined The form field value MUST be a text string in the format defined
in Section 3.1.1.1 of RFC 7231 [RFC7231]. The possible set of in Section 3.1.1.1 of [RFC7231]. The possible set of media types
media types and their parameters are maintained in the IANA Media and their parameters is maintained in the Media Types Registry
Types Registry. [MEDIA-TYPES].
Link Relation Types: Link Relation Types:
<http://coreapps.org/http#type> <http://coreapps.org/http#type>
Specifies the HTTP content type of the link context. Specifies the HTTP content type of the link context.
The link target MUST be a text string in the format defined in The link target MUST be a text string in the format defined in
Section 3.1.1.1 of RFC 7231 [RFC7231]. The possible set of media Section 3.1.1.1 of [RFC7231]. The possible set of media types and
types and their parameters are maintained in the IANA Media Types their parameters is maintained in the Media Types Registry
Registry. [MEDIA-TYPES].
A link of this type MUST NOT occur more than once for the link
context. If absent, its value defaults to the content type
"application/octet-stream".
A.4. CoAP A.4. CoAP
Form Field Types: Form Field Types:
<http://coreapps.org/coap#method> <http://coreapps.org/coap#method>
Specifies the CoAP method for the request. Specifies the CoAP method for the request.
The form field value MUST be an integer identifying one of the The form field value MUST be an integer identifying a CoAP method
CoAP request methods maintained in the IANA CoAP Method Codes (e.g., the integer 2 for the POST method). The possible set of
Registry (e.g., the integer 2 for the POST method). values is maintained in the CoAP Method Codes Registry
[CORE-PARAMETERS].
A form field of this type MUST NOT occur more than once in a form. A form field of this type MUST NOT occur more than once in a form.
If absent, it defaults to the request method implied by the form's If absent, it defaults to the request method implied by the form's
operation type. operation type.
<http://coreapps.org/coap#accept> <http://coreapps.org/coap#accept>
Specifies an acceptable CoAP content format for the request Specifies an acceptable CoAP content format for the request
payload. There may be multiple form fields of this type. If a payload. There may be multiple form fields of this type. If a
form does not include a form field of this type, the server form does not include a form field of this type, the server
accepts any or no request payload, depending on the operation accepts any or no request payload, depending on the operation
type. type.
The form field value MUST be an integer identifying one of the The form field value MUST be an integer identifying a CoAP content
content formats maintained in the IANA CoAP Content-Formats format. The possible set of values is maintained in the CoAP
Registry. Content Formats Registry [CORE-PARAMETERS].
Link Relation Types: Link Relation Types:
<http://coreapps.org/coap#type> <http://coreapps.org/coap#type>
Specifies the CoAP content format of the link context. Specifies the CoAP content format of the link context.
The link target MUST be an integer identifying one of the content The link target MUST be an integer identifying a CoAP content
formats maintained in the IANA CoAP Content-Formats Registry. format (e.g., the integer 42 for the content type "application/
octet-stream" without a content coding). The possible set of
A link of this type MUST NOT occur more than once for the link values is maintained in the CoAP Content Formats Registry
context. If absent, it defaults to content format 42 (i.e., the [CORE-PARAMETERS].
content type "application/octet-stream" without a content coding).
Appendix B. Default Dictionary Appendix B. Default Dictionary
This section defines a default dictionary that is assumed when the This section defines a default dictionary that is assumed when the
"application/coral+cbor" media type is used without a "dictionary" "application/coral+cbor" media type is used without a "dictionary"
parameter. parameter.
+-----+-------------------------------------------------------+ +-----+-------------------------------------------------------+
| Key | Value | | Key | Value |
+=====+=======================================================+ +=====+=======================================================+
skipping to change at line 2136 skipping to change at line 2158
+-----+-------------------------------------------------------+ +-----+-------------------------------------------------------+
| 11 | <http://coreapps.org/base#direction> | | 11 | <http://coreapps.org/base#direction> |
+-----+-------------------------------------------------------+ +-----+-------------------------------------------------------+
| 12 | "ltr" | | 12 | "ltr" |
+-----+-------------------------------------------------------+ +-----+-------------------------------------------------------+
| 13 | "rtl" | | 13 | "rtl" |
+-----+-------------------------------------------------------+ +-----+-------------------------------------------------------+
| 14 | <http://coreapps.org/base#representation> | | 14 | <http://coreapps.org/base#representation> |
+-----+-------------------------------------------------------+ +-----+-------------------------------------------------------+
Table 3: Default Dictionary Table 4: Default Dictionary
Appendix C. Change Log Appendix C. Change Log
This section is to be removed before publishing as an RFC. This section is to be removed before publishing as an RFC.
Changes from -02 to -03:
* Changed the binary format to express relation types, operation
types and form field types using [I-D.ietf-core-href] (#2).
* Clarified the current context and current base for nested elements
and form fields (#53).
* Minor editorial improvements (#27).
Changes from -01 to -02: Changes from -01 to -02:
* Added nested elements to form fields. * Added nested elements to form fields.
* Replaced the special construct for embedded representations with * Replaced the special construct for embedded representations with
links. links.
* Changed the textual format to allow simple/qualified names * Changed the textual format to allow simple/qualified names
wherever IRI references are allowed. wherever IRI references are allowed.
* Introduced predefined names in the textual format (#39). * Introduced predefined names in the textual format (#39).
* Minor editorial improvements and bug fixes. * Minor editorial improvements and bug fixes (#16 #28 #31 #37 #39).
Changes from -00 to -01: Changes from -00 to -01:
* Added a section on the semantics of CoRAL documents in responses. * Added a section on the semantics of CoRAL documents in responses.
* Minor editorial improvements. * Minor editorial improvements.
Acknowledgements Acknowledgements
CoRAL is heavily inspired by Mike Kelly's JSON Hypertext Application CoRAL is heavily inspired by Mike Kelly's JSON Hypertext Application
Language [HAL]. Language [HAL].
The recommendations for minting IRIs have been adopted from RDF 1.1 The recommendations for minting IRIs have been adopted from RDF 1.1
Concepts and Abstract Syntax [W3C.REC-rdf11-concepts-20140225] to Concepts and Abstract Syntax [W3C.REC-rdf11-concepts-20140225] to
ease the interoperability between RDF predicates and link relation ease the interoperability between RDF predicates and link relation
types. types.
Thanks to Christian Amsuess, Carsten Bormann, Thomas Fossati, Jaime Thanks to Christian Amsuess, Carsten Bormann, Thomas Fossati, Jaime
Jimenez, Jim Schaad, Sebastian Kaebisch, Ari Keranen, Michael Koster, Jimenez, Jim Schaad, Sebastian Kaebisch, Ari Keranen, Michael Koster,
Matthias Kovatsch, and Niklas Widell for helpful comments and Matthias Kovatsch and Niklas Widell for helpful comments and
discussions that have shaped the document. discussions that have shaped the document.
Author's Address Author's Address
Klaus Hartke Klaus Hartke
Ericsson Ericsson
Torshamnsgatan 23 Torshamnsgatan 23
SE-16483 Stockholm SE-16483 Stockholm
Sweden Sweden
 End of changes. 168 change blocks. 
436 lines changed or deleted 481 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/