idnits 2.17.1 draft-ietf-core-coral-02.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: ---------------------------------------------------------------------------- == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 2189 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (8 January 2020) is 1570 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'I-D.ietf-core-coral' is mentioned on line 1701, but not defined == Outdated reference: A later version (-16) exists of draft-ietf-cbor-7049bis-12 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-cbor-7049bis' == Outdated reference: A later version (-15) exists of draft-ietf-core-href-02 -- Possible downref: Non-RFC (?) normative reference: ref. 'UAX15' -- Possible downref: Non-RFC (?) normative reference: ref. 'UAX31' -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' == Outdated reference: A later version (-11) exists of draft-kelly-json-hal-08 -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group K. Hartke 3 Internet-Draft Ericsson 4 Intended status: Standards Track 8 January 2020 5 Expires: 11 July 2020 7 The Constrained RESTful Application Language (CoRAL) 8 draft-ietf-core-coral-02 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 and simple resource metadata. 18 Note to Readers 20 This note is to be removed before publishing as an RFC. 22 The issues list for this Internet-Draft can be found at 23 . 25 Companion material for this Internet-Draft can be found at 26 . 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on 11 July 2020. 45 Copyright Notice 47 Copyright (c) 2020 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 52 license-info) in effect on the date of publication of this document. 53 Please review these documents carefully, as they describe your rights 54 and restrictions with respect to this document. Code Components 55 extracted from this document must include Simplified BSD License text 56 as described in Section 4.e of the Trust Legal Provisions and are 57 provided without warranty as described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction 62 1.1. Data and Interaction Model 63 1.2. Serialization Formats 64 1.3. Notational Conventions 65 2. Data and Interaction Model 66 2.1. Browsing Context 67 2.2. Documents 68 2.3. Links 69 2.4. Forms 70 2.5. Form Fields 71 2.6. Navigation 72 2.7. History Traversal 73 3. Binary Format 74 3.1. Data Structure 75 3.1.1. Documents 76 3.1.2. Directives 77 3.1.3. IRIs 78 3.1.4. Links 79 3.1.5. Forms 80 3.1.6. Form Fields 81 3.2. Dictionary Compression 82 3.2.1. Dictionary References 83 3.2.2. Media Type Parameter 84 4. Textual Format 85 4.1. Lexical Structure 86 4.1.1. Line Terminators 87 4.1.2. White Space 88 4.1.3. Comments 89 4.1.4. Identifiers 90 4.1.5. Literals 91 4.1.6. Punctuators 92 4.2. Syntactic Structure 93 4.2.1. Documents 94 4.2.2. Directives 95 4.2.3. IRIs 96 4.2.4. Links 97 4.2.5. Forms 98 4.2.6. Form Fields 99 5. Document Semantics 100 5.1. Submitting Documents 101 5.1.1. PUT Requests 102 5.1.2. POST Requests 103 5.2. Returning Documents 104 5.2.1. Success Responses 105 5.2.2. Redirection Responses 106 5.2.3. Error Responses 107 6. Usage Considerations 108 6.1. Specifying CoRAL-based Applications 109 6.1.1. Application Interfaces 110 6.1.2. Resource Identifiers 111 6.1.3. Implementation Limits 112 6.2. Minting Vocabulary 113 6.3. Expressing Registered Link Relation Types 114 6.4. Expressing Simple RDF Statements 115 6.5. Expressing Natural Language Texts 116 6.6. Embedding Representations in CoRAL 117 6.7. Embedding CoRAL in CBOR Representations 118 7. Security Considerations 119 8. IANA Considerations 120 8.1. Media Type "application/coral+cbor" 121 8.2. Media Type "text/coral" 122 8.3. CoAP Content Formats 123 8.4. CBOR Tag 124 9. References 125 9.1. Normative References 126 9.2. Informative References 127 Appendix A. Core Vocabulary 128 A.1. Base 129 A.2. Collections 130 A.3. HTTP 131 A.4. CoAP 132 Appendix B. Default Dictionary 133 Appendix C. Change Log 134 Acknowledgements 135 Author's Address 137 1. Introduction 139 The Constrained RESTful Application Language (CoRAL) is a language 140 for the description of typed connections between resources on the Web 141 ("links"), possible operations on such resources ("forms"), and 142 simple resource metadata. 144 CoRAL is intended for driving automated software agents that navigate 145 a Web application based on a standardized vocabulary of link relation 146 types and operation types. It is designed to be used in conjunction 147 with a Web transfer protocol, such as the Hypertext Transfer Protocol 148 (HTTP) [RFC7230] or the Constrained Application Protocol (CoAP) 149 [RFC7252]. 151 This document defines the CoRAL data model and interaction model as 152 well as two specialized CoRAL serialization formats. 154 1.1. Data and Interaction Model 156 The data model derives from the Web Linking model of RFC 8288 157 [RFC8288] and primarily consists of two elements: "links" that 158 describe the relationship between two resources and the type of that 159 relationship; and "forms" that describe a possible operation on a 160 resource and the type of that operation. 162 Additionally, the data model can describe simple resource metadata in 163 similarly to statements in the Resource Description Framework (RDF) 164 [W3C.REC-rdf11-concepts-20140225]. In contrast to RDF, the focus of 165 CoRAL, however, is not on the description of a resource graph, but on 166 the discovery of possible future application states of a software 167 agent. 169 The interaction model derives from HTML [W3C.REC-html52-20171214] and 170 specifies how an automated software agent can change the application 171 state, i.e., navigate between resources by following links and 172 perform operations on resources by submitting forms. 174 1.2. Serialization Formats 176 The primary serialization format is a compact, binary encoding of 177 links and forms in Concise Binary Object Representation (CBOR) 178 [I-D.ietf-cbor-7049bis]. The format is intended for environments 179 with constraints on power, memory, and processing resources [RFC7228] 180 and shares many similarities with the message format of the 181 Constrained Application Protocol (CoAP) [RFC7252]. For example, it 182 uses numeric identifiers instead of verbose strings for link relation 183 types and operation types, and pre-parses Uniform Resource 184 Identifiers (URIs) [RFC3986] into (what CoAP considers to be) their 185 components, which considerably simplifies URI processing for 186 constrained nodes that already implement CoAP. As a result, link 187 serializations in CoRAL are often much more compact and easier to 188 process than equivalent serializations in CoRE Link Format [RFC6690]. 190 The secondary serialization format is a lightweight, textual encoding 191 of links and forms that is intended to be easy to read and to write 192 for humans. The format is loosely inspired by the syntax of Turtle 193 [W3C.REC-turtle-20140225] and is mainly intended for giving examples 194 with precise semantics. 196 1.3. Notational Conventions 198 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 199 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 200 "OPTIONAL" in this document are to be interpreted as described in BCP 201 14 [RFC2119] [RFC8174] when, and only when, they appear in all 202 capitals, as shown here. 204 Terms defined in this document appear in _cursive_ where they are 205 introduced. 207 2. Data and Interaction Model 209 The Constrained RESTful Application Language (CoRAL) is designed for 210 building Web-based applications [W3C.REC-webarch-20041215] in which 211 automated software agents navigate between resources by following 212 links and perform operations on resources by submitting forms. 214 2.1. Browsing Context 216 Borrowing from HTML 5 [W3C.REC-html52-20171214], each such agent 217 maintains a _browsing context_ in which the representations of Web 218 resources are processed. (In HTML, the browsing context typically 219 corresponds to a tab or window in a Web browser.) 221 At any time, one representation in a browsing context is designated 222 the _active_ representation. 224 2.2. Documents 226 A resource representation in one of the CoRAL serialization formats 227 is called a CoRAL _document_. The URI that was used to retrieve such 228 a document is called the document's _retrieval context_. 230 A CoRAL document consists of a list of zero or more links and forms, 231 collectively called _elements_. CoRAL serialization formats may 232 define additional types of elements for efficiency or convenience, 233 such as a base for relative URI references. 235 2.3. Links 237 A _link_ describes a relationship between two resources on the Web 238 [RFC8288]. As in RFC 8288, a link in CoRAL has a _link context_, a 239 _link relation type_, and a _link target_. However, in CoRAL, links 240 do not have target attributes. Instead, a link may have a list of 241 zero or more nested elements. These enable both the description of 242 resource metadata (which is done in RFC 8288 with target attributes) 243 and the chaining of links (which can be done in RFC 8288 by setting 244 the anchor of one link to the target of another). 246 A link can be viewed as a statement of the form "{link context} 247 has a {link relation type} resource at {link target}" where the 248 link target may be further described by nested elements. 250 The link relation type identifies the semantics of a link. While in 251 HTML and RFC 8288 these are typically denoted by an IANA-registered 252 name, such as "stylesheet" or "type", link relation types in CoRAL 253 are denoted by an Internationalized Resource Identifier (IRI) 254 [RFC3987], such as or . 256 This allows for the creation of new link relation types without the 257 risk of collisions when from different organizations or domains of 258 knowledge. IRIs can also lead to documentation, schema, and other 259 information about a link relation type. In CoRAL documents, these 260 IRIs are only used as identity tokens, though, and are compared with 261 Simple String Comparison as specified in Section 5.3.1 of RFC 3987. 263 The link context and the link target can be both either a URI, a 264 literal value, or an anonymous resource. If the scheme of a URI 265 indicates a Web transfer protocol such as HTTP or CoAP, an agent can 266 dereference the URI and navigate the browsing context to the link 267 target; this is called _following the link_. A literal value can be 268 either a Boolean value, an integer, a floating-point number, a date/ 269 time instant, a byte string, or a text string. An anonymous resource 270 is a resource which is not identified by a URI and is not a literal. 272 A link can occur as a top-level element in a document or as a nested 273 element within a link. When a link occurs as a top-level element, 274 the link context implicitly is the document's retrieval context. 275 When a link occurs nested within a link, the link context of the 276 inner link is the same resource as the link target of the outer link. 278 There are no restrictions on the cardinality of links; there can be 279 multiple links to and from a particular target, and multiple links of 280 the same or different types between a given link context and target. 281 However, the nested data structure constrains the description of a 282 resource graph to a tree: Links between linked resources can only be 283 described by further nesting links. 285 2.4. Forms 287 A _form_ provides instructions to an agent for performing an 288 operation on a Web resource. A form has a _form context_, an 289 _operation type_, a _request method_, and a _submission target_. 290 Additionally, a form may be accompanied by a list of zero or more 291 _form fields_. 293 A form can be viewed as an instruction of the form "To perform an 294 {operation type} operation on {form context}, make a {request 295 method} request to {submission target}" where the request may be 296 further described by form fields. 298 The operation type identifies the semantics of the operation. 299 Operation types are denoted (like link relation types) by an IRI. 301 Both the form context and the submission target are denoted by a URI. 302 The form context is the resource on which an operation is ultimately 303 performed. To perform the operation, an agent needs to construct a 304 request with the specified method and the specified submission target 305 as the request URI. Usually, the submission target is the same 306 resource as the form context, but it may be a different resource. 307 Constructing and sending the request is called _submitting the form_. 309 A form can occur as a top-level element in a document or as a nested 310 element within a link. When a form occurs as a top-level element, 311 the form context implicitly is the document's retrieval context. 312 When a form occurs nested within a link, the form context is the same 313 resource as the link target of the enclosing link. 315 2.5. Form Fields 317 Form fields can be used to provide more detailed instructions to 318 agents for constructing the request when submitting a form. For 319 example, form fields can instruct the agent to include a certain 320 payload or certain header fields in the request. Form fields might 321 describe a payload by identifying acceptable media types, referencing 322 a schema, or listing a number of data items that need to be included. 323 Form fields can be specific to the Web transfer protocol that is used 324 for submitting the form. 326 A form field is a pair of a _form field type_ and a _form field 327 value_. Additionally, a form field may have a list of zero or more 328 nested elements that further describe the form field value. 330 The form field type identifies the semantics of the form field. Form 331 field types are denoted (like link relation types and operation 332 types) by an IRI. 334 The form field value can be either a URI, a Boolean value, an 335 integer, a floating-point number, a date/time instant, a byte string, 336 a text string, or null. A null denotes the intentional absence of 337 any form field value. 339 2.6. Navigation 341 An agent begins interacting with an application by performing a GET 342 request on an _entry point URI_. The entry point URI is the only URI 343 that the agent is expected to know before interacting with the 344 application. From then on, the agent is expected to make all 345 requests by following links and submitting forms that are provided by 346 servers in responses. The entry point URI can be obtained through 347 some discovery process or manual configuration. 349 If dereferencing the entry point URI yields a CoRAL document (or any 350 other representation that implements the CoRAL data and interaction 351 model), then the agent makes this document the active representation 352 in the browsing context and proceeds as follows: 354 1. The first step for the agent is to decide what to do next, i.e., 355 which type of link to follow or type of form to submit, based on 356 the link relation types and operation types it knows. 358 2. The agent then finds the link(s) or form(s) with the respective 359 type in the active representation. This may yield one or more 360 candidates, from which the agent will have to select the most 361 appropriate one. The set of candidates can be empty, for 362 example, when a transition is not supported or not allowed. 364 3. The agent selects one of the candidates based on the order of 365 appearance in the document and the resource metadata associated 366 with them in the form of nested elements and form fields. 367 Examples for resource metadata include the indication of a 368 content type for the target resource representation, the URI 369 scheme of a link target, or the request method of a form. 371 4. The agent obtains the _request URI_ from the link target or 372 submission target. Link targets and submission targets may be 373 denoted by relative URI references, which need to be resolved to 374 obtain the request URI. Fragment identifiers are not part of the 375 request URI and MUST be separated from the rest of the URI prior 376 to the next step. 378 5. The agent constructs a new request with the request URI. If the 379 agent is following a link, then the request method MUST be GET. 380 If the agent is submitting a form, then the request method MUST 381 be the one indicated by the form. An IRI may need to be 382 converted to a URI (Section 3.1 of RFC 3987) for protocols that 383 do not support IRIs. 385 The agent should set HTTP header fields and CoAP request options 386 according to the nested elements of a link or form fields of a 387 form (e.g., set the HTTP Accept header field or the CoAP Accept 388 option when a media type for the target resource is provided). 389 Depending on the operation type of a form, the agent may also 390 have to include a request payload that matches the specifications 391 of some form fields. 393 6. The agent sends the request and receives the response. 395 7. If a fragment identifier was separated from the request URI, the 396 agent selects the fragment indicated by the fragment identifier 397 within the received representation. 399 8. The agent _updates the browsing context_ by making the (selected 400 fragment of the) received representation the active 401 representation. 403 9. Finally, the agent processes the representation according to the 404 semantics of its content type. If the representation is a CoRAL 405 document (or any other representation that implements the CoRAL 406 data and interaction model), the agent has the choice of what to 407 do next again -- and the cycle repeats. 409 2.7. History Traversal 411 Each browsing context has a _session history_ that lists the resource 412 representations that the agent has processed, is processing, or will 413 process. The maximum length of the session history is up for the 414 agent to decide and may be zero. 416 An entry in the session history consists of a resource representation 417 and the request URI that was used to retrieve the representation. 418 New entries are added to the session history as the agent navigates 419 from resource to resource. 421 In addition to following links and submitting forms, an agent can 422 decide tp navigate a browsing context by _traversing the session 423 history_. For example, when an agent receives a representation that 424 does not contain any further links or forms, it can set the active 425 representation back to one it has visited earlier. 427 Traversing the history should take advantage of caches to avoid new 428 requests. An agent MAY reissue a safe request (e.g., a GET request) 429 when it does not have a fresh representation in its cache. An agent 430 MUST NOT reissue an unsafe request (e.g., a PUT or a POST request) 431 unless it intends to perform that operation again. 433 3. Binary Format 435 This section defines the encoding of documents in the CoRAL binary 436 format. 438 A document in the binary format is encoded in Concise Binary Object 439 Representation (CBOR) [I-D.ietf-cbor-7049bis]. The encoding MUST 440 satisfy the Core Deterministic Encoding Requirements specified in 441 Section XX of RFC XXXX [I-D.ietf-cbor-7049bis]. 443 The CBOR structure of a document is presented in the Concise Data 444 Definition Language (CDDL) [RFC8610]. All CDDL rules not defined in 445 this document are defined in Appendix D of RFC 8610 [RFC8610]. 447 The media type of documents in the binary format is "application/ 448 coral+cbor". 450 3.1. Data Structure 452 The data structure of a document in the binary format is made up of 453 three kinds of elements: links, forms, and (as an extension to the 454 CoRAL data model) directives. Directives provide a way to encode URI 455 references with a common base more efficiently. 457 3.1.1. Documents 459 A document in the binary format is encoded as a CBOR array that 460 contains zero or more elements. An element is either a link, a form, 461 or a directive. 463 document = [*element] 465 element = link / form / directive 467 The elements are processed in the order they appear in the document. 468 Document processors need to maintain an _environment_ while iterating 469 an array of elements. The environment consists of two variables: the 470 _current context_ and the _current base_. Both the current context 471 and the current base are initially set to the document's retrieval 472 context. 474 3.1.2. Directives 476 Directives provide the ability to manipulate the environment while 477 processing elements. 479 There is a single type of directives available: the Base directive. 481 directive = base-directive 483 3.1.2.1. Base Directives 485 A Base directive is encoded as a CBOR array that contains the 486 unsigned integer 1 and a base URI. 488 base-directive = [1, baseURI] 490 The base URI is denoted by a Constrained Resource Identifier (CoRI) 491 reference [I-D.ietf-core-href]. The CoRI reference MUST be resolved 492 against the current context (not the current base). 494 baseURI = CoRI 496 CoRI = 498 The directive is processed by resolving the CoRI reference against 499 the current context and assigning the result to the current base. 501 3.1.3. IRIs 503 IRIs in links and forms are encoded as CoRI references. 505 IRI = CoRI 507 A CoRI reference is processed by resolving it to an IRI as specified 508 in Section XX of RFC XXXX [I-D.ietf-core-href] using the current 509 base. 511 3.1.4. Links 513 A link is encoded as a CBOR array that contains the unsigned integer 514 2, the link relation type, the link target, and, optionally, an array 515 of zero or more nested elements. 517 link = [2, relation-type, link-target, ?[*element]] 519 The link relation type is encoded as a text string that conforms to 520 the syntax of an IRI [RFC3987]. 522 relation-type = text 524 The link target is either an IRI, a literal value, or null. 526 link-target = IRI / literal / null 528 literal = bool / int / float / time / bytes / text 530 The nested elements, if any, MUST be processed in a fresh 531 environment. Both the current context and current base in this 532 environment are initially set to the link target of the enclosing 533 link. 535 3.1.5. Forms 537 A form is encoded as a CBOR array that contains the unsigned integer 538 3, the operation type, the submission target, and, optionally, an 539 array of zero or more form fields. 541 form = [3, operation-type, submission-target, ?[*form-field]] 543 The operation type is encoded as a text string that conforms to the 544 syntax of an IRI [RFC3987]. 546 operation-type = text 548 The submission target is an IRI. 550 submission-target = IRI 552 The request method is either implied by the operation type or encoded 553 as a form field. If both are given, the form field takes precedence 554 over the operation type. Either way, the method MUST be applicable 555 to the Web transfer protocol identified by the scheme of the 556 submission target. 558 The form fields, if any, MUST be processed in a fresh environment. 559 Both the current context and the current base in this environment are 560 initially set to the submission target of the enclosing form. 562 3.1.6. Form Fields 564 A form field is encoded as a CBOR sequence that consists of a form 565 field type, a form field value, and, optionally, an array of zero or 566 more nested elements. 568 form-field = (form-field-type, form-field-value, ?[*element]) 570 The form field type is encoded as a text string that conforms to the 571 syntax of an IRI [RFC3987]. 573 form-field-type = text 575 The form field value is either an IRI, a literal value, or null. 577 form-field-value = IRI / literal / null 579 The nested elements, if any, MUST be processed in a fresh 580 environment. Both the current context and current base in this 581 environment are initially set to the form field value of the 582 enclosing form field. 584 3.2. Dictionary Compression 586 A document in the binary format can reference values from an external 587 dictionary to reduce representation size and processing cost. 588 Dictionary references can be used in place of link relation types, 589 link targets, operation types, submission targets, form field types, 590 and form field values. 592 3.2.1. Dictionary References 594 A dictionary reference is encoded as an unsigned integer. Where a 595 dictionary reference cannot be expressed unambiguously, the unsigned 596 integer is tagged with CBOR tag TBD6, as follows: 598 relation-type /= uint 600 link-target /= #6.TBD6(uint) 602 operation-type /= uint 604 submission-target /= #6.TBD6(uint) 606 form-field-type /= uint 608 form-field-value /= #6.TBD6(uint) 610 A dictionary reference MUST NOT refer to a dictionary value that is 611 otherwise not allowed. For example, a dictionary reference that is 612 used in place of a link relation type is not allowed to refer to a 613 Boolean value. 615 3.2.2. Media Type Parameter 617 The "application/coral+cbor" media type for documents in the binary 618 format is defined to have a "dictionary" parameter that specifies the 619 dictionary in use. The dictionary is identified by a URI [RFC3986]. 620 For example, a CoRAL document that uses the dictionary identified by 621 the URI can use the following content 622 type: 624 application/coral+cbor;dictionary="http://example.com/dictionary" 626 The URI serves only as an identifier; it does not necessarily have to 627 be dereferencable (or even use a dereferencable URI scheme). It is 628 permissible, though, to use a dereferencable URI and to serve a 629 representation that provides information about the dictionary in a 630 machine- or human-readable way. (The representation format and 631 security considerations of such a representation are outside the 632 scope of this document.) 634 For simplicity, a CoRAL document can reference values only from one 635 dictionary; the value of the "dictionary" parameter MUST be a single 636 URI. The "dictionary" parameter is OPTIONAL. If it is absent, the 637 default dictionary specified in Appendix B of this document is 638 assumed. 640 Once a dictionary has made an assignment, the assignment MUST NOT be 641 changed or removed. A dictionary, however, may contain additional 642 information about an assignment, which may change over time. 644 In CoAP [RFC7252], media types (including specific values for their 645 parameters) are encoded as an unsigned integer called the "content 646 format" of a representation. For use with CoAP, each new CoRAL 647 dictionary therefore needs to have a new content format registered 648 with IANA in the CoAP Content-Formats Registry. 650 4. Textual Format 652 This section defines the syntax of documents in the CoRAL textual 653 format using two grammars: The lexical grammar defines how Unicode 654 characters are combined to form line terminators, white space, 655 comments, and tokens. The syntactic grammar defines how tokens are 656 combined to form documents. Both grammars are presented in Augmented 657 Backus-Naur Form (ABNF) [RFC5234]. 659 A document in the textual format is a Unicode string in a Unicode 660 encoding form [UNICODE]. The media type for such documents is "text/ 661 coral". The "charset" parameter of textual media types [RFC6657] is 662 not used; instead, charset information is transported inside the 663 document in the form of an OPTIONAL Byte Order Mark (BOM). The use 664 of the UTF-8 encoding scheme [RFC3629] without a BOM is RECOMMENDED. 666 4.1. Lexical Structure 668 The lexical structure of a document in the textual format is made up 669 of four basic elements: line terminators, white space, comments, and 670 tokens. Of these, only tokens are significant in the syntactic 671 grammar. There are three kinds of tokens: identifier tokens, literal 672 tokens, and punctuator tokens. 674 token = identifier / IRIref / boolean / integer / float 676 token =/ datetime / bytes / text / null / punctuator 678 When several lexical grammar rules match a sequence of characters in 679 a document, the longest match takes priority. 681 4.1.1. Line Terminators 683 Line terminators divide text into lines. A line terminator is any 684 Unicode character with Line_Break class BK, CR, LF, or NL. However, 685 any CR character that immediately precedes a LF character is ignored. 686 (This affects only the numbering of lines in error messages.) 688 4.1.2. White Space 690 White space is a sequence of one or more white space characters. A 691 white space character is any Unicode character with the White_Space 692 property. 694 4.1.3. Comments 696 Comments are sequences of characters that are ignored when parsing 697 text into tokens. Single-line comments begin with the characters 698 "//" and extend to the end of the line. Delimited comments begin 699 with the characters "/*" and end with the characters "*/". Delimited 700 comments can occupy a portion of a line, a single line, or multiple 701 lines. 703 Comments do not nest. The character sequences "/*" and "*/" have no 704 special meaning within a single-line comment; the character sequences 705 "//" and "/*" have no special meaning within a delimited comment. 707 4.1.4. Identifiers 709 An identifier token is a user-defined symbolic name. The rules for 710 identifiers correspond to those recommended by the Unicode Standard 711 Annex #31 [UAX31] with the following profile: 713 identifier = START *CONTINUE *(MEDIAL 1*CONTINUE) 715 START = 717 CONTINUE = 719 MEDIAL = "-" / "." / "~" / %x58A / %xF0B 721 MEDIAL =/ %x2010 / %x2027 / %x30A0 / %x30FB 723 All identifiers MUST be converted into Unicode Normalization Form C 724 (NFC), which is defined in Unicode Standard Annex #15 [UAX15]. 725 Comparison of identifiers is based on NFC and case-sensitive (unless 726 otherwise noted). 728 4.1.5. Literals 730 A literal token is a textual representation of a value. 732 4.1.5.1. IRI Reference Literals 734 IRI reference tokens denote references to resources on the Web. 736 An IRI reference literal consists of a Unicode string that conforms 737 to the syntax defined in RFC 3987 [RFC3987]. An IRI reference is 738 either an IRI or a relative reference. IRI references are enclosed 739 in angle brackets ("<" and ">"). 741 IRIref = "<" IRI-reference ">" 743 IRI-reference = 745 4.1.5.2. Boolean Literals 747 The case-insensitive tokens "true" and "false" denote the Boolean 748 values true and false, respectively. 750 boolean = "true" / "false" 752 4.1.5.3. Integer Literals 754 Integer literal tokens denote an integer value of unspecified 755 precision. By default, integer literals are expressed in decimal, 756 but they can also be specified in an alternate base using a prefix: 757 Binary literals begin with "0b", octal literals begin with "0o", and 758 hexadecimal literals begin with "0x". 760 Decimal literals contain the digits "0" through "9". Binary literals 761 contain "0" and "1", octal literals contain "0" through "7", and 762 hexadecimal literals contain "0" through "9" as well as "A" through 763 "F" in upper- or lowercase. 765 Negative integers are expressed by prepending a minus sign ("-"). 767 integer = ["+" / "-"] (decimal / binary / octal / hexadecimal) 769 decimal = 1*DIGIT 771 binary = %x30 (%x42 / %x62) 1*BINDIG 773 octal = %x30 (%x4F / %x6F) 1*OCTDIG 775 hexadecimal = %x30 (%x58 / %x78) 1*HEXDIG 777 DIGIT = %x30-39 779 BINDIG = %x30-31 781 OCTDIG = %x30-37 783 HEXDIG = %x30-39 / %x41-46 / %x61-66 785 4.1.5.4. Floating-point Literals 787 Floating-point literal tokens denote a floating-point number of 788 unspecified precision. 790 Floating-point literals consist of a sequence of decimal digits 791 followed by a fraction, an exponent, or both. The fraction consists 792 of a decimal point (".") followed by a sequence of decimal digits. 793 The exponent consists of the letter "e" in upper- or lowercase, 794 followed by an optional sign and a sequence of decimal digits that 795 indicate a power of 10 by which the value preceding the "e" is 796 multiplied. 798 Negative floating-point values are expressed by prepending a minus 799 sign ("-"). 801 float = ["+" / "-"] 1*DIGIT [fraction] [exponent] 803 fraction = "." 1*DIGIT 805 exponent = (%x45 / %x65) ["+" / "-"] 1*DIGIT 807 A floating-point literal can additionally denote either the special 808 "Not-a-Number" (NaN) value, positive infinity, or negative infinity. 809 The NaN value is produced by the case-insensitive token "NaN". The 810 two infinite values are produced by the case-insensitive tokens 811 "+Infinity" (or simply "Infinity") and "-Infinity". 813 float =/ "NaN" 815 float =/ ["+" / "-"] "Infinity" 817 4.1.5.5. Date/Time Literals 819 Date/time literal tokens denote an instant in time. 821 A date/time literal consists of the prefix "dt" and a sequence of 822 Unicode characters in Internet Date/Time Format [RFC3339], enclosed 823 in single quotes. 825 datetime = %x64.74 SQUOTE date-time SQUOTE 827 date-time = 829 SQUOTE = %x27 831 4.1.5.6. Byte String Literals 833 Byte string literal tokens denote an ordered sequence of bytes. 835 A byte string literal consists of a prefix and zero or more bytes 836 encoded in Base16, Base32, or Base64 [RFC4648], enclosed in single 837 quotes. Byte string literals encoded in Base16 begin with "h" or 838 "b16", byte string literals encoded in Base32 begin with "b32", and 839 byte string literals encoded in Base64 begin with "b64". 841 bytes = base16 / base32 / base64 843 base16 = (%x68 / %x62.31.36) SQUOTE SQUOTE 845 base32 = %x62.33.32 SQUOTE SQUOTE 847 base64 = %x62.36.34 SQUOTE SQUOTE 849 4.1.5.7. Text String Literals 851 Text string literal tokens denote a Unicode string. 853 A text string literal consists of zero or more Unicode characters 854 enclosed in double quotes. It can include simple escape sequences 855 (such as \t for the tab character) as well as hexadecimal and Unicode 856 escape sequences. 858 text = DQUOTE *(char / %x5C escape) DQUOTE 860 char = 862 escape = simple-escape / hexadecimal-escape / unicode-escape 864 simple-escape = %x30 / %x62 / %x74 / %x6E / %x76 866 simple-escape =/ %x66 / %x72 / %x22 / %x27 / %x5C 868 hexadecimal-escape = (%x78 / %x58) 2HEXDIG 870 unicode-escape = %x75 4HEXDIG / %x55 8HEXDIG 872 DQUOTE = %x22 874 An escape sequence denotes a single Unicode code point. For 875 hexadecimal and Unicode escape sequences, the code point is expressed 876 by the hexadecimal number following the "\x", "\X", "\u", or "\U" 877 prefix. Simple escape sequences indicate the code points listed in 878 Table 1. 880 +-----------------+------------+----------------------+ 881 | Escape Sequence | Code Point | Character Name | 882 +=================+============+======================+ 883 | \0 | U+0000 | Null | 884 +-----------------+------------+----------------------+ 885 | \b | U+0008 | Backspace | 886 +-----------------+------------+----------------------+ 887 | \t | U+0009 | Character Tabulation | 888 +-----------------+------------+----------------------+ 889 | \n | U+000A | Line Feed | 890 +-----------------+------------+----------------------+ 891 | \v | U+000B | Line Tabulation | 892 +-----------------+------------+----------------------+ 893 | \f | U+000C | Form Feed | 894 +-----------------+------------+----------------------+ 895 | \r | U+000D | Carriage Return | 896 +-----------------+------------+----------------------+ 897 | \" | U+0022 | Quotation Mark | 898 +-----------------+------------+----------------------+ 899 | \' | U+0027 | Apostrophe | 900 +-----------------+------------+----------------------+ 901 | \\ | U+005C | Reverse Solidus | 902 +-----------------+------------+----------------------+ 904 Table 1: Simple Escape Sequences 906 4.1.5.8. Null Literal 908 The case-insensitive tokens "null" and "_" denote the intentional 909 absence of any value. 911 null = "null" / "_" 913 4.1.6. Punctuators 915 Punctuator tokens are used for grouping and separating. 917 punctuator = "#" / ":" / "=" / "@" / "[" / "]" / "{" / "}" / "->" 919 4.2. Syntactic Structure 921 The syntactic structure of a document in the textual format is made 922 up of three kinds of elements: links, forms, and (as an extension to 923 the CoRAL data model) directives. Directives provide a way to make 924 documents easier to read and write by setting a base for relative IRI 925 references and introducing shorthands for IRIs. 927 4.2.1. Documents 929 A document in the textual format consists of a sequence of zero or 930 more elements. An element is either a link, a form, or a directive. 932 document = *element 934 element = link / form / directive 936 The elements are processed in the order they appear in the document. 937 Document processors need to maintain an _environment_ while iterating 938 a sequence of elements. The environment consists of three variables: 939 the _current context_, the _current base_, and the _current mapping 940 from identifiers to IRIs_. Both the current context and the current 941 base are initially set to the document's retrieval context. The 942 current mapping from identifiers to IRIs is initially empty. 944 4.2.2. Directives 946 Directives provide the ability to manipulate the environment while 947 processing elements. 949 All directives start with a number sign ("#") followed by an 950 identifier. The identifier is case-insensitive and restricted to 951 Unicode characters in the Basic Latin block. 953 The following two types of directives are available: the Base 954 directive and the Using directive. 956 directive = base-directive / using-directive 958 4.2.2.1. Base Directives 960 A Base directive consists of a number sign ("#"), followed by the 961 case-insensitive token "base", followed by a base IRI. 963 base-directive = "#" "base" baseIRI 965 The base IRI is denoted by an IRI reference. The IRI reference MUST 966 be resolved against the current context (not the current base). 968 baseIRI = IRIref 970 The directive is processed by resolving the IRI reference against the 971 current context and assigning the result to the current base. 973 4.2.2.2. Using Directives 975 A Using directive consists of a number sign ("#"), followed by the 976 case-insensitive token "using", optionally followed by an identifier 977 and an equals sign ("="), finally followed by an IRI. If the 978 identifier is not specified, it is assumed to be the empty string. 980 using-directive = "#" "using" [identifier "="] IRIref 982 The directive is processed by adding the specified identifier and IRI 983 to the current mapping from identifiers to IRIs. It is an error if 984 the identifier is already present in the mapping or if the IRI is not 985 an IRI but a relative reference. 987 4.2.3. IRIs 989 IRIs in links and forms can be either denoted by an IRI reference or 990 looked up from a mapping from identifiers to IRIs using names. There 991 are three kinds of names: simple names, qualified names, and 992 predefined names. 994 IRI = IRIref / simple-name / qualified-name / predefined-name 996 Both IRI references and names are processed by resolving them to an 997 IRI, as described in the following sub-sections. 999 4.2.3.1. IRI References 1001 An IRI reference is resolved to an IRI as specified in Section 6.5 of 1002 RFC 3987 [RFC3987] using the current base. 1004 4.2.3.2. Simple Names 1006 A simple name consists of an identifier. 1008 simple-name = identifier 1010 A simple name is resolved to an IRI by looking up the empty string in 1011 the current mapping from identifiers to IRIs and appending the given 1012 identifier to the result. It is an error if the empty string is not 1013 present in the mapping. 1015 4.2.3.3. Qualified Names 1017 A qualified name consists of two identifiers separated by a colon 1018 (":"). 1020 qualified-name = identifier ":" identifier 1022 A qualified name is resolved to an IRI by looking up the identifier 1023 given on the left hand side in the current mapping from identifiers 1024 to IRIs. The identifier given on the right hand side is appended to 1025 the result. It is an error if the identifier on the left hand side 1026 is not present in the mapping. 1028 4.2.3.4. Predefined Names 1030 A predefined name consists of a commercial at sign ("@") followed by 1031 an identifier. The identifier is case-insensitive and restricted to 1032 Unicode characters in the Basic Latin block. 1034 predefined-name = "@" identifier 1036 A predefined name is resolved to an IRI by looking up the identifier 1037 in Table 2. It is an error if the identifier is not present in the 1038 table. 1040 +------------+--------------------------------------+ 1041 | Identifier | IRI | 1042 +============+======================================+ 1043 | direction | | 1044 +------------+--------------------------------------+ 1045 | language | | 1046 +------------+--------------------------------------+ 1048 Table 2: Predefined Names 1050 4.2.4. Links 1052 A link consists of the link relation type, followed by the link 1053 target, optionally followed by a sequence of zero or more nested 1054 elements enclosed in curly brackets ("{" and "}"). 1056 link = relation-type link-target ["{" *element "}"] 1058 The link relation type is an IRI. 1060 relation-type = IRI 1062 The link target is either an IRI, a literal value, or null. 1064 link-target = IRI / literal / null 1066 literal = boolean / integer / float / datetime / bytes / text 1068 The nested elements, if any, MUST be processed in a fresh 1069 environment. Both the current context and current base in this 1070 environment are initially set to the link target of the enclosing 1071 link. The mapping from identifiers to IRIs is initially set to a 1072 copy of the mapping from identifiers to IRIs in the current 1073 environment. 1075 4.2.5. Forms 1077 A form consists of the operation type, followed by a "->" token and 1078 the submission target, optionally followed by a sequence of zero or 1079 more form fields enclosed in square brackets ("[" and "]"). 1081 form = operation-type "->" submission-target ["[" *form-field "]"] 1083 The operation type is an IRI. 1085 operation-type = IRI 1087 The submission target is an IRI. 1089 submission-target = IRI 1091 The request method is either implied by the operation type or encoded 1092 as a form field. If both are given, the form field takes precedence 1093 over the operation type. Either way, the method MUST be applicable 1094 to the Web transfer protocol identified by the scheme of the 1095 submission target. 1097 The form fields, if any, MUST be processed in a fresh environment. 1098 Both the current context and the current base in this environment are 1099 initially set to the submission target of the enclosing form. The 1100 mapping from identifiers to IRIs is initially set to a copy of the 1101 mapping from identifiers to IRIs in the current environment. 1103 4.2.6. Form Fields 1105 A form field consists of a form field type, followed by a form field 1106 value, optionally followed by a sequence of zero or more nested 1107 elements enclosed in curly brackets ("{" and "}"). 1109 form-field = form-field-type form-field-value ["{" *element "}"] 1111 The form field type is an IRI. 1113 form-field-type = IRI 1115 The form field value is either an IRI, a literal value, or null. 1117 form-field-value = IRI / literal / null 1119 The nested elements, if any, MUST be processed in a fresh 1120 environment. Both the current context and current base in this 1121 environment are initially set to the form field value of the 1122 enclosing form field. The mapping from identifiers to IRIs is 1123 initially set to a copy of the mapping from identifiers to IRIs in 1124 the current environment. 1126 5. Document Semantics 1128 5.1. Submitting Documents 1130 By default, a CoRAL document is a representation that captures the 1131 current state of a resource. The meaning of a CoRAL document changes 1132 when it is submitted in a request. Depending on the request method, 1133 the CoRAL document can capture the intended state of a resource (PUT) 1134 or be subject to application-specific processing (POST). 1136 5.1.1. PUT Requests 1138 A PUT request with a CoRAL document enclosed in the request payload 1139 requests that the state of the target resource be created or replaced 1140 with the state described by the CoRAL document. A successful PUT of 1141 a CoRAL document generally means that a subsequent GET on that same 1142 target resource would result in an equivalent document being sent in 1143 a success response. 1145 An origin server SHOULD verify that a submitted CoRAL document is 1146 consistent with any constraints the server has for the target 1147 resource. When a document is inconsistent with the target resource, 1148 the origin server SHOULD either make it consistent (e.g., by removing 1149 inconsistent elements) or respond with an appropriate error message 1150 containing sufficient information to explain why the document is 1151 unsuitable. 1153 The retrieval context and the base URI of a CoRAL document in a PUT 1154 are the request URI of the request. 1156 5.1.2. POST Requests 1158 A POST request with a CoRAL document enclosed in the request payload 1159 requests that the target resource process the CoRAL document 1160 according to the resource's own specific semantics. 1162 The retrieval context of a CoRAL document in a POST is defined by the 1163 target resource's processing semantics; it can be an unspecified URI. 1164 The base URI of the document is the request URI of the request. 1166 5.2. Returning Documents 1168 In a response, the meaning of a CoRAL document changes depending on 1169 the request method and the response status code. For example, a 1170 CoRAL document in a successful response to a GET represents the 1171 current state of the target resource, whereas a CoRAL document in a 1172 successful response to a POST might represent either the processing 1173 result or the new resource state. A CoRAL document in an error 1174 response represents the error condition, usually describing the error 1175 state and what next steps are suggested for resolving it. 1177 5.2.1. Success Responses 1179 Success responses have a response status code that indicates that the 1180 client's request was successfully received, understood, and accepted 1181 (2xx in HTTP, 2.xx in CoAP). When the representation in a success 1182 response does not describe the state of the target resource, it 1183 describes result of processing the request. For example, when a 1184 request has been fulfilled and has resulted in one or more new 1185 resources being created, a CoRAL document in the response can link to 1186 and describe the resource(s) created. 1188 The retrieval context and the base URI of a CoRAL document 1189 representing the current state of a resource are the request URI of 1190 the request. 1192 The retrieval context of a CoRAL document representing a processing 1193 result is an unspecified URI that refers to the processing result 1194 itself. The base URI of the document is the request URI of the 1195 request. 1197 5.2.2. Redirection Responses 1199 Redirection responses have a response status code that indicates that 1200 further action needs to be taken by the agent (3xx in HTTP). A 1201 redirection response, for example, might indicate that the target 1202 resource is available at a different URI or the server offers a 1203 choice of multiple matching resources, each with its own specific 1204 URI. 1206 In the latter case, the representation in the response might contain 1207 a list of resource metadata and URI references (i.e., links) from 1208 which the agent can choose the most preferred one. 1210 The retrieval context of a CoRAL document representing such multiple 1211 choices in a redirection response is an unspecified URI that refers 1212 to the redirection itself. The base URI of the document is the 1213 request URI of the request. 1215 5.2.3. Error Responses 1217 Error response have a response status code that indicates that either 1218 the request cannot be fulfilled or the server failed to fulfill an 1219 apparently valid request (4xx or 5xx in HTTP, 4.xx or 5.xx in CoAP). 1220 A representation in an error response describes the error condition. 1222 The retrieval context of a CoRAL document representing such an error 1223 condition is an unspecified URI that refers to the error condition 1224 itself. The base URI of the document is the request URI of the 1225 request. 1227 6. Usage Considerations 1229 This section discusses some considerations in creating CoRAL-based 1230 applications and vocabularies. 1232 6.1. Specifying CoRAL-based Applications 1234 CoRAL-based applications naturally implement the Web architecture 1235 [W3C.REC-webarch-20041215] and thus are centered around orthogonal 1236 specifications for identification, interaction, and representation: 1238 * Resources are identified by IRIs or represented by literal values. 1240 * Interactions are based on the hypermedia interaction model of the 1241 Web and the methods provided by the Web transfer protocol. The 1242 semantics of possible interactions are identified by link relation 1243 types and operation types. 1245 * Representations are CoRAL documents encoded in the binary format 1246 defined in Section 3 or the textual format defined in Section 4. 1247 Depending on the application, additional representation formats 1248 may be used. 1250 6.1.1. Application Interfaces 1252 Specifications for CoRAL-based applications need to list the specific 1253 components used in the application interface and their identifiers. 1254 This should include the following items: 1256 * The Web transfer protocols supported. 1258 * The representation formats used, identified by their Internet 1259 media types, including the CoRAL serialization formats. 1261 * The link relation types used. 1263 * The operation types used. Additionally, for each operation type, 1264 the permissible request methods. 1266 * The form field types used. Additionally, for each form field 1267 type, the permissible form field values. 1269 6.1.2. Resource Identifiers 1271 URIs [RFC3986] are a cornerstone of Web-based applications. They 1272 enable the uniform identification of resources and are used every 1273 time a client interacts with a server or a resource representation 1274 needs to refer to another resource. 1276 URIs often include structured application data in the path and query 1277 components, such as paths in a filesystem or keys in a database. It 1278 is a common practice in HTTP-based application programming interfaces 1279 (APIs) to make this part of the application specification, i.e., to 1280 prescribe fixed URI templates that are hard-coded in implementations. 1281 However, there are a number of problems with this practice 1282 [I-D.nottingham-rfc7320bis]. 1284 In CoRAL-based applications, resource names are therefore not part of 1285 the application specification -- they are an implementation detail. 1286 The specification of a CoRAL-based application MUST NOT mandate any 1287 particular form of resource name structure. 1289 BCP 190 [I-D.nottingham-rfc7320bis] describes the problematic 1290 practice of fixed URI structures in more detail and provides some 1291 acceptable alternatives. 1293 6.1.3. Implementation Limits 1295 This document places no restrictions on the number of elements in a 1296 CoRAL document or the depth of nested elements. Applications using 1297 CoRAL (in particular those running in constrained environments) may 1298 limit these numbers and give specific implementation limits that an 1299 application implementation must at least support to be interoperable. 1301 Applications may also mandate the following and other restrictions: 1303 * Use of only either the binary format or the text format. 1305 * Use of only either HTTP or CoAP as the supported Web transfer 1306 protocol. 1308 * Use of only dictionary references in the binary format for certain 1309 vocabulary. 1311 * Use of URI references and CoRI references only up to a specific 1312 length. 1314 6.2. Minting Vocabulary 1316 New link relation types, operation types, and form field types can be 1317 minted by defining an IRI [RFC3987] that uniquely identifies the 1318 item. Although the IRI can point to a resource that contains a 1319 definition of the semantics, clients SHOULD NOT automatically access 1320 that resource to avoid overburdening its server. The IRI SHOULD be 1321 under the control of the person or party defining it, or be delegated 1322 to them. 1324 To avoid interoperability problems, it is RECOMMENDED that only IRIs 1325 are minted that are normalized according to Section 5.3 of RFC 3987. 1326 Non-normalized forms that are best avoided include: 1328 * Uppercase characters in scheme names and domain names 1330 * Percent-encoding of characters where it is not required by the IRI 1331 syntax 1333 * Explicitly stated HTTP default port (e.g., 1334 is preferable over ) 1336 * Completely empty path in HTTP IRIs (e.g., is 1337 preferable over ) 1339 * Dot segments ("/./" or "/../") in the path component of an IRI 1341 * Lowercase hexadecimal letters within percent-encoding triplets 1342 (e.g., "%3F" is preferable over "%3f") 1344 * Punycode-encoding of Internationalized Domain Names in IRIs 1346 * IRIs that are not in Unicode Normalization Form C [UAX15] 1348 IRIs that identify vocabulary do not need to be registered. The 1349 inclusion of domain names in IRIs allows for the decentralized 1350 creation of new IRIs without the risk of collisions. 1352 However, IRIs can be relatively verbose and impose a high overhead on 1353 a representation. This can be a problem in constrained environments 1354 [RFC7228]. Therefore, CoRAL alternatively allows the use of unsigned 1355 integers to reference CBOR data items from a dictionary, as specified 1356 in Section 3.2. These impose a much smaller overhead but instead 1357 need to be assigned by an authority to avoid collisions. 1359 6.3. Expressing Registered Link Relation Types 1361 Link relation types registered in the IANA Link Relations Registry, 1362 such as "collection" [RFC6573] or "icon" [W3C.REC-html52-20171214], 1363 can be used in CoRAL by appending the registered name to the IRI 1364 : 1366 #using iana = 1368 iana:collection 1369 iana:icon 1371 The convention of appending the relation type name to the prefix 1372 "http://www.iana.org/assignments/relation/" to form IRIs is adopted 1373 from Atom [RFC4287]; see also Appendix A.2 of RFC 8288 [RFC8288]. 1375 Note that registered relation type names are required to be lowercase 1376 ASCII letters (Section 3.3 of RFC 8288). 1378 6.4. Expressing Simple RDF Statements 1380 An RDF statement [W3C.REC-rdf11-concepts-20140225] says that some 1381 relationship, indicated by a predicate, holds between two resources. 1382 Existing RDF vocabularies can therefore be good source for link 1383 relation types that describe resource metadata. For example, a CoRAL 1384 document could use the FOAF vocabulary [FOAF] to describe the person 1385 or software that made it: 1387 #using rdf = 1388 #using foaf = 1390 foaf:maker null { 1391 rdf:type 1392 foaf:familyName "Hartke" 1393 foaf:givenName "Klaus" 1394 foaf:mbox 1395 } 1397 6.5. Expressing Natural Language Texts 1399 Text strings that are the target of a link can be associated with a 1400 language tag [RFC5646] and a base text direction (i.e., right-to-left 1401 or left-to-right) by nesting links of type and under that 1403 link, respectively: 1405 #using 1406 #using iana = 1408 iana:terms-of-service { 1409 title "Nutzungsbedingungen" { 1410 language "de" 1411 direction "ltr" 1412 } 1413 title "Terms of use" { 1414 language "en-US" 1415 direction "ltr" 1416 } 1417 } 1419 The link relation types and 1420 are defined in Appendix A. 1422 6.6. Embedding Representations in CoRAL 1424 When a document links to many Web resources and an agent needs a 1425 representation of each of them, it can be inefficient to retrieve 1426 each representations individually. To minimize round-trips, 1427 documents can embed representations of resources. 1429 A representation can be embedded in a document by including a link of 1430 type : 1432 #using 1433 #using http = 1434 #using iana = 1436 iana:icon { 1437 representation 1438 b64'R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAIAOw==' { 1439 http:type "image/gif" 1440 } 1441 } 1443 An embedded representation should have a nested link of type 1444 or 1445 that indicates the content type of the representation. 1447 The link relation types , 1448 , and 1449 are defined in Appendix A. 1451 6.7. Embedding CoRAL in CBOR Representations 1453 Data items in the CoRAL binary format (Section 3) may be embedded in 1454 other CBOR structures [I-D.ietf-cbor-7049bis]. Specifications using 1455 CDDL [RFC8610] can reference the following CDDL definitions for this 1456 purpose: 1458 CoRAL-Document = document 1460 CoRAL-Link = link 1462 CoRAL-Form = form 1464 For each embedded document, link, and form, the specification for the 1465 embedding CBOR structure needs to specify the document retrieval 1466 context, the link context, and the form context, respectively. 1468 7. Security Considerations 1470 CoRAL document processors need to be fully prepared for all types of 1471 hostile input that may be designed to corrupt, overrun, or achieve 1472 control of the agent processing the document. For example, hostile 1473 input may be constructed to overrun buffers, allocate very big data 1474 structures, or exhaust the stack depth by setting up deeply nested 1475 elements. Processors need to have appropriate resource management to 1476 mitigate these attacks. 1478 CoRAL serialization formats intentionally do not feature the 1479 equivalent of XML entity references so as to preclude the entire 1480 class of attacks relating to them, such as exponential XML entity 1481 expansion ("billion laughs") [CAPEC-197] and malicious XML entity 1482 linking [CAPEC-201]. 1484 Implementers of the CoRAL binary format need to consider the security 1485 aspects of decoding CBOR. See Section XX of RFC XXXX 1486 [I-D.ietf-cbor-7049bis] for security considerations relating to CBOR. 1487 In particular, different number encodings for the same numeric value 1488 are not equivalent in CoRAL (e.g., a floating-point value of 0.0 is 1489 not the same as the integer 0). 1491 Implementers of the CoRAL textual format need to consider the 1492 security aspects of handling Unicode input. See Unicode Technical 1493 Report #36 [UTR36] for security considerations relating to visual 1494 spoofing and misuse of character encodings. See Section 10 of RFC 1495 3629 [RFC3629] for security considerations relating to UTF-8. See 1496 Unicode Technical Standard #39 [UTS39] for security mechanisms that 1497 can be used to detect possible security problems relating to Unicode. 1499 CoRAL makes extensive use of resource identifiers. See Section 7 of 1500 RFC 3986 [RFC3986] for security considerations relating to URIs. See 1501 Section 8 of RFC 3987 [RFC3987] for security considerations relating 1502 to IRIs. See Section XX of RFC XXXX [I-D.ietf-core-href] for 1503 security considerations relating to CoRIs. 1505 The security of applications using CoRAL can depend on the proper 1506 preparation and comparison of internationalized strings. For 1507 example, such strings can be used to make authentication and 1508 authorization decisions, and the security of an application could be 1509 compromised if an entity providing a given string is connected to the 1510 wrong account or online resource based on different interpretations 1511 of the string. See RFC 6943 [RFC6943] for security considerations 1512 relating to identifiers in IRIs and other strings. 1514 CoRAL is intended to be used in conjunction with a Web transfer 1515 protocol like HTTP or CoAP. See Section 9 of RFC 7230 [RFC7230], 1516 Section 9 of RFC 7231 [RFC7231], etc., for security considerations 1517 relating to HTTP. See Section 11 of RFC 7252 [RFC7252] for security 1518 considerations relating to CoAP. 1520 CoRAL does not define any specific mechanisms for protecting the 1521 confidentiality and integrity of CoRAL documents. It relies on 1522 security mechanisms on the application layer or transport layer for 1523 this, such as Transport Layer Security (TLS) [RFC8446]. 1525 CoRAL documents and the structure of a web of resources revealed from 1526 automatically following links can disclose personal information and 1527 other sensitive information. Implementations need to prevent the 1528 unintentional disclosure of such information. See Section 9 of RFC 1529 7231 [RFC7231] for additional considerations. 1531 Applications using CoRAL ought to consider the attack vectors opened 1532 by automatically following, trusting, or otherwise using links and 1533 forms in CoRAL documents. See Section 5 of RFC 8288 [RFC8288] for 1534 related considerations. 1536 In particular, when a CoRAL document is the representation of a 1537 resource, the server that is authoritative for that resource may not 1538 necessarily be authoritative for nested elements in the document. In 1539 this case, unless an application defines specific rules, any link or 1540 form where the link/form context and the document's retrieval context 1541 do not share the same Web origin [RFC6454] should be discarded 1542 ("same-origin policy"). 1544 8. IANA Considerations 1546 8.1. Media Type "application/coral+cbor" 1548 This document registers the media type "application/coral+cbor" 1549 according to the procedures of BCP 13 [RFC6838]. 1551 Type name: 1552 application 1554 Subtype name: 1555 coral+cbor 1557 Required parameters: 1558 N/A 1560 Optional parameters: 1561 dictionary - See Section 3.2 of [I-D.ietf-core-coral]. 1563 Encoding considerations: 1564 binary - See Section 3 of [I-D.ietf-core-coral]. 1566 Security considerations: 1567 See Section 7 of [I-D.ietf-core-coral]. 1569 Interoperability considerations: 1570 N/A 1572 Published specification: 1573 [I-D.ietf-core-coral] 1575 Applications that use this media type: 1576 See Section 1 of [I-D.ietf-core-coral]. 1578 Fragment identifier considerations: 1579 As specified for "application/cbor". 1581 Additional information: 1582 Deprecated alias names for this type: N/A 1584 Magic number(s): N/A 1586 File extension(s): .coral.cbor 1588 Macintosh file type code(s): N/A 1590 Person & email address to contact for further information: 1591 See the Author's Address section of [I-D.ietf-core-coral]. 1593 Intended usage: 1594 COMMON 1596 Restrictions on usage: 1597 N/A 1599 Author: 1600 See the Author's Address section of [I-D.ietf-core-coral]. 1602 Change controller: 1603 IESG 1605 Provisional registration? 1606 No 1608 8.2. Media Type "text/coral" 1610 This document registers the media type "text/coral" according to the 1611 procedures of BCP 13 [RFC6838] and guidelines of RFC 6657 [RFC6657]. 1613 Type name: 1614 text 1616 Subtype name: 1617 coral 1619 Required parameters: 1620 N/A 1622 Optional parameters: 1623 N/A 1625 Encoding considerations: 1626 binary - See Section 4 of [I-D.ietf-core-coral]. 1628 Security considerations: 1629 See Section 7 of [I-D.ietf-core-coral]. 1631 Interoperability considerations: 1632 N/A 1634 Published specification: 1635 [I-D.ietf-core-coral] 1637 Applications that use this media type: 1638 See Section 1 of [I-D.ietf-core-coral]. 1640 Fragment identifier considerations: 1641 N/A 1643 Additional information: 1644 Deprecated alias names for this type: N/A 1646 Magic number(s): N/A 1648 File extension(s): .coral 1650 Macintosh file type code(s): N/A 1652 Person & email address to contact for further information: 1653 See the Author's Address section of [I-D.ietf-core-coral]. 1655 Intended usage: 1656 COMMON 1658 Restrictions on usage: 1659 N/A 1661 Author: 1662 See the Author's Address section of [I-D.ietf-core-coral]. 1664 Change controller: 1665 IESG 1667 Provisional registration? 1668 No 1670 8.3. CoAP Content Formats 1672 This document registers CoAP content formats for the content types 1673 "application/coral+cbor" and "text/coral" according to the procedures 1674 of RFC 7252 [RFC7252]. 1676 * Content Type: application/coral+cbor 1677 Content Coding: identity 1678 ID: TBD3 1679 Reference: [I-D.ietf-core-coral] 1681 * Content Type: text/coral 1682 Content Coding: identity 1683 ID: TBD4 1684 Reference: [I-D.ietf-core-coral] 1686 [[NOTE TO RFC EDITOR: Please replace all occurrences of "TBD3" and 1687 "TBD4" in this document with the code points assigned by IANA.]] 1689 [[NOTE TO IMPLEMENTERS: Experimental implementations can use content 1690 format ID 65087 for "application/coral+cbor" and content format ID 1691 65343 for "text/coral" until IANA has assigned code points.]] 1693 8.4. CBOR Tag 1695 This document registers a CBOR tag for dictionary references 1696 according to the procedures of RFC XXXX [I-D.ietf-cbor-7049bis]. 1698 * Tag: TBD6 1699 Data Item: unsigned integer 1700 Semantics: Dictionary reference 1701 Reference: [I-D.ietf-core-coral] 1703 [[NOTE TO RFC EDITOR: Please replace all occurrences of "TBD6" in 1704 this document with the code point assigned by IANA.]] 1706 9. References 1708 9.1. Normative References 1710 [I-D.ietf-cbor-7049bis] 1711 Bormann, C. and P. Hoffman, "Concise Binary Object 1712 Representation (CBOR)", Work in Progress, Internet-Draft, 1713 draft-ietf-cbor-7049bis-12, 18 December 2019, 1714 . 1716 [I-D.ietf-core-href] 1717 Hartke, K., "Constrained Resource Identifiers", Work in 1718 Progress, Internet-Draft, draft-ietf-core-href-02, 8 1719 January 2020, 1720 . 1722 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1723 Requirement Levels", BCP 14, RFC 2119, 1724 DOI 10.17487/RFC2119, March 1997, 1725 . 1727 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1728 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1729 . 1731 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1732 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1733 2003, . 1735 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1736 Resource Identifier (URI): Generic Syntax", STD 66, 1737 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1738 . 1740 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1741 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 1742 January 2005, . 1744 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1745 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1746 . 1748 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1749 Specifications: ABNF", STD 68, RFC 5234, 1750 DOI 10.17487/RFC5234, January 2008, 1751 . 1753 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1754 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1755 September 2009, . 1757 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1758 DOI 10.17487/RFC6454, December 2011, 1759 . 1761 [RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding 1762 "charset" Parameter Handling in Textual Media Types", 1763 RFC 6657, DOI 10.17487/RFC6657, July 2012, 1764 . 1766 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1767 Specifications and Registration Procedures", BCP 13, 1768 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1769 . 1771 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1772 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1773 May 2017, . 1775 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1776 Definition Language (CDDL): A Notational Convention to 1777 Express Concise Binary Object Representation (CBOR) and 1778 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1779 June 2019, . 1781 [UAX15] The Unicode Consortium, "Unicode Standard Annex #15: 1782 Unicode Normalization Forms", 1783 . 1785 [UAX31] The Unicode Consortium, "Unicode Standard Annex #31: 1786 Unicode Identifier and Pattern Syntax", 1787 . 1789 [UNICODE] The Unicode Consortium, "The Unicode Standard", 1790 . Note that this 1791 reference is to the latest version of Unicode, rather than 1792 to a specific release. It is not expected that future 1793 changes in the Unicode specification will have any impact 1794 on this document. 1796 9.2. Informative References 1798 [CAPEC-197] 1799 MITRE, "CAPEC-197: XML Entity Expansion", 30 September 1800 2019, . 1802 [CAPEC-201] 1803 MITRE, "CAPEC-201: XML Entity Linking", 30 September 2019, 1804 . 1806 [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification 1807 0.99", 14 January 2014, 1808 . 1810 [HAL] Kelly, M., "JSON Hypertext Application Language", Work in 1811 Progress, Internet-Draft, draft-kelly-json-hal-08, 12 May 1812 2016, 1813 . 1815 [I-D.nottingham-rfc7320bis] 1816 Nottingham, M., "URI Design and Ownership", Work in 1817 Progress, Internet-Draft, draft-nottingham-rfc7320bis-03, 1818 5 January 2020, . 1821 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1822 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 1823 December 2005, . 1825 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1826 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1827 . 1829 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 1830 RFC 6573, DOI 10.17487/RFC6573, April 2012, 1831 . 1833 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1834 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1835 . 1837 [RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for 1838 Security Purposes", RFC 6943, DOI 10.17487/RFC6943, May 1839 2013, . 1841 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1842 Constrained-Node Networks", RFC 7228, 1843 DOI 10.17487/RFC7228, May 2014, 1844 . 1846 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1847 Protocol (HTTP/1.1): Message Syntax and Routing", 1848 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1849 . 1851 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1852 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1853 DOI 10.17487/RFC7231, June 2014, 1854 . 1856 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1857 Application Protocol (CoAP)", RFC 7252, 1858 DOI 10.17487/RFC7252, June 2014, 1859 . 1861 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1862 FETCH Methods for the Constrained Application Protocol 1863 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1864 . 1866 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1867 DOI 10.17487/RFC8288, October 2017, 1868 . 1870 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1871 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1872 . 1874 [UTR36] The Unicode Consortium, "Unicode Technical Report #36: 1875 Unicode Security Considerations", 1876 . 1878 [UTS39] The Unicode Consortium, "Unicode Technical Standard #39: 1879 Unicode Security Mechanisms", 1880 . 1882 [W3C.REC-html52-20171214] 1883 Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and 1884 S. Moon, "HTML 5.2", World Wide Web Consortium 1885 Recommendation REC-html52-20171214, 14 December 2017, 1886 . 1888 [W3C.REC-rdf-schema-20140225] 1889 Brickley, D. and R. Guha, "RDF Schema 1.1", World Wide Web 1890 Consortium Recommendation REC-rdf-schema-20140225, 25 1891 February 2014, 1892 . 1894 [W3C.REC-rdf11-concepts-20140225] 1895 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 1896 Concepts and Abstract Syntax", World Wide Web Consortium 1897 Recommendation REC-rdf11-concepts-20140225, 25 February 1898 2014, 1899 . 1901 [W3C.REC-turtle-20140225] 1902 Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", 1903 World Wide Web Consortium Recommendation REC-turtle- 1904 20140225, 25 February 2014, 1905 . 1907 [W3C.REC-webarch-20041215] 1908 Jacobs, I. and N. Walsh, "Architecture of the World Wide 1909 Web, Volume One", World Wide Web Consortium 1910 Recommendation REC-webarch-20041215, 15 December 2004, 1911 . 1913 Appendix A. Core Vocabulary 1915 This section defines the core vocabulary for CoRAL: a set of link 1916 relation types, operation types, and form field types. 1918 A.1. Base 1920 Link Relation Types: 1922 1923 Indicates that the link's context is an instance of the class 1924 specified as the link's target, as defined by RDF Schema 1925 [W3C.REC-rdf-schema-20140225]. 1927 1928 Indicates that the link target is a human-readable label (e.g., a 1929 menu entry). 1931 The link target MUST be a text string. The text string SHOULD be 1932 annotated with a language and text direction using nested links of 1933 type and , respectively. 1936 1937 Indicates that the link target is a language tag [RFC5646] that 1938 specifies the language of the link context. 1940 The link target MUST be a text string in the format specified in 1941 Section 2.1 of RFC 5646 [RFC5646]. 1943 1944 Indicates that the link target is a base text direction (right-to- 1945 left or left-to-right) that specifies the text directionality of 1946 the link context. 1948 The link target MUST be either the text string "rtl" or the text 1949 string "ltr". 1951 1952 Indicates that the link target is a representation of the link 1953 context. 1955 The link target MUST be a byte string. 1957 The representation may be a full, partial, or inconsistent version 1958 of the representation served from the URI of the resource. 1960 A link with link relation type can occur as a top-level element in 1961 a document or as a nested element within a link. When it occurs 1962 as a top-level element, it provides an alternate representation of 1963 the document's retrieval context. When it occurs nested within a 1964 link, it provides a representation of link target of the enclosing 1965 link. 1967 Operation Types: 1969 1970 Indicates that the state of the form's context can be replaced 1971 with the state described by a representation submitted to the 1972 server. 1974 This operation type defaults to the PUT method [RFC7231] [RFC7252] 1975 for both HTTP and CoAP. Typical overrides by a form field include 1976 the PATCH method [RFC5789] [RFC8132] for HTTP and CoAP and the 1977 iPATCH method [RFC8132] for CoAP. 1979 1980 Indicates that the form's context can be searched by submitting a 1981 search query. 1983 This operation type defaults to the POST method [RFC7231] for HTTP 1984 and the FETCH method [RFC8132] for CoAP. Typical overrides by a 1985 form field include the POST method [RFC7252] for CoAP. 1987 A.2. Collections 1989 Link Relation Types: 1991 1992 Indicates that the link's context is a collection and that the 1993 link's target is a member of that collection, as defined in 1994 Section 2.1 of RFC 6573 [RFC6573]. 1996 1997 Indicates that the link's target is a collection and that the 1998 link's context is a member of that collection, as defined in 1999 Section 2.2 of RFC 6573 [RFC6573]. 2001 Operation Types: 2003 2004 Indicates that the form's context is a collection and that a new 2005 item can be created in that collection with the state defined by a 2006 representation submitted to the server. 2008 This operation type defaults to the POST method [RFC7231] 2009 [RFC7252] for both HTTP and CoAP. 2011 2012 Indicates that the form's context is a member of a collection and 2013 that the form's context can be removed from that collection. 2015 This operation type defaults to the DELETE method [RFC7231] 2016 [RFC7252] for both HTTP and CoAP. 2018 A.3. HTTP 2020 Form Field Types: 2022 2023 Specifies the HTTP method for the request. 2025 The form field value MUST be a text string in the format defined 2026 in Section 4.1 of RFC 7231 [RFC7231]. The set of possible values 2027 is maintained in the IANA HTTP Method Registry. 2029 A form field of this type MUST NOT occur more than once in a form. 2030 If absent, it defaults to the request method implied by the form's 2031 operation type. 2033 2034 Specifies an acceptable HTTP content type for the request payload. 2035 There may be multiple form fields of this type. If a form does 2036 not include a form field of this type, the server accepts any or 2037 no request payload, depending on the operation type. 2039 The form field value MUST be a text string in the format defined 2040 in Section 3.1.1.1 of RFC 7231 [RFC7231]. The possible set of 2041 media types and their parameters are maintained in the IANA Media 2042 Types Registry. 2044 Link Relation Types: 2046 2047 Specifies the HTTP content type of the link context. 2049 The link target MUST be a text string in the format defined in 2050 Section 3.1.1.1 of RFC 7231 [RFC7231]. The possible set of media 2051 types and their parameters are maintained in the IANA Media Types 2052 Registry. 2054 A link of this type MUST NOT occur more than once for the link 2055 context. If absent, its value defaults to the content type 2056 "application/octet-stream". 2058 A.4. CoAP 2060 Form Field Types: 2062 2063 Specifies the CoAP method for the request. 2065 The form field value MUST be an integer identifying one of the 2066 CoAP request methods maintained in the IANA CoAP Method Codes 2067 Registry (e.g., the integer 2 for the POST method). 2069 A form field of this type MUST NOT occur more than once in a form. 2070 If absent, it defaults to the request method implied by the form's 2071 operation type. 2073 2074 Specifies an acceptable CoAP content format for the request 2075 payload. There may be multiple form fields of this type. If a 2076 form does not include a form field of this type, the server 2077 accepts any or no request payload, depending on the operation 2078 type. 2080 The form field value MUST be an integer identifying one of the 2081 content formats maintained in the IANA CoAP Content-Formats 2082 Registry. 2084 Link Relation Types: 2086 2087 Specifies the CoAP content format of the link context. 2089 The link target MUST be an integer identifying one of the content 2090 formats maintained in the IANA CoAP Content-Formats Registry. 2092 A link of this type MUST NOT occur more than once for the link 2093 context. If absent, it defaults to content format 42 (i.e., the 2094 content type "application/octet-stream" without a content coding). 2096 Appendix B. Default Dictionary 2098 This section defines a default dictionary that is assumed when the 2099 "application/coral+cbor" media type is used without a "dictionary" 2100 parameter. 2102 +-----+-------------------------------------------------------+ 2103 | Key | Value | 2104 +=====+=======================================================+ 2105 | 0 | | 2106 +-----+-------------------------------------------------------+ 2107 | 1 | | 2108 +-----+-------------------------------------------------------+ 2109 | 2 | | 2110 +-----+-------------------------------------------------------+ 2111 | 3 | | 2112 +-----+-------------------------------------------------------+ 2113 | 4 | | 2114 +-----+-------------------------------------------------------+ 2115 | 5 | | 2116 +-----+-------------------------------------------------------+ 2117 | 6 | | 2118 +-----+-------------------------------------------------------+ 2119 | 7 | | 2120 +-----+-------------------------------------------------------+ 2121 | 8 | | 2122 +-----+-------------------------------------------------------+ 2123 | 9 | | 2124 +-----+-------------------------------------------------------+ 2125 | 10 | | 2126 +-----+-------------------------------------------------------+ 2127 | 11 | | 2128 +-----+-------------------------------------------------------+ 2129 | 12 | "ltr" | 2130 +-----+-------------------------------------------------------+ 2131 | 13 | "rtl" | 2132 +-----+-------------------------------------------------------+ 2133 | 14 | | 2134 +-----+-------------------------------------------------------+ 2136 Table 3: Default Dictionary 2138 Appendix C. Change Log 2140 This section is to be removed before publishing as an RFC. 2142 Changes from -01 to -02: 2144 * Added nested elements to form fields. 2146 * Replaced the special construct for embedded representations with 2147 links. 2149 * Changed the textual format to allow simple/qualified names 2150 wherever IRI references are allowed. 2152 * Introduced predefined names in the textual format (#39). 2154 * Minor editorial improvements and bug fixes. 2156 Changes from -00 to -01: 2158 * Added a section on the semantics of CoRAL documents in responses. 2160 * Minor editorial improvements. 2162 Acknowledgements 2164 CoRAL is heavily inspired by Mike Kelly's JSON Hypertext Application 2165 Language [HAL]. 2167 The recommendations for minting IRIs have been adopted from RDF 1.1 2168 Concepts and Abstract Syntax [W3C.REC-rdf11-concepts-20140225] to 2169 ease the interoperability between RDF predicates and link relation 2170 types. 2172 Thanks to Christian Amsuess, Carsten Bormann, Thomas Fossati, Jaime 2173 Jimenez, Jim Schaad, Sebastian Kaebisch, Ari Keranen, Michael Koster, 2174 Matthias Kovatsch, and Niklas Widell for helpful comments and 2175 discussions that have shaped the document. 2177 Author's Address 2179 Klaus Hartke 2180 Ericsson 2181 Torshamnsgatan 23 2182 SE-16483 Stockholm 2183 Sweden 2185 Email: klaus.hartke@ericsson.com