idnits 2.17.1 draft-hartke-t2trg-coral-07.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 1276 has weird spacing: '...ttr:obs true...' -- The document date (February 6, 2019) is 1906 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 1552, but not defined == Outdated reference: A later version (-03) exists of draft-hartke-t2trg-ciri-01 == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-06 ** 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 February 6, 2019 5 Expires: August 10, 2019 7 The Constrained RESTful Application Language (CoRAL) 8 draft-hartke-t2trg-coral-07 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 August 10, 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 . . . . . . . . . . . . . . . . . . . . 4 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 . . . . . . . . . . . . . . . . . . . . . 12 71 4.2. Dictionaries . . . . . . . . . . . . . . . . . . . . . . 13 72 4.2.1. Dictionary References . . . . . . . . . . . . . . . . 13 73 4.2.2. Media Type Parameter . . . . . . . . . . . . . . . . 13 74 5. Textual Format . . . . . . . . . . . . . . . . . . . . . . . 14 75 5.1. Lexical Structure . . . . . . . . . . . . . . . . . . . . 14 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 . . . . . . . . . . . . . . . . . . . . . 15 80 5.1.5. IRIs and IRI References . . . . . . . . . . . . . . . 16 81 5.1.6. Literals . . . . . . . . . . . . . . . . . . . . . . 16 82 5.1.7. Punctuators . . . . . . . . . . . . . . . . . . . . . 19 83 5.2. Syntactic Structure . . . . . . . . . . . . . . . . . . . 20 84 5.2.1. Documents . . . . . . . . . . . . . . . . . . . . . . 20 85 5.2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 20 86 5.2.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 21 87 5.2.4. Embedded Representations . . . . . . . . . . . . . . 22 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 . . . . . . . . . . . . . . . 24 92 6.1.2. Resource Names . . . . . . . . . . . . . . . . . . . 25 93 6.1.3. Implementation Limits . . . . . . . . . . . . . . . . 25 94 6.2. Minting New Relation Types . . . . . . . . . . . . . . . 26 95 6.3. Expressing Registered Link Relation Types . . . . . . . . 27 96 6.4. Expressing Link Target Attributes . . . . . . . . . . . . 27 97 6.5. Expressing Simple RDF Statements . . . . . . . . . . . . 28 98 6.6. Embedding CoRAL in CBOR Structures . . . . . . . . . . . 29 99 7. Security Considerations . . . . . . . . . . . . . . . . . . . 29 100 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 101 8.1. Media Type "application/coral+cbor" . . . . . . . . . . . 30 102 8.2. Media Type "text/coral" . . . . . . . . . . . . . . . . . 32 103 8.3. CoAP Content Formats . . . . . . . . . . . . . . . . . . 33 104 8.4. CBOR Tag . . . . . . . . . . . . . . . . . . . . . . . . 33 105 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 106 9.1. Normative References . . . . . . . . . . . . . . . . . . 34 107 9.2. Informative References . . . . . . . . . . . . . . . . . 36 108 Appendix A. Core Vocabulary . . . . . . . . . . . . . . . . . . 38 109 A.1. Link Relation Types . . . . . . . . . . . . . . . . . . . 38 110 A.2. Form Relation Types . . . . . . . . . . . . . . . . . . . 38 111 A.3. Form Field Names . . . . . . . . . . . . . . . . . . . . 39 112 Appendix B. Default Dictionary . . . . . . . . . . . . . . . . . 39 113 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 40 114 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 40 116 1. Introduction 118 The Constrained RESTful Application Language (CoRAL) is a language 119 for the description of typed connections between resources on the Web 120 ("links"), possible operations on such resources ("forms"), as well 121 as simple resource metadata. 123 CoRAL is intended for driving automated software agents that navigate 124 a Web application based on a standardized vocabulary of link and form 125 relation types. It is designed to be used in conjunction with a Web 126 transfer protocol such as the Hypertext Transfer Protocol (HTTP) 127 [RFC7230] or the Constrained Application Protocol (CoAP) [RFC7252]. 129 This document defines the CoRAL data and interaction model, as well 130 as two specialized CoRAL serialization formats. 132 The CoRAL data and interaction model is a superset of the Web Linking 133 model of RFC 8288 [RFC8288]. The data model consists of two primary 134 elements: "links" that describe the relationship between two 135 resources and the type of that relationship, and "forms" that 136 describe a possible operation on a resource and the type of that 137 operation. Additionally, the data model can describe simple resource 138 metadata in a way similar to the Resource Description Framework (RDF) 139 [W3C.REC-rdf11-concepts-20140225]. In contrast to RDF, the focus of 140 CoRAL however is on the interaction with resources, not just the 141 relationships between them. The interaction model derives from HTML 142 5 [W3C.REC-html52-20171214] and specifies how an automated software 143 agent can navigate between resources by following links and perform 144 operations on resources by submitting forms. 146 The primary CoRAL serialization format is a compact, binary encoding 147 of links and forms in Concise Binary Object Representation (CBOR) 148 [RFC7049]. It is intended for environments with constraints on 149 power, memory, and processing resources [RFC7228] and shares many 150 similarities with the message format of the Constrained Application 151 Protocol (CoAP) [RFC7252]: For example, it uses numeric identifiers 152 instead of verbose strings for link and form relation types, and pre- 153 parses Uniform Resource Identifiers (URIs) [RFC3986] into (what CoAP 154 considers to be) their components, which simplifies URI processing 155 for constrained nodes a lot. As a result, link serializations in 156 CoRAL are often much more compact than equivalent serializations in 157 CoRE Link Format [RFC6690]. 159 The secondary CoRAL serialization format is a lightweight, textual 160 encoding of links and forms that is intended to be easy to read and 161 write for humans. The format is loosely inspired by the syntax of 162 Turtle [W3C.REC-turtle-20140225] and is mainly intended for giving 163 examples. 165 1.1. Notational Conventions 167 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 168 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 169 "OPTIONAL" in this document are to be interpreted as described in BCP 170 14 [RFC2119] [RFC8174] when, and only when, they appear in all 171 capitals, as shown here. 173 Terms defined in this document appear in _cursive_ where they are 174 introduced. 176 2. Examples 178 [[NOTE TO READERS: Examples and test vectors will be provided on a 179 companion website.]] 181 3. Data and Interaction Model 183 The Constrained RESTful Application Language (CoRAL) is designed for 184 building Web-based applications [W3C.REC-webarch-20041215] in which 185 automated software agents navigate between resources by following 186 links and perform operations on resources by submitting forms. 188 3.1. Browsing Context 190 Borrowing from HTML 5 [W3C.REC-html52-20171214], each such agent 191 maintains a _browsing context_ in which the representations of Web 192 resources are processed. (In HTML 5, the browsing context typically 193 corresponds to a tab or window in a Web browser.) 194 At any time, one representation in each browsing context is 195 designated the _active_ representation. 197 3.2. Documents 199 A resource representation in one of the CoRAL serialization formats 200 is called a CoRAL _document_. The Internationalized Resource 201 Identifier (IRI) [RFC3987] that was used to retrieve such a document 202 is called the document's _retrieval context_. 204 A CoRAL document consists of a list of zero or more links, forms, and 205 embedded resource representations, collectively called _elements_. 206 CoRAL serialization formats may define additional types of elements 207 for efficiency or convenience, such as a base for relative IRI 208 references [RFC3987]. 210 3.3. Links 212 A _link_ describes a relationship between two resources on the Web 213 [RFC8288]. As defined in RFC 8288, it consists of a _link context_, 214 a _link relation type_, and a _link target_. In CoRAL, a link can 215 additionally have a nested list of zero or more elements, which take 216 the place of link target attributes. 218 A link can be viewed as a statement of the form "{link context} has a 219 {link relation type} resource at {link target}" where the link target 220 may be further described by nested elements. 222 The link relation type identifies the semantics of a link. In HTML 5 223 and RFC 8288, link relation types are typically denoted by an IANA- 224 registered name, such as "stylesheet" or "type". In CoRAL, they are 225 denoted by an IRI such as or . 227 This allows for the creation of new link relation types without the 228 risk of collisions when from different organizations or domains of 229 knowledge. An IRI also can lead to documentation, schema, and other 230 information about the link relation type. These IRIs are primarily 231 used as identity tokens, though, and are compared using Simple String 232 Comparison (Section 5.1 of RFC 3987). 234 The link context and the link target are both either by an IRI or 235 (similarly to RDF) a literal. If the IRI scheme indicates a Web 236 transfer protocol such as HTTP or CoAP, then an agent can dereference 237 the IRI and navigate the browsing context to the referenced resource; 238 this is called _following the link_. A literal directly identifies a 239 value. This can be a Boolean value, an integer, a floating-point 240 number, a date/time value, a byte string, or a text string. 242 A link can occur as a top-level element in a document or as a nested 243 element within a link. When a link occurs as a top-level element, 244 the link context implicitly is the document's retrieval context. 245 When a link occurs nested within a link, the link context of the 246 inner link is the link target of the outer link. 248 There are no restrictions on the cardinality of links; there can be 249 multiple links to and from a particular target, and multiple links of 250 the same or different types between a given link context and target. 251 However, the nested data structure constrains the description of a 252 resource graph to a tree: Links between linked resources can only be 253 described by further nesting links. 255 3.4. Forms 257 A _form_ provides instructions to an agent for performing an 258 operation on a Web resource. It consists of a _form context_, a 259 _form relation type_, a _request method_, and a _submission target_. 260 Additionally, a form may be accompanied by a list of _form fields_. 262 A form can be viewed as an instruction of the form "To perform a 263 {form relation type} operation on {form context}, make a {request 264 method} request to {submission target}" where the payload of the 265 request may be further described by any form fields. 267 The form relation type identifies the semantics of the operation. 268 Form relation types are denoted like link relation types by an IRI. 270 The form context is the resource on which an operation is ultimately 271 performed. To perform the operation, an agent needs to construct a 272 request with the specified request method and submission target as 273 the request IRI. The submission target typically is the same 274 resource as the form context, but may be a different resource. 275 Constructing and sending the request is called _submitting the form_. 277 If a form is accompanied by a list of form fields, as described in 278 the following section, then the agent also needs to construct a 279 payload that matches the specifications of the form fields and 280 include that in the request. 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 3.5. Form Fields 290 Form fields provide further instructions to agents for constructing a 291 request payload. 293 A form field can directly identify one or more data items that need 294 to include in the request payload or can reference another resource 295 (such as a schema) that describes the structure of the payload. Form 296 fields may also provide other kinds of information, such as 297 acceptable media types for the payload. 299 A form field is a pair of a _form field name_ and a _form field 300 value_. The form field name identifies the semantics of the form 301 field. Form field names are denoted like link and form relation 302 types by an IRI. The form field value can either be an IRI, a 303 Boolean value, an integer, a floating-point number, a date/time 304 value, a byte string, or a text string. 306 3.6. Embedded Representations 308 When a document contains links to many resources and an agent needs a 309 representation of each link target, it may be inefficient to retrieve 310 each of these representations individually. To alleviate this, 311 documents can directly embed representations of resources. 313 An _embedded representation_ consists of a sequence of bytes, labeled 314 with _representation metadata_. 316 An embedded representation may be a full, partial, or inconsistent 317 version of the representation served from the IRI of the resource. 319 An embedded representation can occur as a top-level element in a 320 document or as a nested element within a link. When it occurs as a 321 top-level element, it provides an alternate representation of the 322 document's retrieval context. When it occurs nested within a link, 323 it provides a representation of link target of the enclosing link. 325 3.7. Navigation 327 An agent begins interacting with an application by performing a GET 328 request on an _entry point IRI_. The entry point IRI is the only IRI 329 an agent is expected to know before interacting with an application. 330 From there, the agent is expected to make all requests by following 331 links and submitting forms provided by the server in responses. The 332 entry point IRI can be obtained by manual configuration or through 333 some discovery process. 335 If dereferencing the entry point IRI yields a CoRAL document (or any 336 other representation that implements the CoRAL data and interaction 337 model), then the agent makes this document the active representation 338 in the browsing context and proceeds as follows: 340 1. The first step for the agent is to decide what to do next, i.e., 341 which type of link to follow or form to submit, based on the link 342 and form relation types it understands. 344 2. The agent then finds the link(s) or form(s) with the respective 345 relation type in the active representation. This may yield one 346 or more candidates, from which the agent will have to select the 347 most appropriate one. The set of candidates may be empty, for 348 example, when a transition is not supported or not allowed. 350 3. The agent selects one of the candidates based on the metadata 351 associated with each of these. Metadata includes the content 352 type of the target resource representation, the IRI scheme, the 353 request method, and other information that is provided as nested 354 elements in a link or form fields in a form. 356 If the selected candidate contains an embedded representation, 357 the agent MAY skip the following steps and immediately proceed 358 with step 8. 360 4. The agent obtains the _request IRI_ from the link target or 361 submission target. Fragment identifiers are not part of the 362 request IRI and MUST be separated from the rest of the IRI prior 363 to a dereference. 365 5. The agent constructs a new request with the request IRI. If the 366 agent is following a link, then the request method MUST be GET. 367 If the agent is submitting a form, then the request method MUST 368 be the one specified in the form. The request IRI may need to be 369 converted to a URI (Section 3.1 of RFC 3987) for protocols that 370 do not support IRIs. 372 The agent SHOULD set HTTP header fields and CoAP request options 373 according to metadata associated with the link or form (e.g., set 374 the HTTP Accept header field or the CoAP Accept option when the 375 media type of the target resource is provided). In the case of a 376 form with one or more form fields, the agent also MUST include a 377 request payload that matches the specifications of the form 378 fields. 380 6. The agent sends the request and receives the response. 382 7. If a fragment identifier was separated from the request IRI, the 383 agent dereferences the fragment identifier within the received 384 representation. 386 8. The agent _updates the browsing context_ by making the (embedded 387 or received) representation the active representation. 389 9. Finally, the agent processes the representation according to the 390 semantics of the content type. If the representation is a CoRAL 391 document (or any other representation that implements the CoRAL 392 data and interaction model), this means the agent has the choice 393 of what to do next again -- and the cycle repeats. 395 3.8. History Traversal 397 A browsing context MAY entail a _session history_ that lists the 398 resource representations that the agent has processed, is processing, 399 or will process. 401 An entry in the session history consists of a resource representation 402 and the request IRI that was used to retrieve the representation. 403 New entries are added to the session history as the agent navigates 404 from resource to resource. 406 An agent can navigate a browsing context by _traversing the session 407 history_ in addition to following links and submitting forms. For 408 example, if an agent received a representation that doesn't contain 409 any further links or forms, it can revert the active representation 410 back to one it has visited earlier. 412 Traversing the history should take advantage of caches to avoid new 413 requests. An agent MAY reissue a safe request (e.g., a GET request) 414 if it doesn't have a fresh representation in its cache. An agent 415 MUST NOT reissue an unsafe request (e.g., a PUT or POST request). 417 4. Binary Format 419 This section defines the encoding of documents in the CoRAL binary 420 format. 422 A document in the binary format is a data item in Concise Binary 423 Object Representation (CBOR) [RFC7049]. The structure of this data 424 item is presented in the Concise Data Definition Language (CDDL) 425 [I-D.ietf-cbor-cddl]. The media type is "application/coral+cbor". 427 4.1. Data Structure 429 The data structure of a document in the binary format is made up of 430 four kinds of elements: links, forms, embedded representations, and 431 (as an extension to the CoRAL data model) base directives. Base 432 directives provide a way to encode IRIs with a common base more 433 efficiently. 435 Elements are processed in the order they appear in the document. 436 Document processors need to maintain an _environment_ while iterating 437 an array of elements. The environment consists of two variables: the 438 _current context_ and the _current base_. Both the current context 439 and the current base are initially set to the document's retrieval 440 context. 442 4.1.1. Documents 444 The body of a document in the binary format is encoded as an array of 445 zero or more links, forms, embedded representations, and directives. 447 body = [*(link / form / representation / directive)] 449 4.1.2. Links 451 A link is encoded as an array that consists of the unsigned integer 452 2, followed by the link relation type and the link target, optionally 453 followed by a link body that contains nested elements. 455 link = [link: 2, relation, link-target, ?body] 457 The link relation type is encoded as a text string that conforms to 458 the syntax of an IRI [RFC3987]. 460 relation = text 462 The link target is denoted by an IRI reference or represented by a 463 literal value. An IRI reference MUST be resolved against the current 464 base. The encoding of and resolution process for IRI references in 465 the binary format is described in RFC XXXX [I-D.hartke-t2trg-ciri]. 466 The link target may be null, which indicates that the link target is 467 an unidentified resource. 469 link-target = ciri / literal 471 ciri = 473 literal = bool / int / float / time / bytes / text / null 475 The array of elements in the link body, if any, MUST be processed in 476 a fresh environment. Both the current context and the current base 477 in the new environment are initially set to the link target of the 478 enclosing link. 480 4.1.3. Forms 482 A form is encoded as an array that consists of the unsigned integer 483 3, followed by the form relation type, the request method, and the 484 submission target, optionally followed by a list of form fields. 486 form = [form: 3, relation, method, submission-target, ?form- 487 fields] 489 The form relation type is defined in the same way as a link relation 490 type (Section 4.1.2). 492 The method MUST refer to one of the request methods defined by the 493 Web transfer protocol identified by the scheme of the submission 494 target. It is encoded either as a text string or an unsigned 495 integer. 497 method = text / uint 499 For HTTP [RFC7230], the method MUST be encoded as a text string in 500 the format defined in Section 4.1 of RFC 7231 [RFC7231]; the set of 501 possible values is maintained in the IANA HTTP Method Registry. For 502 CoAP [RFC7252], the method MUST be encoded as an unsigned integer 503 (e.g., the unsigned integer 2 for the POST method); the set of 504 possible values is maintained in the IANA CoAP Method Codes Registry. 506 The submission target is denoted by an IRI reference. This IRI 507 reference MUST be resolved against the current base. 509 submission-target = ciri 511 4.1.3.1. Form Fields 513 A list of form fields is encoded as an array of zero or more name- 514 value pairs. 516 form-fields = [*(form-field-name, form-field-value)] 518 The list, if any, MUST be processed in a fresh environment. Both the 519 current context and the current base in the new environment are 520 initially set to the submission target of the enclosing form. 522 A form field name is defined in the same way as a link relation type 523 (Section 4.1.2). 525 form-field-name = text 527 A form field value can be an IRI reference, a Boolean value, an 528 integer, a floating-point number, a date/time value, a byte string, a 529 text string, or null. An IRI reference MUST be resolved against the 530 current base. 532 form-field-value = ciri / literal 534 4.1.3.2. Short Forms 536 [[NOTE TO READERS: This section used to describe special elements for 537 compressing certain forms that were assumed to occur frequently. The 538 topic of encoding frequently occurring elements more efficiently will 539 be revisited when more real-world examples are available.]] 541 4.1.4. Embedded Representations 543 An embedded representation is encoded as an array that consists of 544 the unsigned integer 0, followed by the HTTP content type or CoAP 545 content format of the representation and a byte string containing the 546 representation data. 548 representation = [representation: 0, text / uint, bytes] 550 For HTTP, the content type MUST be specified as a text string in the 551 format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the set of 552 possible values is maintained in the IANA Media Types Registry. For 553 CoAP, the content format MUST be specified as an unsigned integer; 554 the set of possible values is maintained in the IANA CoAP Content- 555 Formats Registry. 557 4.1.5. Directives 559 Directives provide the ability to manipulate the environment when 560 processing a list of elements. There is one type of directives 561 available: the Base directive. 563 directive = base-directive 565 4.1.5.1. Base Directives 567 A Base directive is encoded as an array that consists of the negative 568 integer -1, followed by a base. 570 base-directive = [base: -1, base] 572 The base is denoted by an IRI reference. This IRI reference MUST be 573 resolved against the current context (not the current base). 575 base = ciri 577 The directive is processed by resolving the IRI reference against the 578 current context and assigning the result to the current base. 580 4.2. Dictionaries 582 The binary format can reference values from a dictionary to reduce 583 representation size and processing cost. Dictionary references can 584 used in place of link relation types, link targets, form relation 585 types, submission targets, form field names, and form field values. 587 4.2.1. Dictionary References 589 A dictionary reference is encoded as an unsigned integer. Where a 590 dictionary reference cannot be expressed unambiguously, the unsigned 591 integer is tagged with CBOR tag TBD6. 593 relation /= uint 595 link-target /= #6.TBD6(uint) 597 submission-target /= #6.TBD6(uint) 599 form-field-name /= uint 601 form-field-value /= #6.TBD6(uint) 603 4.2.2. Media Type Parameter 605 The "application/coral+cbor" media type is defined to have a 606 "dictionary" parameter that specifies the dictionary in use. The 607 dictionary is identified by a URI [RFC3986]. For example, a CoRAL 608 document that uses the dictionary identified by the URI 609 can use the following content type: 611 application/coral+cbor; dictionary="http://example.com/dictionary" 613 The URI serves only as an identifier; it does not necessarily have to 614 be dereferencable (or even use a dereferencable URI scheme). It is 615 permissible, though, to use a dereferencable URI and to serve a 616 representation that provides information about the dictionary in a 617 human- or machine-readable way. (The format of such a representation 618 is outside the scope of this document.) 620 For simplicity, a CoRAL document can reference values only from one 621 dictionary; the value of the "dictionary" parameter MUST be a single 622 URI. If the "dictionary" parameter is absent, the default dictionary 623 specified in Appendix B of this document is assumed. 625 Once a dictionary has made an assignment, the assignment MUST NOT be 626 changed or removed. A dictionary, however, may contain additional 627 information about an assignment, which may change over time. 629 In CoAP [RFC7252], media types (including specific values for media 630 type parameters) are encoded as an unsigned integer called "content 631 format". For use with CoAP, each new CoRAL dictionary MUST register 632 a new content format in the IANA CoAP Content-Formats Registry. 634 5. Textual Format 636 This section defines the syntax of documents in the CoRAL textual 637 format using two grammars: The lexical grammar defines how Unicode 638 characters are combined to form line terminators, white space, 639 comments, and tokens. The syntactic grammar defines how tokens are 640 combined to form documents. Both grammars are presented in Augmented 641 Backus-Naur Form (ABNF) [RFC5234]. 643 A document in the textual format is a Unicode string in a Unicode 644 encoding form [UNICODE]. The media type for such documents is "text/ 645 coral". The "charset" parameter is not used; charset information is 646 transported inside the document in the form of an OPTIONAL Byte Order 647 Mark (BOM). The use of the UTF-8 encoding scheme [RFC3629], without 648 a BOM, is RECOMMENDED. 650 5.1. Lexical Structure 652 The lexical structure of a document in the textual format is made up 653 of four basic elements: line terminators, white space, comments, and 654 tokens. Of these, only tokens are significant in the syntactic 655 grammar. There are five kinds of tokens: identifiers, IRIs, IRI 656 references, literals, and punctuators. 658 token = identifier / iri / iriref / literal / punctuator 660 When several lexical grammar rules match a sequence of characters in 661 a document, the longest match takes priority. 663 5.1.1. Line Terminators 665 Line terminators divide text into lines. A line terminator is any 666 Unicode character with Line_Break class BK, CR, LF, or NL. However, 667 any CR character that immediately precedes a LF character is ignored. 668 (This affects only the numbering of lines in error messages.) 670 5.1.2. White Space 672 White space is a sequence of one or more white space characters. A 673 white space character is any Unicode character with the White_Space 674 property. 676 5.1.3. Comments 678 Comments are sequences of characters that are ignored when parsing 679 text into tokens. Single-line comments begin with the characters 680 "//" and extend to the end of the line. Delimited comments begin 681 with the characters "/*" and end with the characters "*/". Delimited 682 comments can occupy a portion of a line, a single line, or multiple 683 lines. 685 Comments do not nest. The character sequences "/*" and "*/" have no 686 special meaning within a single-line comment; the character sequences 687 "//" and "/*" have no special meaning within a delimited comment. 689 5.1.4. Identifiers 691 An identifier token is a user-defined symbolic name. The rules for 692 identifiers correspond to those recommended by the Unicode Standard 693 Annex #31 [UNICODE-UAX31] using the following profile: 695 identifier = START *CONTINUE *(MEDIAL 1*CONTINUE) 697 START = 699 CONTINUE = 701 MEDIAL = "-" / "." / "~" / %x58A / %xF0B 703 MEDIAL =/ %x2010 / %x2027 / %x30A0 / %x30FB 705 All identifiers MUST be converted into Unicode Normalization Form C 706 (NFC), as defined by the Unicode Standard Annex #15 [UNICODE-UAX15]. 707 Comparison of identifiers is based on NFC and is case-sensitive 708 (unless otherwise noted). 710 5.1.5. IRIs and IRI References 712 IRIs and IRI references are Unicode strings that conform to the 713 syntax defined in RFC 3987 [RFC3987]. An IRI reference can be either 714 an IRI or a relative reference. Both IRIs and IRI references are 715 enclosed in angle brackets ("<" and ">"). 717 iri = "<" IRI ">" 719 iriref = "<" IRI-reference ">" 721 IRI = 723 IRI-reference = 725 5.1.6. Literals 727 A literal is a textual representation of a value. There are seven 728 types of literals: Boolean, integer, floating-point, date/time, byte 729 string, text string, and null. 731 literal = boolean / integer / float / datetime / bytes / text 733 literal =/ null 735 5.1.6.1. Boolean Literals 737 The case-insensitive tokens "true" and "false" denote the Boolean 738 values true and false, respectively. 740 boolean = "true" / "false" 742 5.1.6.2. Integer Literals 744 Integer literals denote an integer value of unspecified precision. 745 By default, integer literals are expressed in decimal, but they can 746 also be specified in an alternate base using a prefix: Binary 747 literals begin with "0b", octal literals begin with "0o", and 748 hexadecimal literals begin with "0x". 750 Decimal literals contain the digits "0" through "9". Binary literals 751 contain "0" and "1", octal literals contain "0" through "7", and 752 hexadecimal literals contain "0" through "9" as well as "A" through 753 "F" in upper- or lowercase. 755 Negative integers are expressed by prepending a minus sign ("-"). 757 integer = ["+" / "-"] (decimal / binary / octal / hexadecimal) 758 decimal = 1*DIGIT 760 binary = %x30 (%x42 / %x62) 1*BINDIG 762 octal = %x30 (%x4F / %x6F) 1*OCTDIG 764 hexadecimal = %x30 (%x58 / %x78) 1*HEXDIG 766 DIGIT = %x30-39 768 BINDIG = %x30-31 770 OCTDIG = %x30-37 772 HEXDIG = %x30-39 / %x41-46 / %x61-66 774 5.1.6.3. Floating-point Literals 776 Floating-point literals denote a floating-point number of unspecified 777 precision. 779 Floating-point literals consist of a sequence of decimal digits 780 followed by a fraction, an exponent, or both. The fraction consists 781 of a decimal point (".") followed by a sequence of decimal digits. 782 The exponent consists of the letter "e" in upper- or lowercase, 783 followed by an optional sign and a sequence of decimal digits that 784 indicate a power of 10 by which the value preceding the "e" is 785 multiplied. 787 Negative floating-point values are expressed by prepending a minus 788 sign ("-"). 790 float = ["+" / "-"] 1*DIGIT [fraction] [exponent] 792 fraction = "." 1*DIGIT 794 exponent = (%x45 / %x65) ["+" / "-"] 1*DIGIT 796 A floating-point literal can additionally denote either the special 797 "Not-a-Number" (NaN) value, positive infinity, or negative infinity. 798 The NaN value is produced by the case-insensitive token "NaN". The 799 two infinite values are produced by the case-insensitive tokens 800 "+Infinity" (or simply "Infinity") and "-Infinity". 802 float =/ "NaN" 804 float =/ ["+" / "-"] "Infinity" 806 5.1.6.4. Date/Time Literals 808 Date/time literals denote an instant in time. 810 A date/time literal consists of a sequence of characters in Internet 811 date/time format [RFC3339], enclosed in dollar signs. 813 datetime = DOLLAR date-time DOLLAR 815 date-time = 817 DOLLAR = %x24 819 5.1.6.5. Byte String Literals 821 Byte string literals denote an ordered sequence of bytes. 823 A byte string literal consists of a prefix and zero or more bytes 824 encoded in Base16, Base32, or Base64 [RFC4648] and enclosed in single 825 quotes. Byte string literals encoded in Base16 begin with "h" or 826 "b16", byte string literals encoded in Base32 begin with "b32", and 827 byte string literals encoded in Base64 begin with "b64". 829 bytes = base16 / base32 / base64 831 base16 = (%x68 / %x62.31.36) SQUOTE SQUOTE 833 base32 = %x62.33.32 SQUOTE SQUOTE 835 base64 = %x62.36.34 SQUOTE SQUOTE 837 SQUOTE = %x27 839 5.1.6.6. Text String Literals 841 Text string literals denote a Unicode string. 843 A text string literal consists of zero or more Unicode characters 844 enclosed in double quotes. It can include simple escape sequences 845 (such as \t for the tab character) as well as hexadecimal and Unicode 846 escape sequences. 848 text = DQUOTE *(char / %x5C escape) DQUOTE 850 char = 852 escape = simple-escape / hexadecimal-escape / unicode-escape 853 simple-escape = %x30 / %x62 / %x74 / %x6E / %x76 855 simple-escape =/ %x66 / %x72 / %x22 / %x27 / %x5C 857 hexadecimal-escape = (%x78 / %x58) 2HEXDIG 859 unicode-escape = %x75 4HEXDIG / %x55 8HEXDIG 861 DQUOTE = %x22 863 An escape sequence denotes a single Unicode code point. For 864 hexadecimal and Unicode escape sequences, the code point is expressed 865 by the hexadecimal number following the "\x", "\X", "\u", or "\U" 866 prefix. Simple escape sequences indicate the code points listed in 867 Table 1. 869 +-----------------+------------+----------------------+ 870 | Escape Sequence | Code Point | Character Name | 871 +-----------------+------------+----------------------+ 872 | \0 | U+0000 | Null | 873 | \b | U+0008 | Backspace | 874 | \t | U+0009 | Character Tabulation | 875 | \n | U+000A | Line Feed | 876 | \v | U+000B | Line Tabulation | 877 | \f | U+000C | Form Feed | 878 | \r | U+000D | Carriage Return | 879 | \" | U+0022 | Quotation Mark | 880 | \' | U+0027 | Apostrophe | 881 | \\ | U+005C | Reverse Solidus | 882 +-----------------+------------+----------------------+ 884 Table 1: Simple Escape Sequences 886 5.1.6.7. Null Literal 888 The case-insensitive tokens "null" and "_" denote the intentional 889 absence of any value. 891 null = "null" / "_" 893 5.1.7. Punctuators 895 Punctuator tokens are used for grouping and separating. 897 punctuator = "#" / ":" / "*" / "[" / "]" / "{" / "}" / "=" / "->" 899 5.2. Syntactic Structure 901 The syntactic structure of a document in the textual format is made 902 up of four kinds of elements: links, forms, embedded representations, 903 and (as an extension to the CoRAL data model) directives. Directives 904 provide a way to make documents easier to read and write by setting a 905 base for relative IRI references and introducing shorthands for IRIs. 907 Elements are processed in the order they appear in the document. 908 Document processors need to maintain an _environment_ while iterating 909 a list of elements. The environment consists of three variables: the 910 _current context_, the _current base_, and the _current mapping from 911 identifiers to IRIs_. Both the current context and the current base 912 are initially set to the document's retrieval context. The current 913 mapping from identifiers to IRIs is initially empty. 915 5.2.1. Documents 917 The body of a document in the textual format consists of zero or more 918 links, forms, embedded representations, and directives. 920 body = *(link / form / representation / directive) 922 5.2.2. Links 924 A link consists of the link relation type, followed by the link 925 target, optionally followed by a link body enclosed in curly brackets 926 ("{" and "}"). 928 link = relation link-target ["{" body "}"] 930 The link relation type is denoted by either an IRI, a simple name, or 931 a qualified name. 933 relation = iri / simple-name / qualified-name 935 A simple name consists of an identifier. It is resolved to an IRI by 936 looking up the empty string in the current mapping from identifiers 937 to IRIs and appending the specified identifier to the result. It is 938 an error if the empty string is not present in the current mapping. 940 simple-name = identifier 942 A qualified name consists of two identifiers separated by a colon 943 (":"). It is resolved to an IRI by looking up the identifier on the 944 left hand side in the current mapping from identifiers to IRIs and 945 appending the identifier on the right hand side to the result. It is 946 an error if the identifier on the left hand side is not present in 947 the current mapping. 949 qualified-name = identifier ":" identifier 951 The link target is denoted by an IRI reference or represented by a 952 value literal. An IRI reference MUST be resolved against the current 953 base. If the link target is null, the link target is an unidentified 954 resource. 956 link-target = iriref / literal 958 The list of elements in the link body, if any, MUST be processed in a 959 fresh environment. Both the current context and current base in this 960 environment are initially set to the link target of the enclosing 961 link. The mapping from identifiers to IRIs is initially set to a 962 copy of the mapping from identifiers to IRIs in the current 963 environment. 965 5.2.3. Forms 967 A form consists of the form relation type, followed by a "->" token, 968 the request method, and the submission target, optionally followed by 969 a list of form fields enclosed in square brackets ("[" and "]"). 971 form = relation "->" method submission-target ["[" form-fields 972 "]"] 974 The form relation type is defined in the same way as a link relation 975 type (Section 5.2.2). 977 The method identifier MUST refer to one of the request methods 978 defined by the Web transfer protocol identified by the scheme of the 979 submission target. Method identifiers are case-insensitive and 980 constrained to Unicode characters in the Basic Latin block. 982 method = identifier 984 For HTTP [RFC7230], the set of possible method identifiers is 985 maintained in the IANA HTTP Method Registry. For CoAP [RFC7252], the 986 set of possible method identifiers is maintained in the IANA CoAP 987 Method Codes Registry. 989 The submission target is denoted by an IRI reference. This IRI 990 reference MUST be resolved against the current base. 992 submission-target = iriref 994 5.2.3.1. Form Fields 996 A list of form fields consists of zero or more name-value pairs. 998 form-fields = *(form-field-name form-field-value) 1000 The list, if any, MUST be processed in a fresh environment. Both the 1001 current context and the current base in this environment are 1002 initially set to the submission target of the enclosing form. The 1003 mapping from identifiers to IRIs is initially set to a copy of the 1004 mapping from identifiers to IRIs in the current environment. 1006 The form field name is defined in the same way as a link relation 1007 type (Section 5.2.2). 1009 form-field-name = iri / simple-name / qualified-name 1011 The form field value can be an IRI reference, Boolean literal, 1012 integer literal, floating-point literal, byte string literal, text 1013 string literal, or null. An IRI reference MUST be resolved against 1014 the current base. 1016 form-field-value = iriref / literal 1018 5.2.4. Embedded Representations 1020 An embedded representation consists of a "*" token, followed by the 1021 representation data, optionally followed by representation metadata 1022 enclosed in square brackets ("[" and "]"). 1024 representation = "*" bytes ["[" representation-metadata "]"] 1026 Representation metadata consists of zero or more name-value pairs. 1028 representation-metadata = *(metadata-name metadata-value) 1030 This document specifies only one kind of metadata item, labeled with 1031 the name "type": the HTTP content type or CoAP content format of the 1032 representation. 1034 metadata-name = "type" 1036 metadata-value = text / integer 1038 For HTTP, the content type MUST be specified as a text string in the 1039 format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the set of 1040 possible values is maintained in the IANA Media Types Registry. For 1041 CoAP, the content format MUST be specified as an integer; the set of 1042 possible values is maintained in the IANA CoAP Content-Formats 1043 Registry. 1045 A metadata item with the name "type" MUST NOT occur more than once. 1046 If absent, its value defaults to content type "application/octet- 1047 stream" or content format 42. 1049 5.2.5. Directives 1051 Directives provide the ability to manipulate the environment when 1052 processing a list of elements. All directives start with a number 1053 sign ("#") followed by a directive identifier. Directive identifiers 1054 are case-insensitive and constrained to Unicode characters in the 1055 Basic Latin block. 1057 The following two types of directives are available: the Base 1058 directive and the Using directive. 1060 directive = base-directive / using-directive 1062 5.2.5.1. Base Directives 1064 A Base directive consists of a number sign ("#"), followed by the 1065 case-insensitive identifier "base", followed by a base. 1067 base-directive = "#" "base" base 1069 The base is denoted by an IRI reference. The IRI reference MUST be 1070 resolved against the current context (not the current base). 1072 base = iriref 1074 The directive is processed by resolving the IRI reference against the 1075 current context and assigning the result to the current base. 1077 5.2.5.2. Using Directives 1079 A Using directive consists of a number sign ("#"), followed by the 1080 case-insensitive identifier "using", optionally followed by an 1081 identifier and an equals sign ("="), finally followed by an IRI. If 1082 the identifier is not specified, it is assumed to be the empty 1083 string. 1085 using-directive = "#" "using" [identifier "="] iri 1087 The directive is processed by adding the specified identifier and IRI 1088 to the current mapping from identifiers to IRIs. It is an error if 1089 the identifier is already present in the mapping. 1091 6. Usage Considerations 1093 This section discusses some considerations in creating CoRAL-based 1094 applications and managing link and form relation types. 1096 6.1. Specifying CoRAL-based Applications 1098 CoRAL-based applications naturally implement the Web architecture 1099 [W3C.REC-webarch-20041215] and thus are centered around orthogonal 1100 specifications for identification, interaction, and representation: 1102 o Resources are identified by IRIs or represented by value literals. 1104 o Interactions are based on the hypermedia interaction model of the 1105 Web and the methods provided by the Web transfer protocol. The 1106 semantics of possible interactions are identified by link and form 1107 relation types. 1109 o Representations are CoRAL documents encoded in the binary format 1110 defined in Section 4 or the textual format defined in Section 5. 1111 Depending on the application, additional representation formats 1112 may be used. 1114 6.1.1. Application Interfaces 1116 Specifications for CoRAL-based applications need to list the specific 1117 components used in the application interface and their identifiers. 1118 This should include the following items: 1120 o IRI schemes that identify the Web transfer protocol(s) used in the 1121 application. 1123 o Internet media types that identify the representation format(s) 1124 used in the application, including the media type(s) of the CoRAL 1125 serialization format(s). 1127 o Link relation types that identify the semantics of links. 1129 o Form relation types that identify the semantics of forms. 1130 Additionally, for each form relation type, the permissible request 1131 method(s). 1133 o Form field names that identify the semantics of form fields. 1134 Additionally, for each form field name, the permissible form field 1135 value(s) and/or type(s). 1137 6.1.2. Resource Names 1139 Resource names -- i.e., URIs [RFC3986] and IRIs [RFC3987] -- are a 1140 cornerstone of Web-based applications. They enable the uniform 1141 identification of resources and are used every time a client 1142 interacts with a server or a resource representation needs to refer 1143 to another resource. 1145 URIs and IRIs often include structured application data in the path 1146 and query components, such as paths in a filesystem or keys in a 1147 database. It is a common practice in many HTTP-based application 1148 programming interfaces (APIs) to make this part of the application 1149 specification, i.e., to prescribe fixed URI templates that are hard- 1150 coded in implementations. There are a number of problems with this 1151 practice [RFC7320], though. 1153 In CoRAL-based applications, resource names are therefore not part of 1154 the application specification -- they are an implementation detail. 1155 The specification of a CoRAL-based application MUST NOT mandate any 1156 particular form of resource name structure. BCP 190 [RFC7320] 1157 describes the problematic practice of fixed URI structures in more 1158 detail and provides some acceptable alternatives. 1160 6.1.3. Implementation Limits 1162 This document places no restrictions on the number of elements in a 1163 CoRAL document or the depth of nested elements. Applications using 1164 CoRAL (in particular those running in constrained environments) may 1165 wish to limit these numbers and specify implementation limits that an 1166 application implementation must at least support to be interoperable. 1168 Applications may also mandate the following and other restrictions: 1170 o use of only either the binary format or the text format; 1172 o use of only either HTTP or CoAP as supported Web transfer 1173 protocol; 1175 o use of only dictionary references in the binary format for certain 1176 link relation types, link targets, form relation types, submission 1177 targets, form field names, and form field values; 1179 o use of only either content type strings or content format IDs; 1181 o use of IRI references only up to a specific string length; 1183 o use of CBOR in a canonical format (see Section 3.9 of RFC 7049). 1185 6.2. Minting New Relation Types 1187 New link relation types, form relation types, and form field names 1188 can be minted by defining an IRI [RFC3987] that uniquely identifies 1189 the item. Although the IRI can point to a resource that contains a 1190 definition of the semantics of the relation type, clients SHOULD NOT 1191 automatically access that resource to avoid overburdening its server. 1192 The IRI SHOULD be under the control of the person or party defining 1193 it, or be delegated to them. 1195 To avoid interoperability problems, it is RECOMMENDED that only IRIs 1196 are minted thare normalized according to Section 5.3 of RFC 3987. 1197 Non-normalized forms that are best avoided include: 1199 o Uppercase characters in scheme names and domain names 1201 o Percent-encoding of characters where it is not required by the IRI 1202 syntax 1204 o Explicitly stated HTTP default port (e.g., 1205 is preferable over ) 1207 o Completely empty path in HTTP IRIs (e.g., is 1208 preferable over ) 1210 o Dot segments ("/./" or "/../") in the path component of an IRI 1212 o Lowercase hexadecimal letters within percent-encoding triplets 1213 (e.g., "%3F" is preferable over "%3f") 1215 o Punycode-encoding of Internationalized Domain Names in IRIs 1217 o IRIs that are not in Unicode Normalization Form C [UNICODE-UAX15] 1219 IRIs that identify link relation types, form relation types, and form 1220 field names do not need to be registered. The inclusion of domain 1221 names in IRIs allows for the decentralized creation of new IRIs 1222 without the risk of collisions. However, IRIs can be relatively 1223 verbose and impose a high overhead on a representation. This can be 1224 a problem in constrained environments [RFC7228]. Therefore, CoRAL 1225 alternatively allows the use of unsigned integers to reference CBOR 1226 data items from a dictionary, as specified in Section 4.2. These 1227 impose a much smaller overhead but instead need to be assigned by an 1228 authority to avoid collisions. 1230 6.3. Expressing Registered Link Relation Types 1232 Link relation types registered in the IANA Link Relations Registry, 1233 such as "collection" [RFC6573] or "icon" [W3C.REC-html52-20171214], 1234 can be used in CoRAL by appending the registered name to the IRI 1235 : 1237 #using iana = 1239 iana:collection 1240 iana:icon 1242 Note that registered link relation types are required to be 1243 lowercased as per Section 3.3 of RFC 8288 [RFC8288]. 1245 (The convention of appending the link relation type to the prefix 1246 "http://www.iana.org/assignments/relation/" to form an IRI is adopted 1247 from Atom [RFC4287]. See also Appendix A.2 of RFC 8288 [RFC8288].) 1249 6.4. Expressing Link Target Attributes 1251 [[NOTE TO READERS: This section describes a mechanism to convert any 1252 link target attributes to CoRAL in a way that allows a conversion 1253 back without loss of information (round-trip conversion). It is 1254 likely that this will be replaced by a specific set of unique link 1255 relation types that match the known RFC 6690 attributes semantically 1256 but do not round-trip in the presence of unknown attributes.]] 1258 Link target attributes defined for use with CoRE Link Format 1259 [RFC6690] (such as "hreflang", "media", "title", "title*", "type", 1260 "ct", "rt", "if", "sz", and "obs") can be expressed in CoRAL by 1261 nesting links under the respective link. The link relation type of 1262 each such nested link is the lowercased attribute name appended to 1263 the IRI . 1265 If the expressed link target attribute has a value, the target of the 1266 nested link MUST be a text string; otherwise, the target MUST be the 1267 Boolean value "true". 1269 #using iana = 1270 #using attr = 1272 iana:item { 1273 attr:type "application/json-patch+json" 1274 attr:ct "51" 1275 attr:sz "247" 1276 attr:obs true 1277 } 1279 <=> 1281 ; rel=item; type="application/json-patch+json"; 1282 ct=51; sz=247; obs 1284 Language information in attributes as per RFC 8187 [RFC8187], such as 1285 in "title*" attributes, is expressed by nesting an additional link of 1286 type under the link representing the 1287 attribute. The target of the nested link MUST be a text string 1288 containing a language tag [RFC5646]. The attribute name is expressed 1289 without the "*" character. 1291 #using iana = 1292 #using attr = 1294 iana:terms-of-service { 1295 attr:title "Nutzungsbedingungen" { attr:hreflang "de" } 1296 attr:title "Terms of use" { attr:hreflang "en" } 1297 } 1299 <=> 1301 ; rel=terms-of-service; 1302 title*=UTF-8'de'Nutzungsbedingungen; 1303 title*=UTF-8'en'Terms%20of%20use 1305 Link target attributes that actually do not describe the link target 1306 but the link itself (such as "rel", "anchor", and "rev") are excluded 1307 from this provision and MUST NOT occur in a CoRAL document. 1309 6.5. Expressing Simple RDF Statements 1311 An RDF statement [W3C.REC-rdf11-concepts-20140225] says that some 1312 relationship, indicated by a predicate, holds between two resources. 1313 RDF predicates can therefore be good source for vocabulary to provide 1314 resource metadata. For example, a CoRAL document could use the FOAF 1315 vocabulary [FOAF] to describe the person or software that made it: 1317 #using rdf = 1318 #using foaf = 1320 foaf:maker null { 1321 rdf:type 1322 foaf:familyName "Hartke" 1323 foaf:givenName "Klaus" 1324 foaf:mbox 1325 } 1327 6.6. Embedding CoRAL in CBOR Structures 1329 Data items in the CoRAL binary format (Section 4) may be embedded in 1330 other CBOR [RFC7049] data structures. Specifications using CDDL 1331 [I-D.ietf-cbor-cddl] SHOULD reference the following CDDL definitions 1332 for this purpose: 1334 CoRAL-Document = body 1336 CoRAL-Link = link 1338 CoRAL-Form = form 1340 7. Security Considerations 1342 Parsers of CoRAL documents must operate on input that is assumed to 1343 be untrusted. This means that parsers MUST fail gracefully in the 1344 face of malicious inputs. Additionally, parsers MUST be prepared to 1345 deal with resource exhaustion (e.g., resulting from the allocation of 1346 big data items) or exhaustion of the call stack (stack overflow). 1347 See Section 8 of RFC 7049 [RFC7049] for security considerations 1348 relating to CBOR. 1350 Implementers of the CoRAL textual format need to consider the 1351 security aspects of handling Unicode input. See the Unicode Standard 1352 Annex #36 [UNICODE-UAX36] for security considerations relating to 1353 visual spoofing and misuse of character encodings. See Section 10 of 1354 RFC 3629 [RFC3629] for security considerations relating to UTF-8. 1356 CoRAL makes extensive use of IRIs and URIs. See Section 8 of RFC 1357 3987 [RFC3987] for security considerations relating to IRIs. See 1358 Section 7 of RFC 3986 [RFC3986] for security considerations relating 1359 to URIs. 1361 The security of applications using CoRAL can depend on the proper 1362 preparation and comparison of internationalized strings. For 1363 example, such strings can be used to make authentication and 1364 authorization decisions, and the security of an application could be 1365 compromised if an entity providing a given string is connected to the 1366 wrong account or online resource based on different interpretations 1367 of the string. See RFC 6943 [RFC6943] for security considerations 1368 relating to identifiers in IRIs and other places. 1370 CoRAL is intended to be used in conjunction with a Web transfer 1371 protocol like HTTP or CoAP. See Section 9 of RFC 7230 [RFC7230], 1372 Section 9 of RFC 7231 [RFC7231], etc., for security considerations 1373 relating to HTTP. See Section 11 of RFC 7252 [RFC7252] for security 1374 considerations relating to CoAP. 1376 CoRAL does not define any specific mechanisms for protecting the 1377 confidentiality and integrity of CoRAL documents. It relies on 1378 application layer or transport layer mechanisms for this, such as 1379 Transport Layer Security (TLS) [RFC8446]. 1381 CoRAL documents and the structure of a web of resources revealed from 1382 automatically following links can disclose personal information and 1383 other sensitive information. Implementations need to prevent the 1384 unintentional disclosure of such information. See Section of 9 of 1385 RFC 7231 [RFC7231] for additional considerations. 1387 Applications using CoRAL ought to consider the attack vectors opened 1388 by automatically following, trusting, or otherwise using links and 1389 forms in CoRAL documents. Notably, a server that is authoritative 1390 for the CoRAL representation of a resource may not necessarily be 1391 authoritative for nested elements in the document. See Section 5 of 1392 RFC 8288 [RFC8288] for related considerations. 1394 Unless an application mitigates this risk by specifying more specific 1395 rules, any link or form in a document where the link or form context 1396 and the document's retrieval context don't share the same Web origin 1397 [RFC6454] MUST be discarded ("same-origin policy"). 1399 8. IANA Considerations 1401 8.1. Media Type "application/coral+cbor" 1403 This document registers the media type "application/coral+cbor" 1404 according to the procedures of BCP 13 [RFC6838]. 1406 Type name: 1407 application 1409 Subtype name: 1410 coral+cbor 1412 Required parameters: 1414 N/A 1416 Optional parameters: 1417 dictionary - See Section 4.2 of [I-D.hartke-t2trg-coral]. 1419 Encoding considerations: 1420 binary - See Section 4 of [I-D.hartke-t2trg-coral]. 1422 Security considerations: 1423 See Section 7 of [I-D.hartke-t2trg-coral]. 1425 Interoperability considerations: 1426 N/A 1428 Published specification: 1429 [I-D.hartke-t2trg-coral] 1431 Applications that use this media type: 1432 See Section 1 of [I-D.hartke-t2trg-coral]. 1434 Fragment identifier considerations: 1435 As specified for "application/cbor". 1437 Additional information: 1438 Deprecated alias names for this type: N/A 1439 Magic number(s): N/A 1440 File extension(s): .coral.cbor 1441 Macintosh file type code(s): N/A 1443 Person & email address to contact for further information: 1444 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1446 Intended usage: 1447 COMMON 1449 Restrictions on usage: 1450 N/A 1452 Author: 1453 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1455 Change controller: 1456 IESG 1458 Provisional registration? 1459 No 1461 8.2. Media Type "text/coral" 1463 This document registers the media type "text/coral" according to the 1464 procedures of BCP 13 [RFC6838] and guidelines in RFC 6657 [RFC6657]. 1466 Type name: 1467 text 1469 Subtype name: 1470 coral 1472 Required parameters: 1473 N/A 1475 Optional parameters: 1476 N/A 1478 Encoding considerations: 1479 binary - See Section 5 of [I-D.hartke-t2trg-coral]. 1481 Security considerations: 1482 See Section 7 of [I-D.hartke-t2trg-coral]. 1484 Interoperability considerations: 1485 N/A 1487 Published specification: 1488 [I-D.hartke-t2trg-coral] 1490 Applications that use this media type: 1491 See Section 1 of [I-D.hartke-t2trg-coral]. 1493 Fragment identifier considerations: 1494 N/A 1496 Additional information: 1497 Deprecated alias names for this type: N/A 1498 Magic number(s): N/A 1499 File extension(s): .coral 1500 Macintosh file type code(s): N/A 1502 Person & email address to contact for further information: 1503 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1505 Intended usage: 1506 COMMON 1508 Restrictions on usage: 1510 N/A 1512 Author: 1513 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1515 Change controller: 1516 IESG 1518 Provisional registration? 1519 No 1521 8.3. CoAP Content Formats 1523 This document registers CoAP content formats for the content types 1524 "application/coral+cbor" and "text/coral" according to the procedures 1525 of RFC 7252 [RFC7252]. 1527 o Content Type: application/coral+cbor 1528 Content Coding: identity 1529 ID: TBD3 1530 Reference: [I-D.hartke-t2trg-coral] 1532 o Content Type: text/coral 1533 Content Coding: identity 1534 ID: TBD4 1535 Reference: [I-D.hartke-t2trg-coral] 1537 [[NOTE TO RFC EDITOR: Please replace all occurrences of "TBD3" and 1538 "TBD4" in this document with the code points assigned by IANA.]] 1540 [[NOTE TO IMPLEMENTERS: Experimental implementations can use content 1541 format ID 65087 for "application/coral+cbor" and content format ID 1542 65343 for "text/coral" until IANA has assigned code points.]] 1544 8.4. CBOR Tag 1546 This document registers a CBOR tag for dictionary references 1547 according to the procedures of RFC 7049 [RFC7049]. 1549 o Tag: TBD6 1550 Data Item: unsigned integer 1551 Semantics: Dictionary reference 1552 Reference: [I-D.hartke-t2trg-coral] 1554 [[NOTE TO RFC EDITOR: Please replace all occurrences of "TBD6" in 1555 this document with the code point assigned by IANA.]] 1557 9. References 1559 9.1. Normative References 1561 [I-D.hartke-t2trg-ciri] 1562 Hartke, K., "Constrained Internationalized Resource 1563 Identifiers", draft-hartke-t2trg-ciri-01 (work in 1564 progress), February 2019. 1566 [I-D.ietf-cbor-cddl] 1567 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1568 definition language (CDDL): a notational convention to 1569 express CBOR and JSON data structures", draft-ietf-cbor- 1570 cddl-06 (work in progress), November 2018. 1572 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1573 Requirement Levels", BCP 14, RFC 2119, 1574 DOI 10.17487/RFC2119, March 1997, 1575 . 1577 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1578 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1579 . 1581 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1582 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1583 2003, . 1585 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1586 Resource Identifier (URI): Generic Syntax", STD 66, 1587 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1588 . 1590 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1591 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 1592 January 2005, . 1594 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1595 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1596 . 1598 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1599 Specifications: ABNF", STD 68, RFC 5234, 1600 DOI 10.17487/RFC5234, January 2008, 1601 . 1603 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1604 DOI 10.17487/RFC6454, December 2011, 1605 . 1607 [RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding 1608 "charset" Parameter Handling in Textual Media Types", 1609 RFC 6657, DOI 10.17487/RFC6657, July 2012, 1610 . 1612 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1613 Specifications and Registration Procedures", BCP 13, 1614 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1615 . 1617 [RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for 1618 Security Purposes", RFC 6943, DOI 10.17487/RFC6943, May 1619 2013, . 1621 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1622 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1623 October 2013, . 1625 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1626 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1627 May 2017, . 1629 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1630 DOI 10.17487/RFC8288, October 2017, 1631 . 1633 [UNICODE] The Unicode Consortium, "The Unicode Standard", 1634 . 1636 Note that this reference is to the latest version of 1637 Unicode, rather than to a specific release. It is not 1638 expected that future changes in the Unicode specification 1639 will have any impact on this document. 1641 [UNICODE-UAX15] 1642 The Unicode Consortium, "Unicode Standard Annex #15: 1643 Unicode Normalization Forms", 1644 . 1646 [UNICODE-UAX31] 1647 The Unicode Consortium, "Unicode Standard Annex #31: 1648 Unicode Identifier and Pattern Syntax", 1649 . 1651 [UNICODE-UAX36] 1652 The Unicode Consortium, "Unicode Standard Annex #36: 1653 Unicode Security Considerations", 1654 . 1656 9.2. Informative References 1658 [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification 1659 0.99", January 2014, 1660 . 1662 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1663 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 1664 December 2005, . 1666 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1667 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1668 September 2009, . 1670 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1671 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1672 . 1674 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 1675 RFC 6573, DOI 10.17487/RFC6573, April 2012, 1676 . 1678 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1679 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1680 . 1682 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1683 Constrained-Node Networks", RFC 7228, 1684 DOI 10.17487/RFC7228, May 2014, 1685 . 1687 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1688 Protocol (HTTP/1.1): Message Syntax and Routing", 1689 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1690 . 1692 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1693 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1694 DOI 10.17487/RFC7231, June 2014, 1695 . 1697 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1698 Application Protocol (CoAP)", RFC 7252, 1699 DOI 10.17487/RFC7252, June 2014, 1700 . 1702 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 1703 RFC 7320, DOI 10.17487/RFC7320, July 2014, 1704 . 1706 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1707 FETCH Methods for the Constrained Application Protocol 1708 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1709 . 1711 [RFC8187] Reschke, J., "Indicating Character Encoding and Language 1712 for HTTP Header Field Parameters", RFC 8187, 1713 DOI 10.17487/RFC8187, September 2017, 1714 . 1716 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1717 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1718 . 1720 [W3C.REC-html52-20171214] 1721 Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and 1722 S. Moon, "HTML 5.2", World Wide Web Consortium 1723 Recommendation REC-html52-20171214, December 2017, 1724 . 1726 [W3C.REC-rdf-schema-20140225] 1727 Brickley, D. and R. Guha, "RDF Schema 1.1", World Wide Web 1728 Consortium Recommendation REC-rdf-schema-20140225, 1729 February 2014, 1730 . 1732 [W3C.REC-rdf11-concepts-20140225] 1733 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 1734 Concepts and Abstract Syntax", World Wide Web Consortium 1735 Recommendation REC-rdf11-concepts-20140225, February 2014, 1736 . 1738 [W3C.REC-turtle-20140225] 1739 Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", 1740 World Wide Web Consortium Recommendation REC-turtle- 1741 20140225, February 2014, 1742 . 1744 [W3C.REC-webarch-20041215] 1745 Jacobs, I. and N. Walsh, "Architecture of the World Wide 1746 Web, Volume One", World Wide Web Consortium 1747 Recommendation REC-webarch-20041215, December 2004, 1748 . 1750 Appendix A. Core Vocabulary 1752 This section defines the core vocabulary for CoRAL: a set of link 1753 relation types, form relation types, and form field names. 1755 [[NOTE TO RFC EDITOR: Please replace all occurrences of "urn:TBD1" in 1756 this document with an IETF-controlled IRI, such as "urn:ietf:..." or 1757 "http://...ietf.org/...".]] 1759 A.1. Link Relation Types 1761 1762 Indicates that the link's context is an instance of the class 1763 specified as the link's target, as defined by RDF Schema 1764 [W3C.REC-rdf-schema-20140225]. 1766 1767 Indicates that the link's context is a collection and that the 1768 link's target is a member of that collection, as defined in 1769 Section 2.1 of RFC 6573 [RFC6573]. 1771 1772 Indicates that the link's target is a collection and that the 1773 link's context is a member of that collection, as defined in 1774 Section 2.2 of RFC 6573 [RFC6573]. 1776 A.2. Form Relation Types 1778 1779 Indicates that the form's context is a collection and that a new 1780 item can be created in that collection by submitting a suitable 1781 representation. This form relation type is typically used with 1782 the POST method [RFC7231] [RFC7252]. 1784 1785 Indicates that the form's context can be updated by submitting a 1786 suitable representation. This form relation type is typically 1787 used with the PUT method [RFC7231] [RFC7252], PATCH method 1788 [RFC5789] [RFC8132], or iPATCH method [RFC8132]. 1790 1791 Indicates that the form's context can be deleted. This form 1792 relation type is typically used with the DELETE method [RFC7231] 1793 [RFC7252]. 1795 1796 Indicates that the form's context can be searched by submitting a 1797 search query. This form relation type is typically used with the 1798 POST method [RFC7231] [RFC7252] or FETCH method [RFC8132]. 1800 A.3. Form Field Names 1802 1803 Specifies an acceptable HTTP content type or CoAP content format 1804 for the request payload. There may be multiple form fields with 1805 this name. If a form does not include a form field with this 1806 name, the server accepts any or no request payload, depending on 1807 the form relation type. 1809 For HTTP, the content type MUST be specified as a text string in 1810 the format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the 1811 set of possible values is maintained in the IANA Media Types 1812 Registry. For CoAP, the content format MUST be specified as an 1813 unsigned integer; the set of possible values is maintained in the 1814 IANA CoAP Content-Formats Registry. 1816 Appendix B. Default Dictionary 1818 This section defines a default dictionary that is assumed when the 1819 "application/coral+cbor" media type is used without a "dictionary" 1820 parameter. 1822 0 = 1824 1 = 1826 2 = 1828 3 = 1830 4 = 1832 5 = 1834 6 = 1836 7 = 1838 Acknowledgements 1840 Thanks to Christian Amsuess for helpful comments and discussions that 1841 have shaped the document. 1843 Author's Address 1845 Klaus Hartke 1846 Ericsson 1847 Torshamnsgatan 23 1848 Stockholm SE-16483 1849 Sweden 1851 Email: klaus.hartke@ericsson.com