idnits 2.17.1 draft-hartke-t2trg-coral-08.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 == Line 1305 has weird spacing: '...ttr:obs true...' -- The document date (March 11, 2019) is 1872 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 1621, but not defined == Outdated reference: A later version (-03) exists of draft-hartke-t2trg-ciri-02 == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-07 ** 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 (~~), 5 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 March 11, 2019 5 Expires: September 12, 2019 7 The Constrained RESTful Application Language (CoRAL) 8 draft-hartke-t2trg-coral-08 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 September 12, 2019. 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. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 3. Data and Interaction Model . . . . . . . . . . . . . . . . . 4 56 3.1. Browsing Context . . . . . . . . . . . . . . . . . . . . 5 57 3.2. Documents . . . . . . . . . . . . . . . . . . . . . . . . 5 58 3.3. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 3.4. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 3.5. Form Fields . . . . . . . . . . . . . . . . . . . . . . . 7 61 3.6. Embedded Representations . . . . . . . . . . . . . . . . 7 62 3.7. Navigation . . . . . . . . . . . . . . . . . . . . . . . 7 63 3.8. History Traversal . . . . . . . . . . . . . . . . . . . . 9 64 4. Binary Format . . . . . . . . . . . . . . . . . . . . . . . . 9 65 4.1. Data Structure . . . . . . . . . . . . . . . . . . . . . 10 66 4.1.1. Documents . . . . . . . . . . . . . . . . . . . . . . 10 67 4.1.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 10 68 4.1.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 11 69 4.1.4. Embedded Representations . . . . . . . . . . . . . . 12 70 4.1.5. Directives . . . . . . . . . . . . . . . . . . . . . 13 71 4.2. Dictionaries . . . . . . . . . . . . . . . . . . . . . . 13 72 4.2.1. Dictionary References . . . . . . . . . . . . . . . . 13 73 4.2.2. Media Type Parameter . . . . . . . . . . . . . . . . 14 74 5. Textual Format . . . . . . . . . . . . . . . . . . . . . . . 14 75 5.1. Lexical Structure . . . . . . . . . . . . . . . . . . . . 15 76 5.1.1. Line Terminators . . . . . . . . . . . . . . . . . . 15 77 5.1.2. White Space . . . . . . . . . . . . . . . . . . . . . 15 78 5.1.3. Comments . . . . . . . . . . . . . . . . . . . . . . 15 79 5.1.4. Identifiers . . . . . . . . . . . . . . . . . . . . . 16 80 5.1.5. IRIs and IRI References . . . . . . . . . . . . . . . 16 81 5.1.6. Literals . . . . . . . . . . . . . . . . . . . . . . 16 82 5.1.7. Punctuators . . . . . . . . . . . . . . . . . . . . . 20 83 5.2. Syntactic Structure . . . . . . . . . . . . . . . . . . . 20 84 5.2.1. Documents . . . . . . . . . . . . . . . . . . . . . . 21 85 5.2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 21 86 5.2.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 22 87 5.2.4. Embedded Representations . . . . . . . . . . . . . . 23 88 5.2.5. Directives . . . . . . . . . . . . . . . . . . . . . 23 89 6. Usage Considerations . . . . . . . . . . . . . . . . . . . . 24 90 6.1. Specifying CoRAL-based Applications . . . . . . . . . . . 24 91 6.1.1. Application Interfaces . . . . . . . . . . . . . . . 25 92 6.1.2. Resource Names . . . . . . . . . . . . . . . . . . . 25 93 6.1.3. Implementation Limits . . . . . . . . . . . . . . . . 26 94 6.2. Minting Vocabulary . . . . . . . . . . . . . . . . . . . 26 95 6.3. Expressing Registered Link Relation Types . . . . . . . . 27 96 6.4. Expressing Link Target Attributes . . . . . . . . . . . . 28 97 6.5. Expressing Simple RDF Statements . . . . . . . . . . . . 29 98 6.6. Embedding CoRAL in CBOR Structures . . . . . . . . . . . 29 99 6.7. Submitting CoRAL Documents . . . . . . . . . . . . . . . 30 100 6.7.1. PUT Requests . . . . . . . . . . . . . . . . . . . . 30 101 6.7.2. POST Requests . . . . . . . . . . . . . . . . . . . . 30 102 7. Security Considerations . . . . . . . . . . . . . . . . . . . 30 103 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 104 8.1. Media Type "application/coral+cbor" . . . . . . . . . . . 32 105 8.2. Media Type "text/coral" . . . . . . . . . . . . . . . . . 33 106 8.3. CoAP Content Formats . . . . . . . . . . . . . . . . . . 34 107 8.4. CBOR Tag . . . . . . . . . . . . . . . . . . . . . . . . 35 108 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 109 9.1. Normative References . . . . . . . . . . . . . . . . . . 35 110 9.2. Informative References . . . . . . . . . . . . . . . . . 37 111 Appendix A. Core Vocabulary . . . . . . . . . . . . . . . . . . 39 112 A.1. Link Relation Types . . . . . . . . . . . . . . . . . . . 39 113 A.2. Operation Types . . . . . . . . . . . . . . . . . . . . . 40 114 A.3. Form Field Types . . . . . . . . . . . . . . . . . . . . 40 115 A.4. Representation Metadata . . . . . . . . . . . . . . . . . 40 116 Appendix B. Default Dictionary . . . . . . . . . . . . . . . . . 41 117 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 41 118 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 41 120 1. Introduction 122 The Constrained RESTful Application Language (CoRAL) is a language 123 for the description of typed connections between resources on the Web 124 ("links"), possible operations on such resources ("forms"), as well 125 as simple resource metadata. 127 CoRAL is intended for driving automated software agents that navigate 128 a Web application based on a standardized vocabulary of link relation 129 types and operation types. It is designed to be used in conjunction 130 with a Web transfer protocol such as the Hypertext Transfer Protocol 131 (HTTP) [RFC7230] or the Constrained Application Protocol (CoAP) 132 [RFC7252]. 134 This document defines the CoRAL data and interaction model, as well 135 as two specialized CoRAL serialization formats. 137 The CoRAL data and interaction model is a superset of the Web Linking 138 model of RFC 8288 [RFC8288]. The data model consists of two primary 139 elements: "links" that describe the relationship between two 140 resources and the type of that relationship, and "forms" that 141 describe a possible operation on a resource and the type of that 142 operation. Additionally, the data model can describe simple resource 143 metadata in a way similar to the Resource Description Framework (RDF) 144 [W3C.REC-rdf11-concepts-20140225]. In contrast to RDF, the focus of 145 CoRAL however is on the interaction with resources, not just the 146 relationships between them. The interaction model derives from HTML 147 5 [W3C.REC-html52-20171214] and specifies how an automated software 148 agent can navigate between resources by following links and perform 149 operations on resources by submitting forms. 151 The primary CoRAL serialization format is a compact, binary encoding 152 of links and forms in Concise Binary Object Representation (CBOR) 153 [RFC7049]. It is intended for environments with constraints on 154 power, memory, and processing resources [RFC7228] and shares many 155 similarities with the message format of the Constrained Application 156 Protocol (CoAP) [RFC7252]: For example, it uses numeric identifiers 157 instead of verbose strings for link relation types and operation 158 types, and pre-parses Uniform Resource Identifiers (URIs) [RFC3986] 159 into (what CoAP considers to be) their components, which simplifies 160 URI processing for constrained nodes a lot. As a result, link 161 serializations in CoRAL are often much more compact than equivalent 162 serializations in CoRE Link Format [RFC6690]. 164 The secondary CoRAL serialization format is a lightweight, textual 165 encoding of links and forms that is intended to be easy to read and 166 write for humans. The format is loosely inspired by the syntax of 167 Turtle [W3C.REC-turtle-20140225] and is mainly intended for giving 168 examples. 170 1.1. Notational Conventions 172 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 173 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 174 "OPTIONAL" in this document are to be interpreted as described in BCP 175 14 [RFC2119] [RFC8174] when, and only when, they appear in all 176 capitals, as shown here. 178 Terms defined in this document appear in _cursive_ where they are 179 introduced. 181 2. Examples 183 [[NOTE TO READERS: Examples and test vectors will be provided on a 184 companion website.]] 186 3. Data and Interaction Model 188 The Constrained RESTful Application Language (CoRAL) is designed for 189 building Web-based applications [W3C.REC-webarch-20041215] in which 190 automated software agents navigate between resources by following 191 links and perform operations on resources by submitting forms. 193 3.1. Browsing Context 195 Borrowing from HTML 5 [W3C.REC-html52-20171214], each such agent 196 maintains a _browsing context_ in which the representations of Web 197 resources are processed. (In HTML 5, the browsing context typically 198 corresponds to a tab or window in a Web browser.) 200 At any time, one representation in each browsing context is 201 designated the _active_ representation. 203 3.2. Documents 205 A resource representation in one of the CoRAL serialization formats 206 is called a CoRAL _document_. The Internationalized Resource 207 Identifier (IRI) [RFC3987] that was used to retrieve such a document 208 is called the document's _retrieval context_. 210 A CoRAL document consists of a list of zero or more links, forms, and 211 embedded resource representations, collectively called _elements_. 212 CoRAL serialization formats may define additional types of elements 213 for efficiency or convenience, such as a base for relative IRI 214 references [RFC3987]. 216 3.3. Links 218 A _link_ describes a relationship between two resources on the Web 219 [RFC8288]. As defined in RFC 8288, it consists of a _link context_, 220 a _link relation type_, and a _link target_. In CoRAL, a link can 221 additionally have a nested list of zero or more elements, which take 222 the place of link target attributes. 224 A link can be viewed as a statement of the form "{link context} has a 225 {link relation type} resource at {link target}" where the link target 226 may be further described by nested elements. 228 The link relation type identifies the semantics of a link. In HTML 5 229 and RFC 8288, link relation types are typically denoted by an IANA- 230 registered name, such as "stylesheet" or "type". In CoRAL, they are 231 denoted by an IRI such as or . 233 This allows for the creation of new link relation types without the 234 risk of collisions when from different organizations or domains of 235 knowledge. An IRI also can lead to documentation, schema, and other 236 information about the link relation type. These IRIs are primarily 237 used as identity tokens, though, and are compared using Simple String 238 Comparison (Section 5.1 of RFC 3987). 240 The link context and the link target are both either by an IRI or 241 (similarly to RDF) a literal. If the IRI scheme indicates a Web 242 transfer protocol such as HTTP or CoAP, then an agent can dereference 243 the IRI and navigate the browsing context to the referenced resource; 244 this is called _following the link_. A literal directly identifies a 245 value. This can be a Boolean value, an integer, a floating-point 246 number, a date/time value, a byte string, or a text string. 248 A link can occur as a top-level element in a document or as a nested 249 element within a link. When a link occurs as a top-level element, 250 the link context implicitly is the document's retrieval context. 251 When a link occurs nested within a link, the link context of the 252 inner link is the link target of the outer link. 254 There are no restrictions on the cardinality of links; there can be 255 multiple links to and from a particular target, and multiple links of 256 the same or different types between a given link context and target. 257 However, the nested data structure constrains the description of a 258 resource graph to a tree: Links between linked resources can only be 259 described by further nesting links. 261 3.4. Forms 263 A _form_ provides instructions to an agent for performing an 264 operation on a Web resource. It consists of a _form context_, an 265 _operation type_, a _request method_, and a _submission target_. 266 Additionally, a form may be accompanied by a list of _form fields_. 268 A form can be viewed as an instruction of the form "To perform an 269 {operation type} operation on {form context}, make a {request method} 270 request to {submission target}" where the payload of the request may 271 be further described by form fields. 273 The operation type identifies the semantics of the operation. 274 Operation types are denoted like link relation types by an IRI. 276 The form context is the resource on which an operation is ultimately 277 performed. To perform the operation, an agent needs to construct a 278 request with the specified request method and submission target as 279 the request IRI. The submission target typically is the same 280 resource as the form context, but may be a different resource. 281 Constructing and sending the request is called _submitting the form_. 283 If a form is accompanied by a list of form fields, as described in 284 the following section, then the agent also needs to construct a 285 payload that matches the specifications of the form fields and 286 include that in the request. 288 A form can occur as a top-level element in a document or as a nested 289 element within a link. When a form occurs as a top-level element, 290 the form context implicitly is the document's retrieval context. 291 When a form occurs nested within a link, the form context is the link 292 target of the enclosing link. 294 3.5. Form Fields 296 Form fields provide further instructions to agents for constructing a 297 request payload. 299 A form field can directly identify one or more data items that need 300 to be included in the request payload or can reference another 301 resource (such as a schema) that describes the structure of the 302 payload. Form fields can also provide other kinds of information, 303 such as acceptable media types for the payload. 305 A form field is a pair of a _form field type_ and a _form field 306 value_. The form field type identifies the semantics of the form 307 field. Form field types are denoted like link relation types and 308 operation types by an IRI. The form field value can be either an 309 IRI, a Boolean value, an integer, a floating-point number, a date/ 310 time value, a byte string, or a text string. 312 3.6. 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 3.7. 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). In the case of a 383 form with one or more form fields, the agent also MUST include a 384 request payload that matches the specifications of the form 385 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 3.8. 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 if 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). 424 4. Binary Format 426 This section defines the encoding of documents in the CoRAL binary 427 format. 429 A document in the binary format is a data item in Concise Binary 430 Object Representation (CBOR) [RFC7049]. The structure of this data 431 item is presented in the Concise Data Definition Language (CDDL) 432 [I-D.ietf-cbor-cddl]. The media type is "application/coral+cbor". 434 4.1. Data Structure 436 The data structure of a document in the binary format is made up of 437 four kinds of elements: links, forms, embedded representations, and 438 (as an extension to the CoRAL data model) base directives. Base 439 directives provide a way to encode IRIs with a common base more 440 efficiently. 442 Elements are processed in the order they appear in the document. 443 Document processors need to maintain an _environment_ while iterating 444 an array of elements. The environment consists of two variables: the 445 _current context_ and the _current base_. Both the current context 446 and the current base are initially set to the document's retrieval 447 context. 449 4.1.1. Documents 451 The body of a document in the binary format is encoded as an array of 452 zero or more links, forms, embedded representations, and directives. 454 body = [*(link / form / representation / directive)] 456 4.1.2. Links 458 A link is encoded as an array that consists of the unsigned integer 459 2, followed by the link relation type and the link target, optionally 460 followed by a link body that contains nested elements. 462 link = [2, relation-type, link-target, ?body] 464 The link relation type is encoded as a text string that conforms to 465 the syntax of an IRI [RFC3987]. 467 relation-type = text 469 The link target is denoted by an IRI reference or represented by a 470 literal value. An IRI reference MUST be resolved against the current 471 base. The encoding of and resolution process for IRI references in 472 the binary format is described in RFC XXXX [I-D.hartke-t2trg-ciri]. 473 The link target may be null, which indicates that the link target is 474 an unidentified resource. 476 link-target = ciri / literal 478 ciri = 479 literal = bool / int / float / time / bytes / text / null 481 The array of elements in the link body, if any, MUST be processed in 482 a fresh environment. Both the current context and the current base 483 in the new environment are initially set to the link target of the 484 enclosing link. 486 4.1.3. Forms 488 A form is encoded as an array that consists of the unsigned integer 489 3, followed by the operation type, the request method, and the 490 submission target, optionally followed by a list of form fields. 492 form = [3, operation-type, method, submission-target, ?form- 493 fields] 495 The operation type is defined in the same way as a link relation type 496 (Section 4.1.2). 498 operation-type = text 500 The method MUST refer to one of the request methods defined by the 501 Web transfer protocol identified by the scheme of the submission 502 target. It is encoded either as a text string or an unsigned 503 integer. 505 method = text / uint 507 For HTTP [RFC7230], the method MUST be encoded as a text string in 508 the format defined in Section 4.1 of RFC 7231 [RFC7231]; the set of 509 possible values is maintained in the IANA HTTP Method Registry. For 510 CoAP [RFC7252], the method MUST be encoded as an unsigned integer 511 (e.g., the unsigned integer 2 for the POST method); the set of 512 possible values is maintained in the IANA CoAP Method Codes Registry. 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 4.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 4.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 4.1.3.2. Short Forms 544 [[NOTE TO READERS: This section used to describe special elements for 545 compressing certain forms that were assumed to occur frequently. The 546 topic of encoding frequently occurring elements more efficiently will 547 be revisited when more real-world examples are available.]] 549 4.1.4. Embedded Representations 551 An embedded representation is encoded as an array that consists of 552 the unsigned integer 0, followed by a byte string containing the 553 representation data, optionally followed by representation metadata. 555 representation = [0, bytes, ?representation-metadata] 557 Representation metadata is encoded as an array of zero or more name- 558 value pairs. 560 representation-metadata = [*(metadata-name, metadata-value)] 562 The metadata, if any, MUST be processed in a fresh environment. All 563 variables in the new environment are initially set to a copy of the 564 variables in the current environment. 566 The metadata name is defined in the same way as a link relation type 567 (Section 4.1.2). 569 metadata-name = text 571 A metadata value can be an IRI reference, a Boolean value, an 572 integer, a floating-point number, a date/time value, a byte string, a 573 text string, or null. An IRI reference MUST be resolved against the 574 current base. 576 metadata-value = ciri / literal 578 4.1.5. Directives 580 Directives provide the ability to manipulate the environment when 581 processing a list of elements. There is one type of directives 582 available: the Base directive. 584 directive = base-directive 586 4.1.5.1. Base Directives 588 A Base directive is encoded as an array that consists of the unsigned 589 integer 1, followed by a base. 591 base-directive = [1, base] 593 The base is denoted by an IRI reference. This IRI reference MUST be 594 resolved against the current context (not the current base). 596 base = ciri 598 The directive is processed by resolving the IRI reference against the 599 current context and assigning the result to the current base. 601 4.2. Dictionaries 603 The binary format can reference values from a dictionary to reduce 604 representation size and processing cost. Dictionary references can 605 be used in place of link relation types, link targets, operation 606 types, submission targets, form field types, form field values, 607 representation metadata names, and representation metadata values. 609 4.2.1. Dictionary References 611 A dictionary reference is encoded as an unsigned integer. Where a 612 dictionary reference cannot be expressed unambiguously, the unsigned 613 integer is tagged with CBOR tag TBD6. 615 relation-type /= uint 617 link-target /= #6.TBD6(uint) 619 operation-type /= uint 620 submission-target /= #6.TBD6(uint) 622 form-field-type /= uint 624 form-field-value /= #6.TBD6(uint) 626 metadata-name /= uint 628 metadata-value /= #6.TBD6(uint) 630 4.2.2. Media Type Parameter 632 The "application/coral+cbor" media type is defined to have a 633 "dictionary" parameter that specifies the dictionary in use. The 634 dictionary is identified by a URI [RFC3986]. For example, a CoRAL 635 document that uses the dictionary identified by the URI 636 can use the following content type: 638 application/coral+cbor; dictionary="http://example.com/dictionary" 640 The URI serves only as an identifier; it does not necessarily have to 641 be dereferencable (or even use a dereferencable URI scheme). It is 642 permissible, though, to use a dereferencable URI and to serve a 643 representation that provides information about the dictionary in a 644 human- or machine-readable way. (The format of such a representation 645 is outside the scope of this document.) 647 For simplicity, a CoRAL document can reference values only from one 648 dictionary; the value of the "dictionary" parameter MUST be a single 649 URI. If the "dictionary" parameter is absent, the default dictionary 650 specified in Appendix B of this document is assumed. 652 Once a dictionary has made an assignment, the assignment MUST NOT be 653 changed or removed. A dictionary, however, may contain additional 654 information about an assignment, which may change over time. 656 In CoAP [RFC7252], media types (including specific values for media 657 type parameters) are encoded as an unsigned integer called "content 658 format". For use with CoAP, each new CoRAL dictionary MUST register 659 a new content format in the IANA CoAP Content-Formats Registry. 661 5. Textual Format 663 This section defines the syntax of documents in the CoRAL textual 664 format using two grammars: The lexical grammar defines how Unicode 665 characters are combined to form line terminators, white space, 666 comments, and tokens. The syntactic grammar defines how tokens are 667 combined to form documents. Both grammars are presented in Augmented 668 Backus-Naur Form (ABNF) [RFC5234]. 670 A document in the textual format is a Unicode string in a Unicode 671 encoding form [UNICODE]. The media type for such documents is "text/ 672 coral". The "charset" parameter is not used; charset information is 673 transported inside the document in the form of an OPTIONAL Byte Order 674 Mark (BOM). The use of the UTF-8 encoding scheme [RFC3629], without 675 a BOM, is RECOMMENDED. 677 5.1. Lexical Structure 679 The lexical structure of a document in the textual format is made up 680 of four basic elements: line terminators, white space, comments, and 681 tokens. Of these, only tokens are significant in the syntactic 682 grammar. There are five kinds of tokens: identifiers, IRIs, IRI 683 references, literals, and punctuators. 685 token = identifier / iri / iriref / literal / punctuator 687 When several lexical grammar rules match a sequence of characters in 688 a document, the longest match takes priority. 690 5.1.1. Line Terminators 692 Line terminators divide text into lines. A line terminator is any 693 Unicode character with Line_Break class BK, CR, LF, or NL. However, 694 any CR character that immediately precedes a LF character is ignored. 695 (This affects only the numbering of lines in error messages.) 697 5.1.2. White Space 699 White space is a sequence of one or more white space characters. A 700 white space character is any Unicode character with the White_Space 701 property. 703 5.1.3. Comments 705 Comments are sequences of characters that are ignored when parsing 706 text into tokens. Single-line comments begin with the characters 707 "//" and extend to the end of the line. Delimited comments begin 708 with the characters "/*" and end with the characters "*/". Delimited 709 comments can occupy a portion of a line, a single line, or multiple 710 lines. 712 Comments do not nest. The character sequences "/*" and "*/" have no 713 special meaning within a single-line comment; the character sequences 714 "//" and "/*" have no special meaning within a delimited comment. 716 5.1.4. Identifiers 718 An identifier token is a user-defined symbolic name. The rules for 719 identifiers correspond to those recommended by the Unicode Standard 720 Annex #31 [UNICODE-UAX31] using the following profile: 722 identifier = START *CONTINUE *(MEDIAL 1*CONTINUE) 724 START = 726 CONTINUE = 728 MEDIAL = "-" / "." / "~" / %x58A / %xF0B 730 MEDIAL =/ %x2010 / %x2027 / %x30A0 / %x30FB 732 All identifiers MUST be converted into Unicode Normalization Form C 733 (NFC), as defined by the Unicode Standard Annex #15 [UNICODE-UAX15]. 734 Comparison of identifiers is based on NFC and is case-sensitive 735 (unless otherwise noted). 737 5.1.5. IRIs and IRI References 739 IRIs and IRI references are Unicode strings that conform to the 740 syntax defined in RFC 3987 [RFC3987]. An IRI reference can be either 741 an IRI or a relative reference. Both IRIs and IRI references are 742 enclosed in angle brackets ("<" and ">"). 744 iri = "<" IRI ">" 746 iriref = "<" IRI-reference ">" 748 IRI = 750 IRI-reference = 752 5.1.6. Literals 754 A literal is a textual representation of a value. There are seven 755 types of literals: Boolean, integer, floating-point, date/time, byte 756 string, text string, and null. 758 literal = boolean / integer / float / datetime / bytes / text 760 literal =/ null 762 5.1.6.1. Boolean Literals 764 The case-insensitive tokens "true" and "false" denote the Boolean 765 values true and false, respectively. 767 boolean = "true" / "false" 769 5.1.6.2. Integer Literals 771 Integer literals denote an integer value of unspecified precision. 772 By default, integer literals are expressed in decimal, but they can 773 also be specified in an alternate base using a prefix: Binary 774 literals begin with "0b", octal literals begin with "0o", and 775 hexadecimal literals begin with "0x". 777 Decimal literals contain the digits "0" through "9". Binary literals 778 contain "0" and "1", octal literals contain "0" through "7", and 779 hexadecimal literals contain "0" through "9" as well as "A" through 780 "F" in upper- or lowercase. 782 Negative integers are expressed by prepending a minus sign ("-"). 784 integer = ["+" / "-"] (decimal / binary / octal / hexadecimal) 786 decimal = 1*DIGIT 788 binary = %x30 (%x42 / %x62) 1*BINDIG 790 octal = %x30 (%x4F / %x6F) 1*OCTDIG 792 hexadecimal = %x30 (%x58 / %x78) 1*HEXDIG 794 DIGIT = %x30-39 796 BINDIG = %x30-31 798 OCTDIG = %x30-37 800 HEXDIG = %x30-39 / %x41-46 / %x61-66 802 5.1.6.3. Floating-point Literals 804 Floating-point literals denote a floating-point number of unspecified 805 precision. 807 Floating-point literals consist of a sequence of decimal digits 808 followed by a fraction, an exponent, or both. The fraction consists 809 of a decimal point (".") followed by a sequence of decimal digits. 811 The exponent consists of the letter "e" in upper- or lowercase, 812 followed by an optional sign and a sequence of decimal digits that 813 indicate a power of 10 by which the value preceding the "e" is 814 multiplied. 816 Negative floating-point values are expressed by prepending a minus 817 sign ("-"). 819 float = ["+" / "-"] 1*DIGIT [fraction] [exponent] 821 fraction = "." 1*DIGIT 823 exponent = (%x45 / %x65) ["+" / "-"] 1*DIGIT 825 A floating-point literal can additionally denote either the special 826 "Not-a-Number" (NaN) value, positive infinity, or negative infinity. 827 The NaN value is produced by the case-insensitive token "NaN". The 828 two infinite values are produced by the case-insensitive tokens 829 "+Infinity" (or simply "Infinity") and "-Infinity". 831 float =/ "NaN" 833 float =/ ["+" / "-"] "Infinity" 835 5.1.6.4. Date/Time Literals 837 Date/time literals denote an instant in time. 839 A date/time literal consists of a sequence of characters in Internet 840 date/time format [RFC3339], enclosed in dollar signs. 842 datetime = DOLLAR date-time DOLLAR 844 date-time = 846 DOLLAR = %x24 848 5.1.6.5. Byte String Literals 850 Byte string literals denote an ordered sequence of bytes. 852 A byte string literal consists of a prefix and zero or more bytes 853 encoded in Base16, Base32, or Base64 [RFC4648] and enclosed in single 854 quotes. Byte string literals encoded in Base16 begin with "h" or 855 "b16", byte string literals encoded in Base32 begin with "b32", and 856 byte string literals encoded in Base64 begin with "b64". 858 bytes = base16 / base32 / base64 859 base16 = (%x68 / %x62.31.36) SQUOTE SQUOTE 861 base32 = %x62.33.32 SQUOTE SQUOTE 863 base64 = %x62.36.34 SQUOTE SQUOTE 865 SQUOTE = %x27 867 5.1.6.6. Text String Literals 869 Text string literals denote a Unicode string. 871 A text string literal consists of zero or more Unicode characters 872 enclosed in double quotes. It can include simple escape sequences 873 (such as \t for the tab character) as well as hexadecimal and Unicode 874 escape sequences. 876 text = DQUOTE *(char / %x5C escape) DQUOTE 878 char = 880 escape = simple-escape / hexadecimal-escape / unicode-escape 882 simple-escape = %x30 / %x62 / %x74 / %x6E / %x76 884 simple-escape =/ %x66 / %x72 / %x22 / %x27 / %x5C 886 hexadecimal-escape = (%x78 / %x58) 2HEXDIG 888 unicode-escape = %x75 4HEXDIG / %x55 8HEXDIG 890 DQUOTE = %x22 892 An escape sequence denotes a single Unicode code point. For 893 hexadecimal and Unicode escape sequences, the code point is expressed 894 by the hexadecimal number following the "\x", "\X", "\u", or "\U" 895 prefix. Simple escape sequences indicate the code points listed in 896 Table 1. 898 +-----------------+------------+----------------------+ 899 | Escape Sequence | Code Point | Character Name | 900 +-----------------+------------+----------------------+ 901 | \0 | U+0000 | Null | 902 | \b | U+0008 | Backspace | 903 | \t | U+0009 | Character Tabulation | 904 | \n | U+000A | Line Feed | 905 | \v | U+000B | Line Tabulation | 906 | \f | U+000C | Form Feed | 907 | \r | U+000D | Carriage Return | 908 | \" | U+0022 | Quotation Mark | 909 | \' | U+0027 | Apostrophe | 910 | \\ | U+005C | Reverse Solidus | 911 +-----------------+------------+----------------------+ 913 Table 1: Simple Escape Sequences 915 5.1.6.7. Null Literal 917 The case-insensitive tokens "null" and "_" denote the intentional 918 absence of any value. 920 null = "null" / "_" 922 5.1.7. Punctuators 924 Punctuator tokens are used for grouping and separating. 926 punctuator = "#" / ":" / "*" / "[" / "]" / "{" / "}" / "=" / "->" 928 5.2. Syntactic Structure 930 The syntactic structure of a document in the textual format is made 931 up of four kinds of elements: links, forms, embedded representations, 932 and (as an extension to the CoRAL data model) directives. Directives 933 provide a way to make documents easier to read and write by setting a 934 base for relative IRI references and introducing shorthands for IRIs. 936 Elements are processed in the order they appear in the document. 937 Document processors need to maintain an _environment_ while iterating 938 a list of elements. The environment consists of three variables: the 939 _current context_, the _current base_, and the _current mapping from 940 identifiers to IRIs_. Both the current context and the current base 941 are initially set to the document's retrieval context. The current 942 mapping from identifiers to IRIs is initially empty. 944 5.2.1. Documents 946 The body of a document in the textual format consists of zero or more 947 links, forms, embedded representations, and directives. 949 body = *(link / form / representation / directive) 951 5.2.2. Links 953 A link consists of the link relation type, followed by the link 954 target, optionally followed by a link body enclosed in curly brackets 955 ("{" and "}"). 957 link = relation-type link-target ["{" body "}"] 959 The link relation type is denoted by either an IRI, a simple name, or 960 a qualified name. 962 relation-type = iri / simple-name / qualified-name 964 A simple name consists of an identifier. It is resolved to an IRI by 965 looking up the empty string in the current mapping from identifiers 966 to IRIs and appending the specified identifier to the result. It is 967 an error if the empty string is not present in the current mapping. 969 simple-name = identifier 971 A qualified name consists of two identifiers separated by a colon 972 (":"). It is resolved to an IRI by looking up the identifier on the 973 left hand side in the current mapping from identifiers to IRIs and 974 appending the identifier on the right hand side to the result. It is 975 an error if the identifier on the left hand side is not present in 976 the current mapping. 978 qualified-name = identifier ":" identifier 980 The link target is denoted by an IRI reference or represented by a 981 value literal. An IRI reference MUST be resolved against the current 982 base. If the link target is null, the link target is an unidentified 983 resource. 985 link-target = iriref / literal 987 The list of elements in the link body, if any, MUST be processed in a 988 fresh environment. Both the current context and current base in this 989 environment are initially set to the link target of the enclosing 990 link. The mapping from identifiers to IRIs is initially set to a 991 copy of the mapping from identifiers to IRIs in the current 992 environment. 994 5.2.3. Forms 996 A form consists of the operation type, followed by a "->" token, the 997 request method, and the submission target, optionally followed by a 998 list of form fields enclosed in square brackets ("[" and "]"). 1000 form = operation-type "->" method submission-target ["[" form- 1001 fields "]"] 1003 The operation type is defined in the same way as a link relation type 1004 (Section 5.2.2). 1006 operation-type = iri / simple-name / qualified-name 1008 The method identifier MUST refer to one of the request methods 1009 defined by the Web transfer protocol identified by the scheme of the 1010 submission target. Method identifiers are case-insensitive and 1011 constrained to Unicode characters in the Basic Latin block. 1013 method = identifier 1015 For HTTP [RFC7230], the set of possible method identifiers is 1016 maintained in the IANA HTTP Method Registry. For CoAP [RFC7252], the 1017 set of possible method identifiers is maintained in the IANA CoAP 1018 Method Codes Registry. 1020 The submission target is denoted by an IRI reference. This IRI 1021 reference MUST be resolved against the current base. 1023 submission-target = iriref 1025 5.2.3.1. Form Fields 1027 A list of form fields consists of zero or more type-value pairs. 1029 form-fields = *(form-field-type form-field-value) 1031 The list, if any, MUST be processed in a fresh environment. Both the 1032 current context and the current base in this environment are 1033 initially set to the submission target of the enclosing form. The 1034 mapping from identifiers to IRIs is initially set to a copy of the 1035 mapping from identifiers to IRIs in the current environment. 1037 The form field type is defined in the same way as a link relation 1038 type (Section 5.2.2). 1040 form-field-type = iri / simple-name / qualified-name 1042 The form field value can be an IRI reference, Boolean literal, 1043 integer literal, floating-point literal, byte string literal, text 1044 string literal, or null. An IRI reference MUST be resolved against 1045 the current base. 1047 form-field-value = iriref / literal 1049 5.2.4. Embedded Representations 1051 An embedded representation consists of a "*" token, followed by the 1052 representation data, optionally followed by representation metadata 1053 enclosed in square brackets ("[" and "]"). 1055 representation = "*" bytes ["[" representation-metadata "]"] 1057 Representation metadata consists of zero or more name-value pairs. 1059 representation-metadata = *(metadata-name metadata-value) 1061 The metadata, if any, MUST be processed in a fresh environment. All 1062 variables in the new environment are initially set to a copy of the 1063 variables in the current environment. 1065 The metadata name is defined in the same way as a link relation type 1066 (Section 5.2.2). 1068 metadata-name = iri / simple-name / qualified-name 1070 The metadata value can be an IRI reference, Boolean literal, integer 1071 literal, floating-point literal, byte string literal, text string 1072 literal, or null. An IRI reference MUST be resolved against the 1073 current base. 1075 metadata-value = iriref / literal 1077 5.2.5. Directives 1079 Directives provide the ability to manipulate the environment when 1080 processing a list of elements. All directives start with a number 1081 sign ("#") followed by a directive identifier. Directive identifiers 1082 are case-insensitive and constrained to Unicode characters in the 1083 Basic Latin block. 1085 The following two types of directives are available: the Base 1086 directive and the Using directive. 1088 directive = base-directive / using-directive 1090 5.2.5.1. Base Directives 1092 A Base directive consists of a number sign ("#"), followed by the 1093 case-insensitive identifier "base", followed by a base. 1095 base-directive = "#" "base" base 1097 The base is denoted by an IRI reference. The IRI reference MUST be 1098 resolved against the current context (not the current base). 1100 base = iriref 1102 The directive is processed by resolving the IRI reference against the 1103 current context and assigning the result to the current base. 1105 5.2.5.2. Using Directives 1107 A Using directive consists of a number sign ("#"), followed by the 1108 case-insensitive identifier "using", optionally followed by an 1109 identifier and an equals sign ("="), finally followed by an IRI. If 1110 the identifier is not specified, it is assumed to be the empty 1111 string. 1113 using-directive = "#" "using" [identifier "="] iri 1115 The directive is processed by adding the specified identifier and IRI 1116 to the current mapping from identifiers to IRIs. It is an error if 1117 the identifier is already present in the mapping. 1119 6. Usage Considerations 1121 This section discusses some considerations in creating CoRAL-based 1122 applications and vocabularies. 1124 6.1. Specifying CoRAL-based Applications 1126 CoRAL-based applications naturally implement the Web architecture 1127 [W3C.REC-webarch-20041215] and thus are centered around orthogonal 1128 specifications for identification, interaction, and representation: 1130 o Resources are identified by IRIs or represented by value literals. 1132 o Interactions are based on the hypermedia interaction model of the 1133 Web and the methods provided by the Web transfer protocol. The 1134 semantics of possible interactions are identified by link relation 1135 types and operation types. 1137 o Representations are CoRAL documents encoded in the binary format 1138 defined in Section 4 or the textual format defined in Section 5. 1139 Depending on the application, additional representation formats 1140 may be used. 1142 6.1.1. Application Interfaces 1144 Specifications for CoRAL-based applications need to list the specific 1145 components used in the application interface and their identifiers. 1146 This should include the following items: 1148 o IRI schemes that identify the Web transfer protocol(s) used in the 1149 application. 1151 o Internet media types that identify the representation format(s) 1152 used in the application, including the media type(s) of the CoRAL 1153 serialization format(s). 1155 o Link relation types that identify the semantics of links. 1157 o Operation types that identify the semantics of forms. 1158 Additionally, for each operation type, the permissible request 1159 method(s). 1161 o Form field types that identify the semantics of form fields. 1162 Additionally, for each form field type, the permissible form field 1163 values. 1165 o Metadata names that identify the semantics of representation 1166 metadata. Additionally, for each metadata name, the permissible 1167 metadata values. 1169 6.1.2. Resource Names 1171 Resource names -- i.e., URIs [RFC3986] and IRIs [RFC3987] -- are a 1172 cornerstone of Web-based applications. They enable the uniform 1173 identification of resources and are used every time a client 1174 interacts with a server or a resource representation needs to refer 1175 to another resource. 1177 URIs and IRIs often include structured application data in the path 1178 and query components, such as paths in a filesystem or keys in a 1179 database. It is a common practice in many HTTP-based application 1180 programming interfaces (APIs) to make this part of the application 1181 specification, i.e., to prescribe fixed URI templates that are hard- 1182 coded in implementations. There are a number of problems with this 1183 practice [RFC7320], though. 1185 In CoRAL-based applications, resource names are therefore not part of 1186 the application specification -- they are an implementation detail. 1187 The specification of a CoRAL-based application MUST NOT mandate any 1188 particular form of resource name structure. BCP 190 [RFC7320] 1189 describes the problematic practice of fixed URI structures in more 1190 detail and provides some acceptable alternatives. 1192 6.1.3. Implementation Limits 1194 This document places no restrictions on the number of elements in a 1195 CoRAL document or the depth of nested elements. Applications using 1196 CoRAL (in particular those running in constrained environments) may 1197 wish to limit these numbers and specify implementation limits that an 1198 application implementation must at least support to be interoperable. 1200 Applications may also mandate the following and other restrictions: 1202 o use of only either the binary format or the text format; 1204 o use of only either HTTP or CoAP as supported Web transfer 1205 protocol; 1207 o use of only dictionary references in the binary format for certain 1208 vocabulary; 1210 o use of only either content type strings or content format IDs; 1212 o use of IRI references only up to a specific string length; 1214 o use of CBOR in a canonical format (see Section 3.9 of RFC 7049). 1216 6.2. Minting Vocabulary 1218 New link relation types, operation types, form field types, and 1219 metadata names can be minted by defining an IRI [RFC3987] that 1220 uniquely identifies the item. Although the IRI can point to a 1221 resource that contains a definition of the semantics, clients SHOULD 1222 NOT automatically access that resource to avoid overburdening its 1223 server. The IRI SHOULD be under the control of the person or party 1224 defining it, or be delegated to them. 1226 To avoid interoperability problems, it is RECOMMENDED that only IRIs 1227 are minted that are normalized according to Section 5.3 of RFC 3987. 1228 Non-normalized forms that are best avoided include: 1230 o Uppercase characters in scheme names and domain names 1231 o Percent-encoding of characters where it is not required by the IRI 1232 syntax 1234 o Explicitly stated HTTP default port (e.g., 1235 is preferable over ) 1237 o Completely empty path in HTTP IRIs (e.g., is 1238 preferable over ) 1240 o Dot segments ("/./" or "/../") in the path component of an IRI 1242 o Lowercase hexadecimal letters within percent-encoding triplets 1243 (e.g., "%3F" is preferable over "%3f") 1245 o Punycode-encoding of Internationalized Domain Names in IRIs 1247 o IRIs that are not in Unicode Normalization Form C [UNICODE-UAX15] 1249 IRIs that identify vocabulary do not need to be registered. The 1250 inclusion of domain names in IRIs allows for the decentralized 1251 creation of new IRIs without the risk of collisions. However, IRIs 1252 can be relatively verbose and impose a high overhead on a 1253 representation. This can be a problem in constrained environments 1254 [RFC7228]. Therefore, CoRAL alternatively allows the use of unsigned 1255 integers to reference CBOR data items from a dictionary, as specified 1256 in Section 4.2. These impose a much smaller overhead but instead 1257 need to be assigned by an authority to avoid collisions. 1259 6.3. Expressing Registered Link Relation Types 1261 Link relation types registered in the IANA Link Relations Registry, 1262 such as "collection" [RFC6573] or "icon" [W3C.REC-html52-20171214], 1263 can be used in CoRAL by appending the registered name to the IRI 1264 : 1266 #using iana = 1268 iana:collection 1269 iana:icon 1271 Note that registered link relation types are required to be 1272 lowercased as per Section 3.3 of RFC 8288 [RFC8288]. 1274 (The convention of appending the link relation type to the prefix 1275 "http://www.iana.org/assignments/relation/" to form an IRI is adopted 1276 from Atom [RFC4287]. See also Appendix A.2 of RFC 8288 [RFC8288].) 1278 6.4. Expressing Link Target Attributes 1280 [[NOTE TO READERS: This section describes a mechanism to convert any 1281 link target attributes to CoRAL in a way that allows a conversion 1282 back without loss of information (round-trip conversion). It is 1283 likely that this will be replaced by a specific set of unique link 1284 relation types that match the known RFC 6690 attributes semantically 1285 but do not round-trip in the presence of unknown attributes.]] 1287 Link target attributes defined for use with CoRE Link Format 1288 [RFC6690] (such as "hreflang", "media", "title", "title*", "type", 1289 "ct", "rt", "if", "sz", and "obs") can be expressed in CoRAL by 1290 nesting links under the respective link. The link relation type of 1291 each such nested link is the lowercased attribute name appended to 1292 the IRI . 1294 If the expressed link target attribute has a value, the target of the 1295 nested link MUST be a text string; otherwise, the target MUST be the 1296 Boolean value "true". 1298 #using iana = 1299 #using attr = 1301 iana:item { 1302 attr:type "application/json-patch+json" 1303 attr:ct "51" 1304 attr:sz "247" 1305 attr:obs true 1306 } 1308 <=> 1310 ; rel=item; type="application/json-patch+json"; 1311 ct=51; sz=247; obs 1313 Language information in attributes as per RFC 8187 [RFC8187], such as 1314 in "title*" attributes, is expressed by nesting an additional link of 1315 type under the link representing the 1316 attribute. The target of the nested link MUST be a text string 1317 containing a language tag [RFC5646]. The attribute name is expressed 1318 without the "*" character. 1320 #using iana = 1321 #using attr = 1323 iana:terms-of-service { 1324 attr:title "Nutzungsbedingungen" { attr:hreflang "de" } 1325 attr:title "Terms of use" { attr:hreflang "en" } 1326 } 1328 <=> 1330 ; rel=terms-of-service; 1331 title*=UTF-8'de'Nutzungsbedingungen; 1332 title*=UTF-8'en'Terms%20of%20use 1334 Link target attributes that actually do not describe the link target 1335 but the link itself (such as "rel", "anchor", and "rev") are excluded 1336 from this provision and MUST NOT occur in a CoRAL document. 1338 6.5. Expressing Simple RDF Statements 1340 An RDF statement [W3C.REC-rdf11-concepts-20140225] says that some 1341 relationship, indicated by a predicate, holds between two resources. 1342 RDF predicates can therefore be good source for vocabulary to provide 1343 resource metadata. For example, a CoRAL document could use the FOAF 1344 vocabulary [FOAF] to describe the person or software that made it: 1346 #using rdf = 1347 #using foaf = 1349 foaf:maker null { 1350 rdf:type 1351 foaf:familyName "Hartke" 1352 foaf:givenName "Klaus" 1353 foaf:mbox 1354 } 1356 6.6. Embedding CoRAL in CBOR Structures 1358 Data items in the CoRAL binary format (Section 4) may be embedded in 1359 other CBOR [RFC7049] data structures. Specifications using CDDL 1360 [I-D.ietf-cbor-cddl] SHOULD reference the following CDDL definitions 1361 for this purpose: 1363 CoRAL-Document = body 1365 CoRAL-Link = link 1367 CoRAL-Form = form 1369 For each embedded document, link, and form, the retrieval context, 1370 link context, and form context needs to be specified, respectively. 1372 6.7. Submitting CoRAL Documents 1374 By default, a CoRAL document is a representation that captures the 1375 current state of a resource. The meaning of a CoRAL document changes 1376 when it is submitted in a request. Depending on the request method, 1377 the CoRAL document can capture the intended state of a resource or be 1378 subject to application-specific processing. 1380 6.7.1. PUT Requests 1382 A PUT request with a CoRAL document enclosed in the request payload 1383 requests that the state of the target resource be created or replaced 1384 with the state described by the CoRAL document. A successful PUT of 1385 a CoRAL document generally means that a subsequent GET on that same 1386 target resource would result in an equivalent document being sent in 1387 a success response. 1389 An origin server SHOULD verify that a submitted CoRAL document is 1390 consistent with any constraints the server has for the target 1391 resource. When a document is inconsistent with the target resource, 1392 the origin server SHOULD either make it consistent (e.g., by removing 1393 inconsistent elements) or respond with an appropriate error message 1394 containing sufficient information to explain why the document is 1395 unsuitable. 1397 The retrieval context of a CoRAL document in a PUT is the request IRI 1398 of the request. 1400 6.7.2. POST Requests 1402 A POST request with a CoRAL document enclosed in the request payload 1403 requests that the target resource process the CoRAL document 1404 according to the resource's own specific semantics. 1406 The retrieval context of a CoRAL document in a POST is the request 1407 IRI of the request. 1409 7. Security Considerations 1411 Parsers of CoRAL documents must operate on input that is assumed to 1412 be untrusted. This means that parsers MUST fail gracefully in the 1413 face of malicious inputs. Additionally, parsers MUST be prepared to 1414 deal with resource exhaustion (e.g., resulting from the allocation of 1415 big data items) or exhaustion of the call stack (stack overflow). 1417 See Section 8 of RFC 7049 [RFC7049] for security considerations 1418 relating to CBOR. 1420 Implementers of the CoRAL textual format need to consider the 1421 security aspects of handling Unicode input. See the Unicode Standard 1422 Annex #36 [UNICODE-UAX36] for security considerations relating to 1423 visual spoofing and misuse of character encodings. See Section 10 of 1424 RFC 3629 [RFC3629] for security considerations relating to UTF-8. 1426 CoRAL makes extensive use of IRIs and URIs. See Section 8 of RFC 1427 3987 [RFC3987] for security considerations relating to IRIs. See 1428 Section 7 of RFC 3986 [RFC3986] for security considerations relating 1429 to URIs. 1431 The security of applications using CoRAL can depend on the proper 1432 preparation and comparison of internationalized strings. For 1433 example, such strings can be used to make authentication and 1434 authorization decisions, and the security of an application could be 1435 compromised if an entity providing a given string is connected to the 1436 wrong account or online resource based on different interpretations 1437 of the string. See RFC 6943 [RFC6943] for security considerations 1438 relating to identifiers in IRIs and other places. 1440 CoRAL is intended to be used in conjunction with a Web transfer 1441 protocol like HTTP or CoAP. See Section 9 of RFC 7230 [RFC7230], 1442 Section 9 of RFC 7231 [RFC7231], etc., for security considerations 1443 relating to HTTP. See Section 11 of RFC 7252 [RFC7252] for security 1444 considerations relating to CoAP. 1446 CoRAL does not define any specific mechanisms for protecting the 1447 confidentiality and integrity of CoRAL documents. It relies on 1448 application layer or transport layer mechanisms for this, such as 1449 Transport Layer Security (TLS) [RFC8446]. 1451 CoRAL documents and the structure of a web of resources revealed from 1452 automatically following links can disclose personal information and 1453 other sensitive information. Implementations need to prevent the 1454 unintentional disclosure of such information. See Section of 9 of 1455 RFC 7231 [RFC7231] for additional considerations. 1457 Applications using CoRAL ought to consider the attack vectors opened 1458 by automatically following, trusting, or otherwise using links and 1459 forms in CoRAL documents. Notably, a server that is authoritative 1460 for the CoRAL representation of a resource may not necessarily be 1461 authoritative for nested elements in the document. See Section 5 of 1462 RFC 8288 [RFC8288] for related considerations. 1464 Unless an application mitigates this risk by specifying more specific 1465 rules, any link or form in a document where the link or form context 1466 and the document's retrieval context don't share the same Web origin 1467 [RFC6454] MUST be discarded ("same-origin policy"). 1469 8. IANA Considerations 1471 8.1. Media Type "application/coral+cbor" 1473 This document registers the media type "application/coral+cbor" 1474 according to the procedures of BCP 13 [RFC6838]. 1476 Type name: 1477 application 1479 Subtype name: 1480 coral+cbor 1482 Required parameters: 1483 N/A 1485 Optional parameters: 1486 dictionary - See Section 4.2 of [I-D.hartke-t2trg-coral]. 1488 Encoding considerations: 1489 binary - See Section 4 of [I-D.hartke-t2trg-coral]. 1491 Security considerations: 1492 See Section 7 of [I-D.hartke-t2trg-coral]. 1494 Interoperability considerations: 1495 N/A 1497 Published specification: 1498 [I-D.hartke-t2trg-coral] 1500 Applications that use this media type: 1501 See Section 1 of [I-D.hartke-t2trg-coral]. 1503 Fragment identifier considerations: 1504 As specified for "application/cbor". 1506 Additional information: 1507 Deprecated alias names for this type: N/A 1508 Magic number(s): N/A 1509 File extension(s): .coral.cbor 1510 Macintosh file type code(s): N/A 1512 Person & email address to contact for further information: 1513 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1515 Intended usage: 1516 COMMON 1518 Restrictions on usage: 1519 N/A 1521 Author: 1522 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1524 Change controller: 1525 IESG 1527 Provisional registration? 1528 No 1530 8.2. Media Type "text/coral" 1532 This document registers the media type "text/coral" according to the 1533 procedures of BCP 13 [RFC6838] and guidelines in RFC 6657 [RFC6657]. 1535 Type name: 1536 text 1538 Subtype name: 1539 coral 1541 Required parameters: 1542 N/A 1544 Optional parameters: 1545 N/A 1547 Encoding considerations: 1548 binary - See Section 5 of [I-D.hartke-t2trg-coral]. 1550 Security considerations: 1551 See Section 7 of [I-D.hartke-t2trg-coral]. 1553 Interoperability considerations: 1554 N/A 1556 Published specification: 1557 [I-D.hartke-t2trg-coral] 1559 Applications that use this media type: 1561 See Section 1 of [I-D.hartke-t2trg-coral]. 1563 Fragment identifier considerations: 1564 N/A 1566 Additional information: 1567 Deprecated alias names for this type: N/A 1568 Magic number(s): N/A 1569 File extension(s): .coral 1570 Macintosh file type code(s): N/A 1572 Person & email address to contact for further information: 1573 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1575 Intended usage: 1576 COMMON 1578 Restrictions on usage: 1579 N/A 1581 Author: 1582 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1584 Change controller: 1585 IESG 1587 Provisional registration? 1588 No 1590 8.3. CoAP Content Formats 1592 This document registers CoAP content formats for the content types 1593 "application/coral+cbor" and "text/coral" according to the procedures 1594 of RFC 7252 [RFC7252]. 1596 o Content Type: application/coral+cbor 1597 Content Coding: identity 1598 ID: TBD3 1599 Reference: [I-D.hartke-t2trg-coral] 1601 o Content Type: text/coral 1602 Content Coding: identity 1603 ID: TBD4 1604 Reference: [I-D.hartke-t2trg-coral] 1606 [[NOTE TO RFC EDITOR: Please replace all occurrences of "TBD3" and 1607 "TBD4" in this document with the code points assigned by IANA.]] 1609 [[NOTE TO IMPLEMENTERS: Experimental implementations can use content 1610 format ID 65087 for "application/coral+cbor" and content format ID 1611 65343 for "text/coral" until IANA has assigned code points.]] 1613 8.4. CBOR Tag 1615 This document registers a CBOR tag for dictionary references 1616 according to the procedures of RFC 7049 [RFC7049]. 1618 o Tag: TBD6 1619 Data Item: unsigned integer 1620 Semantics: Dictionary reference 1621 Reference: [I-D.hartke-t2trg-coral] 1623 [[NOTE TO RFC EDITOR: Please replace all occurrences of "TBD6" in 1624 this document with the code point assigned by IANA.]] 1626 9. References 1628 9.1. Normative References 1630 [I-D.hartke-t2trg-ciri] 1631 Hartke, K., "Constrained Internationalized Resource 1632 Identifiers", draft-hartke-t2trg-ciri-02 (work in 1633 progress), March 2019. 1635 [I-D.ietf-cbor-cddl] 1636 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1637 definition language (CDDL): a notational convention to 1638 express CBOR and JSON data structures", draft-ietf-cbor- 1639 cddl-07 (work in progress), February 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 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1673 DOI 10.17487/RFC6454, December 2011, 1674 . 1676 [RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding 1677 "charset" Parameter Handling in Textual Media Types", 1678 RFC 6657, DOI 10.17487/RFC6657, July 2012, 1679 . 1681 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1682 Specifications and Registration Procedures", BCP 13, 1683 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1684 . 1686 [RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for 1687 Security Purposes", RFC 6943, DOI 10.17487/RFC6943, May 1688 2013, . 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 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1699 DOI 10.17487/RFC8288, October 2017, 1700 . 1702 [UNICODE] The Unicode Consortium, "The Unicode Standard", 1703 . 1705 Note that this reference is to the latest version of 1706 Unicode, rather than to a specific release. It is not 1707 expected that future changes in the Unicode specification 1708 will have any impact on this document. 1710 [UNICODE-UAX15] 1711 The Unicode Consortium, "Unicode Standard Annex #15: 1712 Unicode Normalization Forms", 1713 . 1715 [UNICODE-UAX31] 1716 The Unicode Consortium, "Unicode Standard Annex #31: 1717 Unicode Identifier and Pattern Syntax", 1718 . 1720 [UNICODE-UAX36] 1721 The Unicode Consortium, "Unicode Standard Annex #36: 1722 Unicode Security Considerations", 1723 . 1725 9.2. Informative References 1727 [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification 1728 0.99", January 2014, 1729 . 1731 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1732 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 1733 December 2005, . 1735 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1736 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1737 September 2009, . 1739 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1740 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1741 . 1743 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 1744 RFC 6573, DOI 10.17487/RFC6573, April 2012, 1745 . 1747 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1748 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1749 . 1751 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1752 Constrained-Node Networks", RFC 7228, 1753 DOI 10.17487/RFC7228, May 2014, 1754 . 1756 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1757 Protocol (HTTP/1.1): Message Syntax and Routing", 1758 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1759 . 1761 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1762 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1763 DOI 10.17487/RFC7231, June 2014, 1764 . 1766 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1767 Application Protocol (CoAP)", RFC 7252, 1768 DOI 10.17487/RFC7252, June 2014, 1769 . 1771 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 1772 RFC 7320, DOI 10.17487/RFC7320, July 2014, 1773 . 1775 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1776 FETCH Methods for the Constrained Application Protocol 1777 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1778 . 1780 [RFC8187] Reschke, J., "Indicating Character Encoding and Language 1781 for HTTP Header Field Parameters", RFC 8187, 1782 DOI 10.17487/RFC8187, September 2017, 1783 . 1785 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1786 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1787 . 1789 [W3C.REC-html52-20171214] 1790 Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and 1791 S. Moon, "HTML 5.2", World Wide Web Consortium 1792 Recommendation REC-html52-20171214, December 2017, 1793 . 1795 [W3C.REC-rdf-schema-20140225] 1796 Brickley, D. and R. Guha, "RDF Schema 1.1", World Wide Web 1797 Consortium Recommendation REC-rdf-schema-20140225, 1798 February 2014, 1799 . 1801 [W3C.REC-rdf11-concepts-20140225] 1802 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 1803 Concepts and Abstract Syntax", World Wide Web Consortium 1804 Recommendation REC-rdf11-concepts-20140225, February 2014, 1805 . 1807 [W3C.REC-turtle-20140225] 1808 Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", 1809 World Wide Web Consortium Recommendation REC-turtle- 1810 20140225, February 2014, 1811 . 1813 [W3C.REC-webarch-20041215] 1814 Jacobs, I. and N. Walsh, "Architecture of the World Wide 1815 Web, Volume One", World Wide Web Consortium 1816 Recommendation REC-webarch-20041215, December 2004, 1817 . 1819 Appendix A. Core Vocabulary 1821 This section defines the core vocabulary for CoRAL: a set of link 1822 relation types, operation types, form field types, and metadata 1823 names. 1825 [[NOTE TO RFC EDITOR: Please replace all occurrences of "urn:TBD1" in 1826 this document with an IETF-controlled IRI, such as "urn:ietf:..." or 1827 "http://...ietf.org/...".]] 1829 A.1. Link Relation Types 1831 1832 Indicates that the link's context is an instance of the class 1833 specified as the link's target, as defined by RDF Schema 1834 [W3C.REC-rdf-schema-20140225]. 1836 1837 Indicates that the link's context is a collection and that the 1838 link's target is a member of that collection, as defined in 1839 Section 2.1 of RFC 6573 [RFC6573]. 1841 1842 Indicates that the link's target is a collection and that the 1843 link's context is a member of that collection, as defined in 1844 Section 2.2 of RFC 6573 [RFC6573]. 1846 A.2. Operation Types 1848 1849 Indicates that the form's context is a collection and that a new 1850 item can be created in that collection by submitting a suitable 1851 representation. This operation type is typically used with the 1852 POST method [RFC7231] [RFC7252]. 1854 1855 Indicates that the form's context can be updated by submitting a 1856 suitable representation. This operation type is typically used 1857 with the PUT method [RFC7231] [RFC7252], PATCH method [RFC5789] 1858 [RFC8132], or iPATCH method [RFC8132]. 1860 1861 Indicates that the form's context can be deleted. This operation 1862 type is typically used with the DELETE method [RFC7231] [RFC7252]. 1864 1865 Indicates that the form's context can be searched by submitting a 1866 search query. This operation type is typically used with the POST 1867 method [RFC7231] [RFC7252] or FETCH method [RFC8132]. 1869 A.3. Form Field Types 1871 1872 Specifies an acceptable HTTP content type or CoAP content format 1873 for the request payload. There may be multiple form fields of 1874 this type. If a form does not include a form field of this type, 1875 the server accepts any or no request payload, depending on the 1876 operation type. 1878 For HTTP, the content type MUST be specified as a text string in 1879 the format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the 1880 set of possible values is maintained in the IANA Media Types 1881 Registry. For CoAP, the content format MUST be specified as an 1882 unsigned integer; the set of possible values is maintained in the 1883 IANA CoAP Content-Formats Registry. 1885 A.4. Representation Metadata 1887 1888 Specifies the HTTP content type or CoAP content format of the 1889 representation. 1891 For HTTP, the content type MUST be specified as a text string in 1892 the format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the 1893 set of possible values is maintained in the IANA Media Types 1894 Registry. For CoAP, the content format MUST be specified as an 1895 unsigned integer; the set of possible values is maintained in the 1896 IANA CoAP Content-Formats Registry. 1898 A metadata item of this type MUST NOT occur more than once. If 1899 absent, its value defaults to content type "application/octet- 1900 stream" or content format 42. 1902 Appendix B. Default Dictionary 1904 This section defines a default dictionary that is assumed when the 1905 "application/coral+cbor" media type is used without a "dictionary" 1906 parameter. 1908 +-----+-------------------------------------------------------+ 1909 | Key | Value | 1910 +-----+-------------------------------------------------------+ 1911 | 0 | | 1912 | 1 | | 1913 | 2 | | 1914 | 3 | | 1915 | 4 | | 1916 | 5 | | 1917 | 6 | | 1918 | 7 | | 1919 | 8 | | 1920 +-----+-------------------------------------------------------+ 1922 Table 2: Default Dictionary 1924 Acknowledgements 1926 Thanks to Christian Amsuess for helpful comments and discussions that 1927 have shaped the document. 1929 Author's Address 1931 Klaus Hartke 1932 Ericsson 1933 Torshamnsgatan 23 1934 Stockholm SE-16483 1935 Sweden 1937 Email: klaus.hartke@ericsson.com