< draft-hartke-t2trg-coral-08.txt   draft-hartke-t2trg-coral-09.txt >
Thing-to-Thing Research Group K. Hartke Thing-to-Thing Research Group K. Hartke
Internet-Draft Ericsson Internet-Draft Ericsson
Intended status: Experimental March 11, 2019 Intended status: Experimental July 8, 2019
Expires: September 12, 2019 Expires: January 9, 2020
The Constrained RESTful Application Language (CoRAL) The Constrained RESTful Application Language (CoRAL)
draft-hartke-t2trg-coral-08 draft-hartke-t2trg-coral-09
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. as well as simple resource metadata.
Status of This Memo Status of This Memo
skipping to change at page 1, line 34 skipping to change at page 1, line 34
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 September 12, 2019. This Internet-Draft will expire on January 9, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 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/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are 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 . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Data and Interaction Model . . . . . . . . . . . . . . . . . 4
3. Data and Interaction Model . . . . . . . . . . . . . . . . . 4 2.1. Browsing Context . . . . . . . . . . . . . . . . . . . . 4
3.1. Browsing Context . . . . . . . . . . . . . . . . . . . . 5 2.2. Documents . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2. Documents . . . . . . . . . . . . . . . . . . . . . . . . 5 2.3. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.3. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.4. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.4. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.4.1. Form Fields . . . . . . . . . . . . . . . . . . . . . 7
3.5. Form Fields . . . . . . . . . . . . . . . . . . . . . . . 7 2.5. Embedded Representations . . . . . . . . . . . . . . . . 7
3.6. Embedded Representations . . . . . . . . . . . . . . . . 7 2.6. Navigation . . . . . . . . . . . . . . . . . . . . . . . 7
3.7. Navigation . . . . . . . . . . . . . . . . . . . . . . . 7 2.7. History Traversal . . . . . . . . . . . . . . . . . . . . 9
3.8. History Traversal . . . . . . . . . . . . . . . . . . . . 9 3. Binary Format . . . . . . . . . . . . . . . . . . . . . . . . 9
4. Binary Format . . . . . . . . . . . . . . . . . . . . . . . . 9 3.1. Data Structure . . . . . . . . . . . . . . . . . . . . . 10
4.1. Data Structure . . . . . . . . . . . . . . . . . . . . . 10 3.1.1. Documents . . . . . . . . . . . . . . . . . . . . . . 10
4.1.1. Documents . . . . . . . . . . . . . . . . . . . . . . 10 3.1.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 10
4.1.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 10 3.1.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 11 3.1.4. Embedded Representations . . . . . . . . . . . . . . 12
4.1.4. Embedded Representations . . . . . . . . . . . . . . 12 3.1.5. Directives . . . . . . . . . . . . . . . . . . . . . 13
4.1.5. Directives . . . . . . . . . . . . . . . . . . . . . 13 3.2. Dictionaries . . . . . . . . . . . . . . . . . . . . . . 13
4.2. Dictionaries . . . . . . . . . . . . . . . . . . . . . . 13 3.2.1. Dictionary References . . . . . . . . . . . . . . . . 13
4.2.1. Dictionary References . . . . . . . . . . . . . . . . 13 3.2.2. Media Type Parameter . . . . . . . . . . . . . . . . 14
4.2.2. Media Type Parameter . . . . . . . . . . . . . . . . 14 4. Textual Format . . . . . . . . . . . . . . . . . . . . . . . 14
5. Textual Format . . . . . . . . . . . . . . . . . . . . . . . 14 4.1. Lexical Structure . . . . . . . . . . . . . . . . . . . . 15
5.1. Lexical Structure . . . . . . . . . . . . . . . . . . . . 15 4.1.1. Line Terminators . . . . . . . . . . . . . . . . . . 15
5.1.1. Line Terminators . . . . . . . . . . . . . . . . . . 15 4.1.2. White Space . . . . . . . . . . . . . . . . . . . . . 15
5.1.2. White Space . . . . . . . . . . . . . . . . . . . . . 15 4.1.3. Comments . . . . . . . . . . . . . . . . . . . . . . 15
5.1.3. Comments . . . . . . . . . . . . . . . . . . . . . . 15 4.1.4. Identifiers . . . . . . . . . . . . . . . . . . . . . 15
5.1.4. Identifiers . . . . . . . . . . . . . . . . . . . . . 16 4.1.5. IRIs and IRI References . . . . . . . . . . . . . . . 16
5.1.5. IRIs and IRI References . . . . . . . . . . . . . . . 16 4.1.6. Literals . . . . . . . . . . . . . . . . . . . . . . 16
5.1.6. Literals . . . . . . . . . . . . . . . . . . . . . . 16 4.1.7. Punctuators . . . . . . . . . . . . . . . . . . . . . 20
5.1.7. Punctuators . . . . . . . . . . . . . . . . . . . . . 20 4.2. Syntactic Structure . . . . . . . . . . . . . . . . . . . 20
5.2. Syntactic Structure . . . . . . . . . . . . . . . . . . . 20 4.2.1. Documents . . . . . . . . . . . . . . . . . . . . . . 20
5.2.1. Documents . . . . . . . . . . . . . . . . . . . . . . 21 4.2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 20
5.2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 21 4.2.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 22 4.2.4. Embedded Representations . . . . . . . . . . . . . . 22
5.2.4. Embedded Representations . . . . . . . . . . . . . . 23 4.2.5. Directives . . . . . . . . . . . . . . . . . . . . . 23
5.2.5. Directives . . . . . . . . . . . . . . . . . . . . . 23 5. Usage Considerations . . . . . . . . . . . . . . . . . . . . 24
6. Usage Considerations . . . . . . . . . . . . . . . . . . . . 24 5.1. Specifying CoRAL-based Applications . . . . . . . . . . . 24
6.1. Specifying CoRAL-based Applications . . . . . . . . . . . 24 5.1.1. Application Interfaces . . . . . . . . . . . . . . . 24
6.1.1. Application Interfaces . . . . . . . . . . . . . . . 25 5.1.2. Resource Names . . . . . . . . . . . . . . . . . . . 25
6.1.2. Resource Names . . . . . . . . . . . . . . . . . . . 25 5.1.3. Implementation Limits . . . . . . . . . . . . . . . . 25
6.1.3. Implementation Limits . . . . . . . . . . . . . . . . 26 5.2. Minting Vocabulary . . . . . . . . . . . . . . . . . . . 26
6.2. Minting Vocabulary . . . . . . . . . . . . . . . . . . . 26 5.3. Expressing Registered Link Relation Types . . . . . . . . 27
6.3. Expressing Registered Link Relation Types . . . . . . . . 27 5.4. Expressing Simple RDF Statements . . . . . . . . . . . . 27
6.4. Expressing Link Target Attributes . . . . . . . . . . . . 28 5.5. Expressing Language-Tagged Strings . . . . . . . . . . . 27
6.5. Expressing Simple RDF Statements . . . . . . . . . . . . 29 5.6. Embedding CoRAL in CBOR Data . . . . . . . . . . . . . . 28
6.6. Embedding CoRAL in CBOR Structures . . . . . . . . . . . 29 5.7. Submitting CoRAL Documents . . . . . . . . . . . . . . . 28
6.7. Submitting CoRAL Documents . . . . . . . . . . . . . . . 30 5.7.1. PUT Requests . . . . . . . . . . . . . . . . . . . . 28
6.7.1. PUT Requests . . . . . . . . . . . . . . . . . . . . 30 5.7.2. POST Requests . . . . . . . . . . . . . . . . . . . . 29
6.7.2. POST Requests . . . . . . . . . . . . . . . . . . . . 30 6. Security Considerations . . . . . . . . . . . . . . . . . . . 29
7. Security Considerations . . . . . . . . . . . . . . . . . . . 30 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 7.1. Media Type "application/coral+cbor" . . . . . . . . . . . 30
8.1. Media Type "application/coral+cbor" . . . . . . . . . . . 32 7.2. Media Type "text/coral" . . . . . . . . . . . . . . . . . 32
8.2. Media Type "text/coral" . . . . . . . . . . . . . . . . . 33 7.3. CoAP Content Formats . . . . . . . . . . . . . . . . . . 33
8.3. CoAP Content Formats . . . . . . . . . . . . . . . . . . 34 7.4. CBOR Tag . . . . . . . . . . . . . . . . . . . . . . . . 33
8.4. CBOR Tag . . . . . . . . . . . . . . . . . . . . . . . . 35 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 34
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 8.1. Normative References . . . . . . . . . . . . . . . . . . 34
9.1. Normative References . . . . . . . . . . . . . . . . . . 35 8.2. Informative References . . . . . . . . . . . . . . . . . 36
9.2. Informative References . . . . . . . . . . . . . . . . . 37 Appendix A. Core Vocabulary . . . . . . . . . . . . . . . . . . 38
Appendix A. Core Vocabulary . . . . . . . . . . . . . . . . . . 39 A.1. Base . . . . . . . . . . . . . . . . . . . . . . . . . . 38
A.1. Link Relation Types . . . . . . . . . . . . . . . . . . . 39 A.2. Collections . . . . . . . . . . . . . . . . . . . . . . . 39
A.2. Operation Types . . . . . . . . . . . . . . . . . . . . . 40 A.3. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . 39
A.3. Form Field Types . . . . . . . . . . . . . . . . . . . . 40 A.4. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 40
A.4. Representation Metadata . . . . . . . . . . . . . . . . . 40
Appendix B. Default Dictionary . . . . . . . . . . . . . . . . . 41 Appendix B. Default Dictionary . . . . . . . . . . . . . . . . . 41
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 41 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 41
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 41 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 42
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"), as well
as simple resource metadata. as 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
skipping to change at page 4, line 39 skipping to change at page 4, line 38
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.
2. Examples 2. Data and Interaction Model
[[NOTE TO READERS: Examples and test vectors will be provided on a
companion website.]]
3. Data and Interaction Model
The Constrained RESTful Application Language (CoRAL) is designed for The Constrained RESTful Application Language (CoRAL) is designed for
building Web-based applications [W3C.REC-webarch-20041215] in which building Web-based applications [W3C.REC-webarch-20041215] in which
automated software agents navigate between resources by following automated software agents navigate between resources by following
links and perform operations on resources by submitting forms. links and perform operations on resources by submitting forms.
3.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 5, 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 each browsing context is
designated the _active_ representation. designated the _active_ representation.
3.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 Internationalized Resource is called a CoRAL _document_. The Internationalized Resource
Identifier (IRI) [RFC3987] that was used to retrieve such a document Identifier (IRI) [RFC3987] that was used to retrieve such a document
is called the document's _retrieval context_. 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, forms, and
embedded resource representations, collectively called _elements_. embedded resource representations, collectively called _elements_.
CoRAL serialization formats may define additional types of elements CoRAL serialization formats may define additional types of elements
for efficiency or convenience, such as a base for relative IRI for efficiency or convenience, such as a base for relative IRI
references [RFC3987]. references [RFC3987].
3.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 defined in RFC 8288, it consists of a _link context_,
a _link relation type_, and a _link target_. In CoRAL, a link can a _link relation type_, and a _link target_. In CoRAL, a link can
additionally have a nested list of zero or more elements, which take additionally have a nested list of zero or more elements, which take
the place of link target attributes. the place of link target attributes.
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} has a
{link relation type} resource at {link target}" where the link target {link relation type} resource at {link target}" where the link target
may be further described by nested elements. 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. In HTML 5
and RFC 8288, link relation types are typically denoted by an IANA- and RFC 8288, link relation types are typically denoted by an IANA-
registered name, such as "stylesheet" or "type". In CoRAL, they are registered name, such as "stylesheet" or "type". In CoRAL, they are
denoted by an IRI such as <http://www.iana.org/assignments/relation/ denoted by an IRI such as <http://www.iana.org/assignments/relation/
stylesheet> or <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>. stylesheet> or <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>.
This allows for the creation of new link relation types without the This allows for the creation of new link relation types without the
risk of collisions when from different organizations or domains of risk of collisions when from different organizations or domains of
knowledge. An IRI also can lead to documentation, schema, and other knowledge. An IRI also can lead to documentation, schema, and other
information about the link relation type. These IRIs are primarily information about the link relation type. These IRIs are only used
used as identity tokens, though, and are compared using Simple String as identity tokens, though, and are compared using Simple String
Comparison (Section 5.1 of RFC 3987). Comparison (Section 5.1 of RFC 3987).
The link context and the link target are both either by an IRI or The link context and the link target are both either by an IRI or
(similarly to RDF) a literal. If the IRI scheme indicates a Web (similarly to RDF) a literal. If the IRI scheme indicates a Web
transfer protocol such as HTTP or CoAP, then an agent can dereference transfer protocol such as HTTP or CoAP, then an agent can dereference
the IRI and navigate the browsing context to the referenced resource; the IRI and navigate the browsing context to the referenced resource;
this is called _following the link_. A literal directly identifies a this is called _following the link_. A literal directly identifies a
value. This can be a Boolean value, an integer, a floating-point value. This can be a Boolean value, an integer, a floating-point
number, a date/time value, a byte string, or a text string. number, a date/time value, a byte string, or a text string.
skipping to change at page 6, line 26 skipping to change at page 6, line 18
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 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.
3.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. It consists of 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 _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 method}
request to {submission target}" where the payload of the request may request to {submission target}" where the request may be further
be further described by form fields. 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.
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 request method and submission target as request with the specified method and the specified submission target
the request IRI. The submission target typically is the same as the request IRI. Usually, the submission target is the same
resource as the form context, but 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_.
If a form is accompanied by a list of form fields, as described in Form fields, specified in the next section, can be used to provide
the following section, then the agent also needs to construct a more detailed instructions to the agent for constructing the request.
payload that matches the specifications of the form fields and For example, form fields can instruct the agent to include a payload
include that in the request. 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 link
target of the enclosing link. target of the enclosing link.
3.5. Form Fields 2.4.1. Form Fields
Form fields provide further instructions to agents for constructing a Form fields provide further instructions to agents for constructing a
request payload. request.
A form field can directly identify one or more data items that need For example, a form field could identify one or more data items that
to be included in the request payload or can reference another need to be included in the request payload or reference another
resource (such as a schema) that describes the structure of the resource (such as a schema) that describes the structure of the
payload. Form fields can also provide other kinds of information, payload. A form field could also provide other kinds of information,
such as acceptable media types for the payload. such as acceptable media types for the payload or expected request
headers. Form fields may be specific to the protocol used for
submitting the form.
A form field is a pair of a _form field type_ and a _form field A form field is the pair of a _form field type_ and a _form field
value_. The form field type identifies the semantics of the form value_.
field. Form field types are denoted like link relation types and
operation types by an IRI. The form field value can be either an
IRI, a Boolean value, an integer, a floating-point number, a date/
time value, a byte string, or a text string.
3.6. Embedded Representations The form field type identifies the semantics of the form field. Form
field types are denoted like link relation types and operation types
by an IRI.
The form field value can be either an IRI, a Boolean value, an
integer, a floating-point number, a date/time value, a byte string,
or a text string.
2.5. Embedded Representations
When a document contains links to many resources and an agent needs a When a document contains links to many resources and an agent needs a
representation of each link target, it may be inefficient to retrieve representation of each link target, it may be inefficient to retrieve
each of these representations individually. To alleviate this, each of these representations individually. To alleviate this,
documents can directly embed representations of resources. documents can directly embed representations of resources.
An _embedded representation_ consists of a sequence of bytes, labeled An _embedded representation_ consists of a sequence of bytes, labeled
with _representation metadata_. with _representation metadata_.
An embedded representation may be a full, partial, or inconsistent An embedded representation may be a full, partial, or inconsistent
version of the representation served from the IRI of the resource. version of the representation served from the IRI of the resource.
An embedded representation can occur as a top-level element in a An embedded representation can occur as a top-level element in a
document or as a nested element within a link. When it occurs as a document or as a nested element within a link. When it occurs as a
top-level element, it provides an alternate representation of the top-level element, it provides an alternate representation of the
document's retrieval context. When it occurs nested within a link, document's retrieval context. When it occurs nested within a link,
it provides a representation of link target of the enclosing link. it provides a representation of link target of the enclosing link.
3.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 IRI_. The entry point IRI is the only IRI request on an _entry point IRI_. The entry point IRI is the only IRI
an agent is expected to know before interacting with an application. an agent is expected to know before interacting with an application.
From there, the agent is expected to make all requests by following From there, the agent is expected to make all requests by following
links and submitting forms provided by the server in responses. The links and submitting forms provided by the server in responses. The
entry point IRI can be obtained by manual configuration or through entry point IRI can be obtained by manual configuration or through
some discovery process. some discovery process.
skipping to change at page 8, line 47 skipping to change at page 8, line 47
request IRI and MUST be separated from the rest of the IRI prior request IRI and MUST be separated from the rest of the IRI prior
to a dereference. to a dereference.
5. The agent constructs a new request with the request IRI. If the 5. The agent constructs a new request with the request IRI. 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 in the form. The request IRI may need to be be the one specified in the form. The request 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 metadata associated with the link or form (e.g., set
the HTTP Accept header field or the CoAP Accept option when the the HTTP Accept header field or the CoAP Accept option when the
media type of the target resource is provided). In the case of a media type of the target resource is provided). Depending on the
form with one or more form fields, the agent also MUST include a operation type of a form, the agent may also need to include a
request payload that matches the specifications of the form request payload that matches the specifications of one or more
fields. 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 IRI, the 7. If a fragment identifier was separated from the request IRI, the
agent dereferences the fragment identifier within the received agent dereferences the fragment identifier within the received
representation. representation.
8. The agent _updates the browsing context_ by making the (embedded 8. The agent _updates the browsing context_ by making the (embedded
or received) representation the active representation. or 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 the 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), this means the agent has the choice
of what to do next again -- and the cycle repeats. of what to do next again -- and the cycle repeats.
3.8. History Traversal 2.7. History Traversal
A browsing context MAY entail a _session history_ that lists the A browsing context MAY entail a _session history_ that lists the
resource representations that the agent has processed, is processing, resource representations that the agent has processed, is processing,
or will process. or will process.
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 IRI that was used to retrieve the representation. and the request IRI 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 An agent can navigate a browsing context by _traversing the session
history_ in addition to following links and submitting forms. For history_ in addition to following links and submitting forms. For
example, if an agent received a representation that doesn't contain example, if an agent received a representation that doesn't contain
any further links or forms, it can revert the active representation any further links or forms, it can revert the active representation
back to one it has visited earlier. 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)
if it doesn't have a fresh representation in its cache. An agent when it doesn't 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 POST request)
unless it intends to perform that operation again.
4. 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 a data item in Concise Binary
Object Representation (CBOR) [RFC7049]. The structure of this data Object Representation (CBOR) [RFC7049]. The structure of this data
item is presented in the Concise Data Definition Language (CDDL) item is presented in the Concise Data Definition Language (CDDL)
[I-D.ietf-cbor-cddl]. The media type is "application/coral+cbor". [RFC8610]. The media type is "application/coral+cbor".
4.1. Data Structure The following restrictions are placed on CBOR encoders: Byte strings
and text strings MUST be encoded with definite length. Integers and
floating-point values MUST be encoded as such (e.g., a floating-point
value of 0.0 must not be encoded as the integer 0).
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 four kinds of elements: links, forms, embedded representations, and
(as an extension to the CoRAL data model) base directives. Base (as an extension to the CoRAL data model) base directives. Base
directives provide a way to encode IRIs with a common base more directives provide a way to encode IRIs with a common base more
efficiently. efficiently.
Elements are processed in the order they appear in the document. Elements are processed in the order they appear in the document.
Document processors need to maintain an _environment_ while iterating Document processors need to maintain an _environment_ while iterating
an array of elements. The environment consists of two variables: the an array of elements. The environment consists of two variables: the
_current context_ and the _current base_. Both the current context _current context_ and the _current base_. Both the current context
and the current base are initially set to the document's retrieval and the current base are initially set to the document's retrieval
context. context.
4.1.1. Documents 3.1.1. Documents
The body of a document in the binary format is encoded as an array of The body of a document in the binary format is encoded as an array of
zero or more links, forms, embedded representations, and directives. zero or more links, forms, embedded representations, and directives.
document = body
body = [*(link / form / representation / directive)] body = [*(link / form / representation / directive)]
4.1.2. Links 3.1.2. Links
A link is encoded as an array that consists of the unsigned integer A link is encoded as an array that consists of the unsigned integer
2, followed by the link relation type and the link target, optionally 2, followed by the link relation type and the link target, optionally
followed by a link body that contains nested elements. followed by a link body that contains nested elements.
link = [2, relation-type, link-target, ?body] link = [2, relation-type, link-target, ?body]
The link relation type is encoded as a text string that conforms to The link relation type is encoded as a text string that conforms to
the syntax of an IRI [RFC3987]. the syntax of an IRI [RFC3987].
skipping to change at page 11, line 4 skipping to change at page 11, line 11
The link target is denoted by an IRI reference or represented by a The link target is denoted by an IRI reference or represented by a
literal value. An IRI reference MUST be resolved against the current literal value. An IRI reference MUST be resolved against the current
base. The encoding of and resolution process for IRI references in base. The encoding of and resolution process for IRI references in
the binary format is described in RFC XXXX [I-D.hartke-t2trg-ciri]. the binary format is described in RFC XXXX [I-D.hartke-t2trg-ciri].
The link target may be null, which indicates that the link target is The link target may be null, which indicates that the link target is
an unidentified resource. an unidentified resource.
link-target = ciri / literal link-target = ciri / literal
ciri = <Defined in Section X of RFC XXXX> ciri = <Defined in Section X of RFC XXXX>
literal = bool / int / float / time / bytes / text / null literal = bool / int / float / time / bytes / text / null
The array of elements in the link body, if any, MUST be processed in The array of elements in the link body, if any, MUST be processed in
a fresh environment. Both the current context and the current base a fresh environment. Both the current context and the current base
in the new environment are initially set to the link target of the in the new environment are initially set to the link target of the
enclosing link. enclosing link.
4.1.3. Forms 3.1.3. Forms
A form is encoded as an array that consists of the unsigned integer A form is encoded as an array that consists of the unsigned integer
3, followed by the operation type, the request method, and the 3, followed by the operation type and the submission target,
submission target, optionally followed by a list of form fields. optionally followed by a list of form fields.
form = [3, operation-type, method, submission-target, ?form- form = [3, operation-type, submission-target, ?form-fields]
fields]
The operation type is defined in the same way as a link relation type The operation type is defined in the same way as a link relation type
(Section 4.1.2). (Section 3.1.2).
operation-type = text operation-type = text
The method MUST refer to one of the request methods defined by the The request method is either implied by the operation type or encoded
Web transfer protocol identified by the scheme of the submission as a form field. If there are both, the form field takes precedence
target. It is encoded either as a text string or an unsigned over the operation type. Either way, the method MUST be defined for
integer. the Web transfer protocol identified by the scheme of the submission
target.
method = text / uint
For HTTP [RFC7230], the method MUST be encoded as a text string in
the format defined in Section 4.1 of RFC 7231 [RFC7231]; the set of
possible values is maintained in the IANA HTTP Method Registry. For
CoAP [RFC7252], the method MUST be encoded as an unsigned integer
(e.g., the unsigned integer 2 for the POST method); the set of
possible values is maintained in the IANA CoAP Method Codes Registry.
The submission target is denoted by an IRI reference. This IRI The submission target is denoted by an IRI reference. This IRI
reference MUST be resolved against the current base. reference MUST be resolved against the current base.
submission-target = ciri submission-target = ciri
4.1.3.1. Form Fields 3.1.3.1. Form Fields
A list of form fields is encoded as an array of zero or more type- A list of form fields is encoded as an array of zero or more type-
value pairs. value pairs.
form-fields = [*(form-field-type, form-field-value)] form-fields = [*(form-field-type, form-field-value)]
The list, if any, MUST be processed in a fresh environment. Both the The list, if any, MUST be processed in a fresh environment. Both the
current context and the current base in the new environment are current context and the current base in the new environment are
initially set to the submission target of the enclosing form. 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 A form field type is defined in the same way as a link relation type
(Section 4.1.2). (Section 3.1.2).
form-field-type = text form-field-type = text
A form field value can be an IRI reference, a Boolean value, an A form field value can be an IRI reference, a Boolean value, an
integer, a floating-point number, a date/time value, a byte string, a integer, a floating-point number, a date/time value, a byte string, a
text string, or null. An IRI reference MUST be resolved against the text string, or null. An IRI reference MUST be resolved against the
current base. current base.
form-field-value = ciri / literal form-field-value = ciri / literal
4.1.3.2. Short Forms 3.1.4. Embedded Representations
[[NOTE TO READERS: This section used to describe special elements for
compressing certain forms that were assumed to occur frequently. The
topic of encoding frequently occurring elements more efficiently will
be revisited when more real-world examples are available.]]
4.1.4. Embedded Representations
An embedded representation is encoded as an array that consists of An embedded representation is encoded as an array that consists of
the unsigned integer 0, followed by a byte string containing the the unsigned integer 0, followed by a byte string containing the
representation data, optionally followed by representation metadata. representation data, optionally followed by representation metadata.
representation = [0, bytes, ?representation-metadata] representation = [0, bytes, ?representation-metadata]
Representation metadata is encoded as an array of zero or more name- Representation metadata is encoded as an array of zero or more name-
value pairs. value pairs.
representation-metadata = [*(metadata-name, metadata-value)] representation-metadata = [*(metadata-name, metadata-value)]
The metadata, if any, MUST be processed in a fresh environment. All The metadata, if any, MUST be processed in a fresh environment. All
variables in the new environment are initially set to a copy of the variables in the new environment are initially set to a copy of the
variables in the current environment. variables in the current environment.
The metadata name is defined in the same way as a link relation type The metadata name is defined in the same way as a link relation type
(Section 4.1.2). (Section 3.1.2).
metadata-name = text metadata-name = text
A metadata value can be an IRI reference, a Boolean value, an A metadata value can be an IRI reference, a Boolean value, an
integer, a floating-point number, a date/time value, a byte string, a integer, a floating-point number, a date/time value, a byte string, a
text string, or null. An IRI reference MUST be resolved against the text string, or null. An IRI reference MUST be resolved against the
current base. current base.
metadata-value = ciri / literal metadata-value = ciri / literal
4.1.5. Directives 3.1.5. Directives
Directives provide the ability to manipulate the environment when Directives provide the ability to manipulate the environment when
processing a list of elements. There is one type of directives processing a list of elements. There is one type of directives
available: the Base directive. available: the Base directive.
directive = base-directive directive = base-directive
4.1.5.1. Base Directives 3.1.5.1. Base Directives
A Base directive is encoded as an array that consists of the unsigned A Base directive is encoded as an array that consists of the unsigned
integer 1, followed by a base. integer 1, followed by a base.
base-directive = [1, base] base-directive = [1, base]
The base is denoted by an IRI reference. This IRI reference MUST be The base is denoted by an IRI reference. This IRI reference MUST be
resolved against the current context (not the current base). resolved against the current context (not the current base).
base = ciri base = ciri
The directive is processed by resolving the IRI reference against the The directive is processed by resolving the IRI reference against the
current context and assigning the result to the current base. current context and assigning the result to the current base.
4.2. Dictionaries 3.2. Dictionaries
The binary format can reference values from a dictionary to reduce The binary format can reference values from a dictionary to reduce
representation size and processing cost. Dictionary references can representation size and processing cost. Dictionary references can
be used in place of link relation types, link targets, operation be used in place of link relation types, link targets, operation
types, submission targets, form field types, form field values, types, submission targets, form field types, form field values,
representation metadata names, and representation metadata values. representation metadata names, and representation metadata values.
4.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.
relation-type /= uint relation-type /= uint
link-target /= #6.TBD6(uint) link-target /= #6.TBD6(uint)
operation-type /= uint operation-type /= uint
skipping to change at page 14, line 4 skipping to change at page 13, line 47
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.
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 metadata-name /= uint
metadata-value /= #6.TBD6(uint) metadata-value /= #6.TBD6(uint)
4.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 is defined to have a
"dictionary" parameter that specifies the dictionary in use. The "dictionary" parameter that specifies the dictionary in use. The
dictionary is identified by a URI [RFC3986]. For example, a CoRAL dictionary is identified by a URI [RFC3986]. For example, a CoRAL
document that uses the dictionary identified by the URI document that uses the dictionary identified by the URI
<http://example.com/dictionary> can use the following content type: <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 human- or machine-readable way. (The format of such a representation
is outside the scope of this document.) is 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
skipping to change at page 14, line 45 skipping to change at page 14, line 39
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 media
type parameters) are encoded as an unsigned integer called "content type parameters) are encoded as an unsigned integer called "content
format". For use with CoAP, each new CoRAL dictionary MUST register format". For use with CoAP, each new CoRAL dictionary MUST register
a new content format in the IANA CoAP Content-Formats Registry. a new content format in the IANA CoAP Content-Formats Registry.
5. 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 is not used; charset information is
transported inside the document in the form of an OPTIONAL Byte Order transported inside the document in the form of an OPTIONAL Byte Order
Mark (BOM). The use of the UTF-8 encoding scheme [RFC3629], without Mark (BOM). The use of the UTF-8 encoding scheme [RFC3629], without
a BOM, is RECOMMENDED. a BOM, is RECOMMENDED.
5.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 five kinds of tokens: identifiers, IRIs, IRI
references, literals, and punctuators. references, literals, and punctuators.
token = identifier / iri / iriref / literal / punctuator token = identifier / iri / iriref / literal / 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.
5.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.)
5.1.2. White Space 4.1.2. White Space
White space is a sequence of one or more white space characters. A White space is a sequence of one or more white space characters. A
white space character is any Unicode character with the White_Space white space character is any Unicode character with the White_Space
property. property.
5.1.3. Comments 4.1.3. Comments
Comments are sequences of characters that are ignored when parsing Comments are sequences of characters that are ignored when parsing
text into tokens. Single-line comments begin with the characters text into tokens. Single-line comments begin with the characters
"//" and extend to the end of the line. Delimited comments begin "//" and extend to the end of the line. Delimited comments begin
with the characters "/*" and end with the characters "*/". Delimited with the characters "/*" and end with the characters "*/". Delimited
comments can occupy a portion of a line, a single line, or multiple comments can occupy a portion of a line, a single line, or multiple
lines. lines.
Comments do not nest. The character sequences "/*" and "*/" have no Comments do not nest. The character sequences "/*" and "*/" have no
special meaning within a single-line comment; the character sequences special meaning within a single-line comment; the character sequences
"//" and "/*" have no special meaning within a delimited comment. "//" and "/*" have no special meaning within a delimited comment.
5.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 [UNICODE-UAX31] using 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), as defined by the Unicode Standard Annex #15 [UNICODE-UAX15].
Comparison of identifiers is based on NFC and is case-sensitive Comparison of identifiers is based on NFC and is case-sensitive
(unless otherwise noted). (unless otherwise noted).
5.1.5. IRIs and IRI References 4.1.5. IRIs and IRI References
IRIs and IRI references are Unicode strings that conform to the IRIs and IRI references are Unicode strings that conform to the
syntax defined in RFC 3987 [RFC3987]. An IRI reference can be either syntax defined in RFC 3987 [RFC3987]. An IRI reference can be either
an IRI or a relative reference. Both IRIs and IRI references are an IRI or a relative reference. Both IRIs and IRI references are
enclosed in angle brackets ("<" and ">"). enclosed in angle brackets ("<" and ">").
iri = "<" IRI ">" iri = "<" IRI ">"
iriref = "<" IRI-reference ">" iriref = "<" IRI-reference ">"
IRI = <Defined in Section 2.2 of RFC 3987> IRI = <Defined in Section 2.2 of RFC 3987>
IRI-reference = <Defined in Section 2.2 of RFC 3987> IRI-reference = <Defined in Section 2.2 of RFC 3987>
5.1.6. Literals 4.1.6. Literals
A literal is a textual representation of a value. There are seven A literal is a textual representation of a value. There are seven
types of literals: Boolean, integer, floating-point, date/time, byte types of literals: Boolean, integer, floating-point, date/time, byte
string, text string, and null. string, text string, and null.
literal = boolean / integer / float / datetime / bytes / text literal = boolean / integer / float / datetime / bytes / text
literal =/ null literal =/ null
5.1.6.1. Boolean Literals 4.1.6.1. 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"
5.1.6.2. Integer Literals 4.1.6.2. Integer Literals
Integer literals denote an integer value of unspecified precision. Integer literals denote an integer value of unspecified precision.
By default, integer literals are expressed in decimal, but they can By default, integer literals are expressed in decimal, but they can
also be specified in an alternate base using a prefix: Binary also be specified in an alternate base using a prefix: Binary
literals begin with "0b", octal literals begin with "0o", and 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
skipping to change at page 17, line 45 skipping to change at page 17, line 38
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
5.1.6.3. Floating-point Literals 4.1.6.3. Floating-point Literals
Floating-point literals denote a floating-point number of unspecified Floating-point literals denote a floating-point number of unspecified
precision. 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 page 18, line 21
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"
5.1.6.4. Date/Time Literals 4.1.6.4. Date/Time Literals
Date/time literals denote an instant in time. Date/time literals denote an instant in time.
A date/time literal consists of a sequence of characters in Internet A date/time literal consists of the prefix "dt" and a sequence of
date/time format [RFC3339], enclosed in dollar signs. Unicode characters in Internet Date/Time Format [RFC3339], enclosed
in single quotes.
datetime = DOLLAR date-time DOLLAR 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>
DOLLAR = %x24 SQUOTE = %x27
5.1.6.5. Byte String Literals 4.1.6.5. Byte String Literals
Byte string literals denote an ordered sequence of bytes. Byte string literals 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] and 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
SQUOTE = %x27 4.1.6.6. Text String Literals
5.1.6.6. Text String Literals
Text string literals denote a Unicode string. Text string literals 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
skipping to change at page 20, line 22 skipping to change at page 20, line 5
| \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
5.1.6.7. Null Literal 4.1.6.7. 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" / "_"
5.1.7. Punctuators 4.1.7. Punctuators
Punctuator tokens are used for grouping and separating. Punctuator tokens are used for grouping and separating.
punctuator = "#" / ":" / "*" / "[" / "]" / "{" / "}" / "=" / "->" punctuator = "#" / ":" / "*" / "[" / "]" / "{" / "}" / "=" / "->"
5.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 four kinds of elements: links, forms, embedded representations,
and (as an extension to the CoRAL data model) directives. Directives and (as an extension to the CoRAL data model) directives. Directives
provide a way to make documents easier to read and write by setting a provide a way to make documents easier to read and write by setting a
base for relative IRI references and introducing shorthands for IRIs. base for relative IRI references and introducing shorthands for IRIs.
Elements are processed in the order they appear in the document. 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 list of elements. The environment consists of three variables: the
_current context_, the _current base_, and the _current mapping from _current context_, the _current base_, and the _current mapping from
identifiers to IRIs_. Both the current context and the current base identifiers to IRIs_. Both the current context and the current base
are initially set to the document's retrieval context. The current are initially set to the document's retrieval context. The current
mapping from identifiers to IRIs is initially empty. mapping from identifiers to IRIs is initially empty.
5.2.1. Documents 4.2.1. Documents
The body of a document in the textual format consists of zero or more The body of a document in the textual format consists of zero or more
links, forms, embedded representations, and directives. links, forms, embedded representations, and directives.
document = body
body = *(link / form / representation / directive) body = *(link / form / representation / directive)
5.2.2. Links 4.2.2. Links
A link consists of the link relation type, followed by the link A link consists of the link relation type, followed by the link
target, optionally followed by a link body enclosed in curly brackets target, optionally followed by a link body enclosed in curly brackets
("{" and "}"). ("{" and "}").
link = relation-type link-target ["{" body "}"] link = relation-type link-target ["{" body "}"]
The link relation type is denoted by either an IRI, a simple name, or The link relation type is denoted by either an IRI, a simple name, or
a qualified name. a qualified name.
skipping to change at page 22, line 7 skipping to change at page 21, line 37
link-target = iriref / literal link-target = iriref / literal
The list of elements in the link body, if any, MUST be processed in a The list of elements in the link body, if any, MUST be processed in a
fresh environment. Both the current context and current base in this 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.
5.2.3. Forms 4.2.3. Forms
A form consists of the operation type, followed by a "->" token, the A form consists of the operation type, followed by a "->" token and
request method, and the submission target, optionally followed by a the submission target, optionally followed by a list of form fields
list of form fields enclosed in square brackets ("[" and "]"). enclosed in square brackets ("[" and "]").
form = operation-type "->" method submission-target ["[" form- form = operation-type "->" submission-target ["[" form-fields "]"]
fields "]"]
The operation type is defined in the same way as a link relation type The operation type is defined in the same way as a link relation type
(Section 5.2.2). (Section 4.2.2).
operation-type = iri / simple-name / qualified-name operation-type = iri / simple-name / qualified-name
The method identifier MUST refer to one of the request methods The request method is either implied by the operation type or encoded
defined by the Web transfer protocol identified by the scheme of the as a form field. If there are both, the form field takes precedence
submission target. Method identifiers are case-insensitive and over the operation type. Either way, the method MUST be defined for
constrained to Unicode characters in the Basic Latin block. the Web transfer protocol identified by the scheme of the submission
target.
method = identifier
For HTTP [RFC7230], the set of possible method identifiers is
maintained in the IANA HTTP Method Registry. For CoAP [RFC7252], the
set of possible method identifiers is maintained in the IANA CoAP
Method Codes Registry.
The submission target is denoted by an IRI reference. This IRI The submission target is denoted by an IRI reference. This IRI
reference MUST be resolved against the current base. reference MUST be resolved against the current base.
submission-target = iriref submission-target = iriref
5.2.3.1. Form Fields 4.2.3.1. Form Fields
A list of form fields consists of zero or more type-value pairs. A list of form fields consists of zero or more type-value pairs.
form-fields = *(form-field-type form-field-value) form-fields = *(form-field-type form-field-value)
The list, if any, MUST be processed in a fresh environment. Both the The list, if any, MUST be processed in a fresh environment. Both the
current context and the current base in this environment are 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 The form field type is defined in the same way as a link relation
type (Section 5.2.2). type (Section 4.2.2).
form-field-type = iri / simple-name / qualified-name form-field-type = iri / simple-name / qualified-name
The form field value can be an IRI reference, Boolean literal, The form field value can be an IRI reference, Boolean literal,
integer literal, floating-point literal, byte string literal, text integer literal, floating-point literal, byte string literal, text
string literal, or null. An IRI reference MUST be resolved against string literal, or null. An IRI reference MUST be resolved against
the current base. the current base.
form-field-value = iriref / literal form-field-value = iriref / literal
5.2.4. Embedded Representations 4.2.4. Embedded Representations
An embedded representation consists of a "*" token, followed by the An embedded representation consists of a "*" token, followed by the
representation data, optionally followed by representation metadata representation data, optionally followed by representation metadata
enclosed in square brackets ("[" and "]"). enclosed in square brackets ("[" and "]").
representation = "*" bytes ["[" representation-metadata "]"] representation = "*" bytes ["[" representation-metadata "]"]
Representation metadata consists of zero or more name-value pairs. Representation metadata consists of zero or more name-value pairs.
representation-metadata = *(metadata-name metadata-value) representation-metadata = *(metadata-name metadata-value)
The metadata, if any, MUST be processed in a fresh environment. All The metadata, if any, MUST be processed in a fresh environment. All
variables in the new environment are initially set to a copy of the variables in the new environment are initially set to a copy of the
variables in the current environment. variables in the current environment.
The metadata name is defined in the same way as a link relation type The metadata name is defined in the same way as a link relation type
(Section 5.2.2). (Section 4.2.2).
metadata-name = iri / simple-name / qualified-name metadata-name = iri / simple-name / qualified-name
The metadata value can be an IRI reference, Boolean literal, integer The metadata value can be an IRI reference, Boolean literal, integer
literal, floating-point literal, byte string literal, text string literal, floating-point literal, byte string literal, text string
literal, or null. An IRI reference MUST be resolved against the literal, or null. An IRI reference MUST be resolved against the
current base. current base.
metadata-value = iriref / literal metadata-value = iriref / literal
5.2.5. Directives 4.2.5. Directives
Directives provide the ability to manipulate the environment when Directives provide the ability to manipulate the environment when
processing a list of elements. All directives start with a number processing a list of elements. All directives start with a number
sign ("#") followed by a directive identifier. Directive identifiers sign ("#") followed by a directive identifier. Directive identifiers
are case-insensitive and constrained to Unicode characters in the are case-insensitive and constrained to Unicode characters in the
Basic Latin block. Basic Latin block.
The following two types of directives are available: the Base The following two types of directives are available: the Base
directive and the Using directive. directive and the Using directive.
directive = base-directive / using-directive directive = base-directive / using-directive
5.2.5.1. Base Directives 4.2.5.1. Base Directives
A Base directive consists of a number sign ("#"), followed by the A Base directive consists of a number sign ("#"), followed by the
case-insensitive identifier "base", followed by a base. case-insensitive identifier "base", followed by a base.
base-directive = "#" "base" base base-directive = "#" "base" base
The base is denoted by an IRI reference. The IRI reference MUST be The base is denoted by an IRI reference. The IRI reference MUST be
resolved against the current context (not the current base). resolved against the current context (not the current base).
base = iriref base = iriref
The directive is processed by resolving the IRI reference against the The directive is processed by resolving the IRI reference against the
current context and assigning the result to the current base. current context and assigning the result to the current base.
5.2.5.2. Using Directives 4.2.5.2. Using Directives
A Using directive consists of a number sign ("#"), followed by the A Using directive consists of a number sign ("#"), followed by the
case-insensitive identifier "using", optionally followed by an case-insensitive identifier "using", optionally followed by an
identifier and an equals sign ("="), finally followed by an IRI. If identifier and an equals sign ("="), finally followed by an IRI. If
the identifier is not specified, it is assumed to be the empty the identifier is not specified, it is assumed to be the empty
string. string.
using-directive = "#" "using" [identifier "="] iri using-directive = "#" "using" [identifier "="] iri
The directive is processed by adding the specified identifier and IRI The directive is processed by adding the specified identifier and IRI
to the current mapping from identifiers to IRIs. It is an error if to the current mapping from identifiers to IRIs. It is an error if
the identifier is already present in the mapping. the identifier is already present in the mapping.
6. Usage Considerations 5. 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.
6.1. Specifying CoRAL-based Applications 5.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. o Resources are identified by IRIs or represented by value literals.
o Interactions are based on the hypermedia interaction model of the o 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 o Representations are CoRAL documents encoded in the binary format
defined in Section 4 or the textual format defined in Section 5. 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.
6.1.1. Application Interfaces 5.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 IRI schemes that identify the Web transfer protocol(s) used in the o IRI schemes that identify the Web transfer protocol(s) used in the
application. application.
o Internet media types that identify the representation format(s) o Internet media types that identify the representation format(s)
used in the application, including the media type(s) of the CoRAL used in the application, including the media type(s) of the CoRAL
skipping to change at page 25, line 37 skipping to change at page 25, line 13
method(s). method(s).
o Form field types that identify the semantics of form fields. o Form field types that identify the semantics of form fields.
Additionally, for each form field type, the permissible form field Additionally, for each form field type, the permissible form field
values. values.
o Metadata names that identify the semantics of representation o Metadata names that identify the semantics of representation
metadata. Additionally, for each metadata name, the permissible metadata. Additionally, for each metadata name, the permissible
metadata values. metadata values.
6.1.2. Resource Names 5.1.2. Resource Names
Resource names -- i.e., URIs [RFC3986] and IRIs [RFC3987] -- are a Resource names -- i.e., URIs [RFC3986] and IRIs [RFC3987] -- are a
cornerstone of Web-based applications. They enable the uniform cornerstone of Web-based applications. They enable the uniform
identification of resources and are used every time a client identification of resources and are used every time a client
interacts with a server or a resource representation needs to refer interacts with a server or a resource representation needs to refer
to another resource. to another resource.
URIs and IRIs often include structured application data in the path URIs and IRIs often include structured application data in the path
and query components, such as paths in a filesystem or keys in a and query components, such as paths in a filesystem or keys in a
database. It is a common practice in many HTTP-based application database. It is a common practice in many HTTP-based application
skipping to change at page 26, line 12 skipping to change at page 25, line 36
coded in implementations. There are a number of problems with this coded in implementations. There are a number of problems with this
practice [RFC7320], though. practice [RFC7320], though.
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. BCP 190 [RFC7320]
describes the problematic practice of fixed URI structures in more describes the problematic practice of fixed URI structures in more
detail and provides some acceptable alternatives. detail and provides some acceptable alternatives.
6.1.3. Implementation Limits 5.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 wish to limit these numbers and specify 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; o use of only either the binary format or the text format;
skipping to change at page 26, line 36 skipping to change at page 26, line 11
o use of only dictionary references in the binary format for certain o use of only dictionary references in the binary format for certain
vocabulary; vocabulary;
o use of only either content type strings or content format IDs; o use of only either content type strings or content format IDs;
o use of IRI references only up to a specific string length; o use of IRI references only up to a specific string length;
o use of CBOR in a canonical format (see Section 3.9 of RFC 7049). o use of CBOR in a canonical format (see Section 3.9 of RFC 7049).
6.2. Minting Vocabulary 5.2. Minting Vocabulary
New link relation types, operation types, form field types, and New link relation types, operation types, form field types, and
metadata names can be minted by defining an IRI [RFC3987] that metadata names can be minted by defining an IRI [RFC3987] that
uniquely identifies the item. Although the IRI can point to a uniquely identifies the item. Although the IRI can point to a
resource that contains a definition of the semantics, clients SHOULD resource that contains a definition of the semantics, clients SHOULD
NOT automatically access that resource to avoid overburdening its NOT automatically access that resource to avoid overburdening its
server. The IRI SHOULD be under the control of the person or party server. The IRI SHOULD be under the control of the person or party
defining it, or be delegated to them. defining it, or be delegated to them.
To avoid interoperability problems, it is RECOMMENDED that only IRIs To avoid interoperability problems, it is RECOMMENDED that only IRIs
skipping to change at page 27, line 24 skipping to change at page 26, line 47
o Lowercase hexadecimal letters within percent-encoding triplets o 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 o Punycode-encoding of Internationalized Domain Names in IRIs
o IRIs that are not in Unicode Normalization Form C [UNICODE-UAX15] o IRIs that are not in Unicode Normalization Form C [UNICODE-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. However, IRIs creation of new IRIs without the risk of collisions.
can be relatively verbose and impose a high overhead on a
representation. This can be a problem in constrained environments However, IRIs can be relatively verbose and impose a high overhead on
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 4.2. These impose a much smaller overhead but instead in Section 3.2. These impose a much smaller overhead but instead
need to be assigned by an authority to avoid collisions. need to be assigned by an authority to avoid collisions.
6.3. Expressing Registered Link Relation Types 5.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 Note that registered link relation types are required to be
lowercased as per Section 3.3 of RFC 8288 [RFC8288]. lowercased, as per Section 3.3 of RFC 8288 [RFC8288].
(The convention of appending the link relation type to the prefix
"http://www.iana.org/assignments/relation/" to form an IRI is adopted
from Atom [RFC4287]. See also Appendix A.2 of RFC 8288 [RFC8288].)
6.4. Expressing Link Target Attributes
[[NOTE TO READERS: This section describes a mechanism to convert any
link target attributes to CoRAL in a way that allows a conversion
back without loss of information (round-trip conversion). It is
likely that this will be replaced by a specific set of unique link
relation types that match the known RFC 6690 attributes semantically
but do not round-trip in the presence of unknown attributes.]]
Link target attributes defined for use with CoRE Link Format
[RFC6690] (such as "hreflang", "media", "title", "title*", "type",
"ct", "rt", "if", "sz", and "obs") can be expressed in CoRAL by
nesting links under the respective link. The link relation type of
each such nested link is the lowercased attribute name appended to
the IRI <http://TBD2/>.
If the expressed link target attribute has a value, the target of the
nested link MUST be a text string; otherwise, the target MUST be the
Boolean value "true".
#using iana = <http://www.iana.org/assignments/relation/>
#using attr = <http://TBD2/>
iana:item </patches/1> {
attr:type "application/json-patch+json"
attr:ct "51"
attr:sz "247"
attr:obs true
}
<=>
</patches/1>; rel=item; type="application/json-patch+json";
ct=51; sz=247; obs
Language information in attributes as per RFC 8187 [RFC8187], such as
in "title*" attributes, is expressed by nesting an additional link of
type <http://TBD2/hreflang> under the link representing the
attribute. The target of the nested link MUST be a text string
containing a language tag [RFC5646]. The attribute name is expressed
without the "*" character.
#using iana = <http://www.iana.org/assignments/relation/>
#using attr = <http://TBD2/>
iana:terms-of-service </tos> {
attr:title "Nutzungsbedingungen" { attr:hreflang "de" }
attr:title "Terms of use" { attr:hreflang "en" }
}
<=>
</tos>; rel=terms-of-service;
title*=UTF-8'de'Nutzungsbedingungen;
title*=UTF-8'en'Terms%20of%20use
Link target attributes that actually do not describe the link target (The convention of appending the link relation types to the prefix
but the link itself (such as "rel", "anchor", and "rev") are excluded "http://www.iana.org/assignments/relation/" to form IRIs is adopted
from this provision and MUST NOT occur in a CoRAL document. from Atom [RFC4287]; see also Appendix A.2 of RFC 8288 [RFC8288].)
6.5. Expressing Simple RDF Statements 5.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.
RDF predicates can therefore be good source for vocabulary to provide RDF predicates can therefore be good source for vocabulary to provide
resource metadata. For example, a CoRAL document could use the FOAF resource metadata. For example, a CoRAL document could use the FOAF
vocabulary [FOAF] to describe the person or software that made it: vocabulary [FOAF] to describe the person or software that made it:
#using rdf = <http://www.w3.org/1999/02/22-rdf-syntax-ns#> #using rdf = <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
#using foaf = <http://xmlns.com/foaf/0.1/> #using foaf = <http://xmlns.com/foaf/0.1/>
foaf:maker null { foaf:maker null {
rdf:type <http://xmlns.com/foaf/0.1/Person> rdf:type <http://xmlns.com/foaf/0.1/Person>
foaf:familyName "Hartke" foaf:familyName "Hartke"
foaf:givenName "Klaus" foaf:givenName "Klaus"
foaf:mbox <mailto:klaus.hartke@ericsson.com> foaf:mbox <mailto:klaus.hartke@ericsson.com>
} }
6.6. Embedding CoRAL in CBOR Structures 5.5. Expressing Language-Tagged Strings
Data items in the CoRAL binary format (Section 4) may be embedded in Text strings that are the target of a link can be associated with a
other CBOR [RFC7049] data structures. Specifications using CDDL language tag [RFC5646] by nesting a link of type
[I-D.ietf-cbor-cddl] SHOULD reference the following CDDL definitions <http://coreapps.org/base#lang> under the link. The target of this
for this purpose: nested link MUST be a text string that conforms to the syntax
specified in Section 2.1 of RFC 5646:
CoRAL-Document = body #using <http://coreapps.org/base#>
#using example = <http://example.org/>
#using iana = <http://www.iana.org/assignments/relation/>
iana:terms-of-service </tos> {
example:title "Nutzungsbedingungen" { lang "de" }
example:title "Terms of use" { lang "en" }
}
5.6. Embedding CoRAL in CBOR Data
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-Link = link
CoRAL-Form = form CoRAL-Form = form
For each embedded document, link, and form, the retrieval context, For each embedded document, link, and form, the retrieval context,
link context, and form context needs to be specified, respectively. link context, and form context needs to be specified, respectively.
6.7. Submitting CoRAL Documents 5.7. Submitting CoRAL Documents
By default, a CoRAL document is a representation that captures the By default, a CoRAL document is a representation that captures the
current state of a resource. The meaning of a CoRAL document changes current state of a resource. The meaning of a CoRAL document changes
when it is submitted in a request. Depending on the request method, when it is submitted in a request. Depending on the request method,
the CoRAL document can capture the intended state of a resource or be the CoRAL document can capture the intended state of a resource (PUT)
subject to application-specific processing. or be subject to application-specific processing (POST).
6.7.1. PUT Requests 5.7.1. PUT Requests
A PUT request with a CoRAL document enclosed in the request payload A PUT request with a CoRAL document enclosed in the request payload
requests that the state of the target resource be created or replaced requests that the state of the target resource be created or replaced
with the state described by the CoRAL document. A successful PUT of with the state described by the CoRAL document. A successful PUT of
a CoRAL document generally means that a subsequent GET on that same a CoRAL document generally means that a subsequent GET on that same
target resource would result in an equivalent document being sent in target resource would result in an equivalent document being sent in
a success response. a success response.
An origin server SHOULD verify that a submitted CoRAL document is An origin server SHOULD verify that a submitted CoRAL document is
consistent with any constraints the server has for the target consistent with any constraints the server has for the target
resource. When a document is inconsistent with the target resource, resource. When a document is inconsistent with the target resource,
the origin server SHOULD either make it consistent (e.g., by removing the origin server SHOULD either make it consistent (e.g., by removing
inconsistent elements) or respond with an appropriate error message inconsistent elements) or respond with an appropriate error message
containing sufficient information to explain why the document is containing sufficient information to explain why the document is
unsuitable. unsuitable.
The retrieval context of a CoRAL document in a PUT is the request IRI The retrieval context of a CoRAL document in a PUT is the request IRI
of the request. of the request.
6.7.2. POST Requests 5.7.2. POST Requests
A POST request with a CoRAL document enclosed in the request payload A POST request with a CoRAL document enclosed in the request payload
requests that the target resource process the CoRAL document requests that the target resource process the CoRAL document
according to the resource's own specific semantics. according to the resource's own specific semantics.
The retrieval context of a CoRAL document in a POST is the request The retrieval context of a CoRAL document in a POST is the request
IRI of the request. IRI of the request.
7. Security Considerations 6. Security Considerations
Parsers of CoRAL documents must operate on input that is assumed to Parsers of CoRAL documents must operate on input that is assumed to
be untrusted. This means that parsers MUST fail gracefully in the be untrusted. This means that parsers MUST fail gracefully in the
face of malicious inputs. Additionally, parsers MUST be prepared to face of malicious inputs (e.g., inputs not adhering to the data
deal with resource exhaustion (e.g., resulting from the allocation of structure). Additionally, parsers MUST be prepared to deal with
big data items) or exhaustion of the call stack (stack overflow). resource exhaustion (e.g., resulting from the allocation of big data
items) or exhaustion of the call stack (stack overflow).
See Section 8 of RFC 7049 [RFC7049] for security considerations CoRAL documents intentionally do not feature the equivalent of XML
relating to CBOR. entity references as to preclude the whole class of exponential XML
entity expansion ("billion laughs") [CAPEC-197] and improper XML
external entity [CAPEC-201] attacks.
Implementers of the CoRAL binary format need to consider the security
aspects of processing CBOR with the restrictions described in
Section 3. Notably, different number representations for the same
numeric value are not equivalent in the CoRAL binary format. See
Section 8 of RFC 7049 [RFC7049] for security considerations relating
to CBOR.
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 the Unicode Standard
Annex #36 [UNICODE-UAX36] for security considerations relating to Annex #36 [UNICODE-UAX36] for security considerations relating to
visual spoofing and misuse of character encodings. See Section 10 of visual spoofing and misuse of character encodings. See Section 10 of
RFC 3629 [RFC3629] for security considerations relating to UTF-8. RFC 3629 [RFC3629] for security considerations relating to UTF-8.
CoRAL makes extensive use of IRIs and URIs. See Section 8 of RFC CoRAL makes extensive use of IRIs and URIs. See Section 8 of RFC
3987 [RFC3987] for security considerations relating to IRIs. See 3987 [RFC3987] for security considerations relating to IRIs. See
Section 7 of RFC 3986 [RFC3986] for security considerations relating Section 7 of RFC 3986 [RFC3986] for security considerations relating
skipping to change at page 32, line 10 skipping to change at page 30, line 38
forms in CoRAL documents. Notably, a server that is authoritative forms in CoRAL documents. Notably, a server that is authoritative
for the CoRAL representation of a resource may not necessarily be for the CoRAL representation of a resource may not necessarily be
authoritative for nested elements in the document. See Section 5 of authoritative for nested elements in the document. See Section 5 of
RFC 8288 [RFC8288] for related considerations. RFC 8288 [RFC8288] for related considerations.
Unless an application mitigates this risk by specifying more specific Unless an application mitigates this risk by specifying more specific
rules, any link or form in a document where the link or form context rules, any link or form in a document where the link or form context
and the document's retrieval context don't share the same Web origin and the document's retrieval context don't share the same Web origin
[RFC6454] MUST be discarded ("same-origin policy"). [RFC6454] MUST be discarded ("same-origin policy").
8. IANA Considerations 7. IANA Considerations
8.1. Media Type "application/coral+cbor" 7.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
skipping to change at page 32, line 24 skipping to change at page 31, line 4
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 4.2 of [I-D.hartke-t2trg-coral]. dictionary - See Section 3.2 of [I-D.hartke-t2trg-coral].
Encoding considerations: Encoding considerations:
binary - See Section 4 of [I-D.hartke-t2trg-coral]. binary - See Section 3 of [I-D.hartke-t2trg-coral].
Security considerations: Security considerations:
See Section 7 of [I-D.hartke-t2trg-coral]. See Section 6 of [I-D.hartke-t2trg-coral].
Interoperability considerations: Interoperability considerations:
N/A N/A
Published specification: Published specification:
[I-D.hartke-t2trg-coral] [I-D.hartke-t2trg-coral]
Applications that use this media type: Applications that use this media type:
See Section 1 of [I-D.hartke-t2trg-coral]. See Section 1 of [I-D.hartke-t2trg-coral].
skipping to change at page 33, line 23 skipping to change at page 32, line 5
Author: Author:
See the Author's Address section of [I-D.hartke-t2trg-coral]. See the Author's Address section of [I-D.hartke-t2trg-coral].
Change controller: Change controller:
IESG IESG
Provisional registration? Provisional registration?
No No
8.2. Media Type "text/coral" 7.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 in RFC 6657 [RFC6657].
Type name: Type name:
text text
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 5 of [I-D.hartke-t2trg-coral]. binary - See Section 4 of [I-D.hartke-t2trg-coral].
Security considerations: Security considerations:
See Section 7 of [I-D.hartke-t2trg-coral]. See Section 6 of [I-D.hartke-t2trg-coral].
Interoperability considerations: Interoperability considerations:
N/A N/A
Published specification: Published specification:
[I-D.hartke-t2trg-coral] [I-D.hartke-t2trg-coral]
Applications that use this media type: Applications that use this media type:
See Section 1 of [I-D.hartke-t2trg-coral]. See Section 1 of [I-D.hartke-t2trg-coral].
Fragment identifier considerations: Fragment identifier considerations:
N/A N/A
Additional information: Additional information:
Deprecated alias names for this type: N/A Deprecated alias names for this type: N/A
Magic number(s): N/A Magic number(s): N/A
File extension(s): .coral File extension(s): .coral
Macintosh file type code(s): N/A Macintosh file type code(s): N/A
skipping to change at page 34, line 34 skipping to change at page 33, line 16
Author: Author:
See the Author's Address section of [I-D.hartke-t2trg-coral]. See the Author's Address section of [I-D.hartke-t2trg-coral].
Change controller: Change controller:
IESG IESG
Provisional registration? Provisional registration?
No No
8.3. CoAP Content Formats 7.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 o Content Type: application/coral+cbor
Content Coding: identity Content Coding: identity
ID: TBD3 ID: TBD3
Reference: [I-D.hartke-t2trg-coral] Reference: [I-D.hartke-t2trg-coral]
skipping to change at page 35, line 9 skipping to change at page 33, line 39
ID: TBD4 ID: TBD4
Reference: [I-D.hartke-t2trg-coral] Reference: [I-D.hartke-t2trg-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.]]
8.4. CBOR Tag 7.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 7049 [RFC7049].
o Tag: TBD6 o Tag: TBD6
Data Item: unsigned integer Data Item: unsigned integer
Semantics: Dictionary reference Semantics: Dictionary reference
Reference: [I-D.hartke-t2trg-coral] Reference: [I-D.hartke-t2trg-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.]]
9. References 8. References
9.1. Normative References 8.1. Normative References
[I-D.hartke-t2trg-ciri] [I-D.hartke-t2trg-ciri]
Hartke, K., "Constrained Internationalized Resource Hartke, K., "Constrained Internationalized Resource
Identifiers", draft-hartke-t2trg-ciri-02 (work in Identifiers", draft-hartke-t2trg-ciri-03 (work in
progress), March 2019. progress), July 2019.
[I-D.ietf-cbor-cddl]
Birkholz, H., Vigano, C., and C. Bormann, "Concise data
definition language (CDDL): a notational convention to
express CBOR and JSON data structures", draft-ietf-cbor-
cddl-07 (work in progress), February 2019.
[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 23 skipping to change at page 34, line 45
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>. <https://www.rfc-editor.org/info/rfc4648>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>. <https://www.rfc-editor.org/info/rfc5234>.
[RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
September 2009, <https://www.rfc-editor.org/info/rfc5646>.
[RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454,
DOI 10.17487/RFC6454, December 2011, DOI 10.17487/RFC6454, December 2011,
<https://www.rfc-editor.org/info/rfc6454>. <https://www.rfc-editor.org/info/rfc6454>.
[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
skipping to change at page 36, line 49 skipping to change at page 35, line 27
2013, <https://www.rfc-editor.org/info/rfc6943>. 2013, <https://www.rfc-editor.org/info/rfc6943>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <https://www.rfc-editor.org/info/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>.
[RFC8288] Nottingham, M., "Web Linking", RFC 8288, [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
DOI 10.17487/RFC8288, October 2017, Definition Language (CDDL): A Notational Convention to
<https://www.rfc-editor.org/info/rfc8288>. Express Concise Binary Object Representation (CBOR) and
JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
June 2019, <https://www.rfc-editor.org/info/rfc8610>.
[UNICODE] The Unicode Consortium, "The Unicode Standard", [UNICODE] The Unicode Consortium, "The Unicode Standard",
<http://www.unicode.org/versions/latest/>. <http://www.unicode.org/versions/latest/>.
Note that this reference is to the latest version of Note that this reference is to the latest version of
Unicode, rather than to a specific release. It is not Unicode, rather than to a specific release. It is not
expected that future changes in the Unicode specification expected that future changes in the Unicode specification
will have any impact on this document. will have any impact on this document.
[UNICODE-UAX15] [UNICODE-UAX15]
skipping to change at page 37, line 28 skipping to change at page 36, line 10
[UNICODE-UAX31] [UNICODE-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-UAX36]
The Unicode Consortium, "Unicode Standard Annex #36: The Unicode Consortium, "Unicode Standard Annex #36:
Unicode Security Considerations", Unicode Security Considerations",
<http://unicode.org/reports/tr36/>. <http://unicode.org/reports/tr36/>.
9.2. Informative References 8.2. Informative References
[CAPEC-197]
MITRE, "CAPEC-197: XML Entity Expansion", July 2018,
<https://capec.mitre.org/data/definitions/197.html>.
[CAPEC-201]
MITRE, "CAPEC-201: XML Entity Linking", July 2018,
<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", January 2014,
<http://xmlns.com/foaf/spec/20140114.html>. <http://xmlns.com/foaf/spec/20140114.html>.
[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>.
[RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
September 2009, <https://www.rfc-editor.org/info/rfc5646>.
[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",
RFC 6573, DOI 10.17487/RFC6573, April 2012, RFC 6573, DOI 10.17487/RFC6573, April 2012,
<https://www.rfc-editor.org/info/rfc6573>. <https://www.rfc-editor.org/info/rfc6573>.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
skipping to change at page 38, line 34 skipping to change at page 37, line 24
[RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190,
RFC 7320, DOI 10.17487/RFC7320, July 2014, RFC 7320, DOI 10.17487/RFC7320, July 2014,
<https://www.rfc-editor.org/info/rfc7320>. <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>.
[RFC8187] Reschke, J., "Indicating Character Encoding and Language [RFC8288] Nottingham, M., "Web Linking", RFC 8288,
for HTTP Header Field Parameters", RFC 8187, DOI 10.17487/RFC8288, October 2017,
DOI 10.17487/RFC8187, September 2017, <https://www.rfc-editor.org/info/rfc8288>.
<https://www.rfc-editor.org/info/rfc8187>.
[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>.
[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, December 2017,
<https://www.w3.org/TR/2017/REC-html52-20171214>. <https://www.w3.org/TR/2017/REC-html52-20171214>.
skipping to change at page 39, line 35 skipping to change at page 38, line 23
Web, Volume One", World Wide Web Consortium Web, Volume One", World Wide Web Consortium
Recommendation REC-webarch-20041215, December 2004, Recommendation REC-webarch-20041215, 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, form field types, and metadata
names. names.
[[NOTE TO RFC EDITOR: Please replace all occurrences of "urn:TBD1" in A.1. Base
this document with an IETF-controlled IRI, such as "urn:ietf:..." or
"http://...ietf.org/...".]]
A.1. 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].
<http://coreapps.org/base#lang>
Indicates that the link target is a language tag [RFC5646] that
specifies the language of the link context.
The link target MUST be a text string in the format specified in
Section 2.1 of RFC 5646 [RFC5646].
Operation Types:
<http://coreapps.org/base#update>
Indicates that the state of the form's context can be replaced
with the state described by a representation submitted to the
server.
This operation type defaults to the PUT method [RFC7231] [RFC7252]
for both HTTP and CoAP. Typical overrides by a form field include
the PATCH method [RFC5789] [RFC8132] for HTTP and CoAP and the
iPATCH method [RFC8132] for CoAP.
<http://coreapps.org/base#search>
Indicates that the form's context can be searched by submitting a
search query.
This operation type defaults to the POST method [RFC7231] for HTTP
and the FETCH method [RFC8132] for CoAP. Typical overrides by a
form field include the POST method [RFC7252] for CoAP.
A.2. Collections
Link Relation Types:
<http://www.iana.org/assignments/relation/item> <http://www.iana.org/assignments/relation/item>
Indicates that the link's context is a collection and that the Indicates that the link's context is a collection and that the
link's target is a member of that collection, as defined in link's target is a member of that collection, as defined in
Section 2.1 of RFC 6573 [RFC6573]. Section 2.1 of RFC 6573 [RFC6573].
<http://www.iana.org/assignments/relation/collection> <http://www.iana.org/assignments/relation/collection>
Indicates that the link's target is a collection and that the Indicates that the link's target is a collection and that the
link's context is a member of that collection, as defined in link's context is a member of that collection, as defined in
Section 2.2 of RFC 6573 [RFC6573]. Section 2.2 of RFC 6573 [RFC6573].
A.2. Operation Types Operation Types:
<urn:TBD1#create> <http://coreapps.org/collections#create>
Indicates that the form's context is a collection and that a new Indicates that the form's context is a collection and that a new
item can be created in that collection by submitting a suitable item can be created in that collection with the state defined by a
representation. This operation type is typically used with the representation submitted to the server.
POST method [RFC7231] [RFC7252].
<urn:TBD1#update> This operation type defaults to the POST method [RFC7231]
Indicates that the form's context can be updated by submitting a [RFC7252] for both HTTP and CoAP.
suitable representation. This operation type is typically used
with the PUT method [RFC7231] [RFC7252], PATCH method [RFC5789]
[RFC8132], or iPATCH method [RFC8132].
<urn:TBD1#delete> <http://coreapps.org/collections#delete>
Indicates that the form's context can be deleted. This operation Indicates that the form's context is a member of a collection and
type is typically used with the DELETE method [RFC7231] [RFC7252]. that the form's context can be removed from that collection.
<urn:TBD1#search> This operation type defaults to the DELETE method [RFC7231]
Indicates that the form's context can be searched by submitting a [RFC7252] for both HTTP and CoAP.
search query. This operation type is typically used with the POST
method [RFC7231] [RFC7252] or FETCH method [RFC8132].
A.3. Form Field Types A.3. HTTP
<urn:TBD1#accept> Form Field Types:
Specifies an acceptable HTTP content type or CoAP content format
for the request payload. There may be multiple form fields of <http://coreapps.org/http#method>
this type. If a form does not include a form field of this type, Specifies the HTTP method for the request.
the server accepts any or no request payload, depending on the
The form field value MUST be a text string in the format defined
in Section 4.1 of RFC 7231 [RFC7231]. The set of possible values
is maintained in the IANA HTTP Method Registry.
A form field of this type MUST NOT occur more than once in a form.
If absent, it defaults to the request method implied by the form's
operation type. operation type.
For HTTP, the content type MUST be specified as a text string in <http://coreapps.org/http#accept>
the format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the Specifies an acceptable HTTP content type for the request payload.
set of possible values is maintained in the IANA Media Types There may be multiple form fields of this type. If a form does
Registry. For CoAP, the content format MUST be specified as an not include a form field of this type, the server accepts any or
unsigned integer; the set of possible values is maintained in the no request payload, depending on the operation type.
IANA CoAP Content-Formats Registry.
A.4. Representation Metadata 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
media types and their parameters are maintained in the IANA Media
Types Registry.
<urn:TBD1#type> Representation Metadata:
Specifies the HTTP content type or CoAP content format of the
representation.
For HTTP, the content type MUST be specified as a text string in <http://coreapps.org/http#type>
the format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the Specifies the HTTP content type of the representation.
set of possible values is maintained in the IANA Media Types
Registry. For CoAP, the content format MUST be specified as an
unsigned integer; the set of possible values is maintained in the
IANA CoAP Content-Formats Registry.
A metadata item of this type MUST NOT occur more than once. If The metadata value MUST be specified as a text string in the
absent, its value defaults to content type "application/octet- format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]. The
stream" or content format 42. possible set of media types and their parameters are maintained in
the IANA Media Types Registry.
Metadata of this type MUST NOT occur more than once for a
representation. If absent, its value defaults to content type
"application/octet-stream".
A.4. CoAP
Form Field Types:
<http://coreapps.org/coap#method>
Specifies the CoAP method for the request.
The form field value MUST be an integer identifying one of the
CoAP request methods maintained in the IANA CoAP Method Codes
Registry (e.g., the integer 2 for the POST method).
A form field of this type MUST NOT occur more than once in a form.
If absent, it defaults to the request method implied by the form's
operation type.
<http://coreapps.org/coap#accept>
Specifies an acceptable CoAP content format for the request
payload. 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 no request payload, depending on the operation
type.
The form field value MUST be an integer identifying one of content
formats maintained in the IANA CoAP Content-Formats Registry.
Representation Metadata:
<http://coreapps.org/coap#type>
Specifies the CoAP content format of the representation.
The metadata value MUST be an integer identifying one of content
formats maintained in the IANA CoAP Content-Formats Registry.
Metadata of this type MUST NOT occur more than once for a
representation. If absent, it defaults to content format 42
(i.e., content type "application/octet-stream" without a content
coding).
Appendix B. Default Dictionary Appendix B. Default Dictionary
This section defines a default dictionary that is assumed when the This section defines a default dictionary that is assumed when the
"application/coral+cbor" media type is used without a "dictionary" "application/coral+cbor" media type is used without a "dictionary"
parameter. parameter.
+-----+-------------------------------------------------------+ +-----+-------------------------------------------------------+
| Key | Value | | Key | Value |
+-----+-------------------------------------------------------+ +-----+-------------------------------------------------------+
| 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 | <urn:TBD1#create> | | 3 | <http://coreapps.org/collections#create> |
| 4 | <urn:TBD1#update> | | 4 | <http://coreapps.org/base#update> |
| 5 | <urn:TBD1#delete> | | 5 | <http://coreapps.org/collections#delete> |
| 6 | <urn:TBD1#search> | | 6 | <http://coreapps.org/base#search> |
| 7 | <urn:TBD1#accept> | | 7 | <http://coreapps.org/coap#accept> |
| 8 | <urn:TBD1#type> | | 8 | <http://coreapps.org/coap#type> |
| 9 | <http://coreapps.org/base#lang> |
| 10 | <http://coreapps.org/coap#method> |
+-----+-------------------------------------------------------+ +-----+-------------------------------------------------------+
Table 2: Default Dictionary Table 2: Default Dictionary
Acknowledgements Acknowledgements
Thanks to Christian Amsuess for helpful comments and discussions that Thanks to Christian Amsuess, Carsten Bormann, Jaime Jimenez,
have shaped the document. Sebastian Kaebisch, Ari Keranen, Michael Koster, Matthias Kovatsch,
Jim Schaad, 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 Stockholm SE-16483
Sweden Sweden
Email: klaus.hartke@ericsson.com Email: klaus.hartke@ericsson.com
 End of changes. 149 change blocks. 
386 lines changed or deleted 415 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/