idnits 2.17.1 draft-hartke-t2trg-coral-01.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 (October 17, 2016) is 2749 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 512 == Missing Reference: 'H' is mentioned on line 280, but not defined == Missing Reference: 'R' is mentioned on line 280, but not defined -- Looks like a reference, but probably isn't: '2' on line 512 == Missing Reference: 'F' is mentioned on line 279, but not defined == Missing Reference: 'B' is mentioned on line 279, but not defined -- Looks like a reference, but probably isn't: '4' on line 279 -- Looks like a reference, but probably isn't: '3' on line 512 == Missing Reference: 'A' is mentioned on line 280, but not defined == Missing Reference: 'RFCXXXX' is mentioned on line 746, but not defined == Unused Reference: 'I-D.ietf-core-links-json' is defined on line 806, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** 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-04 == Outdated reference: A later version (-14) exists of draft-ietf-core-interfaces-05 == 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: 3 errors (**), 0 flaws (~~), 13 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 October 17, 2016 5 Expires: April 20, 2017 7 The Constrained RESTful Application Language (CoRAL) 8 draft-hartke-t2trg-coral-01 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 April 20, 2017. 33 Copyright Notice 35 Copyright (c) 2016 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . . . . . . . . 10 65 5.2. Transform References . . . . . . . . . . . . . . . . . . 11 66 5.3. Remove Dot Segments . . . . . . . . . . . . . . . . . . . 12 67 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 69 7.1. CoRAL Option Number Registry . . . . . . . . . . . . . . 12 70 7.2. Media Type . . . . . . . . . . . . . . . . . . . . . . . 14 71 7.3. Structured Syntax Suffix . . . . . . . . . . . . . . . . 15 72 7.4. CoAP Content-Format . . . . . . . . . . . . . . . . . . . 16 73 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 74 8.1. Normative References . . . . . . . . . . . . . . . . . . 16 75 8.2. Informative References . . . . . . . . . . . . . . . . . 17 76 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 18 77 A.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 18 78 A.2. CoRE Lighting . . . . . . . . . . . . . . . . . . . . . . 23 79 A.3. CoRE Link Format . . . . . . . . . . . . . . . . . . . . 24 80 A.4. CoRE Interfaces . . . . . . . . . . . . . . . . . . . . . 25 81 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 26 82 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 26 84 1. Introduction 86 Constrained RESTful Environments (CoRE) realize the Web architecture 87 [W3C.REC-webarch-20041215] in a suitable form for constrained nodes 88 and networks [RFC7228]. 90 In the Web, hypertext documents contain links and forms that allow a 91 user to navigate between resources and submit information to a server 92 for processing. By annotating these elements with machine-readable 93 link relation types [RFC5988] and form relation types, it is possible 94 to extend this interaction model to machine-to-machine communication. 96 This document describes the Constrained RESTful Application Language 97 (CoRAL), a compact serialization format for Web links and forms that 98 is based on the Concise Binary Object Representation (CBOR) [RFC7049] 99 and that aligns closely with the Constrained Application Protocol 100 (CoAP) [RFC7252]. 102 1.1. Terminology 104 Readers are expected to be familiar with the terms and concepts 105 described in [RFC5988] and [I-D.hartke-core-apps]. 107 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 109 "OPTIONAL" in this document are to be interpreted as described in 110 [RFC2119]. 112 2. Model 114 CoRAL is designed for building hypermedia-driven Web applications in 115 which software agents navigate between resources by following links 116 and interact with resources by submitting forms. 118 Each agent maintains a "browsing context", an environment in which 119 resource representations are processed. (In the traditional Web, the 120 browsing context corresponds to a tab or window in a Web browser.) A 121 browsing context has a session history, which lists the resources 122 that that browsing context has visited, is visiting, or will visit. 123 At any time, one resource in a browsing context is designated the 124 "current" resource. Following a link or submitting a form causes the 125 browsing context to navigate to a new resource. 127 A link indicates a relationship between two resources, the link 128 context and the link target, and affords the navigation between these 129 two. The semantics of the relationship are identified by a link 130 relation type, which in CoRAL can be IANA-registered or application- 131 specific. To minimize round-trips, a link in CoRAL can optionally 132 embed a (complete or partial) representation of the link target. 133 Furthermore, a link target can be an anonymous resource in CoRAL; in 134 this case, the link turns into a "literal" which consists only of a 135 link relation type and a representation. 137 A form similarly indicates a relationship between two resources, the 138 form context and the form target, and affords the interaction with 139 the context through the submission of the form to the target. In 140 many cases, the target of a form is the same resource as the context, 141 but this is not required. The semantics of a form are identified by 142 a form relation type, which in CoRAL again can be IANA-registered or 143 application-specific. The submission of a form typically requires 144 the agent to construct a payload that is included with the request. 145 For this purpose, a form indicates the acceptable content formats for 146 the payload and can optionally embed a detailed description of the 147 expected data, for example, in the form of a list of form fields. 148 (The syntax for such a description is outside this document's scope.) 150 The CoRAL interaction model is as follows: 152 1. The first step for an agent is to decide what to do next, i.e., 153 which type of link to follow or form to submit, based on the link 154 relation types and form relation types it understands. 156 2. The agent finds the link(s) or form(s) with the given relation 157 type in the current resource. This may yield one or more 158 candidates from which the agent must select the most appropriate 159 one. The set of candidates may be empty if the transition is not 160 allowed, for example, when the agent is unauthorized. The format 161 of links and forms in CoRAL is specified in Section 3. 163 3. The agent selects one of the candidates based on the metadata 164 associated with the link or form. Metadata can include the 165 content format of the target resource representation, the URI 166 scheme, the request method and other attributes that describe the 167 target. Metadata is encoded in CoRAL as CoAP-style options, 168 which are specified in Section 4. 170 4. The agent resolves the URI reference in the link or form to its 171 absolute form in order to obtain the "request URI". CoRAL 172 encodes URI references like CoAP as a sequence of options, which 173 significantly simplifies the implementation of URI processors. 174 The process of reference resolution is specified in Section 5. 176 5. The agent constructs a new request with the request URI. If the 177 agent follows a link, the request method is GET; if the agent 178 submits a form, the request method is indicated by an option. 179 The agent should set request parameters according to the link/ 180 form attributes (e.g., set the CoAP Accept option when the 181 content format of the target resource is indicated). In the case 182 of a form, the agent also needs to construct a request payload 183 that matches the specifications of the form. 185 6. Finally, the agent sends the request and retrieves the response. 186 The agent processes the enclosed representation, updates the 187 browsing context to the new resource, and can decide again what 188 to do next. 190 An agent can furthermore navigate a browsing context by traversing 191 the browsing context's session history. The session history consists 192 of a flat list of session history entries. Each session history 193 entry consists of a URI and may have other information associated 194 with it. Session history entries are added to the session history as 195 the agent navigates from resource to resource. An agent can traverse 196 the session history to any entry by updating the browsing context to 197 the resource for that entry. 199 3. Format 201 CoRAL can be used as a standalone representation format or embedded 202 in representations in other formats. As a standalone format, CoRAL 203 representations have the media type "application/coral" or a media 204 type derived from CoRAL with the structured syntax suffix "+coral". 205 CoRAL is typically embedded in CBOR-based media types, but other 206 media types can embed CoRAL as well. The CoRAL format is in all 207 cases the same. 209 The top-level structure of CoRAL is a CoRAL document. A CoRAL 210 document consists of a sequence of links, forms, literals and bases, 211 which are collectively called elements. Elements consist of a number 212 indicating the element type, a "href type" that indicates how CoRAL- 213 encoded URI references are to be interpreted in reference resolution, 214 a sequence of zero or more options and, optionally, a body. 216 Link, form and literal elements come in two flavors: a "fat" format 217 that includes all the items listed above, and a "tiny" format. The 218 tiny formats provide a concise way to express elements that match 219 certain patterns. Base elements are always in the "fat" format. 220 They encode a base URI for reference resolution and apply to all 221 subsequent elements until the next base element is encountered. 223 In the Web, link relation types are identified by strings, such as 224 "stylesheet", "terms-of-service" or "item". In order to minimize the 225 overhead of using these relation types in constrained environments, 226 [I-D.hartke-core-apps] extends the IANA Link Relation Types registry 227 with a numeric identifier for each type. CoRAL uses these (non- 228 negative) numeric identifiers instead of the textual names. The same 229 optimization is applied to form relation types, CoAP content formats 230 and CoAP request methods. 232 Applications can use negative numbers to indicate application- 233 specific link relation types, form relation types and content 234 formats, which do not need to be IANA-registered. The mappings from 235 numbers to textual names need to be provided by the respective media 236 type definition (i.e., a media type with the "+coral" suffix or a 237 media type embedding CoRAL; the "application/coral" media type itself 238 does not define any application-specific values). 240 CoRAL defines a number of options that can be included in link, form, 241 literal and base elements. Options are used to encode the relation 242 type, the target resource URI and target attributes. They are 243 serialized as a sequence of unwrapped pairs where each pair consists 244 of a CoRAL option number and an option value. The pairs MUST be 245 sorted such that the option numbers are in ascending order. 247 Using the notation of [I-D.greevenbosch-appsawg-cbor-cddl], the CoRAL 248 data format can be expressed as follows: 250 document = [*element] 251 element = tiny-link / tiny-literal / tiny-form 252 / fat-link / fat-literal / fat-form 253 / base 255 tiny-link = [1, href-type, relation] 256 tiny-literal = [2, href-type, relation, format, body] 257 tiny-form = [3, href-type, relation, accept] 258 base = [4, href-type, options] 259 fat-link = [5, href-type, options, ?body] 260 fat-literal = [6, href-type, options, body] 261 fat-form = [7, href-type, options, ?body] 263 href-type = &(append-relation: 0, 264 absolute-path: 1, 265 append-path: 2, 266 relative-path: 3) 268 relation = int 269 format = int 270 accept = int 271 options = [*(option-number, option-value)] 272 option-number = uint 273 option-value = uint / int / text / bytes 274 body = bytes 276 The tiny formats expand as follows: 278 [1, H, R] -> [5, H, [1, R]] 279 [2, H, R, F, B] -> [6, H, [1, R, 4, F], B] 280 [3, H, R, A] -> [7, H, [1, R, 3, A]] 282 4. Options 284 Table 1 summarizes the CoRAL options defined in this document. 286 +-----+---+----------------+--------+--------+-------------+ 287 | No. | R | Name | Format | Length | Default | 288 +-----+---+----------------+--------+--------+-------------+ 289 | 1 | x | Relation | int | | (none) | 290 | 2 | | Method | uint | | 2 (POST) | 291 | 3 | x | Accept | int | | (none) | 292 | 4 | x | Format | int | | (none) | 293 | 5 | | Href.Scheme | text | 1-255 | (none) | 294 | 6 | | Href.Host.Name | text | 1-255 | (none) | 295 | 7 | | Href.Host.IPv4 | bytes | 4 | (none) | 296 | 8 | | Href.Host.IPv6 | bytes | 16 | (none) | 297 | 9 | | Href.Port | uint | | (see below) | 298 | 10 | x | Href.Path | text | 0-255 | (none) | 299 | 11 | x | Href.Query | text | 0-255 | (none) | 300 | 12 | | Href.Fragment | text | 0-255 | (none) | 301 | 13 | | Title | text | 0-255 | (none) | 302 | 14 | | Updatable | bool | | false | 303 | 15 | | Deletable | bool | | false | 304 +-----+---+----------------+--------+--------+-------------+ 306 Table 1: Options 308 The option properties are defined as follows: 310 Number: An option is identified by an option number. 312 Repeatable (R): An option that is repeatable MAY be included one or 313 more times in an element. An option that is not repeatable MUST 314 NOT be included more than once. If an agent encounters an option 315 with more occurrences than the option is defined for, each extra 316 occurrence MUST be ignored. 318 Format: Option values are defined to have a certain format, which is 319 the CBOR encoding of the specified type. 321 Length: Option values with types "text" and "bytes" are defined to 322 have a specific length, often in the form of an upper and lower 323 bound. The length of an option value MUST NOT be outside the 324 defined range. If an agent encounters an option with a length 325 outside the defined range, that option MUST be ignored. 327 Default Value: Options can be defined to have a default value. If 328 the value of an option is intended to be this default value, the 329 option SHOULD NOT be included in the element. If the option is 330 not present, the default value MUST be assumed. 332 The individual options are explained in the following subsections. 334 4.1. Accept 336 The Accept Option indicates the acceptable content formats for the 337 representation included in a form submission. 339 The option value of an Accept Option is either one of the content 340 format IDs registered in the CoAP Content-Formats registry (>= 0) or 341 one of the application-specific content format IDs defined by the 342 media type (< 0). 344 If a form does not include an Accept Option, the service accepts any 345 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 context and target of that 351 form are the link target, the submission method is DELETE and no 352 representation must be submitted. 354 4.3. Format 356 The Format Option, when present in a link or a form, provides a hint 357 indicating what the content format of the payload of the CoAP 358 response should be when following the link or submitting the form. 359 Note that this is only a hint; it does not override the Content- 360 Format Option included in the CoAP response. If the Format Option 361 occurs more than once, an agent can set the Accept Option in its CoAP 362 request to request a particular content format. 364 The Format Option is REQUIRED if a link embeds a representation in 365 the link body. The Format Option is also REQUIRED in a literal. In 366 both cases the first occurrence of the option indicates the content 367 format of the embedded representation. 369 The option value of a Format Option is either one of the content 370 format IDs registered in the CoAP Content-Formats registry (>= 0) or 371 one of the application-specific content format IDs defined by the 372 media type (< 0). 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, 382 o the Href.Host.Name Option specifies the host as a registered name 383 [RFC3986], 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 The option value of a Relation Option is either one of the relation 442 type IDs registered in the Link Relation Types registry (>= 0) or one 443 of the application-specific relation type IDs defined by the media 444 type (< 0). 446 4.7. Title 448 The Title Option, when present, is used to label the target of a link 449 such that it can be used as a human-readable identifier (e.g., a menu 450 entry). 452 4.8. Updatable 454 The Updatable Option, when present in a link, defines a form that can 455 be used to update the link target. The context and target of that 456 form are the link target, the submission method is PUT and the 457 content format of the submitted representation must be one of the 458 formats indicated by the Format Option in the link. 460 5. Reference Resolution 462 This section defines the process of resolving a URI reference within 463 a link or form to an absolute URI suitable for inclusion in a CoAP 464 request. 466 5.1. Establish a Base URI 468 URI references can be relative and thus are only usable when a base 469 URI is known. This means that a base URI must be established before 470 the use of all URI references that might be relative. 472 The base URI of a reference in a link or form is established as 473 specified in Section 5.1 of [RFC3986]. CoRAL supports a "Base URI 474 Embedded in Content" in the form of base elements. A base element 475 applies to all subsequent elements in a document until the next base 476 element is encountered. The URI reference in a base element itself 477 is resolved relative to the base URI of next lower precedence. 479 5.2. Transform References 481 The following pseudocode describes an algorithm for transforming a 482 URI reference R into its target URI T using the base URI B, the href 483 type H, and the link or form relation type S. The URI reference and 484 base URI are assumed to be pre-parsed into a sequence of Href.* 485 options; the result is returned as a sequence of Href.* options as 486 well. 488 if (R starts with Href.Scheme) then 489 T = R 490 elif (R starts with Href.Host.*) then 491 T = [ (k, v) | (k, v) <- B, k == Href.Scheme ] ++ 492 [ (k, v) | (k, v) <- R, k > Href.Scheme ] 493 elif (R starts with Href.Port) then 494 T = [ (k, v) | (k, v) <- B, k < Href.Port ] ++ 495 [ (k, v) | (k, v) <- R, k >= Href.Port ] 496 elif (H is append-relation) then 497 T = [ (k, v) | (k, v) <- B, k <= Href.Path ] ++ 498 [ (Href.Path, (hex S)) ] 499 elif (H is append-path) then 500 T = [ (k, v) | (k, v) <- B, k <= Href.Path ] ++ 501 [ (k, v) | (k, v) <- R, k >= Href.Path ] 502 elif (H is relative-path) then 503 T = [ (k, v) | (k, v) <- B, k < Href.Path ] ++ 504 (init [ (k, v) | (k, v) <- B, k == Href.Path ]) ++ 505 [ (k, v) | (k, v) <- R, k >= Href.Path ] 506 elif (H is absolute-path) then 507 T = [ (k, v) | (k, v) <- B, k < Href.Path ] ++ 508 [ (k, v) | (k, v) <- R, k >= Href.Path ] 509 endif 511 The "init" function returns all the elements of the input list except 512 the last one. For example, (init [1, 2, 3]) returns [1, 2] and (init 513 []) returns []. 515 The "hex" function returns a hexadecimal representation of the input 516 number. For example, (hex -421) returns "-1A5" and (hex 0) returns 517 "0". 519 5.3. Remove Dot Segments 521 After transforming a the URI reference into its target URI, the 522 special path segments "." and ".." need to be removed. Although 523 there are many ways to accomplish this removal process, we describe a 524 simple method using two string buffers. 526 1. The input buffer is initialized with the sequence of path 527 segments and the output buffer is initialized to the empty 528 sequence. 530 2. While the input buffer is not empty, loop as follows: 532 * If the input buffer begins with a "." path segment, then 533 remove this segment from the input buffer; otherwise, 535 * if the input buffer begins with a ".." path segment, then 536 remove this segment from the input buffer and and remove the 537 last segment (if any) from the output buffer; otherwise, 539 * move the first path segment in the input buffer to the end of 540 the output buffer. 542 3. Finally, the sequence of path segments in the target URI is 543 replaced by the sequence of path segments in the output buffer. 545 6. Security Considerations 547 TODO. 549 7. IANA Considerations 551 7.1. CoRAL Option Number Registry 553 This document establishes the CoRAL Option Number registry for the 554 option numbers used in CoRAL. The registry is located within the 555 CoRE Parameters registry. 557 7.1.1. Registering New Option Numbers 559 Option numbers are registered on the advice of a Designated Expert 560 (appointed by the IESG or their delegate), with a Specification 561 Required (using terminology from [RFC5226]). 563 Registration requests consist of the completed registration template 564 below, typically published in an RFC. However, to allow for the 565 allocation of values prior to publication, the Designated Expert may 566 approve registration once they are satisfied that a specification 567 will be published. 569 The registration template is: 571 o Option Number: 573 o Option Name: 575 o Reference: 577 7.1.2. Initial Registry Contents 579 The CoRAL Option Number registry's initial contents are: 581 o Option Number: 1 582 Option Name: Relation 583 Reference: [RFCXXXX] 585 o Option Number: 2 586 Option Name: Method 587 Reference: [RFCXXXX] 589 o Option Number: 3 590 Option Name: Accept 591 Reference: [RFCXXXX] 593 o Option Number: 4 594 Option Name: Format 595 Reference: [RFCXXXX] 597 o Option Number: 5 598 Option Name: Href.Scheme 599 Reference: [RFCXXXX] 601 o Option Number: 6 602 Option Name: Href.Host.Name 603 Reference: [RFCXXXX] 605 o Option Number: 7 606 Option Name: Href.Host.IPv4 607 Reference: [RFCXXXX] 609 o Option Number: 8 610 Option Name: Href.Host.IPv6 611 Reference: [RFCXXXX] 613 o Option Number: 9 614 Option Name: Href.Port 615 Reference: [RFCXXXX] 617 o Option Number: 10 618 Option Name: Href.Path 619 Reference: [RFCXXXX] 621 o Option Number: 11 622 Option Name: Href.Query 623 Reference: [RFCXXXX] 625 o Option Number: 12 626 Option Name: Href.Fragment 627 Reference: [RFCXXXX] 629 o Option Number: 13 630 Option Name: Title 631 Reference: [RFCXXXX] 633 o Option Number: 14 634 Option Name: Updatable 635 Reference: [RFCXXXX] 637 o Option Number: 15 638 Option Name: Deletable 639 Reference: [RFCXXXX] 641 7.2. Media Type 643 This document registers the media type "application/coral" in the 644 "Media Types" registry. 646 Type name: 647 application 649 Subtype name: 650 coral 652 Required parameters: 653 N/A 655 Optional parameters: 656 N/A 658 Encoding considerations: 659 CoRAL is a binary encoding. 661 Security considerations: 663 See Section 6 of [RFCXXXX]. 665 Interoperability considerations: 666 There are no known interoperability issues. 668 Published specification: 669 [RFCXXXX] 671 Applications that use this media type: 672 Hypermedia-driven Web applications that run in constrained nodes 673 and networks. 675 Fragment identifier considerations: 676 N/A 678 Additional information: 680 Deprecated alias names for this type: N/A 682 Magic number(s): N/A 684 File extension(s): .coral 686 Macintosh file type code(s): N/A 688 Person & email address to contact for further information: 689 See "Author's Address" section of [RFCXXXX]. 691 Intended usage: 692 COMMON 694 Restrictions on usage: 695 N/A 697 Author: 698 See "Author's Address" section of [RFCXXXX]. 700 Change controller: 701 IESG 703 7.3. Structured Syntax Suffix 705 This document registers the suffix "+coral" in the "Structured Syntax 706 Suffix" registry. 708 Name: 709 Constrained RESTful Application Language (CoRAL) 711 +suffix: 712 +coral 714 References: 715 [RFCXXXX] 717 Encoding considerations: 718 CoRAL is a binary format. 720 Interoperability considerations: 721 There are no known interoperability issues. 723 Fragment identifier considerations: 724 The syntax and semantics of fragment identifiers specified for 725 +coral are as specified for "application/coral". (At publication 726 of this document, there is no fragment identification syntax 727 defined for "application/coral".) 729 Security considerations: 730 See Section 6 of [RFCXXXX]. 732 Contact: 733 See "Author's Address" section of [RFCXXXX]. 735 Author/Change controller: 736 IESG 738 7.4. CoAP Content-Format 740 This document registers a content format for the "application/coral" 741 media type in the "CoAP Content-Formats" registry. 743 o Media Type: application/coral 744 Encoding: - 745 ID: 70 746 Reference: [RFCXXXX] 748 8. References 750 8.1. Normative References 752 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 753 Requirement Levels", BCP 14, RFC 2119, 754 DOI 10.17487/RFC2119, March 1997, 755 . 757 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 758 Resource Identifier (URI): Generic Syntax", STD 66, 759 RFC 3986, DOI 10.17487/RFC3986, January 2005, 760 . 762 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 763 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 764 DOI 10.17487/RFC5226, May 2008, 765 . 767 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 768 DOI 10.17487/RFC5988, October 2010, 769 . 771 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 772 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 773 October 2013, . 775 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 776 Application Protocol (CoAP)", RFC 7252, 777 DOI 10.17487/RFC7252, June 2014, 778 . 780 8.2. Informative References 782 [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification 783 0.99", January 2014, 784 . 786 [I-D.greevenbosch-appsawg-cbor-cddl] 787 Vigano, C. and H. Birkholz, "CBOR data definition language 788 (CDDL): a notational convention to express CBOR data 789 structures", draft-greevenbosch-appsawg-cbor-cddl-09 (work 790 in progress), September 2016. 792 [I-D.hartke-core-apps] 793 Hartke, K., "CoRE Application Descriptions", draft-hartke- 794 core-apps-04 (work in progress), October 2016. 796 [I-D.hartke-core-lighting] 797 Hartke, K., "CoRE Lighting", draft-hartke-core-lighting-00 798 (work in progress), September 2015. 800 [I-D.ietf-core-interfaces] 801 Shelby, Z., Vial, M., Koster, M., and C. Groves, "Reusable 802 Interface Definitions for Constrained RESTful 803 Environments", draft-ietf-core-interfaces-05 (work in 804 progress), July 2016. 806 [I-D.ietf-core-links-json] 807 Li, K., Rahman, A., and C. Bormann, "Representing CoRE 808 Formats in JSON and CBOR", draft-ietf-core-links-json-06 809 (work in progress), July 2016. 811 [I-D.kelly-json-hal] 812 Kelly, M., "JSON Hypertext Application Language", draft- 813 kelly-json-hal-08 (work in progress), May 2016. 815 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 816 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 817 . 819 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 820 Constrained-Node Networks", RFC 7228, 821 DOI 10.17487/RFC7228, May 2014, 822 . 824 [W3C.REC-rdf11-concepts-20140225] 825 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 826 Concepts and Abstract Syntax", World Wide Web Consortium 827 Recommendation REC-rdf11-concepts-20140225, February 2014, 828 . 830 [W3C.REC-turtle-20140225] 831 Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", 832 World Wide Web Consortium Recommendation REC-turtle- 833 20140225, February 2014, 834 . 836 [W3C.REC-webarch-20041215] 837 Jacobs, I. and N. Walsh, "Architecture of the World Wide 838 Web, Volume One", World Wide Web Consortium 839 Recommendation REC-webarch-20041215, December 2004, 840 . 842 Appendix A. Examples 844 A.1. Overview 846 A.1.1. Links 848 At its core, CoRAL is yet another serialization format for Web links. 849 For example, the following Web link (in RFC 5988 syntax): 851 ;rel=terms-of-service;type=text/plain 853 can be serialized in CoRAL as the following CBOR data item (in CBOR 854 extended diagnostic format; forward slashes indicate comments): 856 [ [ 5, / fat-link / 857 1, / absolute-path / 858 [ 1, 70, / relation = terms-of-service / 859 4, 0, / format = text\plain / 860 5, "coap", / href.scheme = "coap" / 861 6, "example.com", / href.host.name = "example.com" / 862 10, "info", / href.path = "info" / 863 10, "tos" ] ] ] / href.path = "tos" / 865 Multiple links are serialized as items of the top-level array: 867 [ [ 5, / fat-link / 868 3, / relative-path / 869 [ 1, 26, / relation = first / 870 4, 0, / format = text\plain / 871 10, "page1" ] ], / href.path = "page1" / 872 [ 5, / fat-link / 873 3, / relative-path / 874 [ 1, 55, / relation = previous / 875 4, 0, / format = text\plain / 876 10, "page6" ] ], / href.path = "page6" / 877 [ 5, / fat-link / 878 3, / relative-path / 879 [ 1, 41, / relation = next / 880 4, 0, / format = text\plain / 881 10, "page8" ] ], / href.path = "page8" / 882 [ 5, / fat-link / 883 3, / relative-path / 884 [ 1, 34, / relation = last / 885 4, 0, / format = text\plain / 886 10, "page42" ] ] ] / href.path = "page42" / 888 The Format Option, when present, is a hint indicating what the CoAP 889 content format of the result of dereferencing the link should be. If 890 more than one format is available, the Format Option can be repeated: 892 [ [ 5, / fat-link / 893 3, / relative-path / 894 [ 1, 33, / relation = item / 895 4, 47, / format = application\exi / 896 4, 50, / format = application\json / 897 4, 60, / format = application\cbor / 898 10, "item1" ] ] ] / href.path = "item1" / 900 A.1.2. Embedding 902 If a representation links to many resources, it may be inefficient to 903 retrieve a representation of each link target individually. For this 904 reason, CoRAL supports the embedding of a representation of the link 905 target in the link itself: 907 [ [ 5, / fat-link / 908 3, / relative-path / 909 [ 1, 33, / relation = item / 910 4, 50, / format = application\json / 911 10, "item1" ], / href.path = "item1" / 912 h'7b20227461736b223a20 913 2252657475726e207468 914 6520626f6f6b7320746f 915 20746865206c69627261 916 7279222c202261737369 917 676e6565223a2022416c 918 69636522207d' ] ] 920 where the byte string in this example encodes the following JSON 921 object: 923 { 924 "task": "Return the books to the library", 925 "assignee": "Alice" 926 } 928 By embedding representations, it is possible to use CoRAL as a (very 929 basic) substitute for RDF [W3C.REC-rdf11-concepts-20140225]. For 930 example, the RDF graph (in Turtle [W3C.REC-turtle-20140225] syntax) 932 @prefix foaf: . 934 <> foaf:name "John Doe" ; 935 foaf:age 32 ; 936 foaf:homepage . 938 can be serialized in CoRAL as follows: 940 [ [ 2, / tiny-literal / 941 2, / append-path / 942 -100, / relation = name / 943 0, / format = text\plain / 944 h'4a6f686e20446f65' ], / "John Doe" / 945 [ 2, / tiny-literal / 946 2, / append-path / 947 -101, / relation = name / 948 7, / format = uint8 / 949 h'20' ], / 32 / 950 [ 5, / fat-link / 951 1, / absolute-path / 952 [ 1, -102, / relation = homepage / 953 5, "coap", / href.scheme = "coap" / 954 6, "www.doe.example" / href.host.name = "www.doe.example" / 955 ] ] ] 957 A.1.3. Namespaces 959 The link relation type in a serialized link may be from the "global" 960 or the "local" namespace. The global namespace is indicated by an 961 unsigned number and is made up of the link relation types registered 962 with IANA. The local namespace is indicated by a negative number and 963 is defined by the media type of the CoRAL representation. 965 By default, CoRAL representations have the "application/coral" media 966 type where the local namespace is empty. However, it is possible to 967 create new media types based on CoRAL and to register these with the 968 "+coral" suffix. In this case, the media type specification can fill 969 the local namespace with application-specific link relation types. 971 For example, a media type "application/example.shop+coral" could 972 define the following set of local link relation types: 974 +-----+----------------------------------+ 975 | ID | Meaning | 976 +-----+----------------------------------+ 977 | -80 | http://example.com/rels/order | 978 | -81 | http://example.com/rels/basket | 979 | -82 | http://example.com/rels/customer | 980 +-----+----------------------------------+ 982 Similarly, a media type "application/example.foaf+coral" could define 983 the following mapping from link relation type IDs to the FOAF RDF 984 model [FOAF]: 986 +------+------------------------------------+ 987 | ID | Meaning | 988 +------+------------------------------------+ 989 | -100 | http://xmlns.com/foaf/0.1/name | 990 | -101 | http://xmlns.com/foaf/0.1/age | 991 | -102 | http://xmlns.com/foaf/0.1/homepage | 992 +------+------------------------------------+ 994 A.1.4. Forms 996 In addition to Web links, CoRAL supports forms. An agent can use a 997 form to perform an operation on the form context, such as updating a 998 resource or creating a new item in a collection. 1000 Similar to link relation types, the semantics of a form are indicated 1001 by the form relation type. The Href.* Options encode the URI of the 1002 form target to which the agent should submit the form. A form 1003 additionally encodes the submission method (POST, PUT, PATCH, DELETE) 1004 and the description of a representation that the service expects as 1005 part of form submission: 1007 [ [ 7, / fat-form / 1008 3, / relative-path / 1009 [ 1, 1, / relation = create-item / 1010 2, 2, / method = POST / 1011 3, 60, / accept = application\cbor / 1012 10, "items" ] ] ] / href.path = "items" / 1014 The Accept Option specifies the content format of the expected 1015 representation. A content format can use the body of a form to 1016 describe the expected representation in more detail, for example, by 1017 specifying a set of form fields that the agent needs to fill out: 1019 [ [ 7, / fat-form / 1020 3, / relative-path / 1021 [ 1, 1, / relation = create-item / 1022 2, 2, / method = POST / 1023 3, -65535, / accept = example\form / 1024 10, "items" ], / href.path = "items" / 1025 h'6e616d652c206167652c / "name, age, homepage" / 1026 20686f6d6570616765' ] ] 1028 A.1.5. Editing 1030 The target resource of a link may be editable. In this case, the 1031 representation of such a resource typically contains one or more 1032 forms that allow an agent to edit the resource. However, it may be 1033 inefficient to include these forms every time a representation of the 1034 link target is retrieved and more efficient to include them in 1035 representations that link to the resource. CoRAL supports this with 1036 two options. 1038 Setting the Updatable Option in a link to true defines a form that 1039 can be used to update the target resource. The context and target of 1040 that form are both the target of the link, the submission method is 1041 PUT and the content format of the submitted representation must be 1042 one of the formats indicated by the Format Option in the link. For 1043 example, given the following CoRAL representation, an agent can 1044 change the recipient by making a PUT request to <./to> with the new 1045 value in "text/plain" format: 1047 [ [ 5, / fat-link / 1048 3, / relative-path / 1049 [ 1, -120, / relation = sender / 1050 4, 0, / format = text\plain / 1051 10, "from", / href.path = "from" / 1052 14, true ], / updatable = true / 1053 h'4a756c696574' ], / "Juliet" / 1054 [ 5, / fat-link / 1055 3, / relative-path / 1056 [ 1, -121, / relation = recipient / 1057 4, 0, / format = text\plain / 1058 10, "to", / href.path = "to" / 1059 14, true ], / updatable = true / 1060 h'526f6d656f' ], / "Romeo" / 1061 [ 5, / fat-link / 1062 3, / relative-path / 1063 [ 1, -122, / relation = message / 1064 4, 0, / format = text\plain / 1065 10, "message", / href.path = "message" / 1066 14, true ], / updatable = true / 1067 h'4172742074686f75206e / "Art thou not Romeo, / 1068 6f7420526f6d656f2c20 / and a Montague?" / 1069 616e642061204d6f6e74 1070 616775653f' ] ] 1072 Setting the Deletable Flag in a link to true likewise defines a form 1073 that can be used to delete the target resource. 1075 A.2. CoRE Lighting 1077 CoRE Lighting [I-D.hartke-core-lighting] defines a benchmark scenario 1078 for the exploration of hypermedia-oriented design in constrained, 1079 RESTful environments. The bulletin board example in Section 5.2.1 of 1080 [I-D.hartke-core-lighting] can be encoded in CoRAL as follows: 1082 [[7, 3, [1, 1, 3, 65200, 10, "bulletins"]], 1083 [5, 1, [1, 33, 4, 65200, 6, "light-bulb.example"], <<1>>], 1084 [5, 1, [1, 33, 4, 65200, 6, "remote-control.example"], <<2>>]] 1086 where <<1>> is a byte string that encodes the following CoRAL 1087 structure: 1089 [[5, 3, [1, -100, 4, 65202, 10, "config"]], 1090 [2, 3, -101, 0, "Light 2"], 1091 [2, 3, -102, 0, "Illuminates the couch."], 1092 [2, 3, -103, 0, "Living Room"]] 1094 and <<2>> is a byte string that encodes the following CoRAL 1095 structure: 1097 [[5, 3, [1, 1, 4, 65203, 10, "state"]], 1098 [2, 3, -101, 0, "LRC 1"], 1099 [2, 3, -102, 0, "Controls Light 2."], 1100 [2, 3, -103, 0, "Living Room"]] 1102 Table 3 shows a comparison of sizes of the example encoded in CoRAL 1103 and JSON. 1105 +--------+-----------+ 1106 | Format | Size | 1107 +--------+-----------+ 1108 | JSON | 515 bytes | 1109 | CoRAL | 245 bytes | 1110 +--------+-----------+ 1112 Table 3: Size Comparison 1114 A.3. CoRE Link Format 1116 The example in this section is based on an example on page 14 of 1117 [RFC6690]: 1119 ;ct=40;title="Sensor Index", 1120 ;rt="temperature-c";if="sensor", 1121 ;rt="light-lux";if="sensor", 1122 ;anchor="/sensors/temp" 1123 ;rel="describedby", 1124 ;anchor="/sensors/temp";rel="alternate" 1126 The example can be encoded in CoRAL as follows: 1128 [[4, 1, [10, "sensors"]], 1129 [5, 2, [4, 40, 13, "Sensor Index"]], 1130 [5, 2, [10, "temp", 16, "temperature-c", 17, "sensor"]], 1131 [5, 2, [10, "light", 16, "light-lux", 17, "sensor"]], 1132 [5, 1, [1, 18, 5, "http", 6, "www.example.com", 1133 10, "sensors", 10, "t123", 18, "/sensors/temp"]], 1134 [5, 1, [1, 2, 10, "t", 18, "/sensors/temp"]]] 1136 Table 4 shows a comparison of sizes of the example encoded in CoRAL 1137 and a number of Link Format variants. 1139 +--------------------+-----------+ 1140 | Format | Size | 1141 +--------------------+-----------+ 1142 | Link Format | 251 bytes | 1143 | Link Format (JSON) | 320 bytes | 1144 | Link Format (CBOR) | 203 bytes | 1145 | CoRAL | 181 bytes | 1146 +--------------------+-----------+ 1148 Table 4: Size Comparison 1150 A.4. CoRE Interfaces 1152 The example in this section is based on an example on page 10 of 1153 [I-D.ietf-core-interfaces]: 1155 ;rt="simple.sen";if="core.b", 1156 ;rt="simple.sen.lt";if="core.s", 1157 ;rt="simple.sen.tmp";if="core.s";obs, 1158 ;rt="simple.sen.hum";if="core.s", 1159 ;rt="simple.act";if="core.b", 1160 ;rt="simple.act.led";if="core.a", 1161 ;rt="simple.act.led";if="core.a", 1162 ;rt="simple.dev";if="core.ll", 1163 ;if="core.lb" 1165 The example can be encoded in CoRAL as follows: 1167 [[5, 1, [10, "d", 10, "", 16, "simple.dev", 17, "core.ll"]], 1168 [5, 1, [10, "l", 10, "", 17, "core.lb"]], 1169 [4, 1, [17, "core.b"]], 1170 [5, 2, [10, "s", 10, "", 16, "simple.sen"]], 1171 [5, 2, [10, "a", 10, "", 16, "simple.act"]], 1172 [4, 1, [10, "s", 17, "core.s"]], 1173 [5, 2, [10, "lt", 16, "simple.sen.lt"]], 1174 [5, 2, [10, "tmp", 16, "simple.sen.tmp", 19, true]], 1175 [5, 2, [10, "hum", 16, "simple.sen.hum"]], 1176 [4, 1, [10, "a", 16, "simple.act.led", 17, "core.a"]], 1177 [5, 2, [10, "1", 10, "led"]], 1178 [5, 2, [10, "2", 10, "led"]]] 1180 Table 5 shows a comparison of sizes of the example encoded in CoRAL 1181 and a number of Link Format variants. 1183 +--------------------+-----------+ 1184 | Format | Size | 1185 +--------------------+-----------+ 1186 | Link Format | 332 bytes | 1187 | Link Format (JSON) | 456 bytes | 1188 | Link Format (CBOR) | 264 bytes | 1189 | CoRAL | 248 bytes | 1190 +--------------------+-----------+ 1192 Table 5: Size Comparison 1194 Acknowledgements 1196 This specification is heavily inspired by the JSON Hypertext 1197 Application Language (HAL) [I-D.kelly-json-hal]; the author of and 1198 contributors to that specification are acknowledged for their great 1199 work. 1201 Yassin Nasir Hassan suggested placing the hypermedia controls for 1202 modifying a link target in the link context rather than in the 1203 representation of the link target. 1205 Thanks to Carsten Bormann, Jaime Jimenez and Matthias Kovatsch for 1206 helpful comments and discussions that have shaped the document. 1208 Author's Address 1209 Klaus Hartke 1210 Universitaet Bremen TZI 1211 Postfach 330440 1212 Bremen D-28359 1213 Germany 1215 Phone: +49-421-218-63905 1216 Email: hartke@tzi.org