draft-ietf-core-coral-01.txt   draft-ietf-core-coral-02.txt 
CoRE Working Group K. Hartke CoRE Working Group K. Hartke
Internet-Draft Ericsson Internet-Draft Ericsson
Intended status: Standards Track November 4, 2019 Intended status: Standards Track 8 January 2020
Expires: May 7, 2020 Expires: 11 July 2020
The Constrained RESTful Application Language (CoRAL) The Constrained RESTful Application Language (CoRAL)
draft-ietf-core-coral-01 draft-ietf-core-coral-02
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"),
as well as simple resource metadata. and simple resource metadata.
Note to Readers
This note is to be removed before publishing as an RFC.
The issues list for this Internet-Draft can be found at
<https://github.com/core-wg/coral/labels/coral>.
Companion material for this Internet-Draft can be found at
<https://github.com/core-wg/coral>.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 May 7, 2020. This Internet-Draft will expire on 11 July 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 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 Provisions Relating to IETF Documents (https://trustee.ietf.org/
(https://trustee.ietf.org/license-info) in effect on the date of license-info) in effect on the date of publication of this document.
publication of this document. Please review these documents Please review these documents carefully, as they describe your rights
carefully, as they describe your rights and restrictions with respect and restrictions with respect to this document. Code Components
to this document. Code Components extracted from this document must extracted from this document must include Simplified BSD License text
include Simplified BSD License text as described in Section 4.e of as described in Section 4.e of the Trust Legal Provisions and are
the Trust Legal Provisions and are provided without warranty as provided without warranty as described in the Simplified BSD License.
described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 1.1. Data and Interaction Model
2. Data and Interaction Model . . . . . . . . . . . . . . . . . 4 1.2. Serialization Formats
2.1. Browsing Context . . . . . . . . . . . . . . . . . . . . 5 1.3. Notational Conventions
2.2. Documents . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Data and Interaction Model
2.3. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.1. Browsing Context
2.4. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.2. Documents
2.5. Form Fields . . . . . . . . . . . . . . . . . . . . . . . 7 2.3. Links
2.6. Embedded Representations . . . . . . . . . . . . . . . . 7 2.4. Forms
2.7. Navigation . . . . . . . . . . . . . . . . . . . . . . . 8 2.5. Form Fields
2.8. History Traversal . . . . . . . . . . . . . . . . . . . . 9 2.6. Navigation
3. Binary Format . . . . . . . . . . . . . . . . . . . . . . . . 10 2.7. History Traversal
3.1. Data Structure . . . . . . . . . . . . . . . . . . . . . 10 3. Binary Format
3.1.1. Documents . . . . . . . . . . . . . . . . . . . . . . 10 3.1. Data Structure
3.1.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 10 3.1.1. Documents
3.1.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 11 3.1.2. Directives
3.1.4. Embedded Representations . . . . . . . . . . . . . . 12 3.1.3. IRIs
3.1.5. Directives . . . . . . . . . . . . . . . . . . . . . 13 3.1.4. Links
3.2. Dictionaries . . . . . . . . . . . . . . . . . . . . . . 13 3.1.5. Forms
3.2.1. Dictionary References . . . . . . . . . . . . . . . . 13 3.1.6. Form Fields
3.2.2. Media Type Parameter . . . . . . . . . . . . . . . . 14 3.2. Dictionary Compression
4. Textual Format . . . . . . . . . . . . . . . . . . . . . . . 14 3.2.1. Dictionary References
4.1. Lexical Structure . . . . . . . . . . . . . . . . . . . . 15 3.2.2. Media Type Parameter
4.1.1. Line Terminators . . . . . . . . . . . . . . . . . . 15 4. Textual Format
4.1.2. White Space . . . . . . . . . . . . . . . . . . . . . 15 4.1. Lexical Structure
4.1.3. Comments . . . . . . . . . . . . . . . . . . . . . . 15 4.1.1. Line Terminators
4.1.4. Identifiers . . . . . . . . . . . . . . . . . . . . . 16 4.1.2. White Space
4.1.5. IRIs and IRI References . . . . . . . . . . . . . . . 16 4.1.3. Comments
4.1.6. Literals . . . . . . . . . . . . . . . . . . . . . . 16 4.1.4. Identifiers
4.1.7. Punctuators . . . . . . . . . . . . . . . . . . . . . 20 4.1.5. Literals
4.2. Syntactic Structure . . . . . . . . . . . . . . . . . . . 20 4.1.6. Punctuators
4.2.1. Documents . . . . . . . . . . . . . . . . . . . . . . 21 4.2. Syntactic Structure
4.2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 21 4.2.1. Documents
4.2.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 22 4.2.2. Directives
4.2.4. Embedded Representations . . . . . . . . . . . . . . 23 4.2.3. IRIs
4.2.5. Directives . . . . . . . . . . . . . . . . . . . . . 23 4.2.4. Links
5. Usage Considerations . . . . . . . . . . . . . . . . . . . . 24 4.2.5. Forms
5.1. Specifying CoRAL-based Applications . . . . . . . . . . . 24 4.2.6. Form Fields
5.1.1. Application Interfaces . . . . . . . . . . . . . . . 25 5. Document Semantics
5.1.2. Resource Identifiers . . . . . . . . . . . . . . . . 25 5.1. Submitting Documents
5.1.3. Implementation Limits . . . . . . . . . . . . . . . . 26 5.1.1. PUT Requests
5.2. Minting Vocabulary . . . . . . . . . . . . . . . . . . . 26 5.1.2. POST Requests
5.3. Expressing Registered Link Relation Types . . . . . . . . 27 5.2. Returning Documents
5.4. Expressing Simple RDF Statements . . . . . . . . . . . . 28 5.2.1. Success Responses
5.5. Expressing Natural Language Texts . . . . . . . . . . . . 28 5.2.2. Redirection Responses
5.6. Embedding CoRAL in CBOR Data . . . . . . . . . . . . . . 29 5.2.3. Error Responses
5.7. Submitting CoRAL Documents . . . . . . . . . . . . . . . 29 6. Usage Considerations
5.7.1. PUT Requests . . . . . . . . . . . . . . . . . . . . 29 6.1. Specifying CoRAL-based Applications
5.7.2. POST Requests . . . . . . . . . . . . . . . . . . . . 29 6.1.1. Application Interfaces
5.8. Returning CoRAL Documents . . . . . . . . . . . . . . . . 30 6.1.2. Resource Identifiers
5.8.1. Success Responses . . . . . . . . . . . . . . . . . . 30 6.1.3. Implementation Limits
5.8.2. Error Responses . . . . . . . . . . . . . . . . . . . 30 6.2. Minting Vocabulary
6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 6.3. Expressing Registered Link Relation Types
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 6.4. Expressing Simple RDF Statements
7.1. Media Type "application/coral+cbor" . . . . . . . . . . . 32 6.5. Expressing Natural Language Texts
7.2. Media Type "text/coral" . . . . . . . . . . . . . . . . . 33 6.6. Embedding Representations in CoRAL
7.3. CoAP Content Formats . . . . . . . . . . . . . . . . . . 34 6.7. Embedding CoRAL in CBOR Representations
7.4. CBOR Tag . . . . . . . . . . . . . . . . . . . . . . . . 35 7. Security Considerations
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 8. IANA Considerations
8.1. Normative References . . . . . . . . . . . . . . . . . . 35 8.1. Media Type "application/coral+cbor"
8.2. Informative References . . . . . . . . . . . . . . . . . 37 8.2. Media Type "text/coral"
Appendix A. Core Vocabulary . . . . . . . . . . . . . . . . . . 39 8.3. CoAP Content Formats
A.1. Base . . . . . . . . . . . . . . . . . . . . . . . . . . 40 8.4. CBOR Tag
A.2. Collections . . . . . . . . . . . . . . . . . . . . . . . 41 9. References
A.3. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . 41 9.1. Normative References
A.4. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 42 9.2. Informative References
Appendix B. Default Dictionary . . . . . . . . . . . . . . . . . 43 Appendix A. Core Vocabulary
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 44 A.1. Base
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 44 A.2. Collections
A.3. HTTP
A.4. CoAP
Appendix B. Default Dictionary
Appendix C. Change Log
Acknowledgements
Author's Address
1. Introduction 1. Introduction
The Constrained RESTful Application Language (CoRAL) is a language The Constrained RESTful Application Language (CoRAL) is a language
for the description of typed connections between resources on the Web for the description of typed connections between resources on the Web
("links"), possible operations on such resources ("forms"), as well ("links"), possible operations on such resources ("forms"), and
as simple resource metadata. simple resource metadata.
CoRAL is intended for driving automated software agents that navigate CoRAL is intended for driving automated software agents that navigate
a Web application based on a standardized vocabulary of link relation a Web application based on a standardized vocabulary of link relation
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 and interaction model, as well This document defines the CoRAL data model and interaction model as
as two specialized CoRAL serialization formats. well as two specialized CoRAL serialization formats.
The CoRAL data and interaction model is a superset of the Web Linking 1.1. Data and Interaction Model
model of RFC 8288 [RFC8288]. The data model consists of two primary
elements: "links" that describe the relationship between two The data model derives from the Web Linking model of RFC 8288
resources and the type of that relationship, and "forms" that [RFC8288] and primarily consists of two elements: "links" that
describe a possible operation on a resource and the type of that describe the relationship between two resources and the type of that
operation. Additionally, the data model can describe simple resource relationship; and "forms" that describe a possible operation on a
metadata in a way similar to the Resource Description Framework (RDF) resource and the type of that operation.
Additionally, the data model can describe simple resource metadata in
similarly to statements in the Resource Description Framework (RDF)
[W3C.REC-rdf11-concepts-20140225]. In contrast to RDF, the focus of [W3C.REC-rdf11-concepts-20140225]. In contrast to RDF, the focus of
CoRAL however is on the interaction with resources, not just the CoRAL, however, is not on the description of a resource graph, but on
relationships between them. The interaction model derives from HTML the discovery of possible future application states of a software
5 [W3C.REC-html52-20171214] and specifies how an automated software agent.
agent can navigate between resources by following links and perform
operations on resources by submitting forms.
The primary CoRAL serialization format is a compact, binary encoding The interaction model derives from HTML [W3C.REC-html52-20171214] and
of links and forms in Concise Binary Object Representation (CBOR) specifies how an automated software agent can change the application
[RFC7049]. It is intended for environments with constraints on state, i.e., navigate between resources by following links and
power, memory, and processing resources [RFC7228] and shares many perform operations on resources by submitting forms.
similarities with the message format of the Constrained Application
Protocol (CoAP) [RFC7252]: For example, it uses numeric identifiers
instead of verbose strings for link relation types and operation
types, and pre-parses Uniform Resource Identifiers (URIs) [RFC3986]
into (what CoAP considers to be) their components, which simplifies
URI processing for constrained nodes a lot. As a result, link
serializations in CoRAL are often much more compact than equivalent
serializations in CoRE Link Format [RFC6690].
The secondary CoRAL serialization format is a lightweight, textual 1.2. Serialization Formats
encoding of links and forms that is intended to be easy to read and
write for humans. The format is loosely inspired by the syntax of
Turtle [W3C.REC-turtle-20140225] and is mainly intended for giving
examples.
1.1. Notational Conventions The primary serialization format is a compact, binary encoding of
links and forms in Concise Binary Object Representation (CBOR)
[I-D.ietf-cbor-7049bis]. The format is intended for environments
with constraints on power, memory, and processing resources [RFC7228]
and shares many similarities with the message format of the
Constrained Application Protocol (CoAP) [RFC7252]. For example, it
uses numeric identifiers instead of verbose strings for link relation
types and operation types, and pre-parses Uniform Resource
Identifiers (URIs) [RFC3986] into (what CoAP considers to be) their
components, which considerably simplifies URI processing for
constrained nodes that already implement CoAP. As a result, link
serializations in CoRAL are often much more compact and easier to
process than equivalent serializations in CoRE Link Format [RFC6690].
The secondary serialization format is a lightweight, textual encoding
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
[W3C.REC-turtle-20140225] and is mainly intended for giving examples
with precise semantics.
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.
skipping to change at page 5, line 9 skipping to change at line 218
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
Borrowing from HTML 5 [W3C.REC-html52-20171214], each such agent Borrowing from HTML 5 [W3C.REC-html52-20171214], each such agent
maintains a _browsing context_ in which the representations of Web maintains a _browsing context_ in which the representations of Web
resources are processed. (In HTML 5, 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 each browsing context is At any time, one representation in a browsing context is designated
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_.
A CoRAL document consists of a list of zero or more links, forms, and A CoRAL document consists of a list of zero or more links and forms,
embedded resource representations, collectively called _elements_. collectively called _elements_. CoRAL serialization formats may
CoRAL serialization formats may define additional types of elements define additional types of elements for efficiency or convenience,
for efficiency or convenience, such as a base for relative URI such as a base for relative URI references.
references [RFC3986].
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 defined in RFC 8288, it consists of a _link context_, [RFC8288]. As in RFC 8288, a link in CoRAL has a _link context_, a
a _link relation type_, and a _link target_. In CoRAL, a link can _link relation type_, and a _link target_. However, in CoRAL, links
additionally have a nested list of zero or more elements, which take do not have target attributes. Instead, a link may have a list of
the place of link target attributes. zero or more nested elements. These enable both the description of
resource metadata (which is done in RFC 8288 with target attributes)
and the chaining of links (which can be done in RFC 8288 by setting
the anchor of one link to the target of another).
A link can be viewed as a statement of the form "{link context} has a A link can be viewed as a statement of the form "{link context}
{link relation type} resource at {link target}" where the link target has a {link relation type} resource at {link target}" where the
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. In HTML 5 The link relation type identifies the semantics of a link. While in
and RFC 8288, link relation types are typically denoted by an IANA- HTML and RFC 8288 these are typically denoted by an IANA-registered
registered name, such as "stylesheet" or "type". In CoRAL, they are name, such as "stylesheet" or "type", link relation types in CoRAL
denoted by an Internationalized Resource Identifier (IRI) [RFC3987] are denoted by an Internationalized Resource Identifier (IRI)
such as <http://www.iana.org/assignments/relation/stylesheet> or [RFC3987], such as <http://www.iana.org/assignments/relation/
<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>. This allows for stylesheet> or <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>.
the creation of new link relation types without the risk of This allows for the creation of new link relation types without the
collisions when from different organizations or domains of knowledge. risk of collisions when from different organizations or domains of
An IRI also can lead to documentation, schema, and other information knowledge. IRIs can also lead to documentation, schema, and other
about the link relation type. These IRIs are only used as identity information about a link relation type. In CoRAL documents, these
tokens, though, and are compared using Simple String Comparison IRIs are only used as identity tokens, though, and are compared with
(Section 5.1 of RFC 3987). Simple String Comparison as specified in Section 5.3.1 of RFC 3987.
The link context and the link target are both denoted by either a URI The link context and the link target can be both either a URI, a
reference or a literal (similarly to RDF). If the URI scheme literal value, or an anonymous resource. If the scheme of a URI
indicates a Web transfer protocol such as HTTP or CoAP, then an agent indicates a Web transfer protocol such as HTTP or CoAP, an agent can
can dereference the URI and navigate the browsing context to the dereference the URI and navigate the browsing context to the link
referenced resource; this is called _following the link_. A literal target; this is called _following the link_. A literal value can be
directly identifies a value: a Boolean value, an integer, a floating- either a Boolean value, an integer, a floating-point number, a date/
point number, a date/time value, a byte string, or a text string. time instant, a byte string, or a text string. An anonymous resource
is a resource which is not identified by a URI and is not a literal.
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 link target of the outer link. inner link is the same resource as the link target of the outer 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 nested data structure constrains the description of a
resource graph to a tree: Links between linked resources can only be resource graph to a tree: Links between linked resources can only be
described by further nesting links. 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. It consists of a _form context_, an operation on a Web resource. 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 _form fields_. Additionally, a form may be accompanied by a list of zero or more
_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 method} {operation type} operation on {form context}, make a {request
request to {submission target}" where the request may be further method} request to {submission target}" where the request may be
described by form fields. further described by form fields.
The operation type identifies the semantics of the operation. The 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.
The form context is the resource on which an operation is ultimately The form context is the resource on which an 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 and the specified submission target
as the request URI. Usually, the submission target is the same as the request URI. Usually, the submission target is the same
resource as the form context, but it may be a different resource. resource as the form context, but it may be a different resource.
Constructing and sending the request is called _submitting the form_. Constructing and sending the request is called _submitting the form_.
Form fields, specified in the next section, can be used to provide
more detailed instructions to the agent for constructing the request.
For example, form fields can instruct the agent to include a payload
or certain headers in the request that must match the specifications
of the form fields.
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 link When a form occurs nested within a link, the form context is the same
target of the enclosing link. resource as the link target of the enclosing link.
2.5. Form Fields 2.5. Form Fields
Form fields provide further instructions to agents for constructing a Form fields can be used to provide more detailed instructions to
request. agents for constructing the request when submitting a form. For
example, form fields can instruct the agent to include a certain
For example, a form field could identify one or more data items that payload or certain header fields in the request. Form fields might
need to be included in the request payload or reference another describe a payload by identifying acceptable media types, referencing
resource (such as a schema) that describes the structure of the a schema, or listing a number of data items that need to be included.
payload. A form field could also provide other kinds of information, Form fields can be specific to the Web transfer protocol that is used
such as acceptable media types for the payload or expected request for submitting the form.
headers. Form fields may be specific to the protocol used for
submitting the form.
A form field is the 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_. value_. Additionally, a form field may have a list of zero or more
nested elements that further describe the form field value.
The form field type identifies the semantics of the form field. Form The form field type identifies the semantics of the form field. Form
field types are denoted like link relation types and operation types field types are denoted (like link relation types and operation
by an IRI. types) by an IRI.
The form field value can be either a URI reference, a Boolean value,
an integer, a floating-point number, a date/time value, a byte
string, or a text string.
2.6. Embedded Representations
When a document contains links to many resources and an agent needs a
representation of each link target, it may be inefficient to retrieve
each of these representations individually. To alleviate this,
documents can directly embed representations of resources.
An _embedded representation_ consists of a sequence of bytes, labeled
with _representation metadata_.
An embedded representation may be a full, partial, or inconsistent
version of the representation served from the URI of the resource.
An embedded representation can occur as a top-level element in a The form field value can be either a URI, a Boolean value, an
document or as a nested element within a link. When it occurs as a integer, a floating-point number, a date/time instant, a byte string,
top-level element, it provides an alternate representation of the a text string, or null. A null denotes the intentional absence of
document's retrieval context. When it occurs nested within a link, any form field value.
it provides a representation of link target of the enclosing link.
2.7. Navigation 2.6. Navigation
An agent begins interacting with an application by performing a GET An agent begins interacting with an application by performing a GET
request on an _entry point URI_. The entry point URI is the only URI request on an _entry point URI_. The entry point URI is the only URI
an agent is expected to know before interacting with an application. that the agent is expected to know before interacting with the
From there, the agent is expected to make all requests by following application. From then on, the agent is expected to make all
links and submitting forms provided by the server in responses. The requests by following links and submitting forms that are provided by
entry point URI can be obtained by manual configuration or through servers in responses. The entry point URI can be obtained through
some discovery process. some 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), then the agent makes this document the active representation
in the browsing context and proceeds as follows: in 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 form to submit, based on the link which type of link to follow or type of form to submit, based on
relation types and operation types it understands. the link relation types and operation types it knows.
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 may 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 a transition is not supported or not allowed.
3. The agent selects one of the candidates based on the metadata 3. The agent selects one of the candidates based on the order of
associated with each of these. Metadata includes the content appearance in the document and the resource metadata associated
type of the target resource representation, the URI scheme, the with them in the form of nested elements and form fields.
request method, and other information that is provided as nested Examples for resource metadata include the indication of a
elements in a link or form fields in a form. content type for the target resource representation, the URI
scheme of a link target, or the request method of a form.
If the selected candidate contains an embedded representation,
the agent MAY skip the following steps and immediately proceed
with step 8.
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. Fragment identifiers are not part of the submission target. Link targets and submission targets may be
denoted by relative URI references, which need to be resolved to
obtain the request URI. Fragment identifiers are not part of the
request URI and MUST be separated from the rest of the URI prior request URI and MUST be separated from the rest of the URI prior
to a dereference. 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 specified by the form. An IRI may need to be be the one indicated by the form. An IRI may need to be
converted to a URI (Section 3.1 of RFC 3987) for protocols that converted to a URI (Section 3.1 of RFC 3987) for protocols that
do not support IRIs. do not 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 metadata associated with the link or form (e.g., set according to the nested elements of a link or form fields of a
the HTTP Accept header field or the CoAP Accept option when the form (e.g., set the HTTP Accept header field or the CoAP Accept
media type of the target resource is provided). Depending on the option when a media type for the target resource is provided).
operation type of a form, the agent may also need to include a Depending on the operation type of a form, the agent may also
request payload that matches the specifications of one or more have to include a request payload that matches the specifications
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 dereferences the fragment identifier within the received agent selects the fragment indicated by the fragment identifier
representation. within the received representation.
8. The agent _updates the browsing context_ by making the (embedded 8. The agent _updates the browsing context_ by making the (selected
or received) representation the active representation. fragment of the) received representation the active
representation.
9. Finally, the agent processes the representation according to the 9. Finally, the agent processes the representation according to the
semantics of the content type. If the representation is a CoRAL semantics of its content 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), this means the agent has the choice data and interaction model), the agent has the choice of what to
of what to do next again -- and the cycle repeats. do next again -- and the cycle repeats.
2.8. History Traversal 2.7. History Traversal
A browsing context MAY entail a _session history_ that lists the Each browsing context has a _session history_ that lists the resource
resource representations that the agent has processed, is processing, representations that the agent has processed, is processing, or will
or will process. process. The maximum length of the session history is up for the
agent to decide and may be zero.
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 request URI that was used to retrieve the representation.
New entries are added to the session history as the agent navigates New entries are added to the session history as the agent navigates
from resource to resource. from resource to resource.
An agent can navigate a browsing context by _traversing the session In addition to following links and submitting forms, an agent can
history_ in addition to following links and submitting forms. For decide tp navigate a browsing context by _traversing the session
example, if an agent received a representation that doesn't contain history_. For example, when an agent receives a representation that
any further links or forms, it can revert the active representation does not contain any further links or forms, it can set the active
back to one it has visited earlier. representation back to one it has visited earlier.
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 request)
when it doesn't have a fresh representation in its cache. An agent when it does not have a fresh representation in its cache. An agent
MUST NOT reissue an unsafe request (e.g., a PUT or POST request) MUST NOT reissue an unsafe request (e.g., a PUT or a POST request)
unless it intends to perform that operation again. unless it 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 a data item in Concise Binary A document in the binary format is encoded in Concise Binary Object
Object Representation (CBOR) [RFC7049]. The structure of this data Representation (CBOR) [I-D.ietf-cbor-7049bis]. The encoding MUST
item is presented in the Concise Data Definition Language (CDDL) satisfy the Core Deterministic Encoding Requirements specified in
[RFC8610]. The media type is "application/coral+cbor". Section XX of RFC XXXX [I-D.ietf-cbor-7049bis].
The following restrictions are placed on CBOR encoders: Byte strings The CBOR structure of a document is presented in the Concise Data
and text strings MUST be encoded with definite length. Integers and Definition Language (CDDL) [RFC8610]. All CDDL rules not defined in
floating-point values MUST be encoded as such (e.g., a floating-point this document are defined in Appendix D of RFC 8610 [RFC8610].
value of 0.0 must not be encoded as the integer 0).
The media type of documents in the binary format is "application/
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
four kinds of elements: links, forms, embedded representations, and three kinds of elements: links, forms, and (as an extension to the
(as an extension to the CoRAL data model) base directives. Base CoRAL data model) directives. Directives provide a way to encode URI
directives provide a way to encode URI references with a common base references with a common base more efficiently.
more efficiently.
Elements are processed in the order they appear in the document.
Document processors need to maintain an _environment_ while iterating
an array of elements. The environment consists of two variables: the
_current context_ and the _current base_. Both the current context
and the current base are initially set to the document's retrieval
context.
3.1.1. Documents 3.1.1. Documents
The body of a document in the binary format is encoded as an array of A document in the binary format is encoded as a CBOR array that
zero or more links, forms, embedded representations, and directives. contains zero or more elements. An element is either a link, a form,
or a directive.
document = body
body = [*(link / form / representation / directive)]
3.1.2. Links
A link is encoded as an array that consists of the unsigned integer document = [*element]
2, followed by the link relation type and the link target, optionally
followed by a link body that contains nested elements.
link = [2, relation-type, link-target, ?body] element = link / form / directive
The link relation type is encoded as a text string that conforms to The elements are processed in the order they appear in the document.
the syntax of an IRI [RFC3987]. Document processors need to maintain an _environment_ while iterating
an array of elements. The environment consists of two variables: the
_current context_ and the _current base_. Both the current context
and the current base are initially set to the document's retrieval
context.
relation-type = text 3.1.2. Directives
The link target is denoted by a Constrained Resource Identifier Directives provide the ability to manipulate the environment while
(CoRI) reference [I-D.ietf-core-href] or represented by a literal processing elements.
value. A CoRI reference MUST be resolved against the current base.
The link target may be null, which indicates that the link target is
an unidentified resource.
link-target = CoRI / literal There is a single type of directives available: the Base directive.
CoRI = <Defined in Section X of RFC XXXX> directive = base-directive
literal = bool / int / float / time / bytes / text / null 3.1.2.1. Base Directives
The array of elements in the link body, if any, MUST be processed in A Base directive is encoded as a CBOR array that contains the
a fresh environment. Both the current context and the current base unsigned integer 1 and a base URI.
in the new environment are initially set to the link target of the
enclosing link.
3.1.3. Forms base-directive = [1, baseURI]
A form is encoded as an array that consists of the unsigned integer The base URI is denoted by a Constrained Resource Identifier (CoRI)
3, followed by the operation type and the submission target, reference [I-D.ietf-core-href]. The CoRI reference MUST be resolved
optionally followed by a list of form fields. against the current context (not the current base).
form = [3, operation-type, submission-target, ?form-fields] baseURI = CoRI
The operation type is defined in the same way as a link relation type CoRI = <Defined in Section XX of RFC XXXX>
(Section 3.1.2).
operation-type = text The directive is processed by resolving the CoRI reference against
the current context and assigning the result to the current base.
The request method is either implied by the operation type or encoded 3.1.3. IRIs
as a form field. If there are both, the form field takes precedence
over the operation type. Either way, the method MUST be defined for
the Web transfer protocol identified by the scheme of the submission
target.
The submission target is denoted by a CoRI reference. This CoRI IRIs in links and forms are encoded as CoRI references.
reference MUST be resolved against the current base.
submission-target = CoRI IRI = CoRI
3.1.3.1. Form Fields A CoRI 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
base.
A list of form fields is encoded as an array of zero or more type- 3.1.4. Links
value pairs.
form-fields = [*(form-field-type, form-field-value)] 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
of zero or more nested elements.
The list, if any, MUST be processed in a fresh environment. Both the link = [2, relation-type, link-target, ?[*element]]
current context and the current base in the new environment are
initially set to the submission target of the enclosing form.
A form field type is defined in the same way as a link relation type The link relation type is encoded as a text string that conforms to
(Section 3.1.2). the syntax of an IRI [RFC3987].
form-field-type = text relation-type = text
A form field value can be a CoRI reference, a Boolean value, an The link target is either an IRI, a literal value, or null.
integer, a floating-point number, a date/time value, a byte string, a
text string, or null. A CoRI reference MUST be resolved against the
current base.
form-field-value = CoRI / literal link-target = IRI / literal / null
3.1.4. Embedded Representations literal = bool / int / float / time / bytes / text
An embedded representation is encoded as an array that consists of The nested elements, if any, MUST be processed in a fresh
the unsigned integer 0, followed by a byte string containing the environment. Both the current context and current base in this
representation data, optionally followed by representation metadata. environment are initially set to the link target of the enclosing
link.
representation = [0, bytes, ?representation-metadata] 3.1.5. Forms
Representation metadata is encoded as an array of zero or more name- A form is encoded as a CBOR array that contains the unsigned integer
value pairs. 3, the operation type, the submission target, and, optionally, an
array of zero or more form fields.
representation-metadata = [*(metadata-name, metadata-value)] form = [3, operation-type, submission-target, ?[*form-field]]
The metadata, if any, MUST be processed in a fresh environment. All The operation type is encoded as a text string that conforms to the
variables in the new environment are initially set to a copy of the syntax of an IRI [RFC3987].
variables in the current environment.
The metadata name is defined in the same way as a link relation type operation-type = text
(Section 3.1.2).
metadata-name = text The submission target is an IRI.
A metadata value can be a CoRI reference, a Boolean value, an submission-target = IRI
integer, a floating-point number, a date/time value, a byte string, a
text string, or null. A CoRI reference MUST be resolved against the
current base.
metadata-value = CoRI / literal 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
over the operation type. Either way, the method MUST be applicable
to the Web transfer protocol identified by the scheme of the
submission target.
3.1.5. Directives The form fields, if any, MUST be processed in a fresh environment.
Both the current context and the current base in this environment are
initially set to the submission target of the enclosing form.
Directives provide the ability to manipulate the environment when 3.1.6. Form Fields
processing a list of elements. There is one type of directives
available: the Base directive.
directive = base-directive 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
more nested elements.
3.1.5.1. Base Directives form-field = (form-field-type, form-field-value, ?[*element])
A Base directive is encoded as an array that consists of the unsigned The form field type is encoded as a text string that conforms to the
integer 1, followed by a base. syntax of an IRI [RFC3987].
base-directive = [1, base] form-field-type = text
The base is denoted by a CoRI reference. This CoRI reference MUST be The form field value is either an IRI, a literal value, or null.
resolved against the current context (not the current base).
base = CoRI form-field-value = IRI / literal / null
The directive is processed by resolving the CoRI reference against The nested elements, if any, MUST be processed in a fresh
the current context and assigning the result to the current base. environment. Both the current context and current base in this
environment are initially set to the form field value of the
enclosing form field.
3.2. Dictionaries 3.2. Dictionary Compression
The binary format can reference values from a dictionary to reduce A document in the binary format can reference values from an external
representation size and processing cost. Dictionary references can dictionary to reduce representation size and processing cost.
be used in place of link relation types, link targets, operation Dictionary references can be used in place of link relation types,
types, submission targets, form field types, form field values, link targets, operation types, submission targets, form field types,
representation metadata names, and representation metadata values. 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. 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)
metadata-name /= uint A dictionary reference MUST NOT refer to a dictionary value that is
otherwise not allowed. For example, a dictionary reference that is
metadata-value /= #6.TBD6(uint) used in place of a link relation type is not allowed to refer to a
Boolean value.
3.2.2. Media Type Parameter 3.2.2. Media Type Parameter
The "application/coral+cbor" media type is defined to have a The "application/coral+cbor" media type for documents in the binary
"dictionary" parameter that specifies the dictionary in use. The format is defined to have a "dictionary" parameter that specifies the
dictionary is identified by a URI [RFC3986]. For example, a CoRAL dictionary in use. The dictionary is identified by a URI [RFC3986].
document that uses the dictionary identified by the URI For example, a CoRAL document that uses the dictionary identified by
<http://example.com/dictionary> can use the following content type: the URI <http://example.com/dictionary> can use the following content
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
human- or machine-readable way. (The format of such a representation machine- or human-readable way. (The representation format and
is outside the scope of this document.) security considerations of such a representation are outside the
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. If the "dictionary" parameter is absent, the default dictionary URI. The "dictionary" parameter is OPTIONAL. If it is absent, the
specified in Appendix B of this document is assumed. 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 media In CoAP [RFC7252], media types (including specific values for their
type parameters) are encoded as an unsigned integer called "content parameters) are encoded as an unsigned integer called the "content
format". For use with CoAP, each new CoRAL dictionary MUST register format" of a representation. For use with CoAP, each new CoRAL
a new content format in the IANA CoAP Content-Formats Registry. dictionary therefore needs to have a new content format registered
with IANA in the CoAP Content-Formats Registry.
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 is not used; charset information is coral". The "charset" parameter of textual media types [RFC6657] is
transported inside the document in the form of an OPTIONAL Byte Order not used; instead, charset information is transported inside the
Mark (BOM). The use of the UTF-8 encoding scheme [RFC3629], without document in the form of an OPTIONAL Byte Order Mark (BOM). The use
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 five kinds of tokens: identifiers, IRIs, IRI grammar. There are three kinds of tokens: identifier tokens, literal
references, literals, and punctuators. tokens, and punctuator tokens.
token = identifier / iri / iriref / literal / punctuator token = identifier / IRIref / boolean / integer / float
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 page 16, line 9 skipping to change at line 711
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 rules for
identifiers correspond to those recommended by the Unicode Standard identifiers correspond to those recommended by the Unicode Standard
Annex #31 [UNICODE-UAX31] using the following profile: 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 = "-" / "." / "~" / %x58A / %xF0B MEDIAL = "-" / "." / "~" / %x58A / %xF0B
MEDIAL =/ %x2010 / %x2027 / %x30A0 / %x30FB MEDIAL =/ %x2010 / %x2027 / %x30A0 / %x30FB
All identifiers MUST be converted into Unicode Normalization Form C All identifiers MUST be converted into Unicode Normalization Form C
(NFC), as defined by the Unicode Standard Annex #15 [UNICODE-UAX15]. (NFC), which is defined in Unicode Standard Annex #15 [UAX15].
Comparison of identifiers is based on NFC and is case-sensitive Comparison of identifiers is based on NFC and case-sensitive (unless
(unless otherwise noted). otherwise noted).
4.1.5. IRIs and IRI References
IRIs and IRI references are Unicode strings that conform to the
syntax defined in RFC 3987 [RFC3987]. An IRI reference can be either
an IRI or a relative reference. Both IRIs and IRI references are
enclosed in angle brackets ("<" and ">").
iri = "<" IRI ">"
iriref = "<" IRI-reference ">" 4.1.5. Literals
IRI = <Defined in Section 2.2 of RFC 3987> A literal token is a textual representation of a value.
IRI-reference = <Defined in Section 2.2 of RFC 3987> 4.1.5.1. IRI Reference Literals
4.1.6. Literals IRI reference tokens denote references to resources on the Web.
A literal is a textual representation of a value. There are seven An IRI reference literal consists of a Unicode string that conforms
types of literals: Boolean, integer, floating-point, date/time, byte to the syntax defined in RFC 3987 [RFC3987]. An IRI reference is
string, text string, and null. either an IRI or a relative reference. IRI references are enclosed
in angle brackets ("<" and ">").
literal = boolean / integer / float / datetime / bytes / text IRIref = "<" IRI-reference ">"
literal =/ null IRI-reference = <Defined in Section 2.2 of RFC 3987>
4.1.6.1. 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.
boolean = "true" / "false" boolean = "true" / "false"
4.1.6.2. Integer Literals 4.1.5.3. Integer Literals
Integer literals denote an integer value of unspecified precision. Integer literal tokens denote an integer value of unspecified
By default, integer literals are expressed in decimal, but they can precision. By default, integer literals are expressed in decimal,
also be specified in an alternate base using a prefix: Binary but they can also be specified in an alternate base using a prefix:
literals begin with "0b", octal literals begin with "0o", and Binary literals begin with "0b", octal literals begin with "0o", and
hexadecimal literals begin with "0x". hexadecimal literals begin with "0x".
Decimal literals contain the digits "0" through "9". Binary literals Decimal literals contain the digits "0" through "9". Binary literals
contain "0" and "1", octal literals contain "0" through "7", and contain "0" and "1", octal literals contain "0" through "7", and
hexadecimal literals contain "0" through "9" as well as "A" through hexadecimal literals contain "0" through "9" as well as "A" through
"F" in upper- or lowercase. "F" in upper- or lowercase.
Negative integers are expressed by prepending a minus sign ("-"). Negative integers are expressed by prepending a minus sign ("-").
integer = ["+" / "-"] (decimal / binary / octal / hexadecimal) integer = ["+" / "-"] (decimal / binary / octal / hexadecimal)
skipping to change at page 17, line 45 skipping to change at line 785
hexadecimal = %x30 (%x58 / %x78) 1*HEXDIG hexadecimal = %x30 (%x58 / %x78) 1*HEXDIG
DIGIT = %x30-39 DIGIT = %x30-39
BINDIG = %x30-31 BINDIG = %x30-31
OCTDIG = %x30-37 OCTDIG = %x30-37
HEXDIG = %x30-39 / %x41-46 / %x61-66 HEXDIG = %x30-39 / %x41-46 / %x61-66
4.1.6.3. Floating-point Literals 4.1.5.4. Floating-point Literals
Floating-point literals denote a floating-point number of unspecified Floating-point literal tokens denote a floating-point number of
precision. unspecified precision.
Floating-point literals consist of a sequence of decimal digits Floating-point literals consist of a sequence of decimal digits
followed by a fraction, an exponent, or both. The fraction consists followed by a fraction, an exponent, or both. The fraction consists
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]
skipping to change at page 18, line 29 skipping to change at line 817
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"
float =/ ["+" / "-"] "Infinity" float =/ ["+" / "-"] "Infinity"
4.1.6.4. Date/Time Literals 4.1.5.5. Date/Time Literals
Date/time literals 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
date-time = <Defined in Section 5.6 of RFC 3339> date-time = <Defined in Section 5.6 of RFC 3339>
SQUOTE = %x27 SQUOTE = %x27
4.1.6.5. Byte String Literals 4.1.5.6. Byte String Literals
Byte string literals denote an ordered sequence of bytes. Byte string literal tokens denote an ordered sequence of bytes.
A byte string literal consists of a prefix and zero or more bytes A byte string literal consists of a prefix and zero or more bytes
encoded in Base16, Base32, or Base64 [RFC4648], enclosed in single encoded in Base16, Base32, or Base64 [RFC4648], enclosed in single
quotes. Byte string literals encoded in Base16 begin with "h" or quotes. Byte string literals encoded in Base16 begin with "h" or
"b16", byte string literals encoded in Base32 begin with "b32", and "b16", byte string literals encoded in Base32 begin with "b32", and
byte string literals encoded in Base64 begin with "b64". byte string literals encoded in Base64 begin with "b64".
bytes = base16 / base32 / base64 bytes = base16 / base32 / base64
base16 = (%x68 / %x62.31.36) SQUOTE <Base16 encoded data> SQUOTE base16 = (%x68 / %x62.31.36) SQUOTE <Base16 encoded data> SQUOTE
base32 = %x62.33.32 SQUOTE <Base32 encoded data> SQUOTE base32 = %x62.33.32 SQUOTE <Base32 encoded data> SQUOTE
base64 = %x62.36.34 SQUOTE <Base64 encoded data> SQUOTE base64 = %x62.36.34 SQUOTE <Base64 encoded data> SQUOTE
4.1.6.6. Text String Literals 4.1.5.7. Text String Literals
Text string literals 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 %x22, %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
simple-escape =/ %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
skipping to change at page 20, line 7 skipping to change at line 882
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 1.
+-----------------+------------+----------------------+ +-----------------+------------+----------------------+
| Escape Sequence | Code Point | Character Name | | Escape Sequence | Code Point | Character Name |
+-----------------+------------+----------------------+ +=================+============+======================+
| \0 | U+0000 | Null | | \0 | U+0000 | Null |
+-----------------+------------+----------------------+
| \b | U+0008 | Backspace | | \b | U+0008 | Backspace |
+-----------------+------------+----------------------+
| \t | U+0009 | Character Tabulation | | \t | U+0009 | Character Tabulation |
+-----------------+------------+----------------------+
| \n | U+000A | Line Feed | | \n | U+000A | Line Feed |
+-----------------+------------+----------------------+
| \v | U+000B | Line Tabulation | | \v | U+000B | Line 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 1: Simple Escape Sequences
4.1.6.7. 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.7. Punctuators 4.1.6. Punctuators
Punctuator tokens are used for grouping and separating. Punctuator tokens are used for grouping and separating.
punctuator = "#" / ":" / "*" / "[" / "]" / "{" / "}" / "=" / "->" punctuator = "#" / ":" / "=" / "@" / "[" / "]" / "{" / "}" / "->"
4.2. Syntactic Structure 4.2. Syntactic Structure
The syntactic structure of a document in the textual format is made The syntactic structure of a document in the textual format is made
up of four kinds of elements: links, forms, embedded representations, up of three kinds of elements: links, forms, and (as an extension to
and (as an extension to the CoRAL data model) directives. Directives the CoRAL data model) directives. Directives provide a way to make
provide a way to make documents easier to read and write by setting a documents easier to read and write by setting a base for relative IRI
base for relative IRI references and introducing shorthands for IRIs. references and introducing shorthands for IRIs.
Elements are processed in the order they appear in the document. 4.2.1. Documents
A document in the textual format consists of a sequence of zero or
more elements. An element is either a link, a form, or a directive.
document = *element
element = link / form / directive
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 list of elements. The environment consists of three variables: the a sequence of elements. The environment consists of three variables:
_current context_, the _current base_, and the _current mapping from the _current context_, the _current base_, and the _current mapping
identifiers to IRIs_. Both the current context and the current base from identifiers to IRIs_. Both the current context and the current
are initially set to the document's retrieval context. The current base are initially set to the document's retrieval context. The
mapping from identifiers to IRIs is initially empty. current mapping from identifiers to IRIs is initially empty.
4.2.1. Documents 4.2.2. Directives
The body of a document in the textual format consists of zero or more Directives provide the ability to manipulate the environment while
links, forms, embedded representations, and directives. processing elements.
document = body All directives start with a number sign ("#") followed by an
identifier. The identifier is case-insensitive and restricted to
Unicode characters in the Basic Latin block.
body = *(link / form / representation / directive) The following two types of directives are available: the Base
directive and the Using directive.
4.2.2. Links directive = base-directive / using-directive
A link consists of the link relation type, followed by the link 4.2.2.1. Base Directives
target, optionally followed by a link body enclosed in curly brackets
("{" and "}").
link = relation-type link-target ["{" body "}"] A Base directive consists of a number sign ("#"), followed by the
case-insensitive token "base", followed by a base IRI.
The link relation type is denoted by either an IRI, a simple name, or base-directive = "#" "base" baseIRI
a qualified name.
relation-type = iri / simple-name / qualified-name The base IRI is denoted by an IRI reference. The IRI reference MUST
be resolved against the current context (not the current base).
A simple name consists of an identifier. It is resolved to an IRI by baseIRI = IRIref
looking up the empty string in the current mapping from identifiers
to IRIs and appending the specified identifier to the result. It is The directive is processed by resolving the IRI reference against the
an error if the empty string is not present in the current mapping. current context and assigning the result to the current base.
4.2.2.2. Using Directives
A Using directive consists of a number sign ("#"), followed by the
case-insensitive token "using", optionally followed by an identifier
and an equals sign ("="), finally followed by an IRI. If the
identifier is not specified, it is assumed to be the empty string.
using-directive = "#" "using" [identifier "="] IRIref
The directive is processed by adding the specified identifier and IRI
to the current mapping from identifiers to IRIs. It is an error if
the identifier is already present in the mapping or if the IRI is not
an IRI but a relative reference.
4.2.3. IRIs
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
are three kinds of names: simple names, qualified names, and
predefined names.
IRI = IRIref / simple-name / qualified-name / predefined-name
Both IRI references and names are processed by resolving them to an
IRI, as described in the following sub-sections.
4.2.3.1. IRI References
An IRI reference is resolved to an IRI as specified in Section 6.5 of
RFC 3987 [RFC3987] using the current base.
4.2.3.2. Simple Names
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
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
present in the mapping.
4.2.3.3. Qualified Names
A qualified name consists of two identifiers separated by a colon A qualified name consists of two identifiers separated by a colon
(":"). It is resolved to an IRI by looking up the identifier on the (":").
left hand side in the current mapping from identifiers to IRIs and
appending the identifier on the right hand side to the result. It is
an error if the identifier on the left hand side is not present in
the current mapping.
qualified-name = identifier ":" identifier qualified-name = identifier ":" identifier
The link target is denoted by an IRI reference or represented by a A qualified name is resolved to an IRI by looking up the identifier
value literal. An IRI reference MUST be resolved against the current given on the left hand side in the current mapping from identifiers
base. If the link target is null, the link target is an unidentified to IRIs. The identifier given on the right hand side is appended to
resource. the result. It is an error if the identifier on the left hand side
is not present in the mapping.
link-target = iriref / literal 4.2.3.4. Predefined Names
The list of elements in the link body, if any, MUST be processed in a A predefined name consists of a commercial at sign ("@") followed by
fresh environment. Both the current context and current base in this an identifier. The identifier is case-insensitive and restricted to
Unicode characters in the Basic Latin block.
predefined-name = "@" 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
table.
+------------+--------------------------------------+
| Identifier | IRI |
+============+======================================+
| direction | <http://coreapps.org/base#direction> |
+------------+--------------------------------------+
| language | <http://coreapps.org/base#language> |
+------------+--------------------------------------+
Table 2: Predefined Names
4.2.4. Links
A link consists of the link relation type, followed by the link
target, optionally followed by a sequence of zero or more nested
elements enclosed in curly brackets ("{" and "}").
link = relation-type link-target ["{" *element "}"]
The link relation type is an IRI.
relation-type = IRI
The link target is either an IRI, a literal value, or null.
link-target = IRI / literal / null
literal = boolean / integer / float / datetime / bytes / text
The nested elements, if any, MUST be processed in a fresh
environment. Both the current context and current base in this
environment are initially set to the link target of the enclosing environment are initially set to the link target of the enclosing
link. The mapping from identifiers to IRIs is initially set to a link. The mapping from identifiers to IRIs is initially set to a
copy of the mapping from identifiers to IRIs in the current copy of the mapping from identifiers to IRIs in the current
environment. environment.
4.2.3. 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 list of form fields the submission target, optionally followed by a sequence of zero or
enclosed in square brackets ("[" and "]"). more form fields enclosed in square brackets ("[" and "]").
form = operation-type "->" submission-target ["[" form-fields "]"]
The operation type is defined in the same way as a link relation type
(Section 4.2.2).
operation-type = iri / simple-name / qualified-name
The request method is either implied by the operation type or encoded form = operation-type "->" submission-target ["[" *form-field "]"]
as a form field. If there are both, the form field takes precedence
over the operation type. Either way, the method MUST be defined for
the Web transfer protocol identified by the scheme of the submission
target.
The submission target is denoted by an IRI reference. This IRI The operation type is an IRI.
reference MUST be resolved against the current base.
submission-target = iriref operation-type = IRI
4.2.3.1. Form Fields The submission target is an IRI.
A list of form fields consists of zero or more type-value pairs. submission-target = IRI
form-fields = *(form-field-type form-field-value) 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
over the operation type. Either way, the method MUST be applicable
to the Web transfer protocol identified by the scheme of the
submission target.
The list, if any, MUST be processed in a fresh environment. Both the The form fields, if any, MUST be processed in a fresh environment.
current context and the current base in this environment are Both the current context and the current base in this environment are
initially set to the submission target of the enclosing form. The initially set to the submission target of the enclosing form. The
mapping from identifiers to IRIs is initially set to a copy of the mapping from identifiers to IRIs is initially set to a copy of the
mapping from identifiers to IRIs in the current environment. mapping from identifiers to IRIs in the current environment.
The form field type is defined in the same way as a link relation 4.2.6. Form Fields
type (Section 4.2.2).
form-field-type = iri / simple-name / qualified-name 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
elements enclosed in curly brackets ("{" and "}").
The form field value can be an IRI reference, Boolean literal, form-field = form-field-type form-field-value ["{" *element "}"]
integer literal, floating-point literal, byte string literal, text
string literal, or null. An IRI reference MUST be resolved against
the current base.
form-field-value = iriref / literal The form field type is an IRI.
4.2.4. Embedded Representations form-field-type = IRI
An embedded representation consists of a "*" token, followed by the The form field value is either an IRI, a literal value, or null.
representation data, optionally followed by representation metadata
enclosed in square brackets ("[" and "]").
representation = "*" bytes ["[" representation-metadata "]"] form-field-value = IRI / literal / null
Representation metadata consists of zero or more name-value pairs. The nested elements, if any, MUST be processed in a fresh
environment. Both the current context and current base in this
environment are initially set to the form field value of the
enclosing form field. The mapping from identifiers to IRIs is
initially set to a copy of the mapping from identifiers to IRIs in
the current environment.
representation-metadata = *(metadata-name metadata-value) 5. Document Semantics
The metadata, if any, MUST be processed in a fresh environment. All 5.1. Submitting Documents
variables in the new environment are initially set to a copy of the
variables in the current environment.
The metadata name is defined in the same way as a link relation type By default, a CoRAL document is a representation that captures the
(Section 4.2.2). current state of a resource. The meaning of a CoRAL document changes
when it is submitted in a request. Depending on the request method,
the CoRAL document can capture the intended state of a resource (PUT)
or be subject to application-specific processing (POST).
metadata-name = iri / simple-name / qualified-name 5.1.1. PUT Requests
The metadata value can be an IRI reference, Boolean literal, integer A PUT request with a CoRAL document enclosed in the request payload
literal, floating-point literal, byte string literal, text string requests that the state of the target resource be created or replaced
literal, or null. An IRI reference MUST be resolved against the with the state described by the CoRAL document. A successful PUT of
current base. a CoRAL document generally means that a subsequent GET on that same
target resource would result in an equivalent document being sent in
a success response.
metadata-value = iriref / literal An origin server SHOULD verify that a submitted CoRAL document is
consistent with any constraints the server has for the target
resource. When a document is inconsistent with the target resource,
the origin server SHOULD either make it consistent (e.g., by removing
inconsistent elements) or respond with an appropriate error message
containing sufficient information to explain why the document is
unsuitable.
4.2.5. Directives The retrieval context and the base URI of a CoRAL document in a PUT
are the request URI of the request.
Directives provide the ability to manipulate the environment when 5.1.2. POST Requests
processing a list of elements. All directives start with a number
sign ("#") followed by a directive identifier. Directive identifiers
are case-insensitive and constrained to Unicode characters in the
Basic Latin block.
The following two types of directives are available: the Base A POST request with a CoRAL document enclosed in the request payload
directive and the Using directive. requests that the target resource process the CoRAL document
according to the resource's own specific semantics.
directive = base-directive / using-directive 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.
The base URI of the document is the request URI of the request.
4.2.5.1. Base Directives 5.2. Returning Documents
A Base directive consists of a number sign ("#"), followed by the In a response, the meaning of a CoRAL document changes depending on
case-insensitive identifier "base", followed by a base. the request method and the response status code. For example, a
CoRAL document in a successful response to a GET represents the
current state of the target resource, whereas a CoRAL document in a
successful response to a POST might represent either the processing
result or the new resource state. A CoRAL document in an error
response represents the error condition, usually describing the error
state and what next steps are suggested for resolving it.
base-directive = "#" "base" base 5.2.1. Success Responses
The base is denoted by an IRI reference. The IRI reference MUST be Success responses have a response status code that indicates that the
resolved against the current context (not the current base). client's request was successfully received, understood, and accepted
(2xx in HTTP, 2.xx in CoAP). When the representation in a success
response does not describe the state of the target resource, it
describes result of processing the request. For example, when a
request has been fulfilled and has resulted in one or more new
resources being created, a CoRAL document in the response can link to
and describe the resource(s) created.
base = iriref The retrieval context and the base URI of a CoRAL document
representing the current state of a resource are the request URI of
the request.
The directive is processed by resolving the IRI reference against the The retrieval context of a CoRAL document representing a processing
current context and assigning the result to the current base. result is an unspecified URI that refers to the processing result
itself. The base URI of the document is the request URI of the
request.
4.2.5.2. Using Directives 5.2.2. Redirection Responses
A Using directive consists of a number sign ("#"), followed by the Redirection responses have a response status code that indicates that
case-insensitive identifier "using", optionally followed by an further action needs to be taken by the agent (3xx in HTTP). A
identifier and an equals sign ("="), finally followed by an IRI. If redirection response, for example, might indicate that the target
the identifier is not specified, it is assumed to be the empty resource is available at a different URI or the server offers a
string. choice of multiple matching resources, each with its own specific
URI.
using-directive = "#" "using" [identifier "="] iri In the latter case, the representation in the response might contain
a list of resource metadata and URI references (i.e., links) from
which the agent can choose the most preferred one.
The directive is processed by adding the specified identifier and IRI The retrieval context of a CoRAL document representing such multiple
to the current mapping from identifiers to IRIs. It is an error if choices in a redirection response is an unspecified URI that refers
the identifier is already present in the mapping. to the redirection itself. The base URI of the document is the
request URI of the request.
5. Usage Considerations 5.2.3. Error Responses
Error response have a response status code that indicates that either
the request cannot be fulfilled or the server failed to fulfill an
apparently valid request (4xx or 5xx in HTTP, 4.xx or 5.xx in CoAP).
A representation in an error response describes the error condition.
The retrieval context of a CoRAL document representing such an error
condition is an unspecified URI that refers to the error condition
itself. The base URI of the document is the request URI of the
request.
6. Usage Considerations
This section discusses some considerations in creating CoRAL-based This section discusses some considerations in creating CoRAL-based
applications and vocabularies. applications and vocabularies.
5.1. Specifying CoRAL-based Applications 6.1. Specifying CoRAL-based Applications
CoRAL-based applications naturally implement the Web architecture CoRAL-based applications naturally implement the Web architecture
[W3C.REC-webarch-20041215] and thus are centered around orthogonal [W3C.REC-webarch-20041215] and thus are centered around orthogonal
specifications for identification, interaction, and representation: specifications for identification, interaction, and representation:
o Resources are identified by IRIs or represented by value literals. * Resources are identified by IRIs or represented by literal values.
o Interactions are based on the hypermedia interaction model of the * Interactions are based on the hypermedia interaction model of the
Web and the methods provided by the Web transfer protocol. The Web and the methods provided by the Web transfer protocol. The
semantics of possible interactions are identified by link relation semantics of possible interactions are identified by link relation
types and operation types. types and operation types.
o Representations are CoRAL documents encoded in the binary format * Representations are CoRAL documents encoded in the binary format
defined in Section 3 or the textual format defined in Section 4. defined in Section 3 or the textual format defined in Section 4.
Depending on the application, additional representation formats Depending on the application, additional representation formats
may be used. may be used.
5.1.1. Application Interfaces 6.1.1. Application Interfaces
Specifications for CoRAL-based applications need to list the specific Specifications for CoRAL-based applications need to list the specific
components used in the application interface and their identifiers. components used in the application interface and their identifiers.
This should include the following items: This should include the following items:
o URI schemes that identify the Web transfer protocol(s) used in the * The Web transfer protocols supported.
application.
o Internet media types that identify the representation format(s)
used in the application, including the media type(s) of the CoRAL
serialization format(s).
o Link relation types that identify the semantics of links. * The representation formats used, identified by their Internet
media types, including the CoRAL serialization formats.
o Operation types that identify the semantics of forms. * The link relation types used.
Additionally, for each operation type, the permissible request
method(s).
o Form field types that identify the semantics of form fields. * The operation types used. Additionally, for each operation type,
Additionally, for each form field type, the permissible form field the permissible request methods.
values.
o Metadata names that identify the semantics of representation * The form field types used. Additionally, for each form field
metadata. Additionally, for each metadata name, the permissible type, the permissible form field values.
metadata values.
5.1.2. Resource Identifiers 6.1.2. Resource Identifiers
URIs [RFC3986] are a cornerstone of Web-based applications. They URIs [RFC3986] are a cornerstone of Web-based applications. They
enable the uniform identification of resources and are used every enable the uniform identification of resources and are used every
time a client interacts with a server or a resource representation time a client interacts with a server or a resource representation
needs to refer to another resource. needs to refer 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 many HTTP-based application programming is a common practice in HTTP-based application programming interfaces
interfaces (APIs) to make this part of the application specification, (APIs) to make this part of the application specification, i.e., to
i.e., to prescribe fixed URI templates that are hard-coded in prescribe fixed URI templates that are hard-coded in implementations.
implementations. There are a number of problems with this practice However, there are a number of problems with this practice
[RFC7320], though. [I-D.nottingham-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. BCP 190 [RFC7320] particular form of resource name structure.
describes the problematic practice of fixed URI structures in more
detail and provides some acceptable alternatives.
5.1.3. Implementation Limits BCP 190 [I-D.nottingham-rfc7320bis] describes the problematic
practice of fixed URI structures in more detail and provides some
acceptable alternatives.
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
wish to limit these numbers and specify implementation limits that an limit these numbers and give specific implementation limits that an
application implementation must at least support to be interoperable. application implementation must at least support to be interoperable.
Applications may also mandate the following and other restrictions: Applications may also mandate the following and other restrictions:
o use of only either the binary format or the text format; * Use of only either the binary format or the text format.
o use of only either HTTP or CoAP as supported Web transfer
protocol;
o use of only dictionary references in the binary format for certain
vocabulary;
o use of only either content type strings or content format IDs; * Use of only either HTTP or CoAP as the supported Web transfer
protocol.
o use of CoRI references only up to a specific length; * Use of only dictionary references in the binary format for certain
vocabulary.
o use of CBOR in a canonical format (see Section 3.9 of RFC 7049). * Use of URI references and CoRI references only up to a specific
length.
5.2. Minting Vocabulary 6.2. Minting Vocabulary
New link relation types, operation types, form field types, and New link relation types, operation types, and form field types can be
metadata names can be minted by defining an IRI [RFC3987] that minted by defining an IRI [RFC3987] that uniquely identifies the
uniquely identifies the item. Although the IRI can point to a item. Although the IRI can point to a resource that contains a
resource that contains a definition of the semantics, clients SHOULD definition of the semantics, clients SHOULD NOT automatically access
NOT automatically access that resource to avoid overburdening its that resource to avoid overburdening its server. The IRI SHOULD be
server. The IRI SHOULD be under the control of the person or party under the control of the person or party defining it, or be delegated
defining it, or be delegated to them. to 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 RFC 3987.
Non-normalized forms that are best avoided include: Non-normalized forms that are best avoided include:
o Uppercase characters in scheme names and domain names * Uppercase characters in scheme names and domain names
o 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
o 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/>)
o 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>)
o Dot segments ("/./" or "/../") in the path component of an IRI * Dot segments ("/./" or "/../") in the path component of an IRI
o 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")
o Punycode-encoding of Internationalized Domain Names in IRIs * Punycode-encoding of Internationalized Domain Names in IRIs
o IRIs that are not in Unicode Normalization Form C [UNICODE-UAX15] * IRIs that are not in Unicode Normalization Form C [UAX15]
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.
5.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 IANA Link Relations Registry,
such as "collection" [RFC6573] or "icon" [W3C.REC-html52-20171214], such as "collection" [RFC6573] or "icon" [W3C.REC-html52-20171214],
can be used in CoRAL by appending the registered name to the IRI can be used in CoRAL by appending the registered name to the IRI
<http://www.iana.org/assignments/relation/>: <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>
Note that registered link relation types are required to be The convention of appending the relation type name to the prefix
lowercased, as per Section 3.3 of RFC 8288 [RFC8288].
(The convention of appending the link relation types 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 Atom [RFC4287]; see also Appendix A.2 of RFC 8288 [RFC8288].
5.4. Expressing Simple RDF Statements Note that registered relation type names are required to be lowercase
ASCII letters (Section 3.3 of RFC 8288).
6.4. Expressing Simple RDF Statements
An RDF statement [W3C.REC-rdf11-concepts-20140225] says that some An RDF statement [W3C.REC-rdf11-concepts-20140225] 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 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>
} }
5.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 that are the target of a link can be associated with a
language tag [RFC5646] and a base text direction (i.e., right-to-left language tag [RFC5646] and a base text direction (i.e., right-to-left
or left-to-right) by nesting links of type <http://coreapps.org/ or left-to-right) by nesting links of type <http://coreapps.org/
base#language> and <http://coreapps.org/base#direction> under that base#language> and <http://coreapps.org/base#direction> under that
link, respectively: link, respectively:
#using <http://coreapps.org/base#> #using <http://coreapps.org/base#>
#using iana = <http://www.iana.org/assignments/relation/> #using iana = <http://www.iana.org/assignments/relation/>
skipping to change at page 29, line 5 skipping to change at line 1422
} }
title "Terms of use" { 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.
5.6. Embedding CoRAL in CBOR Data 6.6. Embedding Representations in CoRAL
Data items in the CoRAL binary format (Section 3) may be embedded in
other CBOR data [RFC7049] data. Specifications using CDDL [RFC8610]
SHOULD 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 retrieval context,
link context, and form context needs to be specified, respectively.
5.7. Submitting CoRAL Documents
By default, a CoRAL document is a representation that captures the
current state of a resource. The meaning of a CoRAL document changes
when it is submitted in a request. Depending on the request method,
the CoRAL document can capture the intended state of a resource (PUT)
or be subject to application-specific processing (POST).
5.7.1. PUT Requests
A PUT request with a CoRAL document enclosed in the request payload
requests that the state of the target resource be created or replaced
with the state described by the CoRAL document. A successful PUT of
a CoRAL document generally means that a subsequent GET on that same
target resource would result in an equivalent document being sent in
a success response.
An origin server SHOULD verify that a submitted CoRAL document is
consistent with any constraints the server has for the target
resource. When a document is inconsistent with the target resource,
the origin server SHOULD either make it consistent (e.g., by removing
inconsistent elements) or respond with an appropriate error message
containing sufficient information to explain why the document is
unsuitable.
The retrieval context and the base URI of a CoRAL document in a PUT
are the request URI of the request.
5.7.2. POST Requests When a document links to many Web resources and an agent needs a
representation of each of them, it can be inefficient to retrieve
each representations individually. To minimize round-trips,
documents can embed representations of resources.
A POST request with a CoRAL document enclosed in the request payload A representation can be embedded in a document by including a link of
requests that the target resource process the CoRAL document type <http://coreapps.org/base#representation>:
according to the resource's own specific semantics.
The retrieval context of a CoRAL document in a POST is an unspecified #using <http://coreapps.org/base#>
URI. The base URI of the document is the request URI of the request. #using http = <http://coreapps.org/http#>
#using iana = <http://www.iana.org/assignments/relation/>
5.8. Returning CoRAL Documents iana:icon </favicon.gif> {
representation
b64'R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAIAOw==' {
http:type "image/gif"
}
}
In a response, the meaning of a CoRAL document changes depending on An embedded representation should have a nested link of type
the request method and the response status code. For example, a <http://coreapps.org/http#type> or <http://coreapps.org/coap#type>
CoRAL document in a successful response to a GET represents the that indicates the content type of the representation.
current state of the target resource, whereas a CoRAL document in a
successful response to a POST might represent either the processing
result or the new resource state. A CoRAL document in an error
response represents the error condition, usually describing the error
state and what next steps are suggested for resolving it.
5.8.1. Success Responses The link relation types <http://coreapps.org/base#representation>,
<http://coreapps.org/http#type>, and <http://coreapps.org/coap#type>
are defined in Appendix A.
Success responses have a response status code that indicates that the 6.7. Embedding CoRAL in CBOR Representations
client's request was successfully received, understood, and accepted.
When the representation in a success response does not describe the
state of the target resource, it describes result of processing the
request.
For example, when a request has been fulfilled and has resulted in Data items in the CoRAL binary format (Section 3) may be embedded in
one or more new resources being created, a CoRAL document in the other CBOR structures [I-D.ietf-cbor-7049bis]. Specifications using
response can link to and describe the resource(s) created. CDDL [RFC8610] can reference the following CDDL definitions for this
purpose:
The retrieval context of a CoRAL document representing a processing CoRAL-Document = document
result is an unspecified URI that refers to the processing result
itself. The base URI of the document is the request URI of the
request.
5.8.2. Error Responses CoRAL-Link = link
Error response have a response status code that indicates that either CoRAL-Form = form
the request cannot be fulfilled or the server failed to fulfill an
apparently valid request. A representation in an error response
describes the error condition.
The retrieval context of such a CoRAL document representing an error For each embedded document, link, and form, the specification for the
condition is an unspecified URI that refers to the error condition embedding CBOR structure needs to specify the document retrieval
itself. The base URI of the document is the request URI of the context, the link context, and the form context, respectively.
request.
6. Security Considerations 7. Security Considerations
Parsers of CoRAL documents must operate on input that is assumed to CoRAL document processors need to be fully prepared for all types of
be untrusted. This means that parsers MUST fail gracefully in the hostile input that may be designed to corrupt, overrun, or achieve
face of malicious inputs (e.g., inputs not adhering to the data control of the agent processing the document. For example, hostile
structure). Additionally, parsers MUST be prepared to deal with input may be constructed to overrun buffers, allocate very big data
resource exhaustion (e.g., resulting from the allocation of big data structures, or exhaust the stack depth by setting up deeply nested
items) or exhaustion of the call stack (stack overflow). elements. Processors need to have appropriate resource management to
mitigate these attacks.
CoRAL serializations intentionally do not feature the equivalent of CoRAL serialization formats intentionally do not feature the
XML entity references as to preclude the whole class of attacks equivalent of XML entity references so as to preclude the entire
relating to these, such as exponential XML entity expansion ("billion class of attacks relating to them, such as exponential XML entity
laughs") [CAPEC-197] and malicious XML entity linking [CAPEC-201]. expansion ("billion laughs") [CAPEC-197] and malicious XML entity
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 processing CBOR with the restrictions described in aspects of decoding CBOR. See Section XX of RFC XXXX
Section 3. Notably, different number representations for the same [I-D.ietf-cbor-7049bis] for security considerations relating to CBOR.
numeric value are not equivalent in the CoRAL binary format. See In particular, different number encodings for the same numeric value
Section 8 of RFC 7049 [RFC7049] for security considerations relating are not equivalent in CoRAL (e.g., a floating-point value of 0.0 is
to CBOR. not the same as the 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 the Unicode Standard security aspects of handling Unicode input. See Unicode Technical
Annex #36 [UNICODE-UAX36] for security considerations relating to Report #36 [UTR36] for security considerations relating to visual
visual spoofing and misuse of character encodings. See Section 10 of spoofing and misuse of character encodings. See Section 10 of RFC
RFC 3629 [RFC3629] for security considerations relating to UTF-8. 3629 [RFC3629] for security considerations relating to UTF-8. See
Unicode Technical Standard #39 [UTS39] for security mechanisms that
can be 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 RFC 3986 [RFC3986] for security considerations relating to URIs. See
Section 8 of RFC 3987 [RFC3987] for security considerations relating Section 8 of RFC 3987 [RFC3987] for security considerations relating
to IRIs. See Section X of RFC XXXX [I-D.ietf-core-href] for security to IRIs. See Section XX of RFC XXXX [I-D.ietf-core-href] for
considerations relating to CoRIs. security considerations relating to CoRIs.
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 RFC 6943 [RFC6943] for security considerations
relating to identifiers in IRIs and other places. relating to 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 RFC 7230 [RFC7230],
Section 9 of RFC 7231 [RFC7231], etc., for security considerations Section 9 of RFC 7231 [RFC7231], etc., for security considerations
relating to HTTP. See Section 11 of RFC 7252 [RFC7252] for security relating to HTTP. See Section 11 of RFC 7252 [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
application layer or transport layer mechanisms for this, such as security mechanisms on the application layer or transport layer for
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 of 9 of unintentional disclosure of such information. See Section 9 of RFC
RFC 7231 [RFC7231] for additional considerations. 7231 [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. Notably, a server that is authoritative forms in CoRAL documents. See Section 5 of RFC 8288 [RFC8288] for
for the CoRAL representation of a resource may not necessarily be related considerations.
authoritative for nested elements in the document. See Section 5 of
RFC 8288 [RFC8288] for related considerations.
Unless an application mitigates this risk by specifying more specific In particular, when a CoRAL document is the representation of a
rules, any link or form in a document where the link or form context resource, the server that is authoritative for that resource may not
and the document's retrieval context don't share the same Web origin necessarily be authoritative for nested elements in the document. In
[RFC6454] MUST be discarded ("same-origin policy"). this case, unless an application defines specific rules, any link or
form where the link/form context and the document's retrieval context
do not share the same Web origin [RFC6454] should be discarded
("same-origin policy").
7. IANA Considerations 8. IANA Considerations
7.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 BCP 13 [RFC6838].
Type name: Type name:
application application
Subtype name: Subtype name:
coral+cbor coral+cbor
Required parameters: Required parameters:
N/A N/A
Optional parameters: Optional parameters:
dictionary - See Section 3.2 of [I-D.ietf-core-coral]. dictionary - See Section 3.2 of [I-D.ietf-core-coral].
Encoding considerations: Encoding considerations:
binary - See Section 3 of [I-D.ietf-core-coral]. binary - See Section 3 of [I-D.ietf-core-coral].
Security considerations: Security considerations:
See Section 6 of [I-D.ietf-core-coral]. See Section 7 of [I-D.ietf-core-coral].
Interoperability considerations: Interoperability considerations:
N/A N/A
Published specification: Published specification:
[I-D.ietf-core-coral] [I-D.ietf-core-coral]
Applications that use this media type: Applications that use this media type:
See Section 1 of [I-D.ietf-core-coral]. See Section 1 of [I-D.ietf-core-coral].
skipping to change at page 33, line 35 skipping to change at line 1608
Author: Author:
See the Author's Address section of [I-D.ietf-core-coral]. See the Author's Address section of [I-D.ietf-core-coral].
Change controller: Change controller:
IESG IESG
Provisional registration? Provisional registration?
No No
7.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 in RFC 6657 [RFC6657]. procedures of BCP 13 [RFC6838] and guidelines of RFC 6657 [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 page 34, line 4 skipping to change at line 1626
Subtype name: Subtype name:
coral coral
Required parameters: Required parameters:
N/A N/A
Optional parameters: Optional parameters:
N/A N/A
Encoding considerations: Encoding considerations:
binary - See Section 4 of [I-D.ietf-core-coral]. binary - See Section 4 of [I-D.ietf-core-coral].
Security considerations: Security considerations:
See Section 6 of [I-D.ietf-core-coral]. See Section 7 of [I-D.ietf-core-coral].
Interoperability considerations: Interoperability considerations:
N/A N/A
Published specification: Published specification:
[I-D.ietf-core-coral] [I-D.ietf-core-coral]
Applications that use this media type: Applications that use this media type:
See Section 1 of [I-D.ietf-core-coral]. See Section 1 of [I-D.ietf-core-coral].
skipping to change at page 34, line 46 skipping to change at line 1670
Author: Author:
See the Author's Address section of [I-D.ietf-core-coral]. See the Author's Address section of [I-D.ietf-core-coral].
Change controller: Change controller:
IESG IESG
Provisional registration? Provisional registration?
No No
7.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 RFC 7252 [RFC7252].
o 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]
o 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" in this document with the code points assigned by IANA.]] "TBD4" in this document with the code points assigned by IANA.]]
[[NOTE TO IMPLEMENTERS: Experimental implementations can use content [[NOTE TO IMPLEMENTERS: Experimental implementations can 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.]]
7.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 7049 [RFC7049]. according to the procedures of RFC XXXX [I-D.ietf-cbor-7049bis].
o 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 document with the code point assigned by IANA.]] this document with the code point assigned by IANA.]]
8. References 9. References
8.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", draft- Hartke, K., "Constrained Resource Identifiers", Work in
ietf-core-href-01 (work in progress), November 2019. Progress, Internet-Draft, draft-ietf-core-href-02, 8
January 2020,
<https://tools.ietf.org/html/draft-ietf-core-href-02>.
[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 page 36, line 45 skipping to change at line 1771
[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>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <https://www.rfc-editor.org/info/rfc7049>.
[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>.
[UNICODE] The Unicode Consortium, "The Unicode Standard", [UAX15] The Unicode Consortium, "Unicode Standard Annex #15:
<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.
[UNICODE-UAX15]
The Unicode Consortium, "Unicode Standard Annex #15:
Unicode Normalization Forms", Unicode Normalization Forms",
<http://unicode.org/reports/tr15/>. <http://unicode.org/reports/tr15/>.
[UNICODE-UAX31] [UAX31] The Unicode Consortium, "Unicode Standard Annex #31:
The Unicode Consortium, "Unicode Standard Annex #31:
Unicode Identifier and Pattern Syntax", Unicode Identifier and Pattern Syntax",
<http://unicode.org/reports/tr31/>. <http://unicode.org/reports/tr31/>.
[UNICODE-UAX36] [UNICODE] The Unicode Consortium, "The Unicode Standard",
The Unicode Consortium, "Unicode Standard Annex #36: <http://www.unicode.org/versions/latest/>. Note that this
Unicode Security Considerations", reference is to the latest version of Unicode, rather than
<http://unicode.org/reports/tr36/>. to a specific release. It is not expected that future
changes in the Unicode specification will have any impact
on this document.
8.2. Informative References 9.2. Informative References
[CAPEC-197] [CAPEC-197]
MITRE, "CAPEC-197: XML Entity Expansion", September 2019, MITRE, "CAPEC-197: XML Entity Expansion", 30 September
<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", 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>.
[FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification
0.99", 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", draft- [HAL] Kelly, M., "JSON Hypertext Application Language", Work in
kelly-json-hal-08 (work in progress), May 2016. Progress, Internet-Draft, draft-kelly-json-hal-08, 12 May
2016,
<https://tools.ietf.org/html/draft-kelly-json-hal-08>.
[I-D.nottingham-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>.
[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 page 38, line 45 skipping to change at line 1861
[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>.
[RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190,
RFC 7320, DOI 10.17487/RFC7320, July 2014,
<https://www.rfc-editor.org/info/rfc7320>.
[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>.
[UTR36] The Unicode Consortium, "Unicode Technical Report #36:
Unicode Security Considerations",
<http://unicode.org/reports/tr36/>.
[UTS39] The Unicode Consortium, "Unicode Technical Standard #39:
Unicode Security Mechanisms",
<http://unicode.org/reports/tr39/>.
[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, 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, Consortium Recommendation REC-rdf-schema-20140225, 25
February 2014, February 2014,
<http://www.w3.org/TR/2014/REC-rdf-schema-20140225>. <http://www.w3.org/TR/2014/REC-rdf-schema-20140225>.
[W3C.REC-rdf11-concepts-20140225] [W3C.REC-rdf11-concepts-20140225]
Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1
Concepts and Abstract Syntax", World Wide Web Consortium Concepts and Abstract Syntax", World Wide Web Consortium
Recommendation REC-rdf11-concepts-20140225, February 2014, Recommendation REC-rdf11-concepts-20140225, 25 February
2014,
<http://www.w3.org/TR/2014/REC-rdf11-concepts-20140225>. <http://www.w3.org/TR/2014/REC-rdf11-concepts-20140225>.
[W3C.REC-turtle-20140225] [W3C.REC-turtle-20140225]
Prud&#039;hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", Prud&#039;hommeaux, E. and G. Carothers, "RDF 1.1 Turtle",
World Wide Web Consortium Recommendation REC-turtle- World Wide Web Consortium Recommendation REC-turtle-
20140225, February 2014, 20140225, 25 February 2014,
<http://www.w3.org/TR/2014/REC-turtle-20140225>. <http://www.w3.org/TR/2014/REC-turtle-20140225>.
[W3C.REC-webarch-20041215] [W3C.REC-webarch-20041215]
Jacobs, I. and N. Walsh, "Architecture of the World Wide Jacobs, I. and N. Walsh, "Architecture of the World Wide
Web, Volume One", World Wide Web Consortium Web, Volume One", World Wide Web Consortium
Recommendation REC-webarch-20041215, December 2004, Recommendation REC-webarch-20041215, 15 December 2004,
<http://www.w3.org/TR/2004/REC-webarch-20041215>. <http://www.w3.org/TR/2004/REC-webarch-20041215>.
Appendix A. Core Vocabulary Appendix A. Core Vocabulary
This section defines the core vocabulary for CoRAL: a set of link This section defines the core vocabulary for CoRAL: a set of link
relation types, operation types, form field types, and metadata relation types, operation types, and form field types.
names.
A.1. Base A.1. Base
Link Relation Types: Link Relation Types:
<http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>
Indicates that the link's context is an instance of the class Indicates that the link's context is an instance of the class
specified as the link's target, as defined by RDF Schema specified as the link's target, as defined by RDF Schema
[W3C.REC-rdf-schema-20140225]. [W3C.REC-rdf-schema-20140225].
skipping to change at page 40, line 38 skipping to change at line 1951
Section 2.1 of RFC 5646 [RFC5646]. Section 2.1 of RFC 5646 [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>
Indicates that the link target is a representation of the link
context.
The link target MUST be a byte string.
The representation may be a full, partial, or inconsistent version
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 document or as a nested element within a link. When it occurs
as a top-level element, it provides an alternate representation of
the document's retrieval context. When it occurs nested within a
link, it provides a representation of 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
the PATCH method [RFC5789] [RFC8132] for HTTP and CoAP and the the PATCH method [RFC5789] [RFC8132] for HTTP and CoAP and the
skipping to change at page 42, line 20 skipping to change at line 2044
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 RFC 7231 [RFC7231]. The possible set of
media types and their parameters are maintained in the IANA Media media types and their parameters are maintained in the IANA Media
Types Registry. Types Registry.
Representation Metadata: Link Relation Types:
<http://coreapps.org/http#type> <http://coreapps.org/http#type>
Specifies the HTTP content type of the representation. Specifies the HTTP content type of the link context.
The metadata value MUST be specified as a text string in the The link target MUST be a text string in the format defined in
format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]. The Section 3.1.1.1 of RFC 7231 [RFC7231]. The possible set of media
possible set of media types and their parameters are maintained in types and their parameters are maintained in the IANA Media Types
the IANA Media Types Registry. Registry.
Metadata of this type MUST NOT occur more than once for a A link of this type MUST NOT occur more than once for the link
representation. If absent, its value defaults to content type context. If absent, its value defaults to the content type
"application/octet-stream". "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 one of the
skipping to change at page 43, line 11 skipping to change at line 2084
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 one of the
content formats maintained in the IANA CoAP Content-Formats content formats maintained in the IANA CoAP Content-Formats
Registry. Registry.
Representation Metadata: Link Relation Types:
<http://coreapps.org/coap#type> <http://coreapps.org/coap#type>
Specifies the CoAP content format of the representation. Specifies the CoAP content format of the link context.
The metadata value MUST be an integer identifying one of the The link target MUST be an integer identifying one of the content
content formats maintained in the IANA CoAP Content-Formats formats maintained in the IANA CoAP Content-Formats Registry.
Registry.
Metadata of this type MUST NOT occur more than once for a A link of this type MUST NOT occur more than once for the link
representation. If absent, it defaults to content format 42 context. If absent, it defaults to content format 42 (i.e., the
(i.e., content type "application/octet-stream" without a content content type "application/octet-stream" without a content coding).
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 |
+-----+-------------------------------------------------------+ +=====+=======================================================+
| 0 | <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> | | 0 | <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> |
+-----+-------------------------------------------------------+
| 1 | <http://www.iana.org/assignments/relation/item> | | 1 | <http://www.iana.org/assignments/relation/item> |
+-----+-------------------------------------------------------+
| 2 | <http://www.iana.org/assignments/relation/collection> | | 2 | <http://www.iana.org/assignments/relation/collection> |
+-----+-------------------------------------------------------+
| 3 | <http://coreapps.org/collections#create> | | 3 | <http://coreapps.org/collections#create> |
+-----+-------------------------------------------------------+
| 4 | <http://coreapps.org/base#update> | | 4 | <http://coreapps.org/base#update> |
+-----+-------------------------------------------------------+
| 5 | <http://coreapps.org/collections#delete> | | 5 | <http://coreapps.org/collections#delete> |
+-----+-------------------------------------------------------+
| 6 | <http://coreapps.org/base#search> | | 6 | <http://coreapps.org/base#search> |
+-----+-------------------------------------------------------+
| 7 | <http://coreapps.org/coap#accept> | | 7 | <http://coreapps.org/coap#accept> |
+-----+-------------------------------------------------------+
| 8 | <http://coreapps.org/coap#type> | | 8 | <http://coreapps.org/coap#type> |
+-----+-------------------------------------------------------+
| 9 | <http://coreapps.org/base#language> | | 9 | <http://coreapps.org/base#language> |
+-----+-------------------------------------------------------+
| 10 | <http://coreapps.org/coap#method> | | 10 | <http://coreapps.org/coap#method> |
+-----+-------------------------------------------------------+
| 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> |
+-----+-------------------------------------------------------+
Table 2: Default Dictionary Table 3: Default Dictionary
Acknowledgements Appendix C. Change Log
CoRAL is heavily inspired by Mike Kelly's JSON Hypertext Application This section is to be removed before publishing as an RFC.
Language [HAL].
This document has benefited greatly from discussions and reviews of Changes from -01 to -02:
the CoRAL design team:
Christian Amsuess * Added nested elements to form fields.
<christian@amsuess.com>
Carsten Bormann, Universitaet Bremen * Replaced the special construct for embedded representations with
<cabo@tzi.org> links.
Michael Koster, SmartThings * Changed the textual format to allow simple/qualified names
<michael.koster@smartthings.com> wherever IRI references are allowed.
Jim Schaad, August Cellars * Introduced predefined names in the textual format (#39).
<ietf@augustcellars.com>
Thanks to Thomas Fossati, Jaime Jimenez, Sebastian Kaebisch, Ari * Minor editorial improvements and bug fixes.
Keranen, Matthias Kovatsch, and Niklas Widell for helpful comments
and discussions that have shaped the document. Changes from -00 to -01:
* Added a section on the semantics of CoRAL documents in responses.
* Minor editorial improvements.
Acknowledgements
CoRAL is heavily inspired by Mike Kelly's JSON Hypertext Application
Language [HAL].
The recommendations for minting IRIs have been adopted from RDF 1.1
Concepts and Abstract Syntax [W3C.REC-rdf11-concepts-20140225] to
ease the interoperability between RDF predicates and link relation
types.
Thanks to Christian Amsuess, Carsten Bormann, Thomas Fossati, Jaime
Jimenez, Jim Schaad, Sebastian Kaebisch, Ari Keranen, Michael Koster,
Matthias Kovatsch, and Niklas Widell for helpful comments and
discussions that have shaped the document.
Author's Address Author's Address
Klaus Hartke Klaus Hartke
Ericsson Ericsson
Torshamnsgatan 23 Torshamnsgatan 23
Stockholm SE-16483 SE-16483 Stockholm
Sweden Sweden
Email: klaus.hartke@ericsson.com Email: klaus.hartke@ericsson.com
 End of changes. 329 change blocks. 
831 lines changed or deleted 950 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/