idnits 2.17.1 draft-ietf-core-coral-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 4, 2019) is 1634 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'I-D.ietf-core-coral' is mentioned on line 1628, but not defined == Outdated reference: A later version (-15) exists of draft-ietf-core-href-01 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE-UAX15' -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE-UAX31' -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE-UAX36' == Outdated reference: A later version (-11) exists of draft-kelly-json-hal-08 -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7320 (Obsoleted by RFC 8820) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group K. Hartke 3 Internet-Draft Ericsson 4 Intended status: Standards Track November 4, 2019 5 Expires: May 7, 2020 7 The Constrained RESTful Application Language (CoRAL) 8 draft-ietf-core-coral-01 10 Abstract 12 The Constrained RESTful Application Language (CoRAL) defines a data 13 model and interaction model as well as two specialized serialization 14 formats for the description of typed connections between resources on 15 the Web ("links"), possible operations on such resources ("forms"), 16 as well as simple resource metadata. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on May 7, 2020. 35 Copyright Notice 37 Copyright (c) 2019 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 54 2. Data and Interaction Model . . . . . . . . . . . . . . . . . 4 55 2.1. Browsing Context . . . . . . . . . . . . . . . . . . . . 5 56 2.2. Documents . . . . . . . . . . . . . . . . . . . . . . . . 5 57 2.3. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 2.4. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 2.5. Form Fields . . . . . . . . . . . . . . . . . . . . . . . 7 60 2.6. Embedded Representations . . . . . . . . . . . . . . . . 7 61 2.7. Navigation . . . . . . . . . . . . . . . . . . . . . . . 8 62 2.8. History Traversal . . . . . . . . . . . . . . . . . . . . 9 63 3. Binary Format . . . . . . . . . . . . . . . . . . . . . . . . 10 64 3.1. Data Structure . . . . . . . . . . . . . . . . . . . . . 10 65 3.1.1. Documents . . . . . . . . . . . . . . . . . . . . . . 10 66 3.1.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 10 67 3.1.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 11 68 3.1.4. Embedded Representations . . . . . . . . . . . . . . 12 69 3.1.5. Directives . . . . . . . . . . . . . . . . . . . . . 13 70 3.2. Dictionaries . . . . . . . . . . . . . . . . . . . . . . 13 71 3.2.1. Dictionary References . . . . . . . . . . . . . . . . 13 72 3.2.2. Media Type Parameter . . . . . . . . . . . . . . . . 14 73 4. Textual Format . . . . . . . . . . . . . . . . . . . . . . . 14 74 4.1. Lexical Structure . . . . . . . . . . . . . . . . . . . . 15 75 4.1.1. Line Terminators . . . . . . . . . . . . . . . . . . 15 76 4.1.2. White Space . . . . . . . . . . . . . . . . . . . . . 15 77 4.1.3. Comments . . . . . . . . . . . . . . . . . . . . . . 15 78 4.1.4. Identifiers . . . . . . . . . . . . . . . . . . . . . 16 79 4.1.5. IRIs and IRI References . . . . . . . . . . . . . . . 16 80 4.1.6. Literals . . . . . . . . . . . . . . . . . . . . . . 16 81 4.1.7. Punctuators . . . . . . . . . . . . . . . . . . . . . 20 82 4.2. Syntactic Structure . . . . . . . . . . . . . . . . . . . 20 83 4.2.1. Documents . . . . . . . . . . . . . . . . . . . . . . 21 84 4.2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 21 85 4.2.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 22 86 4.2.4. Embedded Representations . . . . . . . . . . . . . . 23 87 4.2.5. Directives . . . . . . . . . . . . . . . . . . . . . 23 88 5. Usage Considerations . . . . . . . . . . . . . . . . . . . . 24 89 5.1. Specifying CoRAL-based Applications . . . . . . . . . . . 24 90 5.1.1. Application Interfaces . . . . . . . . . . . . . . . 25 91 5.1.2. Resource Identifiers . . . . . . . . . . . . . . . . 25 92 5.1.3. Implementation Limits . . . . . . . . . . . . . . . . 26 93 5.2. Minting Vocabulary . . . . . . . . . . . . . . . . . . . 26 94 5.3. Expressing Registered Link Relation Types . . . . . . . . 27 95 5.4. Expressing Simple RDF Statements . . . . . . . . . . . . 28 96 5.5. Expressing Natural Language Texts . . . . . . . . . . . . 28 97 5.6. Embedding CoRAL in CBOR Data . . . . . . . . . . . . . . 29 98 5.7. Submitting CoRAL Documents . . . . . . . . . . . . . . . 29 99 5.7.1. PUT Requests . . . . . . . . . . . . . . . . . . . . 29 100 5.7.2. POST Requests . . . . . . . . . . . . . . . . . . . . 29 101 5.8. Returning CoRAL Documents . . . . . . . . . . . . . . . . 30 102 5.8.1. Success Responses . . . . . . . . . . . . . . . . . . 30 103 5.8.2. Error Responses . . . . . . . . . . . . . . . . . . . 30 104 6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 105 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 106 7.1. Media Type "application/coral+cbor" . . . . . . . . . . . 32 107 7.2. Media Type "text/coral" . . . . . . . . . . . . . . . . . 33 108 7.3. CoAP Content Formats . . . . . . . . . . . . . . . . . . 34 109 7.4. CBOR Tag . . . . . . . . . . . . . . . . . . . . . . . . 35 110 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 111 8.1. Normative References . . . . . . . . . . . . . . . . . . 35 112 8.2. Informative References . . . . . . . . . . . . . . . . . 37 113 Appendix A. Core Vocabulary . . . . . . . . . . . . . . . . . . 39 114 A.1. Base . . . . . . . . . . . . . . . . . . . . . . . . . . 40 115 A.2. Collections . . . . . . . . . . . . . . . . . . . . . . . 41 116 A.3. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . 41 117 A.4. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 42 118 Appendix B. Default Dictionary . . . . . . . . . . . . . . . . . 43 119 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 44 120 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 44 122 1. Introduction 124 The Constrained RESTful Application Language (CoRAL) is a language 125 for the description of typed connections between resources on the Web 126 ("links"), possible operations on such resources ("forms"), as well 127 as simple resource metadata. 129 CoRAL is intended for driving automated software agents that navigate 130 a Web application based on a standardized vocabulary of link relation 131 types and operation types. It is designed to be used in conjunction 132 with a Web transfer protocol such as the Hypertext Transfer Protocol 133 (HTTP) [RFC7230] or the Constrained Application Protocol (CoAP) 134 [RFC7252]. 136 This document defines the CoRAL data and interaction model, as well 137 as two specialized CoRAL serialization formats. 139 The CoRAL data and interaction model is a superset of the Web Linking 140 model of RFC 8288 [RFC8288]. The data model consists of two primary 141 elements: "links" that describe the relationship between two 142 resources and the type of that relationship, and "forms" that 143 describe a possible operation on a resource and the type of that 144 operation. Additionally, the data model can describe simple resource 145 metadata in a way similar to the Resource Description Framework (RDF) 147 [W3C.REC-rdf11-concepts-20140225]. In contrast to RDF, the focus of 148 CoRAL however is on the interaction with resources, not just the 149 relationships between them. The interaction model derives from HTML 150 5 [W3C.REC-html52-20171214] and specifies how an automated software 151 agent can navigate between resources by following links and perform 152 operations on resources by submitting forms. 154 The primary CoRAL serialization format is a compact, binary encoding 155 of links and forms in Concise Binary Object Representation (CBOR) 156 [RFC7049]. It is intended for environments with constraints on 157 power, memory, and processing resources [RFC7228] and shares many 158 similarities with the message format of the Constrained Application 159 Protocol (CoAP) [RFC7252]: For example, it uses numeric identifiers 160 instead of verbose strings for link relation types and operation 161 types, and pre-parses Uniform Resource Identifiers (URIs) [RFC3986] 162 into (what CoAP considers to be) their components, which simplifies 163 URI processing for constrained nodes a lot. As a result, link 164 serializations in CoRAL are often much more compact than equivalent 165 serializations in CoRE Link Format [RFC6690]. 167 The secondary CoRAL serialization format is a lightweight, textual 168 encoding of links and forms that is intended to be easy to read and 169 write for humans. The format is loosely inspired by the syntax of 170 Turtle [W3C.REC-turtle-20140225] and is mainly intended for giving 171 examples. 173 1.1. Notational Conventions 175 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 176 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 177 "OPTIONAL" in this document are to be interpreted as described in BCP 178 14 [RFC2119] [RFC8174] when, and only when, they appear in all 179 capitals, as shown here. 181 Terms defined in this document appear in _cursive_ where they are 182 introduced. 184 2. Data and Interaction Model 186 The Constrained RESTful Application Language (CoRAL) is designed for 187 building Web-based applications [W3C.REC-webarch-20041215] in which 188 automated software agents navigate between resources by following 189 links and perform operations on resources by submitting forms. 191 2.1. Browsing Context 193 Borrowing from HTML 5 [W3C.REC-html52-20171214], each such agent 194 maintains a _browsing context_ in which the representations of Web 195 resources are processed. (In HTML 5, the browsing context typically 196 corresponds to a tab or window in a Web browser.) 198 At any time, one representation in each browsing context is 199 designated the _active_ representation. 201 2.2. Documents 203 A resource representation in one of the CoRAL serialization formats 204 is called a CoRAL _document_. The URI that was used to retrieve such 205 a document is called the document's _retrieval context_. 207 A CoRAL document consists of a list of zero or more links, forms, and 208 embedded resource representations, collectively called _elements_. 209 CoRAL serialization formats may define additional types of elements 210 for efficiency or convenience, such as a base for relative URI 211 references [RFC3986]. 213 2.3. Links 215 A _link_ describes a relationship between two resources on the Web 216 [RFC8288]. As defined in RFC 8288, it consists of a _link context_, 217 a _link relation type_, and a _link target_. In CoRAL, a link can 218 additionally have a nested list of zero or more elements, which take 219 the place of link target attributes. 221 A link can be viewed as a statement of the form "{link context} has a 222 {link relation type} resource at {link target}" where the link target 223 may be further described by nested elements. 225 The link relation type identifies the semantics of a link. In HTML 5 226 and RFC 8288, link relation types are typically denoted by an IANA- 227 registered name, such as "stylesheet" or "type". In CoRAL, they are 228 denoted by an Internationalized Resource Identifier (IRI) [RFC3987] 229 such as or 230 . This allows for 231 the creation of new link relation types without the risk of 232 collisions when from different organizations or domains of knowledge. 233 An IRI also can lead to documentation, schema, and other information 234 about the link relation type. These IRIs are only used as identity 235 tokens, though, and are compared using Simple String Comparison 236 (Section 5.1 of RFC 3987). 238 The link context and the link target are both denoted by either a URI 239 reference or a literal (similarly to RDF). If the URI scheme 240 indicates a Web transfer protocol such as HTTP or CoAP, then an agent 241 can dereference the URI and navigate the browsing context to the 242 referenced resource; this is called _following the link_. A literal 243 directly identifies a value: a Boolean value, an integer, a floating- 244 point number, a date/time value, a byte string, or a text string. 246 A link can occur as a top-level element in a document or as a nested 247 element within a link. When a link occurs as a top-level element, 248 the link context implicitly is the document's retrieval context. 249 When a link occurs nested within a link, the link context of the 250 inner link is the link target of the outer link. 252 There are no restrictions on the cardinality of links; there can be 253 multiple links to and from a particular target, and multiple links of 254 the same or different types between a given link context and target. 255 However, the nested data structure constrains the description of a 256 resource graph to a tree: Links between linked resources can only be 257 described by further nesting links. 259 2.4. Forms 261 A _form_ provides instructions to an agent for performing an 262 operation on a Web resource. It consists of a _form context_, an 263 _operation type_, a _request method_, and a _submission target_. 264 Additionally, a form may be accompanied by a list of _form fields_. 266 A form can be viewed as an instruction of the form "To perform an 267 {operation type} operation on {form context}, make a {request method} 268 request to {submission target}" where the request may be further 269 described by form fields. 271 The operation type identifies the semantics of the operation. 272 Operation types are denoted like link relation types by an IRI. 274 The form context is the resource on which an operation is ultimately 275 performed. To perform the operation, an agent needs to construct a 276 request with the specified method and the specified submission target 277 as the request URI. Usually, the submission target is the same 278 resource as the form context, but it may be a different resource. 279 Constructing and sending the request is called _submitting the form_. 281 Form fields, specified in the next section, can be used to provide 282 more detailed instructions to the agent for constructing the request. 283 For example, form fields can instruct the agent to include a payload 284 or certain headers in the request that must match the specifications 285 of the form fields. 287 A form can occur as a top-level element in a document or as a nested 288 element within a link. When a form occurs as a top-level element, 289 the form context implicitly is the document's retrieval context. 290 When a form occurs nested within a link, the form context is the link 291 target of the enclosing link. 293 2.5. Form Fields 295 Form fields provide further instructions to agents for constructing a 296 request. 298 For example, a form field could identify one or more data items that 299 need to be included in the request payload or reference another 300 resource (such as a schema) that describes the structure of the 301 payload. A form field could also provide other kinds of information, 302 such as acceptable media types for the payload or expected request 303 headers. Form fields may be specific to the protocol used for 304 submitting the form. 306 A form field is the pair of a _form field type_ and a _form field 307 value_. 309 The form field type identifies the semantics of the form field. Form 310 field types are denoted like link relation types and operation types 311 by an IRI. 313 The form field value can be either a URI reference, a Boolean value, 314 an integer, a floating-point number, a date/time value, a byte 315 string, or a text string. 317 2.6. Embedded Representations 319 When a document contains links to many resources and an agent needs a 320 representation of each link target, it may be inefficient to retrieve 321 each of these representations individually. To alleviate this, 322 documents can directly embed representations of resources. 324 An _embedded representation_ consists of a sequence of bytes, labeled 325 with _representation metadata_. 327 An embedded representation may be a full, partial, or inconsistent 328 version of the representation served from the URI of the resource. 330 An embedded representation can occur as a top-level element in a 331 document or as a nested element within a link. When it occurs as a 332 top-level element, it provides an alternate representation of the 333 document's retrieval context. When it occurs nested within a link, 334 it provides a representation of link target of the enclosing link. 336 2.7. Navigation 338 An agent begins interacting with an application by performing a GET 339 request on an _entry point URI_. The entry point URI is the only URI 340 an agent is expected to know before interacting with an application. 341 From there, the agent is expected to make all requests by following 342 links and submitting forms provided by the server in responses. The 343 entry point URI can be obtained by manual configuration or through 344 some discovery process. 346 If dereferencing the entry point URI yields a CoRAL document (or any 347 other representation that implements the CoRAL data and interaction 348 model), then the agent makes this document the active representation 349 in the browsing context and proceeds as follows: 351 1. The first step for the agent is to decide what to do next, i.e., 352 which type of link to follow or form to submit, based on the link 353 relation types and operation types it understands. 355 2. The agent then finds the link(s) or form(s) with the respective 356 type in the active representation. This may yield one or more 357 candidates, from which the agent will have to select the most 358 appropriate one. The set of candidates may be empty, for 359 example, when a transition is not supported or not allowed. 361 3. The agent selects one of the candidates based on the metadata 362 associated with each of these. Metadata includes the content 363 type of the target resource representation, the URI scheme, the 364 request method, and other information that is provided as nested 365 elements in a link or form fields in a form. 367 If the selected candidate contains an embedded representation, 368 the agent MAY skip the following steps and immediately proceed 369 with step 8. 371 4. The agent obtains the _request URI_ from the link target or 372 submission target. Fragment identifiers are not part of the 373 request URI and MUST be separated from the rest of the URI prior 374 to a dereference. 376 5. The agent constructs a new request with the request URI. If the 377 agent is following a link, then the request method MUST be GET. 378 If the agent is submitting a form, then the request method MUST 379 be the one specified by the form. An IRI may need to be 380 converted to a URI (Section 3.1 of RFC 3987) for protocols that 381 do not support IRIs. 383 The agent should set HTTP header fields and CoAP request options 384 according to metadata associated with the link or form (e.g., set 385 the HTTP Accept header field or the CoAP Accept option when the 386 media type of the target resource is provided). Depending on the 387 operation type of a form, the agent may also need to include a 388 request payload that matches the specifications of one or more 389 form fields. 391 6. The agent sends the request and receives the response. 393 7. If a fragment identifier was separated from the request URI, the 394 agent dereferences the fragment identifier within the received 395 representation. 397 8. The agent _updates the browsing context_ by making the (embedded 398 or received) representation the active representation. 400 9. Finally, the agent processes the representation according to the 401 semantics of the content type. If the representation is a CoRAL 402 document (or any other representation that implements the CoRAL 403 data and interaction model), this means the agent has the choice 404 of what to do next again -- and the cycle repeats. 406 2.8. History Traversal 408 A browsing context MAY entail a _session history_ that lists the 409 resource representations that the agent has processed, is processing, 410 or will process. 412 An entry in the session history consists of a resource representation 413 and the request URI that was used to retrieve the representation. 414 New entries are added to the session history as the agent navigates 415 from resource to resource. 417 An agent can navigate a browsing context by _traversing the session 418 history_ in addition to following links and submitting forms. For 419 example, if an agent received a representation that doesn't contain 420 any further links or forms, it can revert the active representation 421 back to one it has visited earlier. 423 Traversing the history should take advantage of caches to avoid new 424 requests. An agent MAY reissue a safe request (e.g., a GET request) 425 when it doesn't have a fresh representation in its cache. An agent 426 MUST NOT reissue an unsafe request (e.g., a PUT or POST request) 427 unless it intends to perform that operation again. 429 3. Binary Format 431 This section defines the encoding of documents in the CoRAL binary 432 format. 434 A document in the binary format is a data item in Concise Binary 435 Object Representation (CBOR) [RFC7049]. The structure of this data 436 item is presented in the Concise Data Definition Language (CDDL) 437 [RFC8610]. The media type is "application/coral+cbor". 439 The following restrictions are placed on CBOR encoders: Byte strings 440 and text strings MUST be encoded with definite length. Integers and 441 floating-point values MUST be encoded as such (e.g., a floating-point 442 value of 0.0 must not be encoded as the integer 0). 444 3.1. Data Structure 446 The data structure of a document in the binary format is made up of 447 four kinds of elements: links, forms, embedded representations, and 448 (as an extension to the CoRAL data model) base directives. Base 449 directives provide a way to encode URI references with a common base 450 more efficiently. 452 Elements are processed in the order they appear in the document. 453 Document processors need to maintain an _environment_ while iterating 454 an array of elements. The environment consists of two variables: the 455 _current context_ and the _current base_. Both the current context 456 and the current base are initially set to the document's retrieval 457 context. 459 3.1.1. Documents 461 The body of a document in the binary format is encoded as an array of 462 zero or more links, forms, embedded representations, and directives. 464 document = body 466 body = [*(link / form / representation / directive)] 468 3.1.2. Links 470 A link is encoded as an array that consists of the unsigned integer 471 2, followed by the link relation type and the link target, optionally 472 followed by a link body that contains nested elements. 474 link = [2, relation-type, link-target, ?body] 476 The link relation type is encoded as a text string that conforms to 477 the syntax of an IRI [RFC3987]. 479 relation-type = text 481 The link target is denoted by a Constrained Resource Identifier 482 (CoRI) reference [I-D.ietf-core-href] or represented by a literal 483 value. A CoRI reference MUST be resolved against the current base. 484 The link target may be null, which indicates that the link target is 485 an unidentified resource. 487 link-target = CoRI / literal 489 CoRI = 491 literal = bool / int / float / time / bytes / text / null 493 The array of elements in the link body, if any, MUST be processed in 494 a fresh environment. Both the current context and the current base 495 in the new environment are initially set to the link target of the 496 enclosing link. 498 3.1.3. Forms 500 A form is encoded as an array that consists of the unsigned integer 501 3, followed by the operation type and the submission target, 502 optionally followed by a list of form fields. 504 form = [3, operation-type, submission-target, ?form-fields] 506 The operation type is defined in the same way as a link relation type 507 (Section 3.1.2). 509 operation-type = text 511 The request method is either implied by the operation type or encoded 512 as a form field. If there are both, the form field takes precedence 513 over the operation type. Either way, the method MUST be defined for 514 the Web transfer protocol identified by the scheme of the submission 515 target. 517 The submission target is denoted by a CoRI reference. This CoRI 518 reference MUST be resolved against the current base. 520 submission-target = CoRI 522 3.1.3.1. Form Fields 524 A list of form fields is encoded as an array of zero or more type- 525 value pairs. 527 form-fields = [*(form-field-type, form-field-value)] 529 The list, if any, MUST be processed in a fresh environment. Both the 530 current context and the current base in the new environment are 531 initially set to the submission target of the enclosing form. 533 A form field type is defined in the same way as a link relation type 534 (Section 3.1.2). 536 form-field-type = text 538 A form field value can be a CoRI reference, a Boolean value, an 539 integer, a floating-point number, a date/time value, a byte string, a 540 text string, or null. A CoRI reference MUST be resolved against the 541 current base. 543 form-field-value = CoRI / literal 545 3.1.4. Embedded Representations 547 An embedded representation is encoded as an array that consists of 548 the unsigned integer 0, followed by a byte string containing the 549 representation data, optionally followed by representation metadata. 551 representation = [0, bytes, ?representation-metadata] 553 Representation metadata is encoded as an array of zero or more name- 554 value pairs. 556 representation-metadata = [*(metadata-name, metadata-value)] 558 The metadata, if any, MUST be processed in a fresh environment. All 559 variables in the new environment are initially set to a copy of the 560 variables in the current environment. 562 The metadata name is defined in the same way as a link relation type 563 (Section 3.1.2). 565 metadata-name = text 567 A metadata value can be a CoRI reference, a Boolean value, an 568 integer, a floating-point number, a date/time value, a byte string, a 569 text string, or null. A CoRI reference MUST be resolved against the 570 current base. 572 metadata-value = CoRI / literal 574 3.1.5. Directives 576 Directives provide the ability to manipulate the environment when 577 processing a list of elements. There is one type of directives 578 available: the Base directive. 580 directive = base-directive 582 3.1.5.1. Base Directives 584 A Base directive is encoded as an array that consists of the unsigned 585 integer 1, followed by a base. 587 base-directive = [1, base] 589 The base is denoted by a CoRI reference. This CoRI reference MUST be 590 resolved against the current context (not the current base). 592 base = CoRI 594 The directive is processed by resolving the CoRI reference against 595 the current context and assigning the result to the current base. 597 3.2. Dictionaries 599 The binary format can reference values from a dictionary to reduce 600 representation size and processing cost. Dictionary references can 601 be used in place of link relation types, link targets, operation 602 types, submission targets, form field types, form field values, 603 representation metadata names, and representation metadata values. 605 3.2.1. Dictionary References 607 A dictionary reference is encoded as an unsigned integer. Where a 608 dictionary reference cannot be expressed unambiguously, the unsigned 609 integer is tagged with CBOR tag TBD6. 611 relation-type /= uint 613 link-target /= #6.TBD6(uint) 615 operation-type /= uint 616 submission-target /= #6.TBD6(uint) 618 form-field-type /= uint 620 form-field-value /= #6.TBD6(uint) 622 metadata-name /= uint 624 metadata-value /= #6.TBD6(uint) 626 3.2.2. Media Type Parameter 628 The "application/coral+cbor" media type is defined to have a 629 "dictionary" parameter that specifies the dictionary in use. The 630 dictionary is identified by a URI [RFC3986]. For example, a CoRAL 631 document that uses the dictionary identified by the URI 632 can use the following content type: 634 application/coral+cbor;dictionary="http://example.com/dictionary" 636 The URI serves only as an identifier; it does not necessarily have to 637 be dereferencable (or even use a dereferencable URI scheme). It is 638 permissible, though, to use a dereferencable URI and to serve a 639 representation that provides information about the dictionary in a 640 human- or machine-readable way. (The format of such a representation 641 is outside the scope of this document.) 643 For simplicity, a CoRAL document can reference values only from one 644 dictionary; the value of the "dictionary" parameter MUST be a single 645 URI. If the "dictionary" parameter is absent, the default dictionary 646 specified in Appendix B of this document is assumed. 648 Once a dictionary has made an assignment, the assignment MUST NOT be 649 changed or removed. A dictionary, however, may contain additional 650 information about an assignment, which may change over time. 652 In CoAP [RFC7252], media types (including specific values for media 653 type parameters) are encoded as an unsigned integer called "content 654 format". For use with CoAP, each new CoRAL dictionary MUST register 655 a new content format in the IANA CoAP Content-Formats Registry. 657 4. Textual Format 659 This section defines the syntax of documents in the CoRAL textual 660 format using two grammars: The lexical grammar defines how Unicode 661 characters are combined to form line terminators, white space, 662 comments, and tokens. The syntactic grammar defines how tokens are 663 combined to form documents. Both grammars are presented in Augmented 664 Backus-Naur Form (ABNF) [RFC5234]. 666 A document in the textual format is a Unicode string in a Unicode 667 encoding form [UNICODE]. The media type for such documents is "text/ 668 coral". The "charset" parameter is not used; charset information is 669 transported inside the document in the form of an OPTIONAL Byte Order 670 Mark (BOM). The use of the UTF-8 encoding scheme [RFC3629], without 671 a BOM, is RECOMMENDED. 673 4.1. Lexical Structure 675 The lexical structure of a document in the textual format is made up 676 of four basic elements: line terminators, white space, comments, and 677 tokens. Of these, only tokens are significant in the syntactic 678 grammar. There are five kinds of tokens: identifiers, IRIs, IRI 679 references, literals, and punctuators. 681 token = identifier / iri / iriref / literal / punctuator 683 When several lexical grammar rules match a sequence of characters in 684 a document, the longest match takes priority. 686 4.1.1. Line Terminators 688 Line terminators divide text into lines. A line terminator is any 689 Unicode character with Line_Break class BK, CR, LF, or NL. However, 690 any CR character that immediately precedes a LF character is ignored. 691 (This affects only the numbering of lines in error messages.) 693 4.1.2. White Space 695 White space is a sequence of one or more white space characters. A 696 white space character is any Unicode character with the White_Space 697 property. 699 4.1.3. Comments 701 Comments are sequences of characters that are ignored when parsing 702 text into tokens. Single-line comments begin with the characters 703 "//" and extend to the end of the line. Delimited comments begin 704 with the characters "/*" and end with the characters "*/". Delimited 705 comments can occupy a portion of a line, a single line, or multiple 706 lines. 708 Comments do not nest. The character sequences "/*" and "*/" have no 709 special meaning within a single-line comment; the character sequences 710 "//" and "/*" have no special meaning within a delimited comment. 712 4.1.4. Identifiers 714 An identifier token is a user-defined symbolic name. The rules for 715 identifiers correspond to those recommended by the Unicode Standard 716 Annex #31 [UNICODE-UAX31] using the following profile: 718 identifier = START *CONTINUE *(MEDIAL 1*CONTINUE) 720 START = 722 CONTINUE = 724 MEDIAL = "-" / "." / "~" / %x58A / %xF0B 726 MEDIAL =/ %x2010 / %x2027 / %x30A0 / %x30FB 728 All identifiers MUST be converted into Unicode Normalization Form C 729 (NFC), as defined by the Unicode Standard Annex #15 [UNICODE-UAX15]. 730 Comparison of identifiers is based on NFC and is case-sensitive 731 (unless otherwise noted). 733 4.1.5. IRIs and IRI References 735 IRIs and IRI references are Unicode strings that conform to the 736 syntax defined in RFC 3987 [RFC3987]. An IRI reference can be either 737 an IRI or a relative reference. Both IRIs and IRI references are 738 enclosed in angle brackets ("<" and ">"). 740 iri = "<" IRI ">" 742 iriref = "<" IRI-reference ">" 744 IRI = 746 IRI-reference = 748 4.1.6. Literals 750 A literal is a textual representation of a value. There are seven 751 types of literals: Boolean, integer, floating-point, date/time, byte 752 string, text string, and null. 754 literal = boolean / integer / float / datetime / bytes / text 756 literal =/ null 758 4.1.6.1. Boolean Literals 760 The case-insensitive tokens "true" and "false" denote the Boolean 761 values true and false, respectively. 763 boolean = "true" / "false" 765 4.1.6.2. Integer Literals 767 Integer literals denote an integer value of unspecified precision. 768 By default, integer literals are expressed in decimal, but they can 769 also be specified in an alternate base using a prefix: Binary 770 literals begin with "0b", octal literals begin with "0o", and 771 hexadecimal literals begin with "0x". 773 Decimal literals contain the digits "0" through "9". Binary literals 774 contain "0" and "1", octal literals contain "0" through "7", and 775 hexadecimal literals contain "0" through "9" as well as "A" through 776 "F" in upper- or lowercase. 778 Negative integers are expressed by prepending a minus sign ("-"). 780 integer = ["+" / "-"] (decimal / binary / octal / hexadecimal) 782 decimal = 1*DIGIT 784 binary = %x30 (%x42 / %x62) 1*BINDIG 786 octal = %x30 (%x4F / %x6F) 1*OCTDIG 788 hexadecimal = %x30 (%x58 / %x78) 1*HEXDIG 790 DIGIT = %x30-39 792 BINDIG = %x30-31 794 OCTDIG = %x30-37 796 HEXDIG = %x30-39 / %x41-46 / %x61-66 798 4.1.6.3. Floating-point Literals 800 Floating-point literals denote a floating-point number of unspecified 801 precision. 803 Floating-point literals consist of a sequence of decimal digits 804 followed by a fraction, an exponent, or both. The fraction consists 805 of a decimal point (".") followed by a sequence of decimal digits. 807 The exponent consists of the letter "e" in upper- or lowercase, 808 followed by an optional sign and a sequence of decimal digits that 809 indicate a power of 10 by which the value preceding the "e" is 810 multiplied. 812 Negative floating-point values are expressed by prepending a minus 813 sign ("-"). 815 float = ["+" / "-"] 1*DIGIT [fraction] [exponent] 817 fraction = "." 1*DIGIT 819 exponent = (%x45 / %x65) ["+" / "-"] 1*DIGIT 821 A floating-point literal can additionally denote either the special 822 "Not-a-Number" (NaN) value, positive infinity, or negative infinity. 823 The NaN value is produced by the case-insensitive token "NaN". The 824 two infinite values are produced by the case-insensitive tokens 825 "+Infinity" (or simply "Infinity") and "-Infinity". 827 float =/ "NaN" 829 float =/ ["+" / "-"] "Infinity" 831 4.1.6.4. Date/Time Literals 833 Date/time literals denote an instant in time. 835 A date/time literal consists of the prefix "dt" and a sequence of 836 Unicode characters in Internet Date/Time Format [RFC3339], enclosed 837 in single quotes. 839 datetime = %x64.74 SQUOTE date-time SQUOTE 841 date-time = 843 SQUOTE = %x27 845 4.1.6.5. Byte String Literals 847 Byte string literals denote an ordered sequence of bytes. 849 A byte string literal consists of a prefix and zero or more bytes 850 encoded in Base16, Base32, or Base64 [RFC4648], enclosed in single 851 quotes. Byte string literals encoded in Base16 begin with "h" or 852 "b16", byte string literals encoded in Base32 begin with "b32", and 853 byte string literals encoded in Base64 begin with "b64". 855 bytes = base16 / base32 / base64 857 base16 = (%x68 / %x62.31.36) SQUOTE SQUOTE 859 base32 = %x62.33.32 SQUOTE SQUOTE 861 base64 = %x62.36.34 SQUOTE SQUOTE 863 4.1.6.6. Text String Literals 865 Text string literals denote a Unicode string. 867 A text string literal consists of zero or more Unicode characters 868 enclosed in double quotes. It can include simple escape sequences 869 (such as \t for the tab character) as well as hexadecimal and Unicode 870 escape sequences. 872 text = DQUOTE *(char / %x5C escape) DQUOTE 874 char = 876 escape = simple-escape / hexadecimal-escape / unicode-escape 878 simple-escape = %x30 / %x62 / %x74 / %x6E / %x76 880 simple-escape =/ %x66 / %x72 / %x22 / %x27 / %x5C 882 hexadecimal-escape = (%x78 / %x58) 2HEXDIG 884 unicode-escape = %x75 4HEXDIG / %x55 8HEXDIG 886 DQUOTE = %x22 888 An escape sequence denotes a single Unicode code point. For 889 hexadecimal and Unicode escape sequences, the code point is expressed 890 by the hexadecimal number following the "\x", "\X", "\u", or "\U" 891 prefix. Simple escape sequences indicate the code points listed in 892 Table 1. 894 +-----------------+------------+----------------------+ 895 | Escape Sequence | Code Point | Character Name | 896 +-----------------+------------+----------------------+ 897 | \0 | U+0000 | Null | 898 | \b | U+0008 | Backspace | 899 | \t | U+0009 | Character Tabulation | 900 | \n | U+000A | Line Feed | 901 | \v | U+000B | Line Tabulation | 902 | \f | U+000C | Form Feed | 903 | \r | U+000D | Carriage Return | 904 | \" | U+0022 | Quotation Mark | 905 | \' | U+0027 | Apostrophe | 906 | \\ | U+005C | Reverse Solidus | 907 +-----------------+------------+----------------------+ 909 Table 1: Simple Escape Sequences 911 4.1.6.7. Null Literal 913 The case-insensitive tokens "null" and "_" denote the intentional 914 absence of any value. 916 null = "null" / "_" 918 4.1.7. Punctuators 920 Punctuator tokens are used for grouping and separating. 922 punctuator = "#" / ":" / "*" / "[" / "]" / "{" / "}" / "=" / "->" 924 4.2. Syntactic Structure 926 The syntactic structure of a document in the textual format is made 927 up of four kinds of elements: links, forms, embedded representations, 928 and (as an extension to the CoRAL data model) directives. Directives 929 provide a way to make documents easier to read and write by setting a 930 base for relative IRI references and introducing shorthands for IRIs. 932 Elements are processed in the order they appear in the document. 933 Document processors need to maintain an _environment_ while iterating 934 a list of elements. The environment consists of three variables: the 935 _current context_, the _current base_, and the _current mapping from 936 identifiers to IRIs_. Both the current context and the current base 937 are initially set to the document's retrieval context. The current 938 mapping from identifiers to IRIs is initially empty. 940 4.2.1. Documents 942 The body of a document in the textual format consists of zero or more 943 links, forms, embedded representations, and directives. 945 document = body 947 body = *(link / form / representation / directive) 949 4.2.2. Links 951 A link consists of the link relation type, followed by the link 952 target, optionally followed by a link body enclosed in curly brackets 953 ("{" and "}"). 955 link = relation-type link-target ["{" body "}"] 957 The link relation type is denoted by either an IRI, a simple name, or 958 a qualified name. 960 relation-type = iri / simple-name / qualified-name 962 A simple name consists of an identifier. It is resolved to an IRI by 963 looking up the empty string in the current mapping from identifiers 964 to IRIs and appending the specified identifier to the result. It is 965 an error if the empty string is not present in the current mapping. 967 simple-name = identifier 969 A qualified name consists of two identifiers separated by a colon 970 (":"). It is resolved to an IRI by looking up the identifier on the 971 left hand side in the current mapping from identifiers to IRIs and 972 appending the identifier on the right hand side to the result. It is 973 an error if the identifier on the left hand side is not present in 974 the current mapping. 976 qualified-name = identifier ":" identifier 978 The link target is denoted by an IRI reference or represented by a 979 value literal. An IRI reference MUST be resolved against the current 980 base. If the link target is null, the link target is an unidentified 981 resource. 983 link-target = iriref / literal 985 The list of elements in the link body, if any, MUST be processed in a 986 fresh environment. Both the current context and current base in this 987 environment are initially set to the link target of the enclosing 988 link. The mapping from identifiers to IRIs is initially set to a 989 copy of the mapping from identifiers to IRIs in the current 990 environment. 992 4.2.3. Forms 994 A form consists of the operation type, followed by a "->" token and 995 the submission target, optionally followed by a list of form fields 996 enclosed in square brackets ("[" and "]"). 998 form = operation-type "->" submission-target ["[" form-fields "]"] 1000 The operation type is defined in the same way as a link relation type 1001 (Section 4.2.2). 1003 operation-type = iri / simple-name / qualified-name 1005 The request method is either implied by the operation type or encoded 1006 as a form field. If there are both, the form field takes precedence 1007 over the operation type. Either way, the method MUST be defined for 1008 the Web transfer protocol identified by the scheme of the submission 1009 target. 1011 The submission target is denoted by an IRI reference. This IRI 1012 reference MUST be resolved against the current base. 1014 submission-target = iriref 1016 4.2.3.1. Form Fields 1018 A list of form fields consists of zero or more type-value pairs. 1020 form-fields = *(form-field-type form-field-value) 1022 The list, if any, MUST be processed in a fresh environment. Both the 1023 current context and the current base in this environment are 1024 initially set to the submission target of the enclosing form. The 1025 mapping from identifiers to IRIs is initially set to a copy of the 1026 mapping from identifiers to IRIs in the current environment. 1028 The form field type is defined in the same way as a link relation 1029 type (Section 4.2.2). 1031 form-field-type = iri / simple-name / qualified-name 1033 The form field value can be an IRI reference, Boolean literal, 1034 integer literal, floating-point literal, byte string literal, text 1035 string literal, or null. An IRI reference MUST be resolved against 1036 the current base. 1038 form-field-value = iriref / literal 1040 4.2.4. Embedded Representations 1042 An embedded representation consists of a "*" token, followed by the 1043 representation data, optionally followed by representation metadata 1044 enclosed in square brackets ("[" and "]"). 1046 representation = "*" bytes ["[" representation-metadata "]"] 1048 Representation metadata consists of zero or more name-value pairs. 1050 representation-metadata = *(metadata-name metadata-value) 1052 The metadata, if any, MUST be processed in a fresh environment. All 1053 variables in the new environment are initially set to a copy of the 1054 variables in the current environment. 1056 The metadata name is defined in the same way as a link relation type 1057 (Section 4.2.2). 1059 metadata-name = iri / simple-name / qualified-name 1061 The metadata value can be an IRI reference, Boolean literal, integer 1062 literal, floating-point literal, byte string literal, text string 1063 literal, or null. An IRI reference MUST be resolved against the 1064 current base. 1066 metadata-value = iriref / literal 1068 4.2.5. Directives 1070 Directives provide the ability to manipulate the environment when 1071 processing a list of elements. All directives start with a number 1072 sign ("#") followed by a directive identifier. Directive identifiers 1073 are case-insensitive and constrained to Unicode characters in the 1074 Basic Latin block. 1076 The following two types of directives are available: the Base 1077 directive and the Using directive. 1079 directive = base-directive / using-directive 1081 4.2.5.1. Base Directives 1083 A Base directive consists of a number sign ("#"), followed by the 1084 case-insensitive identifier "base", followed by a base. 1086 base-directive = "#" "base" base 1088 The base is denoted by an IRI reference. The IRI reference MUST be 1089 resolved against the current context (not the current base). 1091 base = iriref 1093 The directive is processed by resolving the IRI reference against the 1094 current context and assigning the result to the current base. 1096 4.2.5.2. Using Directives 1098 A Using directive consists of a number sign ("#"), followed by the 1099 case-insensitive identifier "using", optionally followed by an 1100 identifier and an equals sign ("="), finally followed by an IRI. If 1101 the identifier is not specified, it is assumed to be the empty 1102 string. 1104 using-directive = "#" "using" [identifier "="] iri 1106 The directive is processed by adding the specified identifier and IRI 1107 to the current mapping from identifiers to IRIs. It is an error if 1108 the identifier is already present in the mapping. 1110 5. Usage Considerations 1112 This section discusses some considerations in creating CoRAL-based 1113 applications and vocabularies. 1115 5.1. Specifying CoRAL-based Applications 1117 CoRAL-based applications naturally implement the Web architecture 1118 [W3C.REC-webarch-20041215] and thus are centered around orthogonal 1119 specifications for identification, interaction, and representation: 1121 o Resources are identified by IRIs or represented by value literals. 1123 o Interactions are based on the hypermedia interaction model of the 1124 Web and the methods provided by the Web transfer protocol. The 1125 semantics of possible interactions are identified by link relation 1126 types and operation types. 1128 o Representations are CoRAL documents encoded in the binary format 1129 defined in Section 3 or the textual format defined in Section 4. 1130 Depending on the application, additional representation formats 1131 may be used. 1133 5.1.1. Application Interfaces 1135 Specifications for CoRAL-based applications need to list the specific 1136 components used in the application interface and their identifiers. 1137 This should include the following items: 1139 o URI schemes that identify the Web transfer protocol(s) used in the 1140 application. 1142 o Internet media types that identify the representation format(s) 1143 used in the application, including the media type(s) of the CoRAL 1144 serialization format(s). 1146 o Link relation types that identify the semantics of links. 1148 o Operation types that identify the semantics of forms. 1149 Additionally, for each operation type, the permissible request 1150 method(s). 1152 o Form field types that identify the semantics of form fields. 1153 Additionally, for each form field type, the permissible form field 1154 values. 1156 o Metadata names that identify the semantics of representation 1157 metadata. Additionally, for each metadata name, the permissible 1158 metadata values. 1160 5.1.2. Resource Identifiers 1162 URIs [RFC3986] are a cornerstone of Web-based applications. They 1163 enable the uniform identification of resources and are used every 1164 time a client interacts with a server or a resource representation 1165 needs to refer to another resource. 1167 URIs often include structured application data in the path and query 1168 components, such as paths in a filesystem or keys in a database. It 1169 is a common practice in many HTTP-based application programming 1170 interfaces (APIs) to make this part of the application specification, 1171 i.e., to prescribe fixed URI templates that are hard-coded in 1172 implementations. There are a number of problems with this practice 1173 [RFC7320], though. 1175 In CoRAL-based applications, resource names are therefore not part of 1176 the application specification -- they are an implementation detail. 1177 The specification of a CoRAL-based application MUST NOT mandate any 1178 particular form of resource name structure. BCP 190 [RFC7320] 1179 describes the problematic practice of fixed URI structures in more 1180 detail and provides some acceptable alternatives. 1182 5.1.3. Implementation Limits 1184 This document places no restrictions on the number of elements in a 1185 CoRAL document or the depth of nested elements. Applications using 1186 CoRAL (in particular those running in constrained environments) may 1187 wish to limit these numbers and specify implementation limits that an 1188 application implementation must at least support to be interoperable. 1190 Applications may also mandate the following and other restrictions: 1192 o use of only either the binary format or the text format; 1194 o use of only either HTTP or CoAP as supported Web transfer 1195 protocol; 1197 o use of only dictionary references in the binary format for certain 1198 vocabulary; 1200 o use of only either content type strings or content format IDs; 1202 o use of CoRI references only up to a specific length; 1204 o use of CBOR in a canonical format (see Section 3.9 of RFC 7049). 1206 5.2. Minting Vocabulary 1208 New link relation types, operation types, form field types, and 1209 metadata names can be minted by defining an IRI [RFC3987] that 1210 uniquely identifies the item. Although the IRI can point to a 1211 resource that contains a definition of the semantics, clients SHOULD 1212 NOT automatically access that resource to avoid overburdening its 1213 server. The IRI SHOULD be under the control of the person or party 1214 defining it, or be delegated to them. 1216 To avoid interoperability problems, it is RECOMMENDED that only IRIs 1217 are minted that are normalized according to Section 5.3 of RFC 3987. 1218 Non-normalized forms that are best avoided include: 1220 o Uppercase characters in scheme names and domain names 1221 o Percent-encoding of characters where it is not required by the IRI 1222 syntax 1224 o Explicitly stated HTTP default port (e.g., 1225 is preferable over ) 1227 o Completely empty path in HTTP IRIs (e.g., is 1228 preferable over ) 1230 o Dot segments ("/./" or "/../") in the path component of an IRI 1232 o Lowercase hexadecimal letters within percent-encoding triplets 1233 (e.g., "%3F" is preferable over "%3f") 1235 o Punycode-encoding of Internationalized Domain Names in IRIs 1237 o IRIs that are not in Unicode Normalization Form C [UNICODE-UAX15] 1239 IRIs that identify vocabulary do not need to be registered. The 1240 inclusion of domain names in IRIs allows for the decentralized 1241 creation of new IRIs without the risk of collisions. 1243 However, IRIs can be relatively verbose and impose a high overhead on 1244 a representation. This can be a problem in constrained environments 1245 [RFC7228]. Therefore, CoRAL alternatively allows the use of unsigned 1246 integers to reference CBOR data items from a dictionary, as specified 1247 in Section 3.2. These impose a much smaller overhead but instead 1248 need to be assigned by an authority to avoid collisions. 1250 5.3. Expressing Registered Link Relation Types 1252 Link relation types registered in the IANA Link Relations Registry, 1253 such as "collection" [RFC6573] or "icon" [W3C.REC-html52-20171214], 1254 can be used in CoRAL by appending the registered name to the IRI 1255 : 1257 #using iana = 1259 iana:collection 1260 iana:icon 1262 Note that registered link relation types are required to be 1263 lowercased, as per Section 3.3 of RFC 8288 [RFC8288]. 1265 (The convention of appending the link relation types to the prefix 1266 "http://www.iana.org/assignments/relation/" to form IRIs is adopted 1267 from Atom [RFC4287]; see also Appendix A.2 of RFC 8288 [RFC8288].) 1269 5.4. Expressing Simple RDF Statements 1271 An RDF statement [W3C.REC-rdf11-concepts-20140225] says that some 1272 relationship, indicated by a predicate, holds between two resources. 1273 Existing RDF vocabularies can therefore be good source for link 1274 relation types that describe resource metadata. For example, a CoRAL 1275 document could use the FOAF vocabulary [FOAF] to describe the person 1276 or software that made it: 1278 #using rdf = 1279 #using foaf = 1281 foaf:maker null { 1282 rdf:type 1283 foaf:familyName "Hartke" 1284 foaf:givenName "Klaus" 1285 foaf:mbox 1286 } 1288 5.5. Expressing Natural Language Texts 1290 Text strings that are the target of a link can be associated with a 1291 language tag [RFC5646] and a base text direction (i.e., right-to-left 1292 or left-to-right) by nesting links of type and under that 1294 link, respectively: 1296 #using 1297 #using iana = 1299 iana:terms-of-service { 1300 title "Nutzungsbedingungen" { 1301 language "de" 1302 direction "ltr" 1303 } 1304 title "Terms of use" { 1305 language "en-US" 1306 direction "ltr" 1307 } 1308 } 1310 The link relation types and 1311 are defined in Appendix A. 1313 5.6. Embedding CoRAL in CBOR Data 1315 Data items in the CoRAL binary format (Section 3) may be embedded in 1316 other CBOR data [RFC7049] data. Specifications using CDDL [RFC8610] 1317 SHOULD reference the following CDDL definitions for this purpose: 1319 CoRAL-Document = document 1321 CoRAL-Link = link 1323 CoRAL-Form = form 1325 For each embedded document, link, and form, the retrieval context, 1326 link context, and form context needs to be specified, respectively. 1328 5.7. Submitting CoRAL Documents 1330 By default, a CoRAL document is a representation that captures the 1331 current state of a resource. The meaning of a CoRAL document changes 1332 when it is submitted in a request. Depending on the request method, 1333 the CoRAL document can capture the intended state of a resource (PUT) 1334 or be subject to application-specific processing (POST). 1336 5.7.1. PUT Requests 1338 A PUT request with a CoRAL document enclosed in the request payload 1339 requests that the state of the target resource be created or replaced 1340 with the state described by the CoRAL document. A successful PUT of 1341 a CoRAL document generally means that a subsequent GET on that same 1342 target resource would result in an equivalent document being sent in 1343 a success response. 1345 An origin server SHOULD verify that a submitted CoRAL document is 1346 consistent with any constraints the server has for the target 1347 resource. When a document is inconsistent with the target resource, 1348 the origin server SHOULD either make it consistent (e.g., by removing 1349 inconsistent elements) or respond with an appropriate error message 1350 containing sufficient information to explain why the document is 1351 unsuitable. 1353 The retrieval context and the base URI of a CoRAL document in a PUT 1354 are the request URI of the request. 1356 5.7.2. POST Requests 1358 A POST request with a CoRAL document enclosed in the request payload 1359 requests that the target resource process the CoRAL document 1360 according to the resource's own specific semantics. 1362 The retrieval context of a CoRAL document in a POST is an unspecified 1363 URI. The base URI of the document is the request URI of the request. 1365 5.8. Returning CoRAL Documents 1367 In a response, the meaning of a CoRAL document changes depending on 1368 the request method and the response status code. For example, a 1369 CoRAL document in a successful response to a GET represents the 1370 current state of the target resource, whereas a CoRAL document in a 1371 successful response to a POST might represent either the processing 1372 result or the new resource state. A CoRAL document in an error 1373 response represents the error condition, usually describing the error 1374 state and what next steps are suggested for resolving it. 1376 5.8.1. Success Responses 1378 Success responses have a response status code that indicates that the 1379 client's request was successfully received, understood, and accepted. 1380 When the representation in a success response does not describe the 1381 state of the target resource, it describes result of processing the 1382 request. 1384 For example, when a request has been fulfilled and has resulted in 1385 one or more new resources being created, a CoRAL document in the 1386 response can link to and describe the resource(s) created. 1388 The retrieval context of a CoRAL document representing a processing 1389 result is an unspecified URI that refers to the processing result 1390 itself. The base URI of the document is the request URI of the 1391 request. 1393 5.8.2. Error Responses 1395 Error response have a response status code that indicates that either 1396 the request cannot be fulfilled or the server failed to fulfill an 1397 apparently valid request. A representation in an error response 1398 describes the error condition. 1400 The retrieval context of such a CoRAL document representing an error 1401 condition is an unspecified URI that refers to the error condition 1402 itself. The base URI of the document is the request URI of the 1403 request. 1405 6. Security Considerations 1407 Parsers of CoRAL documents must operate on input that is assumed to 1408 be untrusted. This means that parsers MUST fail gracefully in the 1409 face of malicious inputs (e.g., inputs not adhering to the data 1410 structure). Additionally, parsers MUST be prepared to deal with 1411 resource exhaustion (e.g., resulting from the allocation of big data 1412 items) or exhaustion of the call stack (stack overflow). 1414 CoRAL serializations intentionally do not feature the equivalent of 1415 XML entity references as to preclude the whole class of attacks 1416 relating to these, such as exponential XML entity expansion ("billion 1417 laughs") [CAPEC-197] and malicious XML entity linking [CAPEC-201]. 1419 Implementers of the CoRAL binary format need to consider the security 1420 aspects of processing CBOR with the restrictions described in 1421 Section 3. Notably, different number representations for the same 1422 numeric value are not equivalent in the CoRAL binary format. See 1423 Section 8 of RFC 7049 [RFC7049] for security considerations relating 1424 to CBOR. 1426 Implementers of the CoRAL textual format need to consider the 1427 security aspects of handling Unicode input. See the Unicode Standard 1428 Annex #36 [UNICODE-UAX36] for security considerations relating to 1429 visual spoofing and misuse of character encodings. See Section 10 of 1430 RFC 3629 [RFC3629] for security considerations relating to UTF-8. 1432 CoRAL makes extensive use of resource identifiers. See Section 7 of 1433 RFC 3986 [RFC3986] for security considerations relating to URIs. See 1434 Section 8 of RFC 3987 [RFC3987] for security considerations relating 1435 to IRIs. See Section X of RFC XXXX [I-D.ietf-core-href] for security 1436 considerations relating to CoRIs. 1438 The security of applications using CoRAL can depend on the proper 1439 preparation and comparison of internationalized strings. For 1440 example, such strings can be used to make authentication and 1441 authorization decisions, and the security of an application could be 1442 compromised if an entity providing a given string is connected to the 1443 wrong account or online resource based on different interpretations 1444 of the string. See RFC 6943 [RFC6943] for security considerations 1445 relating to identifiers in IRIs and other places. 1447 CoRAL is intended to be used in conjunction with a Web transfer 1448 protocol like HTTP or CoAP. See Section 9 of RFC 7230 [RFC7230], 1449 Section 9 of RFC 7231 [RFC7231], etc., for security considerations 1450 relating to HTTP. See Section 11 of RFC 7252 [RFC7252] for security 1451 considerations relating to CoAP. 1453 CoRAL does not define any specific mechanisms for protecting the 1454 confidentiality and integrity of CoRAL documents. It relies on 1455 application layer or transport layer mechanisms for this, such as 1456 Transport Layer Security (TLS) [RFC8446]. 1458 CoRAL documents and the structure of a web of resources revealed from 1459 automatically following links can disclose personal information and 1460 other sensitive information. Implementations need to prevent the 1461 unintentional disclosure of such information. See Section of 9 of 1462 RFC 7231 [RFC7231] for additional considerations. 1464 Applications using CoRAL ought to consider the attack vectors opened 1465 by automatically following, trusting, or otherwise using links and 1466 forms in CoRAL documents. Notably, a server that is authoritative 1467 for the CoRAL representation of a resource may not necessarily be 1468 authoritative for nested elements in the document. See Section 5 of 1469 RFC 8288 [RFC8288] for related considerations. 1471 Unless an application mitigates this risk by specifying more specific 1472 rules, any link or form in a document where the link or form context 1473 and the document's retrieval context don't share the same Web origin 1474 [RFC6454] MUST be discarded ("same-origin policy"). 1476 7. IANA Considerations 1478 7.1. Media Type "application/coral+cbor" 1480 This document registers the media type "application/coral+cbor" 1481 according to the procedures of BCP 13 [RFC6838]. 1483 Type name: 1484 application 1486 Subtype name: 1487 coral+cbor 1489 Required parameters: 1490 N/A 1492 Optional parameters: 1493 dictionary - See Section 3.2 of [I-D.ietf-core-coral]. 1495 Encoding considerations: 1496 binary - See Section 3 of [I-D.ietf-core-coral]. 1498 Security considerations: 1499 See Section 6 of [I-D.ietf-core-coral]. 1501 Interoperability considerations: 1502 N/A 1504 Published specification: 1505 [I-D.ietf-core-coral] 1507 Applications that use this media type: 1508 See Section 1 of [I-D.ietf-core-coral]. 1510 Fragment identifier considerations: 1511 As specified for "application/cbor". 1513 Additional information: 1514 Deprecated alias names for this type: N/A 1515 Magic number(s): N/A 1516 File extension(s): .coral.cbor 1517 Macintosh file type code(s): N/A 1519 Person & email address to contact for further information: 1520 See the Author's Address section of [I-D.ietf-core-coral]. 1522 Intended usage: 1523 COMMON 1525 Restrictions on usage: 1526 N/A 1528 Author: 1529 See the Author's Address section of [I-D.ietf-core-coral]. 1531 Change controller: 1532 IESG 1534 Provisional registration? 1535 No 1537 7.2. Media Type "text/coral" 1539 This document registers the media type "text/coral" according to the 1540 procedures of BCP 13 [RFC6838] and guidelines in RFC 6657 [RFC6657]. 1542 Type name: 1543 text 1545 Subtype name: 1546 coral 1548 Required parameters: 1549 N/A 1551 Optional parameters: 1552 N/A 1554 Encoding considerations: 1556 binary - See Section 4 of [I-D.ietf-core-coral]. 1558 Security considerations: 1559 See Section 6 of [I-D.ietf-core-coral]. 1561 Interoperability considerations: 1562 N/A 1564 Published specification: 1565 [I-D.ietf-core-coral] 1567 Applications that use this media type: 1568 See Section 1 of [I-D.ietf-core-coral]. 1570 Fragment identifier considerations: 1571 N/A 1573 Additional information: 1574 Deprecated alias names for this type: N/A 1575 Magic number(s): N/A 1576 File extension(s): .coral 1577 Macintosh file type code(s): N/A 1579 Person & email address to contact for further information: 1580 See the Author's Address section of [I-D.ietf-core-coral]. 1582 Intended usage: 1583 COMMON 1585 Restrictions on usage: 1586 N/A 1588 Author: 1589 See the Author's Address section of [I-D.ietf-core-coral]. 1591 Change controller: 1592 IESG 1594 Provisional registration? 1595 No 1597 7.3. CoAP Content Formats 1599 This document registers CoAP content formats for the content types 1600 "application/coral+cbor" and "text/coral" according to the procedures 1601 of RFC 7252 [RFC7252]. 1603 o Content Type: application/coral+cbor 1604 Content Coding: identity 1605 ID: TBD3 1606 Reference: [I-D.ietf-core-coral] 1608 o Content Type: text/coral 1609 Content Coding: identity 1610 ID: TBD4 1611 Reference: [I-D.ietf-core-coral] 1613 [[NOTE TO RFC EDITOR: Please replace all occurrences of "TBD3" and 1614 "TBD4" in this document with the code points assigned by IANA.]] 1616 [[NOTE TO IMPLEMENTERS: Experimental implementations can use content 1617 format ID 65087 for "application/coral+cbor" and content format ID 1618 65343 for "text/coral" until IANA has assigned code points.]] 1620 7.4. CBOR Tag 1622 This document registers a CBOR tag for dictionary references 1623 according to the procedures of RFC 7049 [RFC7049]. 1625 o Tag: TBD6 1626 Data Item: unsigned integer 1627 Semantics: Dictionary reference 1628 Reference: [I-D.ietf-core-coral] 1630 [[NOTE TO RFC EDITOR: Please replace all occurrences of "TBD6" in 1631 this document with the code point assigned by IANA.]] 1633 8. References 1635 8.1. Normative References 1637 [I-D.ietf-core-href] 1638 Hartke, K., "Constrained Resource Identifiers", draft- 1639 ietf-core-href-01 (work in progress), November 2019. 1641 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1642 Requirement Levels", BCP 14, RFC 2119, 1643 DOI 10.17487/RFC2119, March 1997, 1644 . 1646 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1647 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1648 . 1650 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1651 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1652 2003, . 1654 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1655 Resource Identifier (URI): Generic Syntax", STD 66, 1656 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1657 . 1659 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1660 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 1661 January 2005, . 1663 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1664 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1665 . 1667 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1668 Specifications: ABNF", STD 68, RFC 5234, 1669 DOI 10.17487/RFC5234, January 2008, 1670 . 1672 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1673 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1674 September 2009, . 1676 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1677 DOI 10.17487/RFC6454, December 2011, 1678 . 1680 [RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding 1681 "charset" Parameter Handling in Textual Media Types", 1682 RFC 6657, DOI 10.17487/RFC6657, July 2012, 1683 . 1685 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1686 Specifications and Registration Procedures", BCP 13, 1687 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1688 . 1690 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1691 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1692 October 2013, . 1694 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1695 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1696 May 2017, . 1698 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1699 Definition Language (CDDL): A Notational Convention to 1700 Express Concise Binary Object Representation (CBOR) and 1701 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1702 June 2019, . 1704 [UNICODE] The Unicode Consortium, "The Unicode Standard", 1705 . 1707 Note that this reference is to the latest version of 1708 Unicode, rather than to a specific release. It is not 1709 expected that future changes in the Unicode specification 1710 will have any impact on this document. 1712 [UNICODE-UAX15] 1713 The Unicode Consortium, "Unicode Standard Annex #15: 1714 Unicode Normalization Forms", 1715 . 1717 [UNICODE-UAX31] 1718 The Unicode Consortium, "Unicode Standard Annex #31: 1719 Unicode Identifier and Pattern Syntax", 1720 . 1722 [UNICODE-UAX36] 1723 The Unicode Consortium, "Unicode Standard Annex #36: 1724 Unicode Security Considerations", 1725 . 1727 8.2. Informative References 1729 [CAPEC-197] 1730 MITRE, "CAPEC-197: XML Entity Expansion", September 2019, 1731 . 1733 [CAPEC-201] 1734 MITRE, "CAPEC-201: XML Entity Linking", September 2019, 1735 . 1737 [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification 1738 0.99", January 2014, 1739 . 1741 [HAL] Kelly, M., "JSON Hypertext Application Language", draft- 1742 kelly-json-hal-08 (work in progress), May 2016. 1744 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1745 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 1746 December 2005, . 1748 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1749 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1750 . 1752 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 1753 RFC 6573, DOI 10.17487/RFC6573, April 2012, 1754 . 1756 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1757 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1758 . 1760 [RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for 1761 Security Purposes", RFC 6943, DOI 10.17487/RFC6943, May 1762 2013, . 1764 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1765 Constrained-Node Networks", RFC 7228, 1766 DOI 10.17487/RFC7228, May 2014, 1767 . 1769 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1770 Protocol (HTTP/1.1): Message Syntax and Routing", 1771 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1772 . 1774 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1775 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1776 DOI 10.17487/RFC7231, June 2014, 1777 . 1779 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1780 Application Protocol (CoAP)", RFC 7252, 1781 DOI 10.17487/RFC7252, June 2014, 1782 . 1784 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 1785 RFC 7320, DOI 10.17487/RFC7320, July 2014, 1786 . 1788 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1789 FETCH Methods for the Constrained Application Protocol 1790 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1791 . 1793 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1794 DOI 10.17487/RFC8288, October 2017, 1795 . 1797 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1798 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1799 . 1801 [W3C.REC-html52-20171214] 1802 Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and 1803 S. Moon, "HTML 5.2", World Wide Web Consortium 1804 Recommendation REC-html52-20171214, December 2017, 1805 . 1807 [W3C.REC-rdf-schema-20140225] 1808 Brickley, D. and R. Guha, "RDF Schema 1.1", World Wide Web 1809 Consortium Recommendation REC-rdf-schema-20140225, 1810 February 2014, 1811 . 1813 [W3C.REC-rdf11-concepts-20140225] 1814 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 1815 Concepts and Abstract Syntax", World Wide Web Consortium 1816 Recommendation REC-rdf11-concepts-20140225, February 2014, 1817 . 1819 [W3C.REC-turtle-20140225] 1820 Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", 1821 World Wide Web Consortium Recommendation REC-turtle- 1822 20140225, February 2014, 1823 . 1825 [W3C.REC-webarch-20041215] 1826 Jacobs, I. and N. Walsh, "Architecture of the World Wide 1827 Web, Volume One", World Wide Web Consortium 1828 Recommendation REC-webarch-20041215, December 2004, 1829 . 1831 Appendix A. Core Vocabulary 1833 This section defines the core vocabulary for CoRAL: a set of link 1834 relation types, operation types, form field types, and metadata 1835 names. 1837 A.1. Base 1839 Link Relation Types: 1841 1842 Indicates that the link's context is an instance of the class 1843 specified as the link's target, as defined by RDF Schema 1844 [W3C.REC-rdf-schema-20140225]. 1846 1847 Indicates that the link target is a human-readable label (e.g., a 1848 menu entry). 1850 The link target MUST be a text string. The text string SHOULD be 1851 annotated with a language and text direction using nested links of 1852 type and , respectively. 1855 1856 Indicates that the link target is a language tag [RFC5646] that 1857 specifies the language of the link context. 1859 The link target MUST be a text string in the format specified in 1860 Section 2.1 of RFC 5646 [RFC5646]. 1862 1863 Indicates that the link target is a base text direction (right-to- 1864 left or left-to-right) that specifies the text directionality of 1865 the link context. 1867 The link target MUST be either the text string "rtl" or the text 1868 string "ltr". 1870 Operation Types: 1872 1873 Indicates that the state of the form's context can be replaced 1874 with the state described by a representation submitted to the 1875 server. 1877 This operation type defaults to the PUT method [RFC7231] [RFC7252] 1878 for both HTTP and CoAP. Typical overrides by a form field include 1879 the PATCH method [RFC5789] [RFC8132] for HTTP and CoAP and the 1880 iPATCH method [RFC8132] for CoAP. 1882 1883 Indicates that the form's context can be searched by submitting a 1884 search query. 1886 This operation type defaults to the POST method [RFC7231] for HTTP 1887 and the FETCH method [RFC8132] for CoAP. Typical overrides by a 1888 form field include the POST method [RFC7252] for CoAP. 1890 A.2. Collections 1892 Link Relation Types: 1894 1895 Indicates that the link's context is a collection and that the 1896 link's target is a member of that collection, as defined in 1897 Section 2.1 of RFC 6573 [RFC6573]. 1899 1900 Indicates that the link's target is a collection and that the 1901 link's context is a member of that collection, as defined in 1902 Section 2.2 of RFC 6573 [RFC6573]. 1904 Operation Types: 1906 1907 Indicates that the form's context is a collection and that a new 1908 item can be created in that collection with the state defined by a 1909 representation submitted to the server. 1911 This operation type defaults to the POST method [RFC7231] 1912 [RFC7252] for both HTTP and CoAP. 1914 1915 Indicates that the form's context is a member of a collection and 1916 that the form's context can be removed from that collection. 1918 This operation type defaults to the DELETE method [RFC7231] 1919 [RFC7252] for both HTTP and CoAP. 1921 A.3. HTTP 1923 Form Field Types: 1925 1926 Specifies the HTTP method for the request. 1928 The form field value MUST be a text string in the format defined 1929 in Section 4.1 of RFC 7231 [RFC7231]. The set of possible values 1930 is maintained in the IANA HTTP Method Registry. 1932 A form field of this type MUST NOT occur more than once in a form. 1933 If absent, it defaults to the request method implied by the form's 1934 operation type. 1936 1937 Specifies an acceptable HTTP content type for the request payload. 1938 There may be multiple form fields of this type. If a form does 1939 not include a form field of this type, the server accepts any or 1940 no request payload, depending on the operation type. 1942 The form field value MUST be a text string in the format defined 1943 in Section 3.1.1.1 of RFC 7231 [RFC7231]. The possible set of 1944 media types and their parameters are maintained in the IANA Media 1945 Types Registry. 1947 Representation Metadata: 1949 1950 Specifies the HTTP content type of the representation. 1952 The metadata value MUST be specified as a text string in the 1953 format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]. The 1954 possible set of media types and their parameters are maintained in 1955 the IANA Media Types Registry. 1957 Metadata of this type MUST NOT occur more than once for a 1958 representation. If absent, its value defaults to content type 1959 "application/octet-stream". 1961 A.4. CoAP 1963 Form Field Types: 1965 1966 Specifies the CoAP method for the request. 1968 The form field value MUST be an integer identifying one of the 1969 CoAP request methods maintained in the IANA CoAP Method Codes 1970 Registry (e.g., the integer 2 for the POST method). 1972 A form field of this type MUST NOT occur more than once in a form. 1973 If absent, it defaults to the request method implied by the form's 1974 operation type. 1976 1977 Specifies an acceptable CoAP content format for the request 1978 payload. There may be multiple form fields of this type. If a 1979 form does not include a form field of this type, the server 1980 accepts any or no request payload, depending on the operation 1981 type. 1983 The form field value MUST be an integer identifying one of the 1984 content formats maintained in the IANA CoAP Content-Formats 1985 Registry. 1987 Representation Metadata: 1989 1990 Specifies the CoAP content format of the representation. 1992 The metadata value MUST be an integer identifying one of the 1993 content formats maintained in the IANA CoAP Content-Formats 1994 Registry. 1996 Metadata of this type MUST NOT occur more than once for a 1997 representation. If absent, it defaults to content format 42 1998 (i.e., content type "application/octet-stream" without a content 1999 coding). 2001 Appendix B. Default Dictionary 2003 This section defines a default dictionary that is assumed when the 2004 "application/coral+cbor" media type is used without a "dictionary" 2005 parameter. 2007 +-----+-------------------------------------------------------+ 2008 | Key | Value | 2009 +-----+-------------------------------------------------------+ 2010 | 0 | | 2011 | 1 | | 2012 | 2 | | 2013 | 3 | | 2014 | 4 | | 2015 | 5 | | 2016 | 6 | | 2017 | 7 | | 2018 | 8 | | 2019 | 9 | | 2020 | 10 | | 2021 | 11 | | 2022 | 12 | "ltr" | 2023 | 13 | "rtl" | 2024 +-----+-------------------------------------------------------+ 2026 Table 2: Default Dictionary 2028 Acknowledgements 2030 CoRAL is heavily inspired by Mike Kelly's JSON Hypertext Application 2031 Language [HAL]. 2033 This document has benefited greatly from discussions and reviews of 2034 the CoRAL design team: 2036 Christian Amsuess 2037 2039 Carsten Bormann, Universitaet Bremen 2040 2042 Michael Koster, SmartThings 2043 2045 Jim Schaad, August Cellars 2046 2048 Thanks to Thomas Fossati, Jaime Jimenez, Sebastian Kaebisch, Ari 2049 Keranen, Matthias Kovatsch, and Niklas Widell for helpful comments 2050 and discussions that have shaped the document. 2052 Author's Address 2054 Klaus Hartke 2055 Ericsson 2056 Torshamnsgatan 23 2057 Stockholm SE-16483 2058 Sweden 2060 Email: klaus.hartke@ericsson.com