idnits 2.17.1 draft-hartke-t2trg-coral-06.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 1336 has weird spacing: '...ttr:obs true...' -- The document date (October 22, 2018) is 2011 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 ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '4' on line 650 -- Looks like a reference, but probably isn't: '5' on line 653 -- Looks like a reference, but probably isn't: '6' on line 656 -- Looks like a reference, but probably isn't: '7' on line 657 == Missing Reference: 'I-D.hartke-t2trg-coral' is mentioned on line 1549, but not defined == Outdated reference: A later version (-03) exists of draft-hartke-t2trg-ciri-00 == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-05 ** 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 (==), 9 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 October 22, 2018 5 Expires: April 25, 2019 7 The Constrained RESTful Application Language (CoRAL) 8 draft-hartke-t2trg-coral-06 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 April 25, 2019. 35 Copyright Notice 37 Copyright (c) 2018 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. Requirements Notation . . . . . . . . . . . . . . . . . . 4 54 2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 2.1. Web Linking . . . . . . . . . . . . . . . . . . . . . . . 4 56 2.2. Links, Forms, and Metadata . . . . . . . . . . . . . . . 5 57 3. Data and Interaction Model . . . . . . . . . . . . . . . . . 6 58 3.1. Browsing Context . . . . . . . . . . . . . . . . . . . . 7 59 3.2. Documents . . . . . . . . . . . . . . . . . . . . . . . . 7 60 3.3. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 3.4. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 3.5. Form Data . . . . . . . . . . . . . . . . . . . . . . . . 9 63 3.6. Embedded Representations . . . . . . . . . . . . . . . . 9 64 3.7. Navigation . . . . . . . . . . . . . . . . . . . . . . . 10 65 3.8. History Traversal . . . . . . . . . . . . . . . . . . . . 11 66 4. Binary Format . . . . . . . . . . . . . . . . . . . . . . . . 11 67 4.1. Data Structure . . . . . . . . . . . . . . . . . . . . . 11 68 4.1.1. Documents . . . . . . . . . . . . . . . . . . . . . . 12 69 4.1.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 12 70 4.1.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 13 71 4.1.4. Embedded Representations . . . . . . . . . . . . . . 15 72 4.1.5. Directives . . . . . . . . . . . . . . . . . . . . . 15 73 5. Textual Format . . . . . . . . . . . . . . . . . . . . . . . 16 74 5.1. Lexical Structure . . . . . . . . . . . . . . . . . . . . 16 75 5.1.1. Line Terminators . . . . . . . . . . . . . . . . . . 16 76 5.1.2. White Space . . . . . . . . . . . . . . . . . . . . . 16 77 5.1.3. Comments . . . . . . . . . . . . . . . . . . . . . . 16 78 5.1.4. Identifiers . . . . . . . . . . . . . . . . . . . . . 17 79 5.1.5. IRI References . . . . . . . . . . . . . . . . . . . 17 80 5.1.6. Literals . . . . . . . . . . . . . . . . . . . . . . 17 81 5.1.7. Punctuators . . . . . . . . . . . . . . . . . . . . . 21 82 5.2. Syntactic Structure . . . . . . . . . . . . . . . . . . . 21 83 5.2.1. Documents . . . . . . . . . . . . . . . . . . . . . . 21 84 5.2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 21 85 5.2.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 22 86 5.2.4. Embedded Representations . . . . . . . . . . . . . . 23 87 5.2.5. Directives . . . . . . . . . . . . . . . . . . . . . 24 88 6. Usage Considerations . . . . . . . . . . . . . . . . . . . . 25 89 6.1. Specifying CoRAL-based Applications . . . . . . . . . . . 25 90 6.1.1. Naming Resources . . . . . . . . . . . . . . . . . . 26 91 6.1.2. Implementation Limits . . . . . . . . . . . . . . . . 26 92 6.2. Minting New Relation Types . . . . . . . . . . . . . . . 27 93 6.3. Registering Relation Types . . . . . . . . . . . . . . . 27 94 6.4. Expressing Link Target Attributes . . . . . . . . . . . . 29 95 6.5. Embedding CoRAL in CBOR Structures . . . . . . . . . . . 29 96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 30 97 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 98 8.1. Media Type "application/coral+cbor" . . . . . . . . . . . 31 99 8.2. Media Type "text/coral" . . . . . . . . . . . . . . . . . 32 100 8.3. CoAP Content Formats . . . . . . . . . . . . . . . . . . 33 101 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 102 9.1. Normative References . . . . . . . . . . . . . . . . . . 34 103 9.2. Informative References . . . . . . . . . . . . . . . . . 36 104 Appendix A. Core Vocabulary . . . . . . . . . . . . . . . . . . 37 105 A.1. Link Relation Types . . . . . . . . . . . . . . . . . . . 38 106 A.2. Form Relation Types . . . . . . . . . . . . . . . . . . . 38 107 A.3. Form Field Names . . . . . . . . . . . . . . . . . . . . 39 108 Appendix B. Default Profile . . . . . . . . . . . . . . . . . . 39 109 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 39 111 1. Introduction 113 The Constrained RESTful Application Language (CoRAL) is a language 114 for the description of typed connections between resources on the Web 115 ("links"), possible operations on such resources ("forms"), as well 116 as simple resource metadata. 118 CoRAL is intended for driving automated software agents that navigate 119 a Web application based on a standardized vocabulary of link and form 120 relation types. It is designed to be used in conjunction with a Web 121 transfer protocol such as the Hypertext Transfer Protocol (HTTP) 122 [RFC7230] or the Constrained Application Protocol (CoAP) [RFC7252]. 124 This document defines the CoRAL data and interaction model, as well 125 as two specialized CoRAL serialization formats: 127 The CoRAL data and interaction model is a superset of the Web Linking 128 model of RFC 8288 [RFC8288]. The CoRAL data model consists of two 129 elements: _links_ that describe the relationships between pairs of 130 resources and the type of those relationships, and _forms_ that 131 describe possible operations on resources and the type of those 132 operations. Additionally, the data model can describe simple 133 resource metadata in a way similar to the Resource Description 134 Framework (RDF) [W3C.REC-rdf11-concepts-20140225]. In contrast to 135 RDF, the focus of CoRAL is on the interaction with resources, not 136 just the relationships between them. The CoRAL interaction model 137 derives from HTML 5 [W3C.REC-html52-20171214] and specifies how an 138 automated software agent can navigate between resources by following 139 links and perform operations on resources by submitting forms. 141 The primary CoRAL serialization format is a compact, binary encoding 142 of links and forms in Concise Binary Object Representation (CBOR) 143 [RFC7049]. It is intended for environments with constraints on 144 power, memory, and processing resources [RFC7228] and shares many 145 similarities with the message format of the Constrained Application 146 Protocol (CoAP) [RFC7252]. For example, it uses numeric identifiers 147 instead of verbose strings for link and form relation types, and pre- 148 parses URIs into (what CoAP considers to be) their components, which 149 greatly simplifies URI processing. As a result, link serializations 150 are often much more compact than equivalent serializations in CoRE 151 Link Format [RFC6690] [I-D.ietf-core-links-json]. 153 The secondary CoRAL serialization format is a lightweight, textual 154 encoding of links and forms that is intended to be easy to read and 155 write for humans. The format is loosely inspired by the syntax of 156 Turtle [W3C.REC-turtle-20140225] and is used throughout the document 157 for examples. 159 1.1. Requirements Notation 161 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 162 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 163 "OPTIONAL" in this document are to be interpreted as described in BCP 164 14 [RFC2119] [RFC8174] when, and only when, they appear in all 165 capitals, as shown here. 167 2. Examples 169 2.1. Web Linking 171 At its core, CoRAL is just yet another serialization format for Web 172 links. For example, if an HTTP client sends the following request: 174 GET /TheBook/chapter3 HTTP/1.1 175 Host: example.com 177 and receives the following response: 179 HTTP/1.1 200 OK 180 Content-Type: text/coral 182 #using 184 next <./chapter4> 185 icon 186 license 188 then the representation contains the following three links: 190 o one link of type "http://www.iana.org/assignments/relation/next" 191 from to 192 , 194 o one link of type "http://www.iana.org/assignments/relation/icon" 195 from to , and 198 o one link of type "http://www.iana.org/assignments/relation/ 199 license" from to 200 . 202 This representation is equivalent to the following Link header field 203 [RFC8288]: 205 Link: <./chapter4>; rel="next", 206 ; rel="icon", 207 ; rel="license" 209 and the following HTML 5 [W3C.REC-html52-20171214] link elements: 211 212 213 216 2.2. Links, Forms, and Metadata 218 In its entirety, CoRAL is an expressive language for describing Web 219 links between resources, possible operations on these resources, and 220 simple resource metadata. For example, if an HTTP client sends the 221 following request: 223 GET /tasks HTTP/1.1 224 Host: example.com 226 and receives the following response: 228 HTTP/1.1 200 OK 229 Content-Type: text/coral 231 #using 232 #using coral = 234 task { 235 description "Pick up the kids" 236 } 238 task { 239 description "Return the books to the library" 240 coral:delete -> DELETE 241 } 243 coral:create -> POST [coral:accept "example/task"] 245 then the representation contains the following six elements: 247 o one link of type "http://example.org/vocabulary#task" from 248 to , 250 o one link of type "http://example.org/vocabulary#description" from 251 to "Pick up the kids", 253 o one link of type "http://example.org/vocabulary#task" from 254 to , 256 o one link of type "http://example.org/vocabulary#description" from 257 to "Return the books to the library", 259 o one form of type "urn:TBD#delete" that can be used to delete 260 by making a DELETE request to 261 , and 263 o one form of type "urn:TBD#create" that can be used to create a new 264 item in by making a POST request to 265 with an "example/task" payload. 267 3. Data and Interaction Model 269 The Constrained RESTful Application Language (CoRAL) is designed for 270 building Web-based applications [W3C.REC-webarch-20041215] in which 271 automated software agents navigate between resources by following 272 links and perform operations on resources by submitting forms. 274 3.1. Browsing Context 276 Borrowing from HTML 5 [W3C.REC-html52-20171214], each such agent 277 maintains a _browsing context_ in which the representations of Web 278 resources are processed. (In HTML 5, the browsing context typically 279 corresponds to a tab or window in a Web browser.) 281 A browsing context has a _session history_ that lists the resource 282 representations that the agent has processed, is processing, or will 283 process. At any time, one representation in each browsing context is 284 designated the _active_ representation. 286 A session history consists of a flat list of session history entries. 287 Each _session history entry_ consists of a resource representation 288 and the Internationalized Resource Identifier (IRI) [RFC3987] that 289 was used to retrieve the representation. An entry may additionally 290 have other information associated with it. New entries are added to 291 the session history as the agent navigates from resource to resource. 293 3.2. Documents 295 A resource representation in one of the CoRAL serialization formats 296 is called a CoRAL _document_. The IRI that was used to retrieve such 297 a document is called the document's _retrieval context_. 299 A CoRAL document consists of a list of zero or more links, forms, and 300 embedded resource representations, collectively called _elements_. 301 CoRAL serialization formats may define additional types of elements 302 for efficiency or convenience, such as base IRIs for relative IRI 303 references. 305 3.3. Links 307 A _link_ describes a relationship between two resources on the Web 308 [RFC8288]. As defined in RFC 8288, it consists of a _link context_, 309 a _link relation type_, and a _link target_. In CoRAL, a link can 310 additionally have a nested list of zero or more elements, which take 311 the place of link target attributes. 313 A link can be viewed as a statement of the form "{link context} has a 314 {link relation type} resource at {link target}" where the link target 315 may be further described by nested elements. 317 The link relation type identifies the semantics of a link. In HTML 5 318 and the RFC 8288 Link header field, link relation types are typically 319 denoted by an IANA-registered name, such as "stylesheet" or "icon". 320 In CoRAL, in contrast, link relation types are denoted by an IRI or 321 an unsigned integer. IRIs on the one hand allow for the creation of 322 new, unique relation types in a decentralized fashion, but can incur 323 a high overhead in terms of message size. Small, unsigned integers 324 on the other hand minimize the overhead of link relation types in 325 constrained environments, but require the assignment of values by a 326 registry to avoid collisions. 328 The link context and the link target are both resources on the Web. 329 Resources are denoted in CoRAL either by an IRI reference [RFC3987] 330 or (similarly to RDF) a literal. If the IRI scheme indicates a Web 331 transfer protocol such as HTTP or CoAP, then an agent can dereference 332 the IRI and navigate the browsing context to the referenced resource; 333 this is called _following the link_. A literal directly identifies a 334 value, which in CoRAL can be a Boolean value, an integer, a floating- 335 point number, a byte string, or a text string. 337 A link can occur as a top-level element in a document or as a nested 338 element within a link. When a link occurs as a top-level element, 339 the link context is implicitly the document's retrieval context. 340 When a link occurs nested within a link, the link context of the 341 inner link is the link target of the outer link. 343 There are no restrictions on the cardinality of links; there can be 344 multiple links to and from a particular target, and multiple links of 345 the same or different types between a given link context and target. 346 However, the CoRAL data model constrains the description of a 347 resource graph to a tree: Links between linked resources can only be 348 described by further nesting links. 350 3.4. Forms 352 A _form_ provides instructions to an agent for performing an 353 operation on a Web resource. It consists of a _form context_, a 354 _form relation type_, a _request method_, and a _submission IRI_. 355 Additionally, a form may be accompanied by _form data_. 357 A form can be viewed as an instruction of the form "To perform a 358 {form relation type} operation on {form context}, make a {request 359 method} request to {submission IRI}" where the payload of the request 360 may be further described by form data. 362 The form relation type identifies the semantics of the operation. 363 Like link relation types, form relation types are denoted by an IRI 364 or an unsigned integer. 366 The form context is the resource on which an operation is ultimately 367 performed. To perform the operation, an agent needs to construct a 368 request with the specified request method and submission IRI. The 369 submission IRI typically refers to the form context, but MAY refer to 370 another resource. Constructing and sending the request is called 371 _submitting the form_. 373 If a form is accompanied by form data (Section 3.5), then the agent 374 MUST also construct a payload that matches the specifications of the 375 form data and include that in the request. 377 A form can occur as a top-level element in a document or as a nested 378 element within a link. When a form occurs as a top-level element, 379 the form context is implicitly the document's retrieval context. 380 When a form occurs nested within a link, the form context is the link 381 target of the enclosing link. 383 3.5. Form Data 385 Form data provides instructions for agents to construct a request 386 payload. It consists of a list of zero or more _form fields_. Each 387 form field consists of a _form field name_ and a _form field value_. 389 Form fields can either directly identify data items that need to be 390 included in the request payload or reference another resource (such 391 as a schema) that describes the data items. Form fields may also 392 provide other information, such as acceptable representation formats. 394 The form field name identifies the semantics of the form field. Like 395 link and form relation types, form field names are denoted by an IRI 396 or an unsigned integer. 398 The form field value can be an IRI, a Boolean value, an integer, a 399 floating-point number, a byte string, or a text string. 401 3.6. Embedded Representations 403 When a document contains links to many resources and an agent needs a 404 representation of each link target, it may be inefficient to retrieve 405 each of these representations individually. To alleviate this, 406 documents can directly embed representations of resources. 408 An _embedded representation_ consists of a sequence of bytes, plus 409 _representation metadata_ to describe those bytes. 411 An embedded representation may be a full, partial, or inconsistent 412 version of the representation served from the IRI of the represented 413 resource. 415 An embedded representation can occur as a top-level element in a 416 document or as a nested element within a link. When it occurs as a 417 top-level element, it provides an alternate representation of the 418 document's retrieval context. When it occurs nested within a link, 419 it provides a representation of link target of the enclosing link. 421 3.7. Navigation 423 An agent begins interacting with an application by performing a GET 424 request on an _entry point IRI_. The entry point IRI is the only IRI 425 an agent is expected to know before interacting with an application. 426 From there, the agent is expected to make all requests by following 427 links and submitting forms provided by the server in responses. The 428 entry point IRI can be obtained by manual configuration or through 429 some discovery process. 431 If dereferencing the entry point IRI yields a CoRAL document or any 432 other representation that implements the CoRAL data and interaction 433 model, then the agent proceeds as follows: 435 1. The first step for the agent is to decide what to do next, i.e., 436 which type of link to follow or form to submit, based on the link 437 relation types and form relation types it understands. 439 2. The agent finds the link(s) or form(s) with the respective 440 relation type in the active representation. This may yield one 441 or more candidates, from which the agent must select the most 442 appropriate one in the next step. The set of candidates may be 443 empty, for example, when a transition is not supported or not 444 allowed. 446 3. The agent selects one of the candidates based on the metadata 447 associated with the link(s) or form(s). Metadata typically 448 includes the media type of the target resource representation, 449 the IRI scheme, the request method, and other information that is 450 provided as nested elements in a link and form data in a form. 452 If the selected candidate contains an embedded representation, 453 then the agent MAY skip the following steps and immediately 454 proceed with step 8. 456 4. The agent resolves the IRI reference in the link or form 457 (Section 5 of RFC 3986 [RFC3986]) to obtain the _request IRI_. 458 Fragment identifiers are not part of the request IRI and MUST be 459 separated from the rest of the IRI prior to a dereference. The 460 request IRI may need to be converted to a URI (Section 3.1 of RFC 461 3987 [RFC3987]) for protocols that do not support IRIs. 463 5. The agent constructs a new request with the request IRI. If the 464 agent follows a link, the request method MUST be GET. If the 465 agent submits a form, the request method MUST be the one 466 specified in the form. The agent SHOULD set HTTP header fields 467 and CoAP request options according to provided metadata (e.g., 468 set the HTTP Accept header field or the CoAP Accept option when 469 the media type of the target resource is provided). In case of a 470 form with form data, the agent MUST also include a request 471 payload that matches the specifications of the form data. 473 6. The agent sends the request and receives the response. 475 7. If a fragment identifier was separated from the request IRI, the 476 agent dereferences the fragment identifier within the received 477 representation. 479 8. The agent _updates the session history_: It removes all the 480 entries in the browsing context's session history after the 481 current entry. Then it appends a new entry at the end of the 482 history representing the new resource and makes that entry the 483 active representation. 485 9. Finally, the agent processes the representation. In case of a 486 CoRAL document or any other representation that implements the 487 CoRAL data and interaction model, this means the agent decides 488 again what to do next -- and the cycle repeats. 490 3.8. History Traversal 492 An agent can navigate a browsing context also by traversing the 493 browsing context's session history. An agent can _traverse the 494 session history_ by updating the active representation to the that 495 entry. 497 4. Binary Format 499 This section defines the encoding of documents in the CoRAL binary 500 format. 502 A document in the binary format is a data item in Concise Binary 503 Object Representation (CBOR) [RFC7049]. The structure of this data 504 item is presented in the Concise Data Definition Language (CDDL) 505 [I-D.ietf-cbor-cddl]. The media type is "application/coral+cbor". 507 4.1. Data Structure 509 The data structure of a document in the binary format is made up of 510 four kinds of elements: links, forms, embedded representations, and 511 (as an extension to the CoRAL data model) base IRI directives. Base 512 IRI directives provide a way to encode IRI references with a common 513 base more efficiently. 515 Elements are processed in the order they appear in the document. 516 Document processors need to maintain an _environment_ while iterating 517 an array of elements. The environment consists of three variables: a 518 _current context IRI_, a _current base IRI_, and a _current relation 519 type_. The current context IRI and current base IRI are initially 520 both set to the document's retrieval context. The current relation 521 type is initially set to the unsigned integer zero. 523 4.1.1. Documents 525 The body of a document in the binary format is encoded as an array of 526 zero or more links, forms, embedded representations, and directives. 528 body = [*(link / form / representation / directive)] 530 4.1.2. Links 532 A link is encoded as an array that consists of the unsigned integer 533 2, followed by the link relation type and the link target, optionally 534 followed by a link body that contains nested elements. 536 link = [link: 2, relation, target, ?body] 538 The link relation type is encoded either as a text string containing 539 an absolute IRI reference or as an (unsigned or negative) integer 540 representing the difference to the current relation type. A link is 541 processed by updating the current relation type to the result of 542 adding the specified integer (or zero in the case of a text string) 543 to the current relation type. It is an error if the current relation 544 type becomes negative. 546 relation = text / int 548 The link target is denoted by an IRI reference or represented by a 549 literal value. The IRI reference MAY be relative or absolute, and 550 MUST be resolved against the current base IRI. The encoding of IRI 551 references in the binary format is described in RFC XXXX 552 [I-D.hartke-t2trg-ciri]. The link target MAY be null, which 553 indicates that the link target is an unidentified resource. 555 target = ciri / literal / null 557 literal = bool / int / float / bytes / text 559 The array of elements in the link body, if any, MUST be processed in 560 a fresh environment. The current context IRI and current base IRI in 561 the new environment are initially both set to the link target of the 562 enclosing link. The current relation type in the new environment is 563 initially set to the current relation type. 565 4.1.3. Forms 567 A form is encoded as an array that consists of the unsigned integer 568 3, followed by the form relation type, the submission method, and a 569 submission IRI reference, optionally followed by form data. 571 form = [form: 3, relation, method, ciri, ?form-data] 573 The form relation type is encoded and processed in the same way as a 574 link relation type (Section 4.1.2). 576 The method MUST refer to one of the request methods defined by the 577 Web transfer protocol identified by the scheme of the submission IRI. 578 It is encoded either as a text string or an unsigned integer. 580 method = text / uint 582 For HTTP [RFC7230], the method MUST be encoded as a text string in 583 the format defined in Section 4.1 of RFC 7231 [RFC7231]; the set of 584 possible values is maintained in the IANA HTTP Method Registry. For 585 CoAP [RFC7252], the method MUST be encoded as an unsigned integer 586 (e.g., the unsigned integer 2 for the POST method); the set of 587 possible values is maintained in the IANA CoAP Method Codes Registry. 589 The submission IRI reference MAY be relative or absolute, and MUST be 590 resolved against the current base IRI. The encoding of IRI 591 references in the binary format is described in RFC XXXX 592 [I-D.hartke-t2trg-ciri]. 594 4.1.3.1. Form Data 596 Form data is encoded as an array of zero or more name-value pairs. 598 form-data = [*(form-field-name, form-field-value)] 600 Form data, if any, MUST be processed in a fresh environment. The 601 current context IRI and current base IRI in the new environment are 602 initially both set to the submission IRI of the enclosing form. The 603 current relation type in the new environment is initially set to the 604 current relation type. 606 A form field name is encoded and processed in the same way as a link 607 relation type (Section 4.1.2). 609 form-field-name = text / uint 611 A form field value can be an IRI reference, a Boolean value, an 612 integer, a floating-point number, a byte string, a text string, or 613 null. An IRI reference MAY be relative or absolute, and MUST be 614 resolved against the current base IRI. The encoding of IRI 615 references in the binary format is described in RFC XXXX 616 [I-D.hartke-t2trg-ciri]. 618 form-field-value = ciri / bool / int / float / bytes / text / null 620 4.1.3.2. Short Forms 622 Forms in certain shapes can be encoded in a more efficient manner 623 using short forms. The following short forms are available: 625 form /= [form.create: 4, ?accept: uint .size 2] 627 form /= [form.update: 5, ?accept: uint .size 2] 629 form /= [form.delete: 6] 631 form /= [form.search: 7, ?accept: uint .size 2] 633 If the scheme of the submission IRI indicates HTTP, the short forms 634 expand as follows: 636 [4] -> [3, "urn:TBD#create", "POST", []] 637 [4, x] -> [3, "urn:TBD#create", "POST", [], 638 ["urn:TBD#accept", x]] 639 [5] -> [3, "urn:TBD#update", "PUT", []] 640 [5, x] -> [3, "urn:TBD#update", "PUT", [], 641 ["urn:TBD#accept", x]] 642 [6] -> [3, "urn:TBD#delete", "DELETE", []] 643 [7] -> [3, "urn:TBD#search", "POST", []] 644 [7, x] -> [3, "urn:TBD#search", "POST", [], 645 ["urn:TBD#accept", x]] 647 If the scheme of the submission IRI indicates CoAP, the short forms 648 expand as follows (the only difference being the request methods): 650 [4] -> [3, "urn:TBD#create", 2, []] 651 [4, x] -> [3, "urn:TBD#create", 2, [], 652 ["urn:TBD#accept", x]] 653 [5] -> [3, "urn:TBD#update", 3, []] 654 [5, x] -> [3, "urn:TBD#update", 3, [], 655 ["urn:TBD#accept", x]] 656 [6] -> [3, "urn:TBD#delete", 4, []] 657 [7] -> [3, "urn:TBD#search", 5, []] 658 [7, x] -> [3, "urn:TBD#search", 5, [], 659 ["urn:TBD#accept", x]] 661 The form relation types and form field names used in these expansions 662 are defined in Appendix A. 664 4.1.4. Embedded Representations 666 An embedded representation is encoded as an array that consists of 667 the unsigned integer 0, followed by the HTTP content type or CoAP 668 content format of the representation and a byte string containing the 669 representation data. 671 representation = [representation: 0, text / uint, bytes] 673 For HTTP, the content type MUST be specified as a text string in the 674 format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the set of 675 possible values is maintained in the IANA Media Types Registry. For 676 CoAP, the content format MUST be specified as an unsigned integer; 677 the set of possible values is maintained in the IANA CoAP Content- 678 Formats Registry. 680 4.1.5. Directives 682 Directives provide the ability to manipulate the environment when 683 processing a list of elements. There is one directive available: the 684 Base IRI directive. 686 directive = base-directive 688 4.1.5.1. Base IRI Directives 690 A Base IRI directive is encoded as an array that consists of the 691 negative integer -1, followed by an IRI reference. 693 base-directive = [base: -1, ciri] 695 The IRI reference MAY be relative or absolute, and MUST be resolved 696 against the current context IRI. The encoding of IRI references in 697 the binary format is described in RFC XXXX [I-D.hartke-t2trg-ciri]. 699 The directive is processed by resolving the IRI reference against the 700 current context IRI and assigning the result to the current base IRI. 702 5. Textual Format 704 This section defines the syntax of documents in the CoRAL textual 705 format using two grammars: The lexical grammar defines how Unicode 706 characters are combined to form line terminators, white space, 707 comments, and tokens. The syntactic grammar defines how the tokens 708 are combined to form documents. Both grammars are presented in 709 Augmented Backus-Naur Form (ABNF) [RFC5234]. 711 A document in the textual format is a Unicode string in a Unicode 712 encoding form [UNICODE]. The media type for such documents is "text/ 713 coral". The "charset" parameter is not used; charset information is 714 transported inside the document in the form of an OPTIONAL Byte Order 715 Mark (BOM). The use of the UTF-8 encoding scheme [RFC3629], without 716 a BOM, is RECOMMENDED. 718 5.1. Lexical Structure 720 The lexical structure of a document in the textual format is made up 721 of four basic elements: line terminators, white space, comments, and 722 tokens. Of these, only tokens are significant in the syntactic 723 grammar. There are four kinds of tokens: identifiers, IRI 724 references, literals, and punctuators. 726 When several lexical grammar rules match a sequence of characters in 727 a document, the longest match takes priority. 729 5.1.1. Line Terminators 731 Line terminators divide text into lines. A line terminator is any 732 Unicode character with Line_Break class BK, CR, LF, or NL. However, 733 any CR character that immediately precedes a LF character is ignored. 734 (This affects only the numbering of lines in error messages.) 736 5.1.2. White Space 738 White space is a sequence of one or more white space characters. A 739 white space character is any Unicode character with the White_Space 740 property. 742 5.1.3. Comments 744 Comments are sequences of characters that are ignored when parsing 745 text into tokens. Single-line comments begin with the characters 746 "//" and extend to the end of the line. Delimited comments begin 747 with the characters "/*" and end with the characters "*/". Delimited 748 comments can occupy a portion of a line, a single line, or multiple 749 lines. 751 Comments do not nest. The character sequences "/*" and "*/" have no 752 special meaning within a single-line comment; the character sequences 753 "//" and "/*" have no special meaning within a delimited comment. 755 5.1.4. Identifiers 757 An identifier tokens is a user-defined symbolic name. The rules for 758 identifiers correspond to those recommended by the Unicode Standard 759 Annex #31 [UNICODE-UAX31] using the following profile: 761 identifier = start *continue *(medial 1*continue) 763 start = 765 continue = 767 medial = "-" / "." / "~" / %xB7 / %x58A / %xF0B 769 medial =/ %x2010 / %x2027 / %x30A0 / %x30FB 771 All identifiers MUST be converted into Unicode Normalization Form C 772 (NFC), as defined by the Unicode Standard Annex #15 [UNICODE-UAX15]. 773 Comparison of identifiers is based on NFC and is case-sensitive 774 (unless otherwise noted). 776 5.1.5. IRI References 778 An IRI reference is a Unicode string that conforms to the syntax 779 defined in RFC 3987 [RFC3987]. An IRI reference can be absolute or 780 relative, and can contain a fragment identifier. IRI references are 781 enclosed in angle brackets ("<" and ">"). 783 iri = "<" IRI-reference ">" 785 IRI-reference = 787 5.1.6. Literals 789 A literal is a textual representation of a value. There are six 790 types of literals: Boolean, integer, floating-point, byte string, 791 text string, and null. 793 5.1.6.1. Boolean Literals 795 The case-insensitive tokens "true" and "false" denote the Boolean 796 values true and false, respectively. 798 boolean = "true" / "false" 800 5.1.6.2. Integer Literals 802 Integer literals denote integer values of unspecified precision. By 803 default, integer literals are expressed in decimal, but they can also 804 be specified in an alternate base using a prefix. Binary literals 805 begin with "0b", octal literals begin with "0o", and hexadecimal 806 literals begin with "0x". 808 Decimal literals contain the digits "0" through "9". Binary literals 809 contain "0" and "1", octal literals contain "0" through "7", and 810 hexadecimal literals contain "0" through "9" as well as "A" through 811 "F" in upper- or lowercase. 813 Negative integers are expressed by prepending a minus sign ("-"). 815 integer = ["+" / "-"] (decimal / binary / octal / hexadecimal) 817 decimal = 1*DIGIT 819 binary = %x30 (%x42 / %x62) 1*BINDIG 821 octal = %x30 (%x4F / %x6F) 1*OCTDIG 823 hexadecimal = %x30 (%x58 / %x78) 1*HEXDIG 825 DIGIT = %x30-39 827 BINDIG = %x30-31 829 OCTDIG = %x30-37 831 HEXDIG = %x30-39 / %x41-46 / %x61-66 833 5.1.6.3. Floating-point Literals 835 Floating-point literals denote floating-point numbers of unspecified 836 precision. 838 Floating-point literals consist of a sequence of decimal digits 839 followed by a fraction, an exponent, or both. The fraction consists 840 of a decimal point (".") followed by a sequence of decimal digits. 842 The exponent consists of the letter "e" in upper- or lowercase, 843 followed by an optional sign and a sequence of decimal digits that 844 indicate a power of 10 by which the value preceding the "e" is 845 multiplied. 847 Negative floating-point values are expressed by prepending a minus 848 sign ("-"). 850 floating-point = ["+" / "-"] 1*DIGIT [fraction] [exponent] 852 fraction = "." 1*DIGIT 854 exponent = (%x45 / %x65) ["+" / "-"] 1*DIGIT 856 Floating-point literals can additionally denote the special "Not- 857 a-Number" (NaN) value, positive infinity, and negative infinity. The 858 NaN value is produced by the case-insensitive token "NaN". The two 859 infinite values are produced by the case-insensitive tokens 860 "+Infinity" (or simply "Infinity") and "-Infinity". 862 floating-point =/ "NaN" 864 floating-point =/ ["+" / "-"] "Infinity" 866 5.1.6.4. Byte String Literals 868 A byte string literal consists of a prefix and zero or more bytes 869 encoded in Base16, Base32, or Base64 [RFC4648] and enclosed in single 870 quotes. Byte string literals encoded in Base16 begin with "h" or 871 "b16", byte string literals encoded in Base32 begin with "b32", and 872 byte string literals encoded in Base64 begin with "b64". 874 bytes = base16 / base32 / base64 876 base16 = (%x68 / %x62.31.36) SQUOTE SQUOTE 878 base32 = %x62.33.32 SQUOTE SQUOTE 880 base64 = %x62.36.34 SQUOTE SQUOTE 882 SQUOTE = %x27 884 5.1.6.5. Text String Literals 886 A text string literal consists of zero or more Unicode characters 887 enclosed in double quotes. It can include simple escape sequences 888 (such as \t for the tab character) as well as hexadecimal and Unicode 889 escape sequences. 891 text = DQUOTE *(char / %x5C escape) DQUOTE 893 char = 895 escape = simple-escape / hexadecimal-escape / unicode-escape 897 simple-escape = %x30 / %x62 / %x74 / %x6E / %x76 899 simple-escape =/ %x66 / %x72 / %x22 / %x27 / %x5C 901 hexadecimal-escape = (%x78 / %x58) 2HEXDIG 903 unicode-escape = %x75 4HEXDIG / %x55 8HEXDIG 905 DQUOTE = %x22 907 An escape sequence denotes a single Unicode code point. For 908 hexadecimal and Unicode escape sequences, the code point is expressed 909 by the hexadecimal number following the "\x", "\X", "\u", or "\U" 910 prefix. Simple escape sequences indicate the code points listed in 911 Table 1. 913 +-----------------+------------+----------------------+ 914 | Escape Sequence | Code Point | Character Name | 915 +-----------------+------------+----------------------+ 916 | \0 | U+0000 | Null | 917 | \b | U+0008 | Backspace | 918 | \t | U+0009 | Character Tabulation | 919 | \n | U+000A | Line Feed | 920 | \v | U+000B | Line Tabulation | 921 | \f | U+000C | Form Feed | 922 | \r | U+000D | Carriage Return | 923 | \" | U+0022 | Quotation Mark | 924 | \' | U+0027 | Apostrophe | 925 | \\ | U+005C | Reverse Solidus | 926 +-----------------+------------+----------------------+ 928 Table 1: Simple Escape Sequences 930 5.1.6.6. Null Literal 932 The case-insensitive tokens "null" and "_" denote the intentional 933 absence of any value. 935 null = "null" / "_" 937 5.1.7. Punctuators 939 Punctuator tokens are used for grouping and separating. 941 punctuator = "#" | ":" | "*" | "[" | "]" | "{" | "}" | "=" | "->" 943 5.2. Syntactic Structure 945 The syntactic structure of a document in the textual format is made 946 up of four kinds of elements: links, forms, embedded representations, 947 and (as an extension to the CoRAL data model) directives. Directives 948 provide a way to make documents easier to read and write by defining 949 base IRIs for relative IRI references and introducing shorthands for 950 IRIs. 952 Elements are processed in the order they appear in the document. 953 Document processors need to maintain an _environment_ while iterating 954 a list of elements. The environment consists of three variables: a 955 _current context IRI_, a _current base IRI_, and a _current mapping 956 from identifiers to IRIs_. The current context IRI and current base 957 IRI are initially both set to the document's retrieval context. The 958 current mapping from identifiers to IRIs is initially empty. 960 5.2.1. Documents 962 The body of a document in the textual format consists of zero or more 963 links, forms, and directives. 965 body = *(link / form / representation / directive) 967 5.2.2. Links 969 A link consists of the link relation type, followed by the link 970 target, optionally followed by a link body enclosed in curly brackets 971 ("{" and "}"). 973 link = relation target ["{" body "}"] 975 The link relation type is denoted either by an absolute IRI 976 reference, a simple name, a qualified name, or an integer. 978 relation = iri / simple-name / qualified-name / integer 980 A simple name consists of an identifier. It is resolved to an IRI by 981 looking up the empty string in the current mapping from identifiers 982 to IRIs and appending the specified identifier to the result. It is 983 an error if the empty string is not present in the mapping. 985 simple-name = identifier 987 A qualified name consists of two identifiers separated by a colon 988 (":"). It is resolved to an IRI by looking up the identifier on the 989 left hand side in the current mapping from identifiers to IRIs and 990 appending the identifier on the right hand side to the result. It is 991 an error if the identifier on the left hand side is not present in 992 the mapping. 994 qualified-name = identifier ":" identifier 996 The link target is denoted by an IRI reference or represented by a 997 value literal. The IRI reference MAY be relative or absolute, and 998 MUST be resolved against the current base IRI. If the link target is 999 null, the link target is an unidentified resource. 1001 target = iri / literal / null 1003 literal = boolean / integer / floating-point / bytes / text 1005 The list of elements in the link body, if any, MUST be processed in a 1006 fresh environment. The current context IRI and current base IRI in 1007 this environment are initially both set to the link target of the 1008 enclosing link. The mapping from identifiers to IRIs is initially 1009 set to a copy of the mapping from identifiers to IRIs in the current 1010 environment. 1012 5.2.3. Forms 1014 A form consists of the form relation type, followed by a "->" token, 1015 a method identifier, and a submission IRI reference, optionally 1016 followed by form data enclosed in square brackets ("[" and "]"). 1018 form = relation "->" method iri ["[" form-data "]"] 1020 The form relation type is denoted in the same way as a link relation 1021 type (Section 5.2.2). 1023 The method identifier refers to one of the request methods defined by 1024 the Web transfer protocol identified by the scheme of the submission 1025 IRI. Method identifiers are case-insensitive and constrained to 1026 Unicode characters in the Basic Latin block. 1028 method = identifier 1030 For HTTP [RFC7230], the set of possible method identifiers is 1031 maintained in the IANA HTTP Method Registry. For CoAP [RFC7252], the 1032 set of possible method identifiers is maintained in the IANA CoAP 1033 Method Codes Registry. 1035 The submission IRI reference MAY be relative or absolute, and MUST be 1036 resolved against the current base IRI. 1038 5.2.3.1. Form Data 1040 Form data consists of zero or more name-value pairs. 1042 form-data = *(form-field-name form-field-value) 1044 Form data, if any, MUST be processed in a fresh environment. The 1045 current context IRI and current base IRI in this environment are 1046 initially both set to the submission IRI of the enclosing form. The 1047 mapping from identifiers to IRIs is initially set to a copy of the 1048 mapping from identifiers to IRIs in the current environment. 1050 The form field name is denoted in the same way as a link relation 1051 type (Section 5.2.2). 1053 form-field-name = iri / simple-name / qualified-name / integer 1055 The form field value can be an IRI reference, Boolean literal, 1056 integer literal, floating-point literal, byte string literal, text 1057 string literal, or null. An IRI reference MAY be relative or 1058 absolute, and MUST be resolved against the current base IRI. 1060 form-field-value = iri / boolean / integer 1062 form-field-value =/ floating-point / bytes / text / null 1064 5.2.4. Embedded Representations 1066 An embedded representation consists of a "*" token, followed by the 1067 representation data, optionally followed by representation metadata 1068 enclosed in square brackets ("[" and "]"). 1070 representation = "*" bytes ["[" representation-metadata "]"] 1072 Representation metadata consists of zero or more name-value pairs. 1074 representation-metadata = *(metadata-name metadata-value) 1076 This document specifies only one kind of metadata item, labeled with 1077 the name "type": the HTTP content type or CoAP content format of the 1078 representation. 1080 metadata-name = "type" 1082 metadata-value = text / integer 1084 For HTTP, the content type MUST be specified as a text string in the 1085 format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the set of 1086 possible values is maintained in the IANA Media Types Registry. For 1087 CoAP, the content format MUST be specified as an integer; the set of 1088 possible values is maintained in the IANA CoAP Content-Formats 1089 Registry. 1091 A metadata item with the name "type" MUST NOT occur more than once. 1092 If absent, its value defaults to content type "application/octet- 1093 stream" or content format 42. 1095 5.2.5. Directives 1097 Directives provide the ability to manipulate the environment when 1098 processing a list of elements. All directives start with a number 1099 sign ("#") followed by a directive identifier. Directive identifiers 1100 are case-insensitive and constrained to Unicode characters in the 1101 Basic Latin block. 1103 The following directives are available: Base IRI directives and Using 1104 directives. 1106 directive = base-directive / using-directive 1108 5.2.5.1. Base IRI Directives 1110 A Base IRI directive consists of a number sign ("#"), followed by the 1111 case-insensitive identifier "base", followed by an IRI reference. 1113 base-directive = "#" "base" iri 1115 The IRI reference MAY be relative or absolute, and MUST be resolved 1116 against the current context IRI. 1118 The directive is processed by resolving the IRI reference against the 1119 current context IRI and assigning the result to the current base IRI. 1121 5.2.5.2. Using Directives 1123 A Using directive consists of a number sign ("#"), followed by the 1124 case-insensitive identifier "using", optionally followed by an 1125 identifier and an equals sign ("="), finally followed by an absolute 1126 IRI reference. If the identifier is not specified, it is assumed to 1127 be the empty string. 1129 using-directive = "#" "using" [identifier "="] iri 1131 The IRI reference MUST be absolute. 1133 The directive is processed by adding the specified identifier and IRI 1134 to the current mapping from identifiers to IRIs. It is an error if 1135 the identifier is already present in the mapping. 1137 6. Usage Considerations 1139 This section discusses some considerations in creating CoRAL-based 1140 applications and managing link and form relation types. 1142 6.1. Specifying CoRAL-based Applications 1144 CoRAL-based applications naturally implement the Web architecture 1145 [W3C.REC-webarch-20041215] and thus are centered around orthogonal 1146 specifications for identification, interaction, and representation: 1148 o Resources are identified by IRIs or represented by value literals. 1150 o Interactions are based on the hypermedia interaction model of the 1151 Web and the methods provided by the Web transfer protocol. The 1152 semantics of possible interactions are identified by link and form 1153 relation types. 1155 o Representations are CoRAL documents encoded in the binary format 1156 defined in Section 4 or the textual format defined in Section 5. 1157 Depending on the application, additional representation formats 1158 may be used. 1160 Specifications for CoRAL-based applications need to list the specific 1161 components used in the application and their identifiers. This 1162 SHOULD include at least the following items: 1164 o IRI schemes that identify the Web transfer protocol(s) used in the 1165 application. 1167 o Internet media types that identify the representation format(s) 1168 used in the application, including the media type(s) of the CoRAL 1169 serialization format(s). 1171 o Link relation types that identify the semantics of links. 1173 o Form relation types that identify the semantics of forms. 1174 Additionally, for each form relation type, the permissible request 1175 method(s). 1177 o Form field names that identify the semantics of form fields. 1178 Additionally, for each form field name, the permissible form field 1179 value(s) or type(s). 1181 6.1.1. Naming Resources 1183 Resource names -- URIs [RFC3986] and IRIs [RFC3987] -- are a 1184 cornerstone of Web-based applications. They enable the uniform 1185 identification of resources and are used every time a client 1186 interacts with a server or a resource representation needs to refer 1187 to another resource. 1189 URIs and IRIs often include structured application data in the path 1190 and query components, such as paths in a filesystem or keys in a 1191 database. It is a common practice in many HTTP-based applications to 1192 make this part of the application specification, i.e., to prescribe 1193 fixed URI templates that are hard-coded in implementations. There 1194 are, however, a number of problems with this practice [RFC7320]. 1196 In CoRAL-based applications, resource names are not part of the 1197 application specification; they are an implementation detail. The 1198 specification of a CoRAL-based application MUST NOT mandate any 1199 particular form of resource name structure. BCP 190 [RFC7320] 1200 describes the problematic practice of fixed URI structures in more 1201 detail and provides some acceptable alternatives. 1203 6.1.2. Implementation Limits 1205 This document places no restrictions on the number of elements in a 1206 CoRAL document or the depth of nested elements. Applications using 1207 CoRAL (in particular those running in constrained environments) MAY 1208 wish to limit these numbers and specify implementation limits that an 1209 application implementation must at least support to be interoperable. 1211 Applications MAY also mandate the following and other restrictions: 1213 o use of only either the binary format or the text format; 1215 o use of only either HTTP or CoAP as supported Web transfer 1216 protocol; 1218 o use of only either IRIs or unsigned integers to denote link 1219 relation types, form relation types, and form field names; 1221 o use of only either short forms or long forms in the binary format; 1223 o use of only either HTTP content types or CoAP content formats; 1224 o use of IRI references only up to a specific length; 1226 o use of CBOR in a canonical format (Section 3.9 of RFC 7049 1227 [RFC7049]). 1229 6.2. Minting New Relation Types 1231 New link relation types, form relation types, and form field names 1232 can be minted by defining an IRI [RFC3987] that uniquely identifies 1233 the item. Although the IRI can point to a resource that contains a 1234 definition of the semantics of the relation type, clients SHOULD NOT 1235 automatically access that resource to avoid overburdening its server. 1236 The IRI SHOULD be under the control of the person or party defining 1237 it, or be delegated to them. 1239 Link relation types registered in the IANA Link Relations Registry, 1240 such as "collection" [RFC6573] or "icon" [W3C.REC-html52-20171214], 1241 can be used in CoRAL by appending the registered name to the IRI 1242 : 1244 #using iana = 1246 iana:collection 1247 iana:icon 1249 A good source for link relation types for resource metadata are RDF 1250 predicates [W3C.REC-rdf11-concepts-20140225]. An RDF statement says 1251 that some relationship, indicated by a predicate, holds between two 1252 resources. RDF predicates and link relation types can therefore 1253 often be used interchangeably. For example, a CoRAL document could 1254 describe its creator by using the FOAF vocabulary [FOAF]: 1256 #using iana = 1257 #using foaf = 1259 foaf:maker _ { 1260 iana:type 1261 foaf:familyName "Hartke" 1262 foaf:givenName "Klaus" 1263 foaf:mbox 1264 } 1266 6.3. Registering Relation Types 1268 IRIs that identify link relation types, form relation types, and form 1269 field names do not need to be registered. The inclusion of DNS names 1270 in IRIs allows for the decentralized creation of new IRIs without the 1271 risk of collisions. 1273 However, IRIs can be relatively verbose and impose a high overhead on 1274 representations. This can be a problem in constrained environments 1275 [RFC7228]. Therefore, CoRAL alternatively allows the use of unsigned 1276 integers to identify link relation types, form relation types, and 1277 form field names. These impose a much smaller overhead but instead 1278 need to be assigned by a registry to avoid collisions. 1280 This document does not create a registry for such integers. Instead, 1281 the media types for CoRAL documents in the binary and textual format 1282 are defined to have a "profile" parameter [RFC6906] that determines 1283 the registry in use. The registry is identified by a URI [RFC3986]. 1284 For example, a CoRAL document that uses the registry identified by 1285 the URI can use the following media 1286 type: 1288 application/coral+cbor; profile="http://example.com/registry" 1290 The URI serves only as an identifier; it does not necessarily have to 1291 be dereferencable (or even use a dereferencable URI scheme). It is 1292 permissible, though, to use a dereferencable URI and to serve a 1293 representation that provides information about the registry in a 1294 human- or machine-readable way. (The format of such a representation 1295 is outside the scope of this document.) 1297 For simplicity, a CoRAL document can use unsigned integers from only 1298 one registry. The "profile" parameter of the CoRAL media types MUST 1299 contain a single URI, not a white space separated list of URIs as 1300 recommended by RFC 6906 [RFC6906]. If the "profile" parameter is 1301 absent, the default profile specified in Appendix B of this document 1302 is assumed. 1304 A CoRAL registry SHOULD map each unsigned integer to a full IRI that 1305 identifies a link relation type, form relation type, or form field 1306 name. Once an integer has been assigned, the assignment MUST NOT be 1307 changed or removed. A registry MAY provide additional information 1308 about an assignment that MAY change over time. 1310 In CoAP [RFC7252], media types (including specific values for their 1311 parameters) are encoded as an unsigned integer called the _content 1312 format_. For use with CoAP, each CoRAL registry needs to register a 1313 new content format in the IANA CoAP Content-Formats Registry. Each 1314 such registered content format MUST specify a CoRAL media type with a 1315 "profile" parameter that contains the registry URI. 1317 6.4. Expressing Link Target Attributes 1319 Link target attributes defined for use with CoRE Link Format 1320 [RFC6690] (such as "type", "hreflang", "media", "ct", "rt", "if", 1321 "sz", and "obs") can be expressed in CoRAL by nesting links under the 1322 respective link and specifying the attribute name appended to the IRI 1323 as the link relation type. 1325 If the expressed link target attribute has a value, the target of the 1326 nested link MUST be a text string; otherwise, the target MUST be the 1327 Boolean value "true": 1329 #using iana = 1330 #using attr = 1332 iana:item { 1333 attr:type "application/json-patch+json" 1334 attr:ct "51" 1335 attr:sz "247" 1336 attr:obs true 1337 } 1339 [[NOTE TO RFC EDITOR: Please replace all occurrences of "http://TBD/" 1340 in this document with an IETF-controlled IRI, such as "urn:ietf:..." 1341 or "http://...ietf.org/...".]] 1343 Link target attributes that do not actually describe the link target 1344 but the link itself (such as "rel", "anchor", "rev", "title", and 1345 "title*") are excluded from this provision and MUST NOT occur in a 1346 CoRAL document. 1348 6.5. Embedding CoRAL in CBOR Structures 1350 Data items in the CoRAL binary format (Section 4) MAY be embedded in 1351 other CBOR [RFC7049] data structures. Specifications using CDDL 1352 [I-D.ietf-cbor-cddl] SHOULD reference the following CDDL definitions 1353 for this purpose: 1355 CoRAL-Body = body 1357 CoRAL-Link = link 1359 CoRAL-Form = form 1361 7. Security Considerations 1363 Parsers of CoRAL documents must operate on input that is assumed to 1364 be untrusted. This means that parsers MUST fail gracefully in the 1365 face of malicious inputs. Additionally, parsers MUST be prepared to 1366 deal with resource exhaustion (e.g., resulting from the allocation of 1367 big data items) or exhaustion of the call stack (stack overflow). 1368 See Section 8 of RFC 7049 [RFC7049] for security considerations 1369 relating to parsing CBOR. 1371 Implementers of the CoRAL textual format need to consider the 1372 security aspects of handling Unicode input. See the Unicode Standard 1373 Annex #36 [UNICODE-UAX36] for security considerations relating to 1374 visual spoofing and misuse of character encodings. See Section 10 of 1375 RFC 3629 [RFC3629] for security considerations relating to UTF-8. 1377 CoRAL makes extensive use of IRIs and URIs. See Section 8 of RFC 1378 3987 [RFC3987] for security considerations relating to IRIs. See 1379 Section 7 of RFC 3986 [RFC3986] for security considerations relating 1380 to URIs. 1382 The security of applications using CoRAL can depend on the proper 1383 preparation and comparison of internationalized strings. For 1384 example, such strings can be used to make authentication and 1385 authorization decisions, and the security of an application could be 1386 compromised if an entity providing a given string is connected to the 1387 wrong account or online resource based on different interpretations 1388 of the string. See RFC 6943 [RFC6943] for security considerations 1389 relating to identifiers in IRIs and other locations. 1391 CoRAL is intended to be used in conjunction with a Web transfer 1392 protocol like HTTP or CoAP. See Section 9 of RFC 7320 [RFC7230], 1393 Section 9 of RFC 7231 [RFC7231], etc., for security considerations 1394 relating to HTTP. See Section 11 of RFC 7252 [RFC7252] for security 1395 considerations relating to CoAP. 1397 CoRAL does not define any specific mechanisms for protecting the 1398 confidentiality and integrity of CoRAL documents. It relies on 1399 application layer or transport layer mechanisms for this, such as 1400 Transport Layer Security (TLS) [RFC8446]. 1402 CoRAL documents and the structure of a web of resources revealed from 1403 automatically following links can disclose personal information and 1404 other sensitive information. Implementations need to prevent the 1405 unintentional disclosure of such information. See Section of 9 of 1406 RFC 7231 [RFC7231] for additional considerations. 1408 Applications using CoRAL ought to consider the attack vectors opened 1409 by automatically following, trusting, or otherwise using links and 1410 forms in CoRAL documents. In particular, a server that is 1411 authoritative for the CoRAL representation of a resource may not 1412 necessarily be authoritative for elements nested inside the top level 1413 links in the document. 1415 8. IANA Considerations 1417 8.1. Media Type "application/coral+cbor" 1419 This document registers the media type "application/coral+cbor" 1420 according to the procedures of BCP 13 [RFC6838]. 1422 Type name: 1423 application 1425 Subtype name: 1426 coral+cbor 1428 Required parameters: 1429 N/A 1431 Optional parameters: 1432 profile - See Section 6.3 of [I-D.hartke-t2trg-coral]. 1434 Encoding considerations: 1435 binary - See Section 4 of [I-D.hartke-t2trg-coral]. 1437 Security considerations: 1438 See Section 7 of [I-D.hartke-t2trg-coral]. 1440 Interoperability considerations: 1441 N/A 1443 Published specification: 1444 [I-D.hartke-t2trg-coral] 1446 Applications that use this media type: 1447 See Section 1 of [I-D.hartke-t2trg-coral]. 1449 Fragment identifier considerations: 1450 As specified for "application/cbor". 1452 Additional information: 1453 Deprecated alias names for this type: N/A 1454 Magic number(s): N/A 1455 File extension(s): N/A 1456 Macintosh file type code(s): N/A 1458 Person & email address to contact for further information: 1459 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1461 Intended usage: 1462 COMMON 1464 Restrictions on usage: 1465 N/A 1467 Author: 1468 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1470 Change controller: 1471 IESG 1473 Provisional registration? 1474 No 1476 8.2. Media Type "text/coral" 1478 This document registers the media type "text/coral" according to the 1479 procedures of BCP 13 [RFC6838] and guidelines in RFC 6657 [RFC6657]. 1481 Type name: 1482 text 1484 Subtype name: 1485 coral 1487 Required parameters: 1488 N/A 1490 Optional parameters: 1491 profile - See Section 6.3 of [I-D.hartke-t2trg-coral]. 1493 Encoding considerations: 1494 binary - See Section 5 of [I-D.hartke-t2trg-coral]. 1496 Security considerations: 1497 See Section 7 of [I-D.hartke-t2trg-coral]. 1499 Interoperability considerations: 1500 N/A 1502 Published specification: 1503 [I-D.hartke-t2trg-coral] 1505 Applications that use this media type: 1506 See Section 1 of [I-D.hartke-t2trg-coral]. 1508 Fragment identifier considerations: 1509 N/A 1511 Additional information: 1512 Deprecated alias names for this type: N/A 1513 Magic number(s): N/A 1514 File extension(s): .coral 1515 Macintosh file type code(s): TEXT 1517 Person & email address to contact for further information: 1518 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1520 Intended usage: 1521 COMMON 1523 Restrictions on usage: 1524 N/A 1526 Author: 1527 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1529 Change controller: 1530 IESG 1532 Provisional registration? 1533 No 1535 8.3. CoAP Content Formats 1537 This document registers CoAP content formats for the media types 1538 "application/coral+cbor" and "text/coral" according to the procedures 1539 of RFC 7252 [RFC7252]. 1541 o Media Type: application/coral+cbor 1542 Content Coding: identity 1543 ID: TBD (maybe 63) 1544 Reference: [I-D.hartke-t2trg-coral] 1546 o Media Type: text/coral 1547 Content Coding: identity 1548 ID: TBD (maybe 10063) 1549 Reference: [I-D.hartke-t2trg-coral] 1551 9. References 1553 9.1. Normative References 1555 [I-D.hartke-t2trg-ciri] 1556 Hartke, K., "Constrained Internationalized Resource 1557 Identifiers", draft-hartke-t2trg-ciri-00 (work in 1558 progress), October 2018. 1560 [I-D.ietf-cbor-cddl] 1561 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1562 definition language (CDDL): a notational convention to 1563 express CBOR and JSON data structures", draft-ietf-cbor- 1564 cddl-05 (work in progress), August 2018. 1566 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1567 Requirement Levels", BCP 14, RFC 2119, 1568 DOI 10.17487/RFC2119, March 1997, 1569 . 1571 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1572 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1573 2003, . 1575 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1576 Resource Identifier (URI): Generic Syntax", STD 66, 1577 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1578 . 1580 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1581 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 1582 January 2005, . 1584 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1585 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1586 . 1588 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1589 Specifications: ABNF", STD 68, RFC 5234, 1590 DOI 10.17487/RFC5234, January 2008, 1591 . 1593 [RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding 1594 "charset" Parameter Handling in Textual Media Types", 1595 RFC 6657, DOI 10.17487/RFC6657, July 2012, 1596 . 1598 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1599 Specifications and Registration Procedures", BCP 13, 1600 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1601 . 1603 [RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for 1604 Security Purposes", RFC 6943, DOI 10.17487/RFC6943, May 1605 2013, . 1607 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1608 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1609 October 2013, . 1611 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1612 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1613 May 2017, . 1615 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1616 DOI 10.17487/RFC8288, October 2017, 1617 . 1619 [UNICODE] The Unicode Consortium, "The Unicode Standard", 1620 . 1622 Note that this reference is to the latest version of 1623 Unicode, rather than to a specific release. It is not 1624 expected that future changes in the Unicode specification 1625 will have any impact on this document. 1627 [UNICODE-UAX15] 1628 The Unicode Consortium, "Unicode Standard Annex #15: 1629 Unicode Normalization Forms", 1630 . 1632 [UNICODE-UAX31] 1633 The Unicode Consortium, "Unicode Standard Annex #31: 1634 Unicode Identifier and Pattern Syntax", 1635 . 1637 [UNICODE-UAX36] 1638 The Unicode Consortium, "Unicode Standard Annex #36: 1639 Unicode Security Considerations", 1640 . 1642 9.2. Informative References 1644 [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification 1645 0.99", January 2014, 1646 . 1648 [I-D.ietf-core-links-json] 1649 Li, K., Rahman, A., and C. Bormann, "Representing 1650 Constrained RESTful Environments (CoRE) Link Format in 1651 JSON and CBOR", draft-ietf-core-links-json-10 (work in 1652 progress), February 2018. 1654 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1655 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1656 . 1658 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 1659 RFC 6573, DOI 10.17487/RFC6573, April 2012, 1660 . 1662 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1663 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1664 . 1666 [RFC6903] Snell, J., "Additional Link Relation Types", RFC 6903, 1667 DOI 10.17487/RFC6903, March 2013, 1668 . 1670 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, 1671 DOI 10.17487/RFC6906, March 2013, 1672 . 1674 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1675 Constrained-Node Networks", RFC 7228, 1676 DOI 10.17487/RFC7228, May 2014, 1677 . 1679 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1680 Protocol (HTTP/1.1): Message Syntax and Routing", 1681 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1682 . 1684 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1685 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1686 DOI 10.17487/RFC7231, June 2014, 1687 . 1689 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1690 Application Protocol (CoAP)", RFC 7252, 1691 DOI 10.17487/RFC7252, June 2014, 1692 . 1694 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 1695 RFC 7320, DOI 10.17487/RFC7320, July 2014, 1696 . 1698 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1699 FETCH Methods for the Constrained Application Protocol 1700 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1701 . 1703 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1704 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1705 . 1707 [W3C.REC-html52-20171214] 1708 Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and 1709 S. Moon, "HTML 5.2", World Wide Web Consortium 1710 Recommendation REC-html52-20171214, December 2017, 1711 . 1713 [W3C.REC-rdf11-concepts-20140225] 1714 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 1715 Concepts and Abstract Syntax", World Wide Web Consortium 1716 Recommendation REC-rdf11-concepts-20140225, February 2014, 1717 . 1719 [W3C.REC-turtle-20140225] 1720 Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", 1721 World Wide Web Consortium Recommendation REC-turtle- 1722 20140225, February 2014, 1723 . 1725 [W3C.REC-webarch-20041215] 1726 Jacobs, I. and N. Walsh, "Architecture of the World Wide 1727 Web, Volume One", World Wide Web Consortium 1728 Recommendation REC-webarch-20041215, December 2004, 1729 . 1731 Appendix A. Core Vocabulary 1733 This section defines the core vocabulary for CoRAL. It is 1734 RECOMMENDED that all CoRAL registries assign an unsigned integer to 1735 each of these link relation types, form relation types, and form 1736 field names. 1738 [[NOTE TO RFC EDITOR: Please replace all occurrences of "urn:TBD" in 1739 this document with an IETF-controlled IRI, such as "urn:ietf:..." or 1740 "http://...ietf.org/...".]] 1742 A.1. Link Relation Types 1744 1745 Indicates that the link's context is an instance of the type 1746 specified as the link's target; see Section 6 of RFC 6903 1747 [RFC6903]. 1749 This link relation type serves in CoRAL the same purpose as the 1750 RDF predicate identified by the IRI . 1753 1754 Indicates that the link's context is a collection and that the 1755 link's target is a member of that collection; see Section 2.1 of 1756 RFC 6573 [RFC6573]. 1758 1759 Indicates that the link's target is a collection and that the 1760 link's context is a member of that collection; see Section 2.2 of 1761 RFC 6573 [RFC6573]. 1763 A.2. Form Relation Types 1765 1766 Indicates that the form's context is a collection and that a new 1767 item can be created in that collection by submitting a suitable 1768 representation. This form relation type is typically used with 1769 the POST method [RFC7231] [RFC7252]. 1771 1772 Indicates that the form's context can be updated by submitting a 1773 suitable representation. This form relation type is typically 1774 used with the PUT method [RFC7231] [RFC7252], PATCH method 1775 [RFC5789] [RFC8132], or iPATCH method [RFC8132]. 1777 1778 Indicates that the form's context can be deleted. This form 1779 relation type is typically used with the DELETE method [RFC7231] 1780 [RFC7252]. 1782 1783 Indicates that the form's context can be searched by submitting a 1784 search query. This form relation type is typically used with the 1785 POST method [RFC7231] [RFC7252] or FETCH method [RFC8132]. 1787 A.3. Form Field Names 1789 1790 Specifies an acceptable HTTP content type or CoAP content format 1791 for the request payload. There MAY be multiple form fields with 1792 this name. If a form does not include a form field with this 1793 name, the server accepts any or no request payload, depending on 1794 the form relation type. 1796 For HTTP, the content type MUST be specified as a text string in 1797 the format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the 1798 set of possible values is maintained in the IANA Media Types 1799 Registry. For CoAP, the content format MUST be specified as an 1800 unsigned integer; the set of possible values is maintained in the 1801 IANA CoAP Content-Formats Registry. 1803 Appendix B. Default Profile 1805 This section defines a default registry that is assumed when a CoRAL 1806 media type without a "profile" parameter is used. 1808 0 = 1810 1 = 1812 2 = 1814 3 = 1816 4 = 1818 5 = 1820 6 = 1822 7 = 1824 Author's Address 1826 Klaus Hartke 1827 Ericsson 1828 Torshamnsgatan 23 1829 Stockholm SE-16483 1830 Sweden 1832 Email: klaus.hartke@ericsson.com