idnits 2.17.1 draft-hartke-t2trg-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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 13, 2017) is 2593 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 520 == Missing Reference: 'H' is mentioned on line 284, but not defined == Missing Reference: 'R' is mentioned on line 284, but not defined -- Looks like a reference, but probably isn't: '2' on line 520 == Missing Reference: 'F' is mentioned on line 283, but not defined == Missing Reference: 'B' is mentioned on line 283, but not defined -- Looks like a reference, but probably isn't: '4' on line 283 -- Looks like a reference, but probably isn't: '3' on line 520 == Missing Reference: 'A' is mentioned on line 284, but not defined == Missing Reference: 'RFCXXXX' is mentioned on line 712, but not defined ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-11) exists of draft-greevenbosch-appsawg-cbor-cddl-09 == Outdated reference: A later version (-08) exists of draft-hartke-core-apps-07 == Outdated reference: A later version (-14) exists of draft-ietf-core-interfaces-08 == Outdated reference: A later version (-10) exists of draft-ietf-core-links-json-06 == Outdated reference: A later version (-11) exists of draft-kelly-json-hal-08 Summary: 2 errors (**), 0 flaws (~~), 12 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Thing-to-Thing Research Group K. Hartke 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Experimental March 13, 2017 5 Expires: September 14, 2017 7 The Constrained RESTful Application Language (CoRAL) 8 draft-hartke-t2trg-coral-02 10 Abstract 12 The Constrained RESTful Application Language (CoRAL) is a compact, 13 binary representation format for building RESTful, hypermedia-driven 14 applications that run in constrained environments. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on September 14, 2017. 33 Copyright Notice 35 Copyright (c) 2017 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 52 2. Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 3. Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 54 4. Options . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 55 4.1. Accept . . . . . . . . . . . . . . . . . . . . . . . . . 8 56 4.2. Deletable . . . . . . . . . . . . . . . . . . . . . . . . 8 57 4.3. Format . . . . . . . . . . . . . . . . . . . . . . . . . 8 58 4.4. Href.* . . . . . . . . . . . . . . . . . . . . . . . . . 8 59 4.5. Method . . . . . . . . . . . . . . . . . . . . . . . . . 10 60 4.6. Relation . . . . . . . . . . . . . . . . . . . . . . . . 10 61 4.7. Title . . . . . . . . . . . . . . . . . . . . . . . . . . 10 62 4.8. Updatable . . . . . . . . . . . . . . . . . . . . . . . . 10 63 5. Reference Resolution . . . . . . . . . . . . . . . . . . . . 10 64 5.1. Establish a Base URI . . . . . . . . . . . . . . . . . . 11 65 5.2. Transform References . . . . . . . . . . . . . . . . . . 11 66 5.3. Remove Dot Segments . . . . . . . . . . . . . . . . . . . 12 67 6. Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . 12 68 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 69 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 70 8.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 14 71 8.2. Content Format . . . . . . . . . . . . . . . . . . . . . 15 72 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 73 9.1. Normative References . . . . . . . . . . . . . . . . . . 16 74 9.2. Informative References . . . . . . . . . . . . . . . . . 16 75 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 18 76 A.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 18 77 A.2. CoRE Lighting . . . . . . . . . . . . . . . . . . . . . . 23 78 A.3. CoRE Link Format . . . . . . . . . . . . . . . . . . . . 24 79 A.4. CoRE Interfaces . . . . . . . . . . . . . . . . . . . . . 25 80 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 26 81 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 26 83 1. Introduction 85 Constrained RESTful Environments (CoRE) realize the Web architecture 86 [W3C.REC-webarch-20041215] in a suitable form for constrained nodes 87 and networks [RFC7228]. 89 In the Web, hypertext documents contain links and forms that allow a 90 user to navigate between resources and submit information to a server 91 for processing. By annotating these elements with machine-readable 92 link relation types [RFC5988] and form relation types, it is possible 93 to extend this interaction model to machine-to-machine communication. 95 This document describes the Constrained RESTful Application Language 96 (CoRAL), a compact serialization format for Web links and forms that 97 is based on Concise Binary Object Representation (CBOR) [RFC7049] and 98 that aligns closely with the Constrained Application Protocol (CoAP) 99 [RFC7252]. 101 1.1. Terminology 103 Readers are expected to be familiar with the terms and concepts 104 described in [RFC5988] and [I-D.hartke-core-apps]. 106 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 107 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 108 "OPTIONAL" in this document are to be interpreted as described in 109 [RFC2119]. 111 2. Model 113 CoRAL is designed for building hypermedia-driven Web applications in 114 which software agents navigate between resources by following links 115 and interact with resources by submitting forms. 117 Each agent maintains a "browsing context", an environment in which 118 resource representations are processed. (In the traditional Web, the 119 browsing context corresponds to a tab or window in a Web browser.) A 120 browsing context has a session history, which lists the resources 121 that the browsing context has visited, is visiting, or will visit. 122 At any time, one resource in a browsing context is designated the 123 "current" resource. Following a link or submitting a form causes the 124 browsing context to navigate to a new resource. 126 A link indicates a relationship between two resources, the link 127 context and the link target, and affords the navigation between 128 these. The semantics of the relationship are identified by a link 129 relation type, which in CoRAL can be IANA-registered or application- 130 specific. To minimize round-trips, a link in CoRAL can optionally 131 embed a (complete or partial) representation of the link target. 132 Furthermore, a link target can be an anonymous resource in CoRAL; in 133 this case, the link turns into a "literal" which consists only of a 134 link relation type and a representation. 136 A form similarly indicates a relationship between two resources, the 137 form context and the form target, and affords the interaction with 138 the context through the submission of the form to the target. In 139 many cases, the target of a form is the same resource as the context, 140 but this is not required. The semantics of a form are identified by 141 a form relation type, which again in CoRAL can be IANA-registered or 142 application-specific. 144 The submission of a form typically requires the agent to construct a 145 payload that is included with the request. For this purpose, a form 146 indicates the acceptable content formats for the payload and can 147 optionally embed a detailed description of the expected data, for 148 example, as a list of form fields. (The syntax for such a 149 description is outside this document's scope.) 151 The CoRAL interaction model is as follows: 153 1. The first step for an agent is to decide what to do next, i.e., 154 which type of link to follow or form to submit, based on the link 155 relation types and form relation types it understands. 157 2. The agent finds the link(s) or form(s) with the given relation 158 type in the current resource. This may yield one or more 159 candidates from which the agent must select the most appropriate 160 one. The set of candidates may be empty if the transition is not 161 allowed, for example, when the agent is unauthorized. The format 162 of links and forms in CoRAL is specified in Section 3. 164 3. The agent selects one of the candidates based on the metadata 165 associated with the link or form. Metadata can include the 166 content format of the target resource representation, the URI 167 scheme, the request method and other attributes that describe the 168 target. Metadata is encoded in CoRAL as CoAP-style options, 169 which are specified in Section 4. 171 4. The agent resolves the URI reference in the link or form to its 172 absolute form in order to obtain the "request URI". CoRAL 173 encodes URI references like CoAP as a sequence of options, which 174 significantly simplifies the implementation of URI processors 175 compared to full RFC 3986 support. The process of reference 176 resolution is specified in Section 5. 178 5. The agent constructs a new request with the request URI. If the 179 agent follows a link, the request method is GET. If the agent 180 submits a form, the request method is indicated by an option. 181 The agent SHOULD set request parameters according to the link/ 182 form attributes (e.g., set the CoAP Accept option when the 183 content format of the target resource is indicated). In the case 184 of a form, the agent also needs to construct a request payload 185 that matches the specifications of the form. 187 6. Finally, the agent sends the request and retrieves the response. 188 The agent processes the enclosed representation, updates the 189 browsing context to the new resource, and again can decide what 190 to do next. 192 An agent can additionally navigate a browsing context by traversing 193 the browsing context's session history. The session history consists 194 of a flat list of session history entries, which consist of a URI and 195 may have other information associated with them. Session history 196 entries are added to the session history as the agent navigates from 197 resource to resource. An agent can traverse the session history by 198 updating the browsing context to the resource for that entry. 200 3. Format 202 CoRAL can be used as a standalone representation format or embedded 203 in representations in other formats. As a standalone format, CoRAL 204 representations have the media type 'application/coral'. When CoRAL 205 is embedded, it is typically embedded in CBOR-based representation 206 formats, but other representation formats can embed CoRAL as well. 207 The CoRAL format is in all cases the same. 209 The top-level structure of CoRAL is called a CoRAL document. A CoRAL 210 document consists of a sequence of links, forms, literals and bases, 211 which are collectively called elements. All elements consist of a 212 number indicating the element type, a "href type" that indicates how 213 CoRAL-encoded URI references are to be interpreted in reference 214 resolution, a sequence of zero or more options and, optionally, a 215 body. 217 Link, form and literal elements come in two flavors: a "fat" format 218 that includes all the items listed above, and a "tiny" format. The 219 tiny formats provide a concise way to express elements that match 220 certain patterns, which are specified below. Base elements are 221 always in the "fat" format. They encode a base URI for reference 222 resolution and apply to all subsequent elements until the next base 223 element is encountered. 225 In the Web, link relation types are identified by strings, such as 226 'stylesheet', 'terms-of-service' or 'item'. In order to minimize the 227 overhead of using these relation types in constrained environments, 228 [I-D.hartke-core-apps] extends the IANA Link Relation Types registry 229 with a numeric identifier for each type. CoRAL uses these numeric 230 identifiers instead of the textual names. The same optimization is 231 applied to form relation types, CoAP content formats and CoAP request 232 methods. 234 Applications MAY use negative numbers to indicate application- 235 specific link relation types and form relation types, which do not 236 need to be IANA-registered. The mapping from numbers to textual 237 names needs to be provided by a CoRAL profile, which is indicated by 238 the optional 'profile' parameter of the 'application/coral' media 239 type (see Section 6). The 'application/coral' media type without a 240 'profile' parameter does not define any application-specific values. 241 A representation format embedding CoRAL documents MAY define 242 application-specific values for the CoRAL documents as well. 244 CoRAL defines a number of options that can be included in elements. 245 Options are used to encode the relation type, the target resource URI 246 and target attributes. Options are serialized in CBOR as a sequence 247 of unwrapped pairs where each pair consists of a CoRAL option number 248 and an option value. The pairs in a CoRAL element MUST be sorted 249 such that the option numbers appear in ascending order. 251 Using the notation of [I-D.greevenbosch-appsawg-cbor-cddl], the CoRAL 252 data format can be expressed as follows: 254 document = [*element] 255 element = tiny-link / tiny-literal / tiny-form 256 / fat-link / fat-literal / fat-form 257 / base 259 tiny-link = [1, href-type, relation] 260 tiny-literal = [2, href-type, relation, format, body] 261 tiny-form = [3, href-type, relation, accept] 262 base = [4, href-type, options] 263 fat-link = [5, href-type, options, ?body] 264 fat-literal = [6, href-type, options, body] 265 fat-form = [7, href-type, options, ?body] 267 href-type = &(append-relation: 0, 268 absolute-path: 1, 269 append-path: 2, 270 relative-path: 3) 272 relation = int 273 format = uint 274 accept = uint 275 options = [*(option-number, option-value)] 276 option-number = uint 277 option-value = uint / int / text / bytes 278 body = bytes 280 The tiny formats expand as follows: 282 [1, H, R] -> [5, H, [1, R]] 283 [2, H, R, F, B] -> [6, H, [1, R, 4, F], B] 284 [3, H, R, A] -> [7, H, [1, R, 3, A]] 286 4. Options 288 Table 1 summarizes the CoRAL options defined in this document. 290 +-----+---+----------------+--------+--------+-------------+ 291 | No. | R | Name | Format | Length | Default | 292 +-----+---+----------------+--------+--------+-------------+ 293 | 1 | x | Relation | int | | (none) | 294 | 2 | | Method | uint | | 2 (POST) | 295 | 3 | x | Accept | uint | | (none) | 296 | 4 | x | Format | uint | | (none) | 297 | 5 | | Href.Scheme | text | 1-255 | (none) | 298 | 6 | | Href.Host.Name | text | 1-255 | (none) | 299 | 7 | | Href.Host.IPv4 | bytes | 4 | (none) | 300 | 8 | | Href.Host.IPv6 | bytes | 16 | (none) | 301 | 9 | | Href.Port | uint | | (see below) | 302 | 10 | x | Href.Path | text | 0-255 | (none) | 303 | 11 | x | Href.Query | text | 0-255 | (none) | 304 | 12 | | Href.Fragment | text | 0-255 | (none) | 305 | 13 | | Title | text | 0-255 | (none) | 306 | 14 | | Updatable | bool | | false | 307 | 15 | | Deletable | bool | | false | 308 +-----+---+----------------+--------+--------+-------------+ 310 Table 1: Options 312 The option properties are defined as follows: 314 Number: An option is identified by an option number. 316 Repeatable (R): An option that is repeatable MAY be included one or 317 more times in an element. An option that is not repeatable MUST 318 NOT be included more than once. If an agent encounters an option 319 with more occurrences than the option is defined for, each extra 320 occurrence MUST be ignored. 322 Format: Option values are defined to have a certain format, which is 323 the CBOR encoding of the specified type. 325 Length: Option values with types "text" and "bytes" are defined to 326 have a specific length, often in the form of an upper and lower 327 bound. The length of an option value MUST NOT be outside the 328 defined range. If an agent encounters an option with a length 329 outside the defined range, that option MUST be ignored. 331 Default Value: Options can be defined to have a default value. If 332 the value of an option is intended to be this default value, the 333 option SHOULD NOT be included in the element. If the option is 334 not present, the default value MUST be assumed. 336 The semantics of the individual options are specified in the 337 following sections. 339 4.1. Accept 341 The Accept Option indicates the acceptable content formats for the 342 representation included in a form submission. The option value of an 343 Accept Option is one of the content format IDs registered in the CoAP 344 Content-Formats registry. If a form does not include an Accept 345 Option, the service accepts any content format. 347 4.2. Deletable 349 The Deletable Option, when present in a link, defines a form that can 350 be used to delete the link target. The form relation type of that 351 form is 'delete', the context and target of the form are identical to 352 the target of the link, the submission method is DELETE and no 353 representation must be submitted. 355 4.3. Format 357 The Format Option, when present in a link or a form, provides a hint 358 indicating what the content format of the payload of the CoAP 359 response should be when following the link or submitting the form. 360 Note that this is only a hint; it does not override the Content- 361 Format Option included in the CoAP response. If the Format Option 362 occurs more than once, an agent SHOULD set the Accept Option in the 363 CoAP request message to request a particular content format. 365 The Format Option is REQUIRED if a link embeds a representation in 366 the link body. The Format Option is also REQUIRED in a literal. In 367 both cases, the first occurrence of the option indicates the content 368 format of the embedded representation; any additional occurrences 369 indicate available alternative content formats. 371 The option value of a Format Option is one of the content format IDs 372 registered in the CoAP Content-Formats registry. 374 4.4. Href.* 376 The Href.Scheme, Href.Host.Name, Href.Host.IPv4, Href.IPv6, 377 Href.Port, Href.Path, Href.Query and Href.Fragment Options are used 378 to specify the target resource URI of a link or form. They hold the 379 following values: 381 o the Href.Scheme Option specifies the URI scheme name, 383 o the Href.Host.Name Option specifies the host as a registered name, 385 o the Href.Host.IPv4 Option specifies the host as a 32-bit IPv4 386 address, 388 o the Href.Host.IPv6 Option specifies the host as a 128-bit IPv6 389 address, 391 o the Href.Port Option specifies the port number, 393 o each Href.Path Option specifies one segment of the path, 395 o each Href.Query Option specifies one argument of the query, and 397 o the Href.Fragment Option specifies the fragment identifier. 399 The Href.Host.Name, Href.Host.IPv4 and Href.Host.IPv6 options are 400 mutually exclusive. 402 The default value of the Href.Port Option is the default port for the 403 URI scheme. 405 Table 2 lists the permitted Href.* options by Href Type. A 'yes' 406 indicates that an option of this type MAY be present; a 'no' 407 indicates that an option of this type MUST NOT be present. The 408 resolution of a sequence of Href.* options against a base URI is 409 specified in Section 5. 411 +----------------+------------+------------+-----------+------------+ 412 | | absolute- | relative- | append- | append- | 413 | | path | path | path | relation | 414 +----------------+------------+------------+-----------+------------+ 415 | Href.Scheme | yes | no | no | no | 416 | Href.Host.Name | yes | no | no | no | 417 | Href.Host.IPv4 | yes | no | no | no | 418 | Href.Host.IPv6 | yes | no | no | no | 419 | Href.Port | yes | no | no | no | 420 | Href.Path | yes | yes | yes | no | 421 | Href.Query | yes | yes | yes | no | 422 | Href.Fragment | yes | yes | yes | no | 423 +----------------+------------+------------+-----------+------------+ 425 Table 2: Permitted Href.* Options by Href Type 427 4.5. Method 429 The Method Option, when present in a form, indicates the CoAP method 430 to use for form submission. The option value is one of the CoAP 431 method codes registered in the CoAP Method Codes registry. The 432 option value defaults to the POST method when the Method Option is 433 not present in a form. 435 4.6. Relation 437 The Relation Option indicates the link relation type of a link or 438 literal and the form relation type of a form. At least one Relation 439 Option is REQUIRED in each link, literal and form element. 441 In a link or literal, the option value of a Relation Option is either 442 one of the link relation type IDs registered in the Link Relation 443 Types registry (>= 0) or one of the application-specific link 444 relation type IDs defined by the CoRAL profile (< 0). 446 In a form, the option value of Relation Option is either one of the 447 form relation type IDs registered in the Form Relation Types registry 448 (>= 0) or one of the application-specific form relation type IDs 449 defined by the CoRAL profile (< 0). 451 4.7. Title 453 The Title Option, when present, is used to label the target of a link 454 such that it can be used as a human-readable identifier (e.g., a menu 455 entry). 457 4.8. Updatable 459 The Updatable Option, when present in a link, defines a form that can 460 be used to update the link target. The form relation type of that 461 form is 'update', the context and target of the form are identical to 462 the target of the link, the submission method is PUT and the content 463 format of the submitted representation must be one of the formats 464 indicated by the Format Option in the link. 466 5. Reference Resolution 468 This section defines the process of resolving a URI reference within 469 a link or form to an absolute URI suitable for inclusion in a CoAP 470 request. 472 5.1. Establish a Base URI 474 URI references can be relative and thus are only usable when a base 475 URI is known. This means that a base URI must be established before 476 the use of all URI references that might be relative. 478 The base URI of a reference in a link or form is established as 479 specified in Section 5.1 of [RFC3986]. CoRAL supports a "Base URI 480 Embedded in Content" in the form of base elements. A base element 481 applies to all subsequent elements in a document until the next base 482 element is encountered. The URI reference in a base element itself 483 is resolved relative to the base URI of next lower precedence (which 484 is usually the "URI used to retrieve the entity" but can be the "Base 485 URI of the encapsulating entity"). 487 5.2. Transform References 489 The following pseudocode describes an algorithm for transforming a 490 URI reference R into its target URI T using the base URI B, the href 491 type H, and the link or form relation type S. The URI reference and 492 base URI are assumed to be pre-parsed into a sequence of Href.* 493 options; the result is returned as a sequence of Href.* options as 494 well. 496 if (R starts with Href.Scheme) then 497 T = R 498 elif (R starts with Href.Host.*) then 499 T = [ (k, v) | (k, v) <- B, k == Href.Scheme ] ++ 500 [ (k, v) | (k, v) <- R, k > Href.Scheme ] 501 elif (R starts with Href.Port) then 502 T = [ (k, v) | (k, v) <- B, k < Href.Port ] ++ 503 [ (k, v) | (k, v) <- R, k >= Href.Port ] 504 elif (H is append-relation) then 505 T = [ (k, v) | (k, v) <- B, k <= Href.Path ] ++ 506 [ (Href.Path, (hex S)) ] 507 elif (H is append-path) then 508 T = [ (k, v) | (k, v) <- B, k <= Href.Path ] ++ 509 [ (k, v) | (k, v) <- R, k >= Href.Path ] 510 elif (H is relative-path) then 511 T = [ (k, v) | (k, v) <- B, k < Href.Path ] ++ 512 (init [ (k, v) | (k, v) <- B, k == Href.Path ]) ++ 513 [ (k, v) | (k, v) <- R, k >= Href.Path ] 514 elif (H is absolute-path) then 515 T = [ (k, v) | (k, v) <- B, k < Href.Path ] ++ 516 [ (k, v) | (k, v) <- R, k >= Href.Path ] 517 endif 519 The "init" function returns all the elements of the input list except 520 the last one. For example, (init [1, 2, 3]) returns [1, 2] and (init 521 []) returns []. 523 The "hex" function returns a hexadecimal representation of the input 524 number. For example, (hex -421) returns "-1A5" and (hex 0) returns 525 "0". 527 5.3. Remove Dot Segments 529 After transforming a the URI reference into its target URI, the 530 special path segments "." and ".." need to be removed. Although 531 there are many ways to accomplish this removal process, we describe a 532 simple method using two string buffers. 534 1. The input buffer is initialized with the sequence of path 535 segments and the output buffer is initialized to the empty 536 sequence. 538 2. While the input buffer is not empty, loop as follows: 540 * If the input buffer begins with a "." path segment, then 541 remove this segment from the input buffer; otherwise, 543 * if the input buffer begins with a ".." path segment, then 544 remove this segment from the input buffer and and remove the 545 last segment (if any) from the output buffer; otherwise, 547 * move the first path segment in the input buffer to the end of 548 the output buffer. 550 3. Finally, the sequence of path segments in the target URI is 551 replaced by the sequence of path segments in the output buffer. 553 6. Profiles 555 Profiles provide an easy way to extend CoRAL with application- 556 specific link relation types and form relation types. 558 Application-specific link relation types and form relation types are 559 encoded in CoRAL as negative numbers. The meaning of these numbers 560 is defined by the profile, which maps them to extension link and form 561 relation types. (An extension relation type is a URI [RFC3986] that 562 uniquely identifies the relation type; see Section 4.2 of [RFC5988].) 563 For example, a CoRAL profile for online shops could define the 564 following set of application-specific link relation types: 566 +-----+----------------------------------+ 567 | ID | Link Relation Type | 568 +-----+----------------------------------+ 569 | -80 | http://example.com/rels/order | 570 | -81 | http://example.com/rels/basket | 571 | -82 | http://example.com/rels/customer | 572 +-----+----------------------------------+ 574 Table 3: Example profile for online shops 576 A good source for existing extension link relation types are RDF 577 predicates [W3C.REC-rdf11-concepts-20140225]. An RDF statement says 578 that some relationship, indicated by a predicate, holds between two 579 resources. Link relation types and RDF predicates can therefore be 580 used interchangeably in many cases. For example, a CoRAL profile 581 could define the following mapping from link relation type numbers to 582 the FOAF vocabulary [FOAF]: 584 +------+------------------------------------+ 585 | ID | RDF Predicate | 586 +------+------------------------------------+ 587 | -100 | http://xmlns.com/foaf/0.1/name | 588 | -101 | http://xmlns.com/foaf/0.1/age | 589 | -102 | http://xmlns.com/foaf/0.1/homepage | 590 +------+------------------------------------+ 592 Table 4: Example profile for the FOAF vocabulary 594 CoRAL profiles are identified by a URI [RFC3986] and are indicated by 595 the 'profile' parameter of the 'application/coral' media type, 596 following the recommendations of [RFC6906], Section 3.1. For 597 example, the FOAF profile above could use the media type 598 'application/coral; profile="http://xmlns.com/foaf/0.1/"'. 600 The profile URI serves only as an identifier, similar to an XML 601 namespace URI [W3C.REC-xml-names-20091208]. That is, the profile URI 602 does not necessarily have to identify a dereferencable resource (or 603 even use a dereferencable URI scheme). It is possible, though, to 604 use a dereferencable URI and serve a representation that provides 605 information about the profile in a human- or machine-readable way. 606 (The format of such a representation is outside the scope of this 607 document.) 609 For simplicity, a CoRAL document can use only at most one profile at 610 the same time. The 'profile' parameter of the 'application/coral' 611 media type contains a single profile URI, not a whitespace-separated 612 list of profile URIs as recommended by [RFC6906]. 614 Profile URIs do not have to be registered. The use of DNS names in 615 them allows decentralized creation of new profile identifiers without 616 the risk of collisions. However, in CoAP the media type of a 617 representation is indicated by a small numeric identifier, called the 618 content format, not by a string of characters. A content format has 619 no internal structure and indicates a media type including specific 620 values for its parameters. For example, content format 0 indicates 621 the media type 'text/plain; charset=utf-8'. A media type 'text/ 622 plain; charset=iso-8859-1' would require a separate content format. 623 Therefore, for use with CoAP, each CoRAL profiles needs to register a 624 new content format in the "CoAP Content-Formats" registry, specifying 625 the 'application/coral' media type and the profile URI as the value 626 of the 'profile' parameter. 628 7. Security Considerations 630 TODO. 632 8. IANA Considerations 634 8.1. Media Type 636 This document registers the media type 'application/coral' in the 637 Media Types Registry. 639 Type name: 640 application 642 Subtype name: 643 coral 645 Required parameters: 646 N/A 648 Optional parameters: 650 profile 651 See Section 6 of [RFCXXXX]. 653 Encoding considerations: 654 CoRAL is a binary encoding. 656 Security considerations: 657 See Section 7 of [RFCXXXX]. 659 Interoperability considerations: 660 There are no known interoperability issues. 662 Published specification: 663 [RFCXXXX] 665 Applications that use this media type: 666 Hypermedia-driven Web applications that run on constrained nodes 667 and networks. 669 Fragment identifier considerations: 670 N/A 672 Additional information: 674 Deprecated alias names for this type: N/A 676 Magic number(s): N/A 678 File extension(s): .coral 680 Macintosh file type code(s): N/A 682 Person & email address to contact for further information: 683 See "Author's Address" section of [RFCXXXX]. 685 Intended usage: 686 COMMON 688 Restrictions on usage: 689 N/A 691 Author: 692 See "Author's Address" section of [RFCXXXX]. 694 Change controller: 695 IESG 697 8.2. Content Format 699 This document registers a content format for the 'application/coral' 700 media type in the CoAP Content-Formats Registry. 702 Media type: 703 application/coral 705 Content coding: 706 identity 708 ID: 709 TBD 711 Reference: 712 [RFCXXXX] 714 9. References 716 9.1. Normative References 718 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 719 Requirement Levels", BCP 14, RFC 2119, 720 DOI 10.17487/RFC2119, March 1997, 721 . 723 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 724 Resource Identifier (URI): Generic Syntax", STD 66, 725 RFC 3986, DOI 10.17487/RFC3986, January 2005, 726 . 728 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 729 DOI 10.17487/RFC5988, October 2010, 730 . 732 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, 733 DOI 10.17487/RFC6906, March 2013, 734 . 736 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 737 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 738 October 2013, . 740 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 741 Application Protocol (CoAP)", RFC 7252, 742 DOI 10.17487/RFC7252, June 2014, 743 . 745 9.2. Informative References 747 [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification 748 0.99", January 2014, 749 . 751 [I-D.greevenbosch-appsawg-cbor-cddl] 752 Vigano, C. and H. Birkholz, "CBOR data definition language 753 (CDDL): a notational convention to express CBOR data 754 structures", draft-greevenbosch-appsawg-cbor-cddl-09 (work 755 in progress), September 2016. 757 [I-D.hartke-core-apps] 758 Hartke, K., "CoRE Application Descriptions", draft-hartke- 759 core-apps-07 (work in progress), February 2017. 761 [I-D.hartke-core-lighting] 762 Hartke, K., "CoRE Lighting", draft-hartke-core-lighting-00 763 (work in progress), September 2015. 765 [I-D.ietf-core-interfaces] 766 Shelby, Z., Vial, M., Koster, M., and C. Groves, "Reusable 767 Interface Definitions for Constrained RESTful 768 Environments", draft-ietf-core-interfaces-08 (work in 769 progress), February 2017. 771 [I-D.ietf-core-links-json] 772 Li, K., Rahman, A., and C. Bormann, "Representing CoRE 773 Formats in JSON and CBOR", draft-ietf-core-links-json-06 774 (work in progress), July 2016. 776 [I-D.kelly-json-hal] 777 Kelly, M., "JSON Hypertext Application Language", draft- 778 kelly-json-hal-08 (work in progress), May 2016. 780 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 781 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 782 . 784 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 785 Constrained-Node Networks", RFC 7228, 786 DOI 10.17487/RFC7228, May 2014, 787 . 789 [W3C.REC-rdf11-concepts-20140225] 790 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 791 Concepts and Abstract Syntax", World Wide Web Consortium 792 Recommendation REC-rdf11-concepts-20140225, February 2014, 793 . 795 [W3C.REC-turtle-20140225] 796 Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", 797 World Wide Web Consortium Recommendation REC-turtle- 798 20140225, February 2014, 799 . 801 [W3C.REC-webarch-20041215] 802 Jacobs, I. and N. Walsh, "Architecture of the World Wide 803 Web, Volume One", World Wide Web Consortium 804 Recommendation REC-webarch-20041215, December 2004, 805 . 807 [W3C.REC-xml-names-20091208] 808 Bray, T., Hollander, D., Layman, A., Tobin, R., and H. 809 Thompson, "Namespaces in XML 1.0 (Third Edition)", World 810 Wide Web Consortium Recommendation REC-xml-names-20091208, 811 December 2009, 812 . 814 Appendix A. Examples 816 A.1. Overview 818 A.1.1. Links 820 At its core, CoRAL is just yet another serialization format for Web 821 links. For example, the following Web link (in RFC 5988 syntax): 823 ;rel=terms-of-service;type=text/plain 825 can be serialized in CoRAL as the following CBOR data item (in CBOR 826 extended diagnostic format; text enclosed in forward slashes are 827 comments): 829 [ [ 5, / fat-link / 830 1, / absolute-path / 831 [ 1, 70, / relation = terms-of-service / 832 4, 0, / format = text\plain / 833 5, "coap", / href.scheme = "coap" / 834 6, "example.com", / href.host.name = "example.com" / 835 10, "info", / href.path = "info" / 836 10, "tos" ] ] ] / href.path = "tos" / 838 Multiple links are serialized as items of the top-level array: 840 [ [ 5, / fat-link / 841 3, / relative-path / 842 [ 1, 26, / relation = first / 843 4, 0, / format = text\plain / 844 10, "page1" ] ], / href.path = "page1" / 845 [ 5, / fat-link / 846 3, / relative-path / 847 [ 1, 55, / relation = previous / 848 4, 0, / format = text\plain / 849 10, "page6" ] ], / href.path = "page6" / 850 [ 5, / fat-link / 851 3, / relative-path / 852 [ 1, 41, / relation = next / 853 4, 0, / format = text\plain / 854 10, "page8" ] ], / href.path = "page8" / 855 [ 5, / fat-link / 856 3, / relative-path / 857 [ 1, 34, / relation = last / 858 4, 0, / format = text\plain / 859 10, "page42" ] ] ] / href.path = "page42" / 861 The Format Option, when present, is a hint indicating what the CoAP 862 content format of the result of dereferencing the link should be. If 863 more than one format is available, the Format Option can be repeated: 865 [ [ 5, / fat-link / 866 3, / relative-path / 867 [ 1, 33, / relation = item / 868 4, 47, / format = application\exi / 869 4, 50, / format = application\json / 870 4, 60, / format = application\cbor / 871 10, "item1" ] ] ] / href.path = "item1" / 873 A.1.2. Embedding 875 If a representation links to many resources, it may be inefficient to 876 retrieve a representation of each link target individually. For this 877 reason, CoRAL supports the embedding of a representation of the link 878 target in the link itself: 880 [ [ 5, / fat-link / 881 3, / relative-path / 882 [ 1, 33, / relation = item / 883 4, 50, / format = application\json / 884 10, "item1" ], / href.path = "item1" / 885 h'7b20227461736b223a20 886 2252657475726e207468 887 6520626f6f6b7320746f 888 20746865206c69627261 889 7279222c202261737369 890 676e6565223a2022416c 891 69636522207d' ] ] 893 where the byte string in this example encodes the following JSON 894 object: 896 { 897 "task": "Return the books to the library", 898 "assignee": "Alice" 899 } 901 By embedding representations, it is possible to use CoRAL as a (very 902 basic) substitute for RDF [W3C.REC-rdf11-concepts-20140225]. For 903 example, the RDF graph (in Turtle [W3C.REC-turtle-20140225] syntax): 905 @prefix foaf: . 907 <> foaf:name "John Doe" ; 908 foaf:age 32 ; 909 foaf:homepage . 911 can be serialized in CoRAL as follows: 913 [ [ 2, / tiny-literal / 914 2, / append-path / 915 -100, / relation = name / 916 0, / format = text\plain / 917 h'4a6f686e20446f65' ], / "John Doe" / 918 [ 2, / tiny-literal / 919 2, / append-path / 920 -101, / relation = age / 921 7, / format = uint8 / 922 h'20' ], / 32 / 923 [ 5, / fat-link / 924 1, / absolute-path / 925 [ 1, -102, / relation = homepage / 926 5, "coap", / href.scheme = "coap" / 927 6, "www.doe.example" / href.host.name = "www.doe.example" / 928 ] ] ] 930 A.1.3. Forms 932 In addition to Web links, CoRAL supports forms. An agent can use a 933 form to perform an operation on the form context, such as updating a 934 resource or creating a new item in a collection. 936 Similar to link relation types, the semantics of a form are indicated 937 by the form relation type. The Href.* Options encode the URI of the 938 form target to which the agent should submit the form. A form 939 additionally encodes the submission method (POST, PUT, PATCH, DELETE) 940 and the description of a representation that the service expects as 941 part of form submission: 943 [ [ 7, / fat-form / 944 3, / relative-path / 945 [ 1, 1, / relation = create-item / 946 2, 2, / method = POST / 947 3, 60, / accept = application\cbor / 948 10, "items" ] ] ] / href.path = "items" / 950 The Accept Option specifies the content format of the expected 951 representation. A content format can use the body of a form to 952 describe the expected representation in more detail, for example, by 953 specifying a set of form fields that the agent needs to fill out: 955 [ [ 7, / fat-form / 956 3, / relative-path / 957 [ 1, 1, / relation = create-item / 958 2, 2, / method = POST / 959 3, 65535, / accept = example\form / 960 10, "items" ], / href.path = "items" / 961 h'6e616d652c206167652c / "name, age, homepage" / 962 20686f6d6570616765' ] ] 964 A.1.4. Editing 966 The target resource of a link may be editable. In this case, the 967 representation of such a resource typically contains one or more 968 forms that allow an agent to edit the resource. However, it may be 969 inefficient to include these forms every time a representation of the 970 link target is retrieved and more efficient to include them in 971 representations that link to that resource. CoRAL supports this with 972 two options. 974 Setting the Updatable Option in a link to true defines a form that 975 can be used to update the target resource. The context and target of 976 that form are both the target of the link, the submission method is 977 PUT and the content format of the submitted representation must be 978 one of the formats indicated by the Format Option in the link. For 979 example, given the following CoRAL representation, an agent can 980 change the recipient by making a PUT request to <./to> with the new 981 value in 'text/plain' format: 983 [ [ 5, / fat-link / 984 3, / relative-path / 985 [ 1, -120, / relation = sender / 986 4, 0, / format = text\plain / 987 10, "from", / href.path = "from" / 988 14, true ], / updatable = true / 989 h'4a756c696574' ], / "Juliet" / 990 [ 5, / fat-link / 991 3, / relative-path / 992 [ 1, -121, / relation = recipient / 993 4, 0, / format = text\plain / 994 10, "to", / href.path = "to" / 995 14, true ], / updatable = true / 996 h'526f6d656f' ], / "Romeo" / 997 [ 5, / fat-link / 998 3, / relative-path / 999 [ 1, -122, / relation = message / 1000 4, 0, / format = text\plain / 1001 10, "message", / href.path = "message" / 1002 14, true ], / updatable = true / 1003 h'4172742074686f75206e / "Art thou not Romeo, / 1004 6f7420526f6d656f2c20 / and a Montague?" / 1005 616e642061204d6f6e74 1006 616775653f' ] ] 1008 Setting the Deletable Flag in a link to true likewise defines a form 1009 that can be used to delete the target resource. 1011 A.2. CoRE Lighting 1013 CoRE Lighting [I-D.hartke-core-lighting] defines a benchmark scenario 1014 for the exploration of hypermedia-oriented design in constrained, 1015 RESTful environments. The bulletin board example in Section 5.2.1 of 1016 [I-D.hartke-core-lighting] can be encoded in CoRAL as follows: 1018 [[7, 3, [1, 1, 3, 65200, 10, "bulletins"]], 1019 [5, 1, [1, 33, 4, 65200, 6, "light-bulb.example"], <<1>>], 1020 [5, 1, [1, 33, 4, 65200, 6, "remote-control.example"], <<2>>]] 1022 where <<1>> is a byte string that encodes the following CoRAL 1023 structure: 1025 [[5, 3, [1, -100, 4, 65202, 10, "config"]], 1026 [2, 3, -101, 0, "Light 2"], 1027 [2, 3, -102, 0, "Illuminates the couch."], 1028 [2, 3, -103, 0, "Living Room"]] 1030 and <<2>> is a byte string that encodes the following CoRAL 1031 structure: 1033 [[5, 3, [1, 1, 4, 65203, 10, "state"]], 1034 [2, 3, -101, 0, "LRC 1"], 1035 [2, 3, -102, 0, "Controls Light 2."], 1036 [2, 3, -103, 0, "Living Room"]] 1038 Table 5 shows a comparison of sizes of the example encoded in CoRAL 1039 and JSON. 1041 +--------+-----------+ 1042 | Format | Size | 1043 +--------+-----------+ 1044 | JSON | 515 bytes | 1045 | CoRAL | 245 bytes | 1046 +--------+-----------+ 1048 Table 5: Size Comparison 1050 A.3. CoRE Link Format 1052 The example in this section is based on an example on page 14 of 1053 [RFC6690]: 1055 ;ct=40;title="Sensor Index", 1056 ;rt="temperature-c";if="sensor", 1057 ;rt="light-lux";if="sensor", 1058 ;anchor="/sensors/temp" 1059 ;rel="describedby", 1060 ;anchor="/sensors/temp";rel="alternate" 1062 The example can be encoded in CoRAL as follows: 1064 [[4, 1, [10, "sensors"]], 1065 [5, 2, [4, 40, 13, "Sensor Index"]], 1066 [5, 2, [10, "temp", 16, "temperature-c", 17, "sensor"]], 1067 [5, 2, [10, "light", 16, "light-lux", 17, "sensor"]], 1068 [5, 1, [1, 18, 5, "http", 6, "www.example.com", 1069 10, "sensors", 10, "t123", 18, "/sensors/temp"]], 1070 [5, 1, [1, 2, 10, "t", 18, "/sensors/temp"]]] 1072 Table 6 shows a comparison of sizes of the example encoded in CoRAL 1073 and a number of Link Format variants [I-D.ietf-core-links-json]. 1075 +--------------------+-----------+ 1076 | Format | Size | 1077 +--------------------+-----------+ 1078 | Link Format | 251 bytes | 1079 | Link Format (JSON) | 320 bytes | 1080 | Link Format (CBOR) | 203 bytes | 1081 | CoRAL | 181 bytes | 1082 +--------------------+-----------+ 1084 Table 6: Size Comparison 1086 A.4. CoRE Interfaces 1088 The example in this section is based on an example in figure 1 of 1089 [I-D.ietf-core-interfaces]: 1091 ;rt="simple.sen";if="core.b", 1092 ;rt="simple.sen.lt";if="core.s", 1093 ;rt="simple.sen.tmp";if="core.s";obs, 1094 ;rt="simple.sen.hum";if="core.s", 1095 ;rt="simple.act";if="core.b", 1096 ;rt="simple.act.led";if="core.a", 1097 ;rt="simple.act.led";if="core.a", 1098 ;rt="simple.dev";if="core.ll", 1099 ;if="core.lb" 1101 The example can be encoded in CoRAL as follows: 1103 [[5, 1, [10, "d", 10, "", 16, "simple.dev", 17, "core.ll"]], 1104 [5, 1, [10, "l", 10, "", 17, "core.lb"]], 1105 [4, 1, [17, "core.b"]], 1106 [5, 2, [10, "s", 10, "", 16, "simple.sen"]], 1107 [5, 2, [10, "a", 10, "", 16, "simple.act"]], 1108 [4, 1, [10, "s", 17, "core.s"]], 1109 [5, 2, [10, "lt", 16, "simple.sen.lt"]], 1110 [5, 2, [10, "tmp", 16, "simple.sen.tmp", 19, true]], 1111 [5, 2, [10, "hum", 16, "simple.sen.hum"]], 1112 [4, 1, [10, "a", 16, "simple.act.led", 17, "core.a"]], 1113 [5, 2, [10, "1", 10, "led"]], 1114 [5, 2, [10, "2", 10, "led"]]] 1116 Table 7 shows a comparison of sizes of the example encoded in CoRAL 1117 and a number of Link Format variants. 1119 +--------------------+-----------+ 1120 | Format | Size | 1121 +--------------------+-----------+ 1122 | Link Format | 332 bytes | 1123 | Link Format (JSON) | 456 bytes | 1124 | Link Format (CBOR) | 264 bytes | 1125 | CoRAL | 248 bytes | 1126 +--------------------+-----------+ 1128 Table 7: Size Comparison 1130 Acknowledgements 1132 This specification is heavily inspired by the JSON Hypertext 1133 Application Language (HAL) [I-D.kelly-json-hal]; the author of and 1134 contributors to that specification are acknowledged for their great 1135 work. 1137 Yassin Nasir Hassan suggested placing the hypermedia controls for 1138 modifying a link target in the link context rather than in the 1139 representation of the link target. 1141 Thanks to Carsten Bormann, Jaime Jimenez and Matthias Kovatsch for 1142 helpful comments and discussions that have shaped the document. 1144 Author's Address 1146 Klaus Hartke 1147 Universitaet Bremen TZI 1148 Postfach 330440 1149 Bremen D-28359 1150 Germany 1152 Phone: +49-421-218-63905 1153 Email: hartke@tzi.org