idnits 2.17.1 draft-hartke-t2trg-coral-09.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 (July 8, 2019) is 1753 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: Experimental ---------------------------------------------------------------------------- == Missing Reference: 'I-D.hartke-t2trg-coral' is mentioned on line 1577, but not defined ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) -- 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 (~~), 2 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Thing-to-Thing Research Group K. Hartke 3 Internet-Draft Ericsson 4 Intended status: Experimental July 8, 2019 5 Expires: January 9, 2020 7 The Constrained RESTful Application Language (CoRAL) 8 draft-hartke-t2trg-coral-09 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 January 9, 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 . . . . . . . . . . . . . . . . . . . . 4 56 2.2. Documents . . . . . . . . . . . . . . . . . . . . . . . . 5 57 2.3. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 2.4. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 2.4.1. Form Fields . . . . . . . . . . . . . . . . . . . . . 7 60 2.5. Embedded Representations . . . . . . . . . . . . . . . . 7 61 2.6. Navigation . . . . . . . . . . . . . . . . . . . . . . . 7 62 2.7. History Traversal . . . . . . . . . . . . . . . . . . . . 9 63 3. Binary Format . . . . . . . . . . . . . . . . . . . . . . . . 9 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 . . . . . . . . . . . . . . . . . . . . . 15 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 . . . . . . . . . . . . . . . . . . . . . . 20 84 4.2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 20 85 4.2.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 21 86 4.2.4. Embedded Representations . . . . . . . . . . . . . . 22 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 . . . . . . . . . . . . . . . 24 91 5.1.2. Resource Names . . . . . . . . . . . . . . . . . . . 25 92 5.1.3. Implementation Limits . . . . . . . . . . . . . . . . 25 93 5.2. Minting Vocabulary . . . . . . . . . . . . . . . . . . . 26 94 5.3. Expressing Registered Link Relation Types . . . . . . . . 27 95 5.4. Expressing Simple RDF Statements . . . . . . . . . . . . 27 96 5.5. Expressing Language-Tagged Strings . . . . . . . . . . . 27 97 5.6. Embedding CoRAL in CBOR Data . . . . . . . . . . . . . . 28 98 5.7. Submitting CoRAL Documents . . . . . . . . . . . . . . . 28 99 5.7.1. PUT Requests . . . . . . . . . . . . . . . . . . . . 28 100 5.7.2. POST Requests . . . . . . . . . . . . . . . . . . . . 29 101 6. Security Considerations . . . . . . . . . . . . . . . . . . . 29 102 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 103 7.1. Media Type "application/coral+cbor" . . . . . . . . . . . 30 104 7.2. Media Type "text/coral" . . . . . . . . . . . . . . . . . 32 105 7.3. CoAP Content Formats . . . . . . . . . . . . . . . . . . 33 106 7.4. CBOR Tag . . . . . . . . . . . . . . . . . . . . . . . . 33 107 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 108 8.1. Normative References . . . . . . . . . . . . . . . . . . 34 109 8.2. Informative References . . . . . . . . . . . . . . . . . 36 110 Appendix A. Core Vocabulary . . . . . . . . . . . . . . . . . . 38 111 A.1. Base . . . . . . . . . . . . . . . . . . . . . . . . . . 38 112 A.2. Collections . . . . . . . . . . . . . . . . . . . . . . . 39 113 A.3. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . 39 114 A.4. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 40 115 Appendix B. Default Dictionary . . . . . . . . . . . . . . . . . 41 116 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 41 117 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 42 119 1. Introduction 121 The Constrained RESTful Application Language (CoRAL) is a language 122 for the description of typed connections between resources on the Web 123 ("links"), possible operations on such resources ("forms"), as well 124 as simple resource metadata. 126 CoRAL is intended for driving automated software agents that navigate 127 a Web application based on a standardized vocabulary of link relation 128 types and operation types. It is designed to be used in conjunction 129 with a Web transfer protocol such as the Hypertext Transfer Protocol 130 (HTTP) [RFC7230] or the Constrained Application Protocol (CoAP) 131 [RFC7252]. 133 This document defines the CoRAL data and interaction model, as well 134 as two specialized CoRAL serialization formats. 136 The CoRAL data and interaction model is a superset of the Web Linking 137 model of RFC 8288 [RFC8288]. The data model consists of two primary 138 elements: "links" that describe the relationship between two 139 resources and the type of that relationship, and "forms" that 140 describe a possible operation on a resource and the type of that 141 operation. Additionally, the data model can describe simple resource 142 metadata in a way similar to the Resource Description Framework (RDF) 143 [W3C.REC-rdf11-concepts-20140225]. In contrast to RDF, the focus of 144 CoRAL however is on the interaction with resources, not just the 145 relationships between them. The interaction model derives from HTML 146 5 [W3C.REC-html52-20171214] and specifies how an automated software 147 agent can navigate between resources by following links and perform 148 operations on resources by submitting forms. 150 The primary CoRAL serialization format is a compact, binary encoding 151 of links and forms in Concise Binary Object Representation (CBOR) 152 [RFC7049]. It is intended for environments with constraints on 153 power, memory, and processing resources [RFC7228] and shares many 154 similarities with the message format of the Constrained Application 155 Protocol (CoAP) [RFC7252]: For example, it uses numeric identifiers 156 instead of verbose strings for link relation types and operation 157 types, and pre-parses Uniform Resource Identifiers (URIs) [RFC3986] 158 into (what CoAP considers to be) their components, which simplifies 159 URI processing for constrained nodes a lot. As a result, link 160 serializations in CoRAL are often much more compact than equivalent 161 serializations in CoRE Link Format [RFC6690]. 163 The secondary CoRAL serialization format is a lightweight, textual 164 encoding of links and forms that is intended to be easy to read and 165 write for humans. The format is loosely inspired by the syntax of 166 Turtle [W3C.REC-turtle-20140225] and is mainly intended for giving 167 examples. 169 1.1. Notational Conventions 171 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 172 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 173 "OPTIONAL" in this document are to be interpreted as described in BCP 174 14 [RFC2119] [RFC8174] when, and only when, they appear in all 175 capitals, as shown here. 177 Terms defined in this document appear in _cursive_ where they are 178 introduced. 180 2. Data and Interaction Model 182 The Constrained RESTful Application Language (CoRAL) is designed for 183 building Web-based applications [W3C.REC-webarch-20041215] in which 184 automated software agents navigate between resources by following 185 links and perform operations on resources by submitting forms. 187 2.1. Browsing Context 189 Borrowing from HTML 5 [W3C.REC-html52-20171214], each such agent 190 maintains a _browsing context_ in which the representations of Web 191 resources are processed. (In HTML 5, the browsing context typically 192 corresponds to a tab or window in a Web browser.) 193 At any time, one representation in each browsing context is 194 designated the _active_ representation. 196 2.2. Documents 198 A resource representation in one of the CoRAL serialization formats 199 is called a CoRAL _document_. The Internationalized Resource 200 Identifier (IRI) [RFC3987] that was used to retrieve such a document 201 is called the document's _retrieval context_. 203 A CoRAL document consists of a list of zero or more links, forms, and 204 embedded resource representations, collectively called _elements_. 205 CoRAL serialization formats may define additional types of elements 206 for efficiency or convenience, such as a base for relative IRI 207 references [RFC3987]. 209 2.3. Links 211 A _link_ describes a relationship between two resources on the Web 212 [RFC8288]. As defined in RFC 8288, it consists of a _link context_, 213 a _link relation type_, and a _link target_. In CoRAL, a link can 214 additionally have a nested list of zero or more elements, which take 215 the place of link target attributes. 217 A link can be viewed as a statement of the form "{link context} has a 218 {link relation type} resource at {link target}" where the link target 219 may be further described by nested elements. 221 The link relation type identifies the semantics of a link. In HTML 5 222 and RFC 8288, link relation types are typically denoted by an IANA- 223 registered name, such as "stylesheet" or "type". In CoRAL, they are 224 denoted by an IRI such as or . 226 This allows for the creation of new link relation types without the 227 risk of collisions when from different organizations or domains of 228 knowledge. An IRI also can lead to documentation, schema, and other 229 information about the link relation type. These IRIs are only used 230 as identity tokens, though, and are compared using Simple String 231 Comparison (Section 5.1 of RFC 3987). 233 The link context and the link target are both either by an IRI or 234 (similarly to RDF) a literal. If the IRI scheme indicates a Web 235 transfer protocol such as HTTP or CoAP, then an agent can dereference 236 the IRI and navigate the browsing context to the referenced resource; 237 this is called _following the link_. A literal directly identifies a 238 value. This can be a Boolean value, an integer, a floating-point 239 number, a date/time value, a byte string, or a text string. 241 A link can occur as a top-level element in a document or as a nested 242 element within a link. When a link occurs as a top-level element, 243 the link context implicitly is the document's retrieval context. 244 When a link occurs nested within a link, the link context of the 245 inner link is the link target of the outer link. 247 There are no restrictions on the cardinality of links; there can be 248 multiple links to and from a particular target, and multiple links of 249 the same or different types between a given link context and target. 250 However, the nested data structure constrains the description of a 251 resource graph to a tree: Links between linked resources can only be 252 described by further nesting links. 254 2.4. Forms 256 A _form_ provides instructions to an agent for performing an 257 operation on a Web resource. It consists of a _form context_, an 258 _operation type_, a _request method_, and a _submission target_. 259 Additionally, a form may be accompanied by a list of _form fields_. 261 A form can be viewed as an instruction of the form "To perform an 262 {operation type} operation on {form context}, make a {request method} 263 request to {submission target}" where the request may be further 264 described by form fields. 266 The operation type identifies the semantics of the operation. 267 Operation types are denoted like link relation types by an IRI. 269 The form context is the resource on which an operation is ultimately 270 performed. To perform the operation, an agent needs to construct a 271 request with the specified method and the specified submission target 272 as the request IRI. Usually, the submission target is the same 273 resource as the form context, but it may be a different resource. 274 Constructing and sending the request is called _submitting the form_. 276 Form fields, specified in the next section, can be used to provide 277 more detailed instructions to the agent for constructing the request. 278 For example, form fields can instruct the agent to include a payload 279 or certain headers in the request that must match the specifications 280 of the form fields. 282 A form can occur as a top-level element in a document or as a nested 283 element within a link. When a form occurs as a top-level element, 284 the form context implicitly is the document's retrieval context. 285 When a form occurs nested within a link, the form context is the link 286 target of the enclosing link. 288 2.4.1. Form Fields 290 Form fields provide further instructions to agents for constructing a 291 request. 293 For example, a form field could identify one or more data items that 294 need to be included in the request payload or reference another 295 resource (such as a schema) that describes the structure of the 296 payload. A form field could also provide other kinds of information, 297 such as acceptable media types for the payload or expected request 298 headers. Form fields may be specific to the protocol used for 299 submitting the form. 301 A form field is the pair of a _form field type_ and a _form field 302 value_. 304 The form field type identifies the semantics of the form field. Form 305 field types are denoted like link relation types and operation types 306 by an IRI. 308 The form field value can be either an IRI, a Boolean value, an 309 integer, a floating-point number, a date/time value, a byte string, 310 or a text string. 312 2.5. Embedded Representations 314 When a document contains links to many resources and an agent needs a 315 representation of each link target, it may be inefficient to retrieve 316 each of these representations individually. To alleviate this, 317 documents can directly embed representations of resources. 319 An _embedded representation_ consists of a sequence of bytes, labeled 320 with _representation metadata_. 322 An embedded representation may be a full, partial, or inconsistent 323 version of the representation served from the IRI of the resource. 325 An embedded representation can occur as a top-level element in a 326 document or as a nested element within a link. When it occurs as a 327 top-level element, it provides an alternate representation of the 328 document's retrieval context. When it occurs nested within a link, 329 it provides a representation of link target of the enclosing link. 331 2.6. Navigation 333 An agent begins interacting with an application by performing a GET 334 request on an _entry point IRI_. The entry point IRI is the only IRI 335 an agent is expected to know before interacting with an application. 337 From there, the agent is expected to make all requests by following 338 links and submitting forms provided by the server in responses. The 339 entry point IRI can be obtained by manual configuration or through 340 some discovery process. 342 If dereferencing the entry point IRI yields a CoRAL document (or any 343 other representation that implements the CoRAL data and interaction 344 model), then the agent makes this document the active representation 345 in the browsing context and proceeds as follows: 347 1. The first step for the agent is to decide what to do next, i.e., 348 which type of link to follow or form to submit, based on the link 349 relation types and operation types it understands. 351 2. The agent then finds the link(s) or form(s) with the respective 352 type in the active representation. This may yield one or more 353 candidates, from which the agent will have to select the most 354 appropriate one. The set of candidates may be empty, for 355 example, when a transition is not supported or not allowed. 357 3. The agent selects one of the candidates based on the metadata 358 associated with each of these. Metadata includes the content 359 type of the target resource representation, the IRI scheme, the 360 request method, and other information that is provided as nested 361 elements in a link or form fields in a form. 363 If the selected candidate contains an embedded representation, 364 the agent MAY skip the following steps and immediately proceed 365 with step 8. 367 4. The agent obtains the _request IRI_ from the link target or 368 submission target. Fragment identifiers are not part of the 369 request IRI and MUST be separated from the rest of the IRI prior 370 to a dereference. 372 5. The agent constructs a new request with the request IRI. If the 373 agent is following a link, then the request method MUST be GET. 374 If the agent is submitting a form, then the request method MUST 375 be the one specified in the form. The request IRI may need to be 376 converted to a URI (Section 3.1 of RFC 3987) for protocols that 377 do not support IRIs. 379 The agent should set HTTP header fields and CoAP request options 380 according to metadata associated with the link or form (e.g., set 381 the HTTP Accept header field or the CoAP Accept option when the 382 media type of the target resource is provided). Depending on the 383 operation type of a form, the agent may also need to include a 384 request payload that matches the specifications of one or more 385 form fields. 387 6. The agent sends the request and receives the response. 389 7. If a fragment identifier was separated from the request IRI, the 390 agent dereferences the fragment identifier within the received 391 representation. 393 8. The agent _updates the browsing context_ by making the (embedded 394 or received) representation the active representation. 396 9. Finally, the agent processes the representation according to the 397 semantics of the content type. If the representation is a CoRAL 398 document (or any other representation that implements the CoRAL 399 data and interaction model), this means the agent has the choice 400 of what to do next again -- and the cycle repeats. 402 2.7. History Traversal 404 A browsing context MAY entail a _session history_ that lists the 405 resource representations that the agent has processed, is processing, 406 or will process. 408 An entry in the session history consists of a resource representation 409 and the request IRI that was used to retrieve the representation. 410 New entries are added to the session history as the agent navigates 411 from resource to resource. 413 An agent can navigate a browsing context by _traversing the session 414 history_ in addition to following links and submitting forms. For 415 example, if an agent received a representation that doesn't contain 416 any further links or forms, it can revert the active representation 417 back to one it has visited earlier. 419 Traversing the history should take advantage of caches to avoid new 420 requests. An agent MAY reissue a safe request (e.g., a GET request) 421 when it doesn't have a fresh representation in its cache. An agent 422 MUST NOT reissue an unsafe request (e.g., a PUT or POST request) 423 unless it intends to perform that operation again. 425 3. Binary Format 427 This section defines the encoding of documents in the CoRAL binary 428 format. 430 A document in the binary format is a data item in Concise Binary 431 Object Representation (CBOR) [RFC7049]. The structure of this data 432 item is presented in the Concise Data Definition Language (CDDL) 433 [RFC8610]. The media type is "application/coral+cbor". 435 The following restrictions are placed on CBOR encoders: Byte strings 436 and text strings MUST be encoded with definite length. Integers and 437 floating-point values MUST be encoded as such (e.g., a floating-point 438 value of 0.0 must not be encoded as the integer 0). 440 3.1. Data Structure 442 The data structure of a document in the binary format is made up of 443 four kinds of elements: links, forms, embedded representations, and 444 (as an extension to the CoRAL data model) base directives. Base 445 directives provide a way to encode IRIs with a common base more 446 efficiently. 448 Elements are processed in the order they appear in the document. 449 Document processors need to maintain an _environment_ while iterating 450 an array of elements. The environment consists of two variables: the 451 _current context_ and the _current base_. Both the current context 452 and the current base are initially set to the document's retrieval 453 context. 455 3.1.1. Documents 457 The body of a document in the binary format is encoded as an array of 458 zero or more links, forms, embedded representations, and directives. 460 document = body 462 body = [*(link / form / representation / directive)] 464 3.1.2. Links 466 A link is encoded as an array that consists of the unsigned integer 467 2, followed by the link relation type and the link target, optionally 468 followed by a link body that contains nested elements. 470 link = [2, relation-type, link-target, ?body] 472 The link relation type is encoded as a text string that conforms to 473 the syntax of an IRI [RFC3987]. 475 relation-type = text 477 The link target is denoted by an IRI reference or represented by a 478 literal value. An IRI reference MUST be resolved against the current 479 base. The encoding of and resolution process for IRI references in 480 the binary format is described in RFC XXXX [I-D.hartke-t2trg-ciri]. 481 The link target may be null, which indicates that the link target is 482 an unidentified resource. 484 link-target = ciri / literal 486 ciri = 488 literal = bool / int / float / time / bytes / text / null 490 The array of elements in the link body, if any, MUST be processed in 491 a fresh environment. Both the current context and the current base 492 in the new environment are initially set to the link target of the 493 enclosing link. 495 3.1.3. Forms 497 A form is encoded as an array that consists of the unsigned integer 498 3, followed by the operation type and the submission target, 499 optionally followed by a list of form fields. 501 form = [3, operation-type, submission-target, ?form-fields] 503 The operation type is defined in the same way as a link relation type 504 (Section 3.1.2). 506 operation-type = text 508 The request method is either implied by the operation type or encoded 509 as a form field. If there are both, the form field takes precedence 510 over the operation type. Either way, the method MUST be defined for 511 the Web transfer protocol identified by the scheme of the submission 512 target. 514 The submission target is denoted by an IRI reference. This IRI 515 reference MUST be resolved against the current base. 517 submission-target = ciri 519 3.1.3.1. Form Fields 521 A list of form fields is encoded as an array of zero or more type- 522 value pairs. 524 form-fields = [*(form-field-type, form-field-value)] 526 The list, if any, MUST be processed in a fresh environment. Both the 527 current context and the current base in the new environment are 528 initially set to the submission target of the enclosing form. 530 A form field type is defined in the same way as a link relation type 531 (Section 3.1.2). 533 form-field-type = text 535 A form field value can be an IRI reference, a Boolean value, an 536 integer, a floating-point number, a date/time value, a byte string, a 537 text string, or null. An IRI reference MUST be resolved against the 538 current base. 540 form-field-value = ciri / literal 542 3.1.4. Embedded Representations 544 An embedded representation is encoded as an array that consists of 545 the unsigned integer 0, followed by a byte string containing the 546 representation data, optionally followed by representation metadata. 548 representation = [0, bytes, ?representation-metadata] 550 Representation metadata is encoded as an array of zero or more name- 551 value pairs. 553 representation-metadata = [*(metadata-name, metadata-value)] 555 The metadata, if any, MUST be processed in a fresh environment. All 556 variables in the new environment are initially set to a copy of the 557 variables in the current environment. 559 The metadata name is defined in the same way as a link relation type 560 (Section 3.1.2). 562 metadata-name = text 564 A metadata value can be an IRI reference, a Boolean value, an 565 integer, a floating-point number, a date/time value, a byte string, a 566 text string, or null. An IRI reference MUST be resolved against the 567 current base. 569 metadata-value = ciri / literal 571 3.1.5. Directives 573 Directives provide the ability to manipulate the environment when 574 processing a list of elements. There is one type of directives 575 available: the Base directive. 577 directive = base-directive 579 3.1.5.1. Base Directives 581 A Base directive is encoded as an array that consists of the unsigned 582 integer 1, followed by a base. 584 base-directive = [1, base] 586 The base is denoted by an IRI reference. This IRI reference MUST be 587 resolved against the current context (not the current base). 589 base = ciri 591 The directive is processed by resolving the IRI reference against the 592 current context and assigning the result to the current base. 594 3.2. Dictionaries 596 The binary format can reference values from a dictionary to reduce 597 representation size and processing cost. Dictionary references can 598 be used in place of link relation types, link targets, operation 599 types, submission targets, form field types, form field values, 600 representation metadata names, and representation metadata values. 602 3.2.1. Dictionary References 604 A dictionary reference is encoded as an unsigned integer. Where a 605 dictionary reference cannot be expressed unambiguously, the unsigned 606 integer is tagged with CBOR tag TBD6. 608 relation-type /= uint 610 link-target /= #6.TBD6(uint) 612 operation-type /= uint 614 submission-target /= #6.TBD6(uint) 616 form-field-type /= uint 618 form-field-value /= #6.TBD6(uint) 619 metadata-name /= uint 621 metadata-value /= #6.TBD6(uint) 623 3.2.2. Media Type Parameter 625 The "application/coral+cbor" media type is defined to have a 626 "dictionary" parameter that specifies the dictionary in use. The 627 dictionary is identified by a URI [RFC3986]. For example, a CoRAL 628 document that uses the dictionary identified by the URI 629 can use the following content type: 631 application/coral+cbor;dictionary="http://example.com/dictionary" 633 The URI serves only as an identifier; it does not necessarily have to 634 be dereferencable (or even use a dereferencable URI scheme). It is 635 permissible, though, to use a dereferencable URI and to serve a 636 representation that provides information about the dictionary in a 637 human- or machine-readable way. (The format of such a representation 638 is outside the scope of this document.) 640 For simplicity, a CoRAL document can reference values only from one 641 dictionary; the value of the "dictionary" parameter MUST be a single 642 URI. If the "dictionary" parameter is absent, the default dictionary 643 specified in Appendix B of this document is assumed. 645 Once a dictionary has made an assignment, the assignment MUST NOT be 646 changed or removed. A dictionary, however, may contain additional 647 information about an assignment, which may change over time. 649 In CoAP [RFC7252], media types (including specific values for media 650 type parameters) are encoded as an unsigned integer called "content 651 format". For use with CoAP, each new CoRAL dictionary MUST register 652 a new content format in the IANA CoAP Content-Formats Registry. 654 4. Textual Format 656 This section defines the syntax of documents in the CoRAL textual 657 format using two grammars: The lexical grammar defines how Unicode 658 characters are combined to form line terminators, white space, 659 comments, and tokens. The syntactic grammar defines how tokens are 660 combined to form documents. Both grammars are presented in Augmented 661 Backus-Naur Form (ABNF) [RFC5234]. 663 A document in the textual format is a Unicode string in a Unicode 664 encoding form [UNICODE]. The media type for such documents is "text/ 665 coral". The "charset" parameter is not used; charset information is 666 transported inside the document in the form of an OPTIONAL Byte Order 667 Mark (BOM). The use of the UTF-8 encoding scheme [RFC3629], without 668 a BOM, is RECOMMENDED. 670 4.1. Lexical Structure 672 The lexical structure of a document in the textual format is made up 673 of four basic elements: line terminators, white space, comments, and 674 tokens. Of these, only tokens are significant in the syntactic 675 grammar. There are five kinds of tokens: identifiers, IRIs, IRI 676 references, literals, and punctuators. 678 token = identifier / iri / iriref / literal / punctuator 680 When several lexical grammar rules match a sequence of characters in 681 a document, the longest match takes priority. 683 4.1.1. Line Terminators 685 Line terminators divide text into lines. A line terminator is any 686 Unicode character with Line_Break class BK, CR, LF, or NL. However, 687 any CR character that immediately precedes a LF character is ignored. 688 (This affects only the numbering of lines in error messages.) 690 4.1.2. White Space 692 White space is a sequence of one or more white space characters. A 693 white space character is any Unicode character with the White_Space 694 property. 696 4.1.3. Comments 698 Comments are sequences of characters that are ignored when parsing 699 text into tokens. Single-line comments begin with the characters 700 "//" and extend to the end of the line. Delimited comments begin 701 with the characters "/*" and end with the characters "*/". Delimited 702 comments can occupy a portion of a line, a single line, or multiple 703 lines. 705 Comments do not nest. The character sequences "/*" and "*/" have no 706 special meaning within a single-line comment; the character sequences 707 "//" and "/*" have no special meaning within a delimited comment. 709 4.1.4. Identifiers 711 An identifier token is a user-defined symbolic name. The rules for 712 identifiers correspond to those recommended by the Unicode Standard 713 Annex #31 [UNICODE-UAX31] using the following profile: 715 identifier = START *CONTINUE *(MEDIAL 1*CONTINUE) 717 START = 719 CONTINUE = 721 MEDIAL = "-" / "." / "~" / %x58A / %xF0B 723 MEDIAL =/ %x2010 / %x2027 / %x30A0 / %x30FB 725 All identifiers MUST be converted into Unicode Normalization Form C 726 (NFC), as defined by the Unicode Standard Annex #15 [UNICODE-UAX15]. 727 Comparison of identifiers is based on NFC and is case-sensitive 728 (unless otherwise noted). 730 4.1.5. IRIs and IRI References 732 IRIs and IRI references are Unicode strings that conform to the 733 syntax defined in RFC 3987 [RFC3987]. An IRI reference can be either 734 an IRI or a relative reference. Both IRIs and IRI references are 735 enclosed in angle brackets ("<" and ">"). 737 iri = "<" IRI ">" 739 iriref = "<" IRI-reference ">" 741 IRI = 743 IRI-reference = 745 4.1.6. Literals 747 A literal is a textual representation of a value. There are seven 748 types of literals: Boolean, integer, floating-point, date/time, byte 749 string, text string, and null. 751 literal = boolean / integer / float / datetime / bytes / text 753 literal =/ null 755 4.1.6.1. Boolean Literals 757 The case-insensitive tokens "true" and "false" denote the Boolean 758 values true and false, respectively. 760 boolean = "true" / "false" 762 4.1.6.2. Integer Literals 764 Integer literals denote an integer value of unspecified precision. 765 By default, integer literals are expressed in decimal, but they can 766 also be specified in an alternate base using a prefix: Binary 767 literals begin with "0b", octal literals begin with "0o", and 768 hexadecimal literals begin with "0x". 770 Decimal literals contain the digits "0" through "9". Binary literals 771 contain "0" and "1", octal literals contain "0" through "7", and 772 hexadecimal literals contain "0" through "9" as well as "A" through 773 "F" in upper- or lowercase. 775 Negative integers are expressed by prepending a minus sign ("-"). 777 integer = ["+" / "-"] (decimal / binary / octal / hexadecimal) 779 decimal = 1*DIGIT 781 binary = %x30 (%x42 / %x62) 1*BINDIG 783 octal = %x30 (%x4F / %x6F) 1*OCTDIG 785 hexadecimal = %x30 (%x58 / %x78) 1*HEXDIG 787 DIGIT = %x30-39 789 BINDIG = %x30-31 791 OCTDIG = %x30-37 793 HEXDIG = %x30-39 / %x41-46 / %x61-66 795 4.1.6.3. Floating-point Literals 797 Floating-point literals denote a floating-point number of unspecified 798 precision. 800 Floating-point literals consist of a sequence of decimal digits 801 followed by a fraction, an exponent, or both. The fraction consists 802 of a decimal point (".") followed by a sequence of decimal digits. 803 The exponent consists of the letter "e" in upper- or lowercase, 804 followed by an optional sign and a sequence of decimal digits that 805 indicate a power of 10 by which the value preceding the "e" is 806 multiplied. 808 Negative floating-point values are expressed by prepending a minus 809 sign ("-"). 811 float = ["+" / "-"] 1*DIGIT [fraction] [exponent] 813 fraction = "." 1*DIGIT 815 exponent = (%x45 / %x65) ["+" / "-"] 1*DIGIT 817 A floating-point literal can additionally denote either the special 818 "Not-a-Number" (NaN) value, positive infinity, or negative infinity. 819 The NaN value is produced by the case-insensitive token "NaN". The 820 two infinite values are produced by the case-insensitive tokens 821 "+Infinity" (or simply "Infinity") and "-Infinity". 823 float =/ "NaN" 825 float =/ ["+" / "-"] "Infinity" 827 4.1.6.4. Date/Time Literals 829 Date/time literals denote an instant in time. 831 A date/time literal consists of the prefix "dt" and a sequence of 832 Unicode characters in Internet Date/Time Format [RFC3339], enclosed 833 in single quotes. 835 datetime = %x64.74 SQUOTE date-time SQUOTE 837 date-time = 839 SQUOTE = %x27 841 4.1.6.5. Byte String Literals 843 Byte string literals denote an ordered sequence of bytes. 845 A byte string literal consists of a prefix and zero or more bytes 846 encoded in Base16, Base32, or Base64 [RFC4648], enclosed in single 847 quotes. Byte string literals encoded in Base16 begin with "h" or 848 "b16", byte string literals encoded in Base32 begin with "b32", and 849 byte string literals encoded in Base64 begin with "b64". 851 bytes = base16 / base32 / base64 853 base16 = (%x68 / %x62.31.36) SQUOTE SQUOTE 855 base32 = %x62.33.32 SQUOTE SQUOTE 857 base64 = %x62.36.34 SQUOTE SQUOTE 859 4.1.6.6. Text String Literals 861 Text string literals denote a Unicode string. 863 A text string literal consists of zero or more Unicode characters 864 enclosed in double quotes. It can include simple escape sequences 865 (such as \t for the tab character) as well as hexadecimal and Unicode 866 escape sequences. 868 text = DQUOTE *(char / %x5C escape) DQUOTE 870 char = 872 escape = simple-escape / hexadecimal-escape / unicode-escape 874 simple-escape = %x30 / %x62 / %x74 / %x6E / %x76 876 simple-escape =/ %x66 / %x72 / %x22 / %x27 / %x5C 878 hexadecimal-escape = (%x78 / %x58) 2HEXDIG 880 unicode-escape = %x75 4HEXDIG / %x55 8HEXDIG 882 DQUOTE = %x22 884 An escape sequence denotes a single Unicode code point. For 885 hexadecimal and Unicode escape sequences, the code point is expressed 886 by the hexadecimal number following the "\x", "\X", "\u", or "\U" 887 prefix. Simple escape sequences indicate the code points listed in 888 Table 1. 890 +-----------------+------------+----------------------+ 891 | Escape Sequence | Code Point | Character Name | 892 +-----------------+------------+----------------------+ 893 | \0 | U+0000 | Null | 894 | \b | U+0008 | Backspace | 895 | \t | U+0009 | Character Tabulation | 896 | \n | U+000A | Line Feed | 897 | \v | U+000B | Line Tabulation | 898 | \f | U+000C | Form Feed | 899 | \r | U+000D | Carriage Return | 900 | \" | U+0022 | Quotation Mark | 901 | \' | U+0027 | Apostrophe | 902 | \\ | U+005C | Reverse Solidus | 903 +-----------------+------------+----------------------+ 905 Table 1: Simple Escape Sequences 907 4.1.6.7. Null Literal 909 The case-insensitive tokens "null" and "_" denote the intentional 910 absence of any value. 912 null = "null" / "_" 914 4.1.7. Punctuators 916 Punctuator tokens are used for grouping and separating. 918 punctuator = "#" / ":" / "*" / "[" / "]" / "{" / "}" / "=" / "->" 920 4.2. Syntactic Structure 922 The syntactic structure of a document in the textual format is made 923 up of four kinds of elements: links, forms, embedded representations, 924 and (as an extension to the CoRAL data model) directives. Directives 925 provide a way to make documents easier to read and write by setting a 926 base for relative IRI references and introducing shorthands for IRIs. 928 Elements are processed in the order they appear in the document. 929 Document processors need to maintain an _environment_ while iterating 930 a list of elements. The environment consists of three variables: the 931 _current context_, the _current base_, and the _current mapping from 932 identifiers to IRIs_. Both the current context and the current base 933 are initially set to the document's retrieval context. The current 934 mapping from identifiers to IRIs is initially empty. 936 4.2.1. Documents 938 The body of a document in the textual format consists of zero or more 939 links, forms, embedded representations, and directives. 941 document = body 943 body = *(link / form / representation / directive) 945 4.2.2. Links 947 A link consists of the link relation type, followed by the link 948 target, optionally followed by a link body enclosed in curly brackets 949 ("{" and "}"). 951 link = relation-type link-target ["{" body "}"] 953 The link relation type is denoted by either an IRI, a simple name, or 954 a qualified name. 956 relation-type = iri / simple-name / qualified-name 958 A simple name consists of an identifier. It is resolved to an IRI by 959 looking up the empty string in the current mapping from identifiers 960 to IRIs and appending the specified identifier to the result. It is 961 an error if the empty string is not present in the current mapping. 963 simple-name = identifier 965 A qualified name consists of two identifiers separated by a colon 966 (":"). It is resolved to an IRI by looking up the identifier on the 967 left hand side in the current mapping from identifiers to IRIs and 968 appending the identifier on the right hand side to the result. It is 969 an error if the identifier on the left hand side is not present in 970 the current mapping. 972 qualified-name = identifier ":" identifier 974 The link target is denoted by an IRI reference or represented by a 975 value literal. An IRI reference MUST be resolved against the current 976 base. If the link target is null, the link target is an unidentified 977 resource. 979 link-target = iriref / literal 981 The list of elements in the link body, if any, MUST be processed in a 982 fresh environment. Both the current context and current base in this 983 environment are initially set to the link target of the enclosing 984 link. The mapping from identifiers to IRIs is initially set to a 985 copy of the mapping from identifiers to IRIs in the current 986 environment. 988 4.2.3. Forms 990 A form consists of the operation type, followed by a "->" token and 991 the submission target, optionally followed by a list of form fields 992 enclosed in square brackets ("[" and "]"). 994 form = operation-type "->" submission-target ["[" form-fields "]"] 996 The operation type is defined in the same way as a link relation type 997 (Section 4.2.2). 999 operation-type = iri / simple-name / qualified-name 1001 The request method is either implied by the operation type or encoded 1002 as a form field. If there are both, the form field takes precedence 1003 over the operation type. Either way, the method MUST be defined for 1004 the Web transfer protocol identified by the scheme of the submission 1005 target. 1007 The submission target is denoted by an IRI reference. This IRI 1008 reference MUST be resolved against the current base. 1010 submission-target = iriref 1012 4.2.3.1. Form Fields 1014 A list of form fields consists of zero or more type-value pairs. 1016 form-fields = *(form-field-type form-field-value) 1018 The list, if any, MUST be processed in a fresh environment. Both the 1019 current context and the current base in this environment are 1020 initially set to the submission target of the enclosing form. The 1021 mapping from identifiers to IRIs is initially set to a copy of the 1022 mapping from identifiers to IRIs in the current environment. 1024 The form field type is defined in the same way as a link relation 1025 type (Section 4.2.2). 1027 form-field-type = iri / simple-name / qualified-name 1029 The form field value can be an IRI reference, Boolean literal, 1030 integer literal, floating-point literal, byte string literal, text 1031 string literal, or null. An IRI reference MUST be resolved against 1032 the current base. 1034 form-field-value = iriref / literal 1036 4.2.4. Embedded Representations 1038 An embedded representation consists of a "*" token, followed by the 1039 representation data, optionally followed by representation metadata 1040 enclosed in square brackets ("[" and "]"). 1042 representation = "*" bytes ["[" representation-metadata "]"] 1044 Representation metadata consists of zero or more name-value pairs. 1046 representation-metadata = *(metadata-name metadata-value) 1048 The metadata, if any, MUST be processed in a fresh environment. All 1049 variables in the new environment are initially set to a copy of the 1050 variables in the current environment. 1052 The metadata name is defined in the same way as a link relation type 1053 (Section 4.2.2). 1055 metadata-name = iri / simple-name / qualified-name 1057 The metadata value can be an IRI reference, Boolean literal, integer 1058 literal, floating-point literal, byte string literal, text string 1059 literal, or null. An IRI reference MUST be resolved against the 1060 current base. 1062 metadata-value = iriref / literal 1064 4.2.5. Directives 1066 Directives provide the ability to manipulate the environment when 1067 processing a list of elements. All directives start with a number 1068 sign ("#") followed by a directive identifier. Directive identifiers 1069 are case-insensitive and constrained to Unicode characters in the 1070 Basic Latin block. 1072 The following two types of directives are available: the Base 1073 directive and the Using directive. 1075 directive = base-directive / using-directive 1077 4.2.5.1. Base Directives 1079 A Base directive consists of a number sign ("#"), followed by the 1080 case-insensitive identifier "base", followed by a base. 1082 base-directive = "#" "base" base 1084 The base is denoted by an IRI reference. The IRI reference MUST be 1085 resolved against the current context (not the current base). 1087 base = iriref 1089 The directive is processed by resolving the IRI reference against the 1090 current context and assigning the result to the current base. 1092 4.2.5.2. Using Directives 1094 A Using directive consists of a number sign ("#"), followed by the 1095 case-insensitive identifier "using", optionally followed by an 1096 identifier and an equals sign ("="), finally followed by an IRI. If 1097 the identifier is not specified, it is assumed to be the empty 1098 string. 1100 using-directive = "#" "using" [identifier "="] iri 1102 The directive is processed by adding the specified identifier and IRI 1103 to the current mapping from identifiers to IRIs. It is an error if 1104 the identifier is already present in the mapping. 1106 5. Usage Considerations 1108 This section discusses some considerations in creating CoRAL-based 1109 applications and vocabularies. 1111 5.1. Specifying CoRAL-based Applications 1113 CoRAL-based applications naturally implement the Web architecture 1114 [W3C.REC-webarch-20041215] and thus are centered around orthogonal 1115 specifications for identification, interaction, and representation: 1117 o Resources are identified by IRIs or represented by value literals. 1119 o Interactions are based on the hypermedia interaction model of the 1120 Web and the methods provided by the Web transfer protocol. The 1121 semantics of possible interactions are identified by link relation 1122 types and operation types. 1124 o Representations are CoRAL documents encoded in the binary format 1125 defined in Section 3 or the textual format defined in Section 4. 1126 Depending on the application, additional representation formats 1127 may be used. 1129 5.1.1. Application Interfaces 1131 Specifications for CoRAL-based applications need to list the specific 1132 components used in the application interface and their identifiers. 1133 This should include the following items: 1135 o IRI schemes that identify the Web transfer protocol(s) used in the 1136 application. 1138 o Internet media types that identify the representation format(s) 1139 used in the application, including the media type(s) of the CoRAL 1140 serialization format(s). 1142 o Link relation types that identify the semantics of links. 1144 o Operation types that identify the semantics of forms. 1145 Additionally, for each operation type, the permissible request 1146 method(s). 1148 o Form field types that identify the semantics of form fields. 1149 Additionally, for each form field type, the permissible form field 1150 values. 1152 o Metadata names that identify the semantics of representation 1153 metadata. Additionally, for each metadata name, the permissible 1154 metadata values. 1156 5.1.2. Resource Names 1158 Resource names -- i.e., URIs [RFC3986] and IRIs [RFC3987] -- are a 1159 cornerstone of Web-based applications. They enable the uniform 1160 identification of resources and are used every time a client 1161 interacts with a server or a resource representation needs to refer 1162 to another resource. 1164 URIs and IRIs often include structured application data in the path 1165 and query components, such as paths in a filesystem or keys in a 1166 database. It is a common practice in many HTTP-based application 1167 programming interfaces (APIs) to make this part of the application 1168 specification, i.e., to prescribe fixed URI templates that are hard- 1169 coded in implementations. There are a number of problems with this 1170 practice [RFC7320], though. 1172 In CoRAL-based applications, resource names are therefore not part of 1173 the application specification -- they are an implementation detail. 1174 The specification of a CoRAL-based application MUST NOT mandate any 1175 particular form of resource name structure. BCP 190 [RFC7320] 1176 describes the problematic practice of fixed URI structures in more 1177 detail and provides some acceptable alternatives. 1179 5.1.3. Implementation Limits 1181 This document places no restrictions on the number of elements in a 1182 CoRAL document or the depth of nested elements. Applications using 1183 CoRAL (in particular those running in constrained environments) may 1184 wish to limit these numbers and specify implementation limits that an 1185 application implementation must at least support to be interoperable. 1187 Applications may also mandate the following and other restrictions: 1189 o use of only either the binary format or the text format; 1191 o use of only either HTTP or CoAP as supported Web transfer 1192 protocol; 1194 o use of only dictionary references in the binary format for certain 1195 vocabulary; 1197 o use of only either content type strings or content format IDs; 1199 o use of IRI references only up to a specific string length; 1201 o use of CBOR in a canonical format (see Section 3.9 of RFC 7049). 1203 5.2. Minting Vocabulary 1205 New link relation types, operation types, form field types, and 1206 metadata names can be minted by defining an IRI [RFC3987] that 1207 uniquely identifies the item. Although the IRI can point to a 1208 resource that contains a definition of the semantics, clients SHOULD 1209 NOT automatically access that resource to avoid overburdening its 1210 server. The IRI SHOULD be under the control of the person or party 1211 defining it, or be delegated to them. 1213 To avoid interoperability problems, it is RECOMMENDED that only IRIs 1214 are minted that are normalized according to Section 5.3 of RFC 3987. 1215 Non-normalized forms that are best avoided include: 1217 o Uppercase characters in scheme names and domain names 1219 o Percent-encoding of characters where it is not required by the IRI 1220 syntax 1222 o Explicitly stated HTTP default port (e.g., 1223 is preferable over ) 1225 o Completely empty path in HTTP IRIs (e.g., is 1226 preferable over ) 1228 o Dot segments ("/./" or "/../") in the path component of an IRI 1230 o Lowercase hexadecimal letters within percent-encoding triplets 1231 (e.g., "%3F" is preferable over "%3f") 1233 o Punycode-encoding of Internationalized Domain Names in IRIs 1235 o IRIs that are not in Unicode Normalization Form C [UNICODE-UAX15] 1237 IRIs that identify vocabulary do not need to be registered. The 1238 inclusion of domain names in IRIs allows for the decentralized 1239 creation of new IRIs without the risk of collisions. 1241 However, IRIs can be relatively verbose and impose a high overhead on 1242 a representation. This can be a problem in constrained environments 1243 [RFC7228]. Therefore, CoRAL alternatively allows the use of unsigned 1244 integers to reference CBOR data items from a dictionary, as specified 1245 in Section 3.2. These impose a much smaller overhead but instead 1246 need to be assigned by an authority to avoid collisions. 1248 5.3. Expressing Registered Link Relation Types 1250 Link relation types registered in the IANA Link Relations Registry, 1251 such as "collection" [RFC6573] or "icon" [W3C.REC-html52-20171214], 1252 can be used in CoRAL by appending the registered name to the IRI 1253 : 1255 #using iana = 1257 iana:collection 1258 iana:icon 1260 Note that registered link relation types are required to be 1261 lowercased, as per Section 3.3 of RFC 8288 [RFC8288]. 1263 (The convention of appending the link relation types to the prefix 1264 "http://www.iana.org/assignments/relation/" to form IRIs is adopted 1265 from Atom [RFC4287]; see also Appendix A.2 of RFC 8288 [RFC8288].) 1267 5.4. Expressing Simple RDF Statements 1269 An RDF statement [W3C.REC-rdf11-concepts-20140225] says that some 1270 relationship, indicated by a predicate, holds between two resources. 1271 RDF predicates can therefore be good source for vocabulary to provide 1272 resource metadata. For example, a CoRAL document could use the FOAF 1273 vocabulary [FOAF] to describe the person or software that made it: 1275 #using rdf = 1276 #using foaf = 1278 foaf:maker null { 1279 rdf:type 1280 foaf:familyName "Hartke" 1281 foaf:givenName "Klaus" 1282 foaf:mbox 1283 } 1285 5.5. Expressing Language-Tagged Strings 1287 Text strings that are the target of a link can be associated with a 1288 language tag [RFC5646] by nesting a link of type 1289 under the link. The target of this 1290 nested link MUST be a text string that conforms to the syntax 1291 specified in Section 2.1 of RFC 5646: 1293 #using 1294 #using example = 1295 #using iana = 1297 iana:terms-of-service { 1298 example:title "Nutzungsbedingungen" { lang "de" } 1299 example:title "Terms of use" { lang "en" } 1300 } 1302 5.6. Embedding CoRAL in CBOR Data 1304 Data items in the CoRAL binary format (Section 3) may be embedded in 1305 other CBOR data [RFC7049] data. Specifications using CDDL [RFC8610] 1306 SHOULD reference the following CDDL definitions for this purpose: 1308 CoRAL-Document = document 1310 CoRAL-Link = link 1312 CoRAL-Form = form 1314 For each embedded document, link, and form, the retrieval context, 1315 link context, and form context needs to be specified, respectively. 1317 5.7. Submitting CoRAL Documents 1319 By default, a CoRAL document is a representation that captures the 1320 current state of a resource. The meaning of a CoRAL document changes 1321 when it is submitted in a request. Depending on the request method, 1322 the CoRAL document can capture the intended state of a resource (PUT) 1323 or be subject to application-specific processing (POST). 1325 5.7.1. PUT Requests 1327 A PUT request with a CoRAL document enclosed in the request payload 1328 requests that the state of the target resource be created or replaced 1329 with the state described by the CoRAL document. A successful PUT of 1330 a CoRAL document generally means that a subsequent GET on that same 1331 target resource would result in an equivalent document being sent in 1332 a success response. 1334 An origin server SHOULD verify that a submitted CoRAL document is 1335 consistent with any constraints the server has for the target 1336 resource. When a document is inconsistent with the target resource, 1337 the origin server SHOULD either make it consistent (e.g., by removing 1338 inconsistent elements) or respond with an appropriate error message 1339 containing sufficient information to explain why the document is 1340 unsuitable. 1342 The retrieval context of a CoRAL document in a PUT is the request IRI 1343 of the request. 1345 5.7.2. POST Requests 1347 A POST request with a CoRAL document enclosed in the request payload 1348 requests that the target resource process the CoRAL document 1349 according to the resource's own specific semantics. 1351 The retrieval context of a CoRAL document in a POST is the request 1352 IRI of the request. 1354 6. Security Considerations 1356 Parsers of CoRAL documents must operate on input that is assumed to 1357 be untrusted. This means that parsers MUST fail gracefully in the 1358 face of malicious inputs (e.g., inputs not adhering to the data 1359 structure). Additionally, parsers MUST be prepared to deal with 1360 resource exhaustion (e.g., resulting from the allocation of big data 1361 items) or exhaustion of the call stack (stack overflow). 1363 CoRAL documents intentionally do not feature the equivalent of XML 1364 entity references as to preclude the whole class of exponential XML 1365 entity expansion ("billion laughs") [CAPEC-197] and improper XML 1366 external entity [CAPEC-201] attacks. 1368 Implementers of the CoRAL binary format need to consider the security 1369 aspects of processing CBOR with the restrictions described in 1370 Section 3. Notably, different number representations for the same 1371 numeric value are not equivalent in the CoRAL binary format. See 1372 Section 8 of RFC 7049 [RFC7049] for security considerations relating 1373 to CBOR. 1375 Implementers of the CoRAL textual format need to consider the 1376 security aspects of handling Unicode input. See the Unicode Standard 1377 Annex #36 [UNICODE-UAX36] for security considerations relating to 1378 visual spoofing and misuse of character encodings. See Section 10 of 1379 RFC 3629 [RFC3629] for security considerations relating to UTF-8. 1381 CoRAL makes extensive use of IRIs and URIs. See Section 8 of RFC 1382 3987 [RFC3987] for security considerations relating to IRIs. See 1383 Section 7 of RFC 3986 [RFC3986] for security considerations relating 1384 to URIs. 1386 The security of applications using CoRAL can depend on the proper 1387 preparation and comparison of internationalized strings. For 1388 example, such strings can be used to make authentication and 1389 authorization decisions, and the security of an application could be 1390 compromised if an entity providing a given string is connected to the 1391 wrong account or online resource based on different interpretations 1392 of the string. See RFC 6943 [RFC6943] for security considerations 1393 relating to identifiers in IRIs and other places. 1395 CoRAL is intended to be used in conjunction with a Web transfer 1396 protocol like HTTP or CoAP. See Section 9 of RFC 7230 [RFC7230], 1397 Section 9 of RFC 7231 [RFC7231], etc., for security considerations 1398 relating to HTTP. See Section 11 of RFC 7252 [RFC7252] for security 1399 considerations relating to CoAP. 1401 CoRAL does not define any specific mechanisms for protecting the 1402 confidentiality and integrity of CoRAL documents. It relies on 1403 application layer or transport layer mechanisms for this, such as 1404 Transport Layer Security (TLS) [RFC8446]. 1406 CoRAL documents and the structure of a web of resources revealed from 1407 automatically following links can disclose personal information and 1408 other sensitive information. Implementations need to prevent the 1409 unintentional disclosure of such information. See Section of 9 of 1410 RFC 7231 [RFC7231] for additional considerations. 1412 Applications using CoRAL ought to consider the attack vectors opened 1413 by automatically following, trusting, or otherwise using links and 1414 forms in CoRAL documents. Notably, a server that is authoritative 1415 for the CoRAL representation of a resource may not necessarily be 1416 authoritative for nested elements in the document. See Section 5 of 1417 RFC 8288 [RFC8288] for related considerations. 1419 Unless an application mitigates this risk by specifying more specific 1420 rules, any link or form in a document where the link or form context 1421 and the document's retrieval context don't share the same Web origin 1422 [RFC6454] MUST be discarded ("same-origin policy"). 1424 7. IANA Considerations 1426 7.1. Media Type "application/coral+cbor" 1428 This document registers the media type "application/coral+cbor" 1429 according to the procedures of BCP 13 [RFC6838]. 1431 Type name: 1432 application 1434 Subtype name: 1435 coral+cbor 1437 Required parameters: 1439 N/A 1441 Optional parameters: 1442 dictionary - See Section 3.2 of [I-D.hartke-t2trg-coral]. 1444 Encoding considerations: 1445 binary - See Section 3 of [I-D.hartke-t2trg-coral]. 1447 Security considerations: 1448 See Section 6 of [I-D.hartke-t2trg-coral]. 1450 Interoperability considerations: 1451 N/A 1453 Published specification: 1454 [I-D.hartke-t2trg-coral] 1456 Applications that use this media type: 1457 See Section 1 of [I-D.hartke-t2trg-coral]. 1459 Fragment identifier considerations: 1460 As specified for "application/cbor". 1462 Additional information: 1463 Deprecated alias names for this type: N/A 1464 Magic number(s): N/A 1465 File extension(s): .coral.cbor 1466 Macintosh file type code(s): N/A 1468 Person & email address to contact for further information: 1469 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1471 Intended usage: 1472 COMMON 1474 Restrictions on usage: 1475 N/A 1477 Author: 1478 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1480 Change controller: 1481 IESG 1483 Provisional registration? 1484 No 1486 7.2. Media Type "text/coral" 1488 This document registers the media type "text/coral" according to the 1489 procedures of BCP 13 [RFC6838] and guidelines in RFC 6657 [RFC6657]. 1491 Type name: 1492 text 1494 Subtype name: 1495 coral 1497 Required parameters: 1498 N/A 1500 Optional parameters: 1501 N/A 1503 Encoding considerations: 1504 binary - See Section 4 of [I-D.hartke-t2trg-coral]. 1506 Security considerations: 1507 See Section 6 of [I-D.hartke-t2trg-coral]. 1509 Interoperability considerations: 1510 N/A 1512 Published specification: 1513 [I-D.hartke-t2trg-coral] 1515 Applications that use this media type: 1516 See Section 1 of [I-D.hartke-t2trg-coral]. 1518 Fragment identifier considerations: 1519 N/A 1521 Additional information: 1522 Deprecated alias names for this type: N/A 1523 Magic number(s): N/A 1524 File extension(s): .coral 1525 Macintosh file type code(s): N/A 1527 Person & email address to contact for further information: 1528 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1530 Intended usage: 1531 COMMON 1533 Restrictions on usage: 1535 N/A 1537 Author: 1538 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1540 Change controller: 1541 IESG 1543 Provisional registration? 1544 No 1546 7.3. CoAP Content Formats 1548 This document registers CoAP content formats for the content types 1549 "application/coral+cbor" and "text/coral" according to the procedures 1550 of RFC 7252 [RFC7252]. 1552 o Content Type: application/coral+cbor 1553 Content Coding: identity 1554 ID: TBD3 1555 Reference: [I-D.hartke-t2trg-coral] 1557 o Content Type: text/coral 1558 Content Coding: identity 1559 ID: TBD4 1560 Reference: [I-D.hartke-t2trg-coral] 1562 [[NOTE TO RFC EDITOR: Please replace all occurrences of "TBD3" and 1563 "TBD4" in this document with the code points assigned by IANA.]] 1565 [[NOTE TO IMPLEMENTERS: Experimental implementations can use content 1566 format ID 65087 for "application/coral+cbor" and content format ID 1567 65343 for "text/coral" until IANA has assigned code points.]] 1569 7.4. CBOR Tag 1571 This document registers a CBOR tag for dictionary references 1572 according to the procedures of RFC 7049 [RFC7049]. 1574 o Tag: TBD6 1575 Data Item: unsigned integer 1576 Semantics: Dictionary reference 1577 Reference: [I-D.hartke-t2trg-coral] 1579 [[NOTE TO RFC EDITOR: Please replace all occurrences of "TBD6" in 1580 this document with the code point assigned by IANA.]] 1582 8. References 1584 8.1. Normative References 1586 [I-D.hartke-t2trg-ciri] 1587 Hartke, K., "Constrained Internationalized Resource 1588 Identifiers", draft-hartke-t2trg-ciri-03 (work in 1589 progress), July 2019. 1591 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1592 Requirement Levels", BCP 14, RFC 2119, 1593 DOI 10.17487/RFC2119, March 1997, 1594 . 1596 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1597 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1598 . 1600 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1601 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1602 2003, . 1604 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1605 Resource Identifier (URI): Generic Syntax", STD 66, 1606 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1607 . 1609 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1610 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 1611 January 2005, . 1613 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1614 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1615 . 1617 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1618 Specifications: ABNF", STD 68, RFC 5234, 1619 DOI 10.17487/RFC5234, January 2008, 1620 . 1622 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1623 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1624 September 2009, . 1626 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1627 DOI 10.17487/RFC6454, December 2011, 1628 . 1630 [RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding 1631 "charset" Parameter Handling in Textual Media Types", 1632 RFC 6657, DOI 10.17487/RFC6657, July 2012, 1633 . 1635 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1636 Specifications and Registration Procedures", BCP 13, 1637 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1638 . 1640 [RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for 1641 Security Purposes", RFC 6943, DOI 10.17487/RFC6943, May 1642 2013, . 1644 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1645 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1646 October 2013, . 1648 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1649 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1650 May 2017, . 1652 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1653 Definition Language (CDDL): A Notational Convention to 1654 Express Concise Binary Object Representation (CBOR) and 1655 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1656 June 2019, . 1658 [UNICODE] The Unicode Consortium, "The Unicode Standard", 1659 . 1661 Note that this reference is to the latest version of 1662 Unicode, rather than to a specific release. It is not 1663 expected that future changes in the Unicode specification 1664 will have any impact on this document. 1666 [UNICODE-UAX15] 1667 The Unicode Consortium, "Unicode Standard Annex #15: 1668 Unicode Normalization Forms", 1669 . 1671 [UNICODE-UAX31] 1672 The Unicode Consortium, "Unicode Standard Annex #31: 1673 Unicode Identifier and Pattern Syntax", 1674 . 1676 [UNICODE-UAX36] 1677 The Unicode Consortium, "Unicode Standard Annex #36: 1678 Unicode Security Considerations", 1679 . 1681 8.2. Informative References 1683 [CAPEC-197] 1684 MITRE, "CAPEC-197: XML Entity Expansion", July 2018, 1685 . 1687 [CAPEC-201] 1688 MITRE, "CAPEC-201: XML Entity Linking", July 2018, 1689 . 1691 [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification 1692 0.99", January 2014, 1693 . 1695 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1696 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 1697 December 2005, . 1699 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1700 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1701 . 1703 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 1704 RFC 6573, DOI 10.17487/RFC6573, April 2012, 1705 . 1707 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1708 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1709 . 1711 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1712 Constrained-Node Networks", RFC 7228, 1713 DOI 10.17487/RFC7228, May 2014, 1714 . 1716 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1717 Protocol (HTTP/1.1): Message Syntax and Routing", 1718 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1719 . 1721 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1722 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1723 DOI 10.17487/RFC7231, June 2014, 1724 . 1726 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1727 Application Protocol (CoAP)", RFC 7252, 1728 DOI 10.17487/RFC7252, June 2014, 1729 . 1731 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 1732 RFC 7320, DOI 10.17487/RFC7320, July 2014, 1733 . 1735 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1736 FETCH Methods for the Constrained Application Protocol 1737 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1738 . 1740 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1741 DOI 10.17487/RFC8288, October 2017, 1742 . 1744 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1745 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1746 . 1748 [W3C.REC-html52-20171214] 1749 Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and 1750 S. Moon, "HTML 5.2", World Wide Web Consortium 1751 Recommendation REC-html52-20171214, December 2017, 1752 . 1754 [W3C.REC-rdf-schema-20140225] 1755 Brickley, D. and R. Guha, "RDF Schema 1.1", World Wide Web 1756 Consortium Recommendation REC-rdf-schema-20140225, 1757 February 2014, 1758 . 1760 [W3C.REC-rdf11-concepts-20140225] 1761 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 1762 Concepts and Abstract Syntax", World Wide Web Consortium 1763 Recommendation REC-rdf11-concepts-20140225, February 2014, 1764 . 1766 [W3C.REC-turtle-20140225] 1767 Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", 1768 World Wide Web Consortium Recommendation REC-turtle- 1769 20140225, February 2014, 1770 . 1772 [W3C.REC-webarch-20041215] 1773 Jacobs, I. and N. Walsh, "Architecture of the World Wide 1774 Web, Volume One", World Wide Web Consortium 1775 Recommendation REC-webarch-20041215, December 2004, 1776 . 1778 Appendix A. Core Vocabulary 1780 This section defines the core vocabulary for CoRAL: a set of link 1781 relation types, operation types, form field types, and metadata 1782 names. 1784 A.1. Base 1786 Link Relation Types: 1788 1789 Indicates that the link's context is an instance of the class 1790 specified as the link's target, as defined by RDF Schema 1791 [W3C.REC-rdf-schema-20140225]. 1793 1794 Indicates that the link target is a language tag [RFC5646] that 1795 specifies the language of the link context. 1797 The link target MUST be a text string in the format specified in 1798 Section 2.1 of RFC 5646 [RFC5646]. 1800 Operation Types: 1802 1803 Indicates that the state of the form's context can be replaced 1804 with the state described by a representation submitted to the 1805 server. 1807 This operation type defaults to the PUT method [RFC7231] [RFC7252] 1808 for both HTTP and CoAP. Typical overrides by a form field include 1809 the PATCH method [RFC5789] [RFC8132] for HTTP and CoAP and the 1810 iPATCH method [RFC8132] for CoAP. 1812 1813 Indicates that the form's context can be searched by submitting a 1814 search query. 1816 This operation type defaults to the POST method [RFC7231] for HTTP 1817 and the FETCH method [RFC8132] for CoAP. Typical overrides by a 1818 form field include the POST method [RFC7252] for CoAP. 1820 A.2. Collections 1822 Link Relation Types: 1824 1825 Indicates that the link's context is a collection and that the 1826 link's target is a member of that collection, as defined in 1827 Section 2.1 of RFC 6573 [RFC6573]. 1829 1830 Indicates that the link's target is a collection and that the 1831 link's context is a member of that collection, as defined in 1832 Section 2.2 of RFC 6573 [RFC6573]. 1834 Operation Types: 1836 1837 Indicates that the form's context is a collection and that a new 1838 item can be created in that collection with the state defined by a 1839 representation submitted to the server. 1841 This operation type defaults to the POST method [RFC7231] 1842 [RFC7252] for both HTTP and CoAP. 1844 1845 Indicates that the form's context is a member of a collection and 1846 that the form's context can be removed from that collection. 1848 This operation type defaults to the DELETE method [RFC7231] 1849 [RFC7252] for both HTTP and CoAP. 1851 A.3. HTTP 1853 Form Field Types: 1855 1856 Specifies the HTTP method for the request. 1858 The form field value MUST be a text string in the format defined 1859 in Section 4.1 of RFC 7231 [RFC7231]. The set of possible values 1860 is maintained in the IANA HTTP Method Registry. 1862 A form field of this type MUST NOT occur more than once in a form. 1863 If absent, it defaults to the request method implied by the form's 1864 operation type. 1866 1867 Specifies an acceptable HTTP content type for the request payload. 1868 There may be multiple form fields of this type. If a form does 1869 not include a form field of this type, the server accepts any or 1870 no request payload, depending on the operation type. 1872 The form field value MUST be a text string in the format defined 1873 in Section 3.1.1.1 of RFC 7231 [RFC7231]. The possible set of 1874 media types and their parameters are maintained in the IANA Media 1875 Types Registry. 1877 Representation Metadata: 1879 1880 Specifies the HTTP content type of the representation. 1882 The metadata value MUST be specified as a text string in the 1883 format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]. The 1884 possible set of media types and their parameters are maintained in 1885 the IANA Media Types Registry. 1887 Metadata of this type MUST NOT occur more than once for a 1888 representation. If absent, its value defaults to content type 1889 "application/octet-stream". 1891 A.4. CoAP 1893 Form Field Types: 1895 1896 Specifies the CoAP method for the request. 1898 The form field value MUST be an integer identifying one of the 1899 CoAP request methods maintained in the IANA CoAP Method Codes 1900 Registry (e.g., the integer 2 for the POST method). 1902 A form field of this type MUST NOT occur more than once in a form. 1903 If absent, it defaults to the request method implied by the form's 1904 operation type. 1906 1907 Specifies an acceptable CoAP content format for the request 1908 payload. There may be multiple form fields of this type. If a 1909 form does not include a form field of this type, the server 1910 accepts any or no request payload, depending on the operation 1911 type. 1913 The form field value MUST be an integer identifying one of content 1914 formats maintained in the IANA CoAP Content-Formats Registry. 1916 Representation Metadata: 1918 1919 Specifies the CoAP content format of the representation. 1921 The metadata value MUST be an integer identifying one of content 1922 formats maintained in the IANA CoAP Content-Formats Registry. 1924 Metadata of this type MUST NOT occur more than once for a 1925 representation. If absent, it defaults to content format 42 1926 (i.e., content type "application/octet-stream" without a content 1927 coding). 1929 Appendix B. Default Dictionary 1931 This section defines a default dictionary that is assumed when the 1932 "application/coral+cbor" media type is used without a "dictionary" 1933 parameter. 1935 +-----+-------------------------------------------------------+ 1936 | Key | Value | 1937 +-----+-------------------------------------------------------+ 1938 | 0 | | 1939 | 1 | | 1940 | 2 | | 1941 | 3 | | 1942 | 4 | | 1943 | 5 | | 1944 | 6 | | 1945 | 7 | | 1946 | 8 | | 1947 | 9 | | 1948 | 10 | | 1949 +-----+-------------------------------------------------------+ 1951 Table 2: Default Dictionary 1953 Acknowledgements 1955 Thanks to Christian Amsuess, Carsten Bormann, Jaime Jimenez, 1956 Sebastian Kaebisch, Ari Keranen, Michael Koster, Matthias Kovatsch, 1957 Jim Schaad, and Niklas Widell for helpful comments and discussions 1958 that have shaped the document. 1960 Author's Address 1962 Klaus Hartke 1963 Ericsson 1964 Torshamnsgatan 23 1965 Stockholm SE-16483 1966 Sweden 1968 Email: klaus.hartke@ericsson.com