idnits 2.17.1 draft-hartke-t2trg-coral-00.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, 2016) is 2963 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Missing Reference: 'RFCXXXX' is mentioned on line 804, but not defined == Outdated reference: A later version (-08) exists of draft-hartke-core-apps-03 ** 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-07 == Outdated reference: A later version (-11) exists of draft-kelly-json-hal-07 Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). 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, 2016 5 Expires: September 14, 2016 7 The Constrained RESTful Application Language (CoRAL) 8 draft-hartke-t2trg-coral-00 10 Abstract 12 The Constrained RESTful Application Language (CoRAL) is a compact, 13 binary representation format for hypermedia-driven applications. It 14 supports links, forms and the embedding of resource representations. 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, 2016. 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. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2.1. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2.2. Embedding . . . . . . . . . . . . . . . . . . . . . . . . 4 55 2.3. Namespaces . . . . . . . . . . . . . . . . . . . . . . . 6 56 2.4. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 57 2.5. Editing . . . . . . . . . . . . . . . . . . . . . . . . . 7 58 3. Data Format . . . . . . . . . . . . . . . . . . . . . . . . . 8 59 3.1. Option Format . . . . . . . . . . . . . . . . . . . . . . 10 60 4. Options . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 61 4.1. Accept . . . . . . . . . . . . . . . . . . . . . . . . . 11 62 4.2. Format . . . . . . . . . . . . . . . . . . . . . . . . . 11 63 4.3. Href.* . . . . . . . . . . . . . . . . . . . . . . . . . 11 64 4.4. Id . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 65 4.5. Method . . . . . . . . . . . . . . . . . . . . . . . . . 13 66 4.6. Other-Href . . . . . . . . . . . . . . . . . . . . . . . 13 67 4.7. Title . . . . . . . . . . . . . . . . . . . . . . . . . . 13 68 5. Reference Resolution . . . . . . . . . . . . . . . . . . . . 13 69 6. Security Considerations . . . . . . . . . . . . . . . . . . . 14 70 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 71 7.1. CoRAL Option Number Registry . . . . . . . . . . . . . . 14 72 7.2. Media Type . . . . . . . . . . . . . . . . . . . . . . . 16 73 7.3. Structured Syntax Suffix . . . . . . . . . . . . . . . . 17 74 7.4. CoAP Content-Format . . . . . . . . . . . . . . . . . . . 18 75 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 76 8.1. Normative References . . . . . . . . . . . . . . . . . . 18 77 8.2. Informative References . . . . . . . . . . . . . . . . . 19 78 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 20 79 A.1. CoRE Lighting . . . . . . . . . . . . . . . . . . . . . . 20 80 A.2. W3C WoT Thing Description . . . . . . . . . . . . . . . . 21 81 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 23 82 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 23 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 data to a server for 92 processing. By annotating these elements with machine-readable link 93 relation types [RFC5988] and form relation types, it is possible to 94 extend this interaction model to machine-to-machine communication. 96 This document describes the Constrained RESTful Application Language 97 (CoRAL), a serialization format for Web links and forms that is based 98 on the Concise Binary Object Representation (CBOR) [RFC7049]. The 99 format also supports the embedding of representations of resources. 100 Thus, CoRAL can be used as a building block for RESTful, hypermedia- 101 driven applications. 103 1.1. Terminology 105 Readers are expected to be familiar with the terms and concepts 106 described in [RFC5988] and [I-D.hartke-core-apps]. 108 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 109 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 110 "OPTIONAL" in this document are to be interpreted as described in 111 [RFC2119]. 113 2. Overview 115 2.1. Links 117 A Web link [RFC5988] is a typed connection between two Web resources. 118 It is comprised of a context, a link relation type, a link target URI 119 and, optionally, a set of target attributes. The link relation type 120 identifies the semantics of a link and thus enables an automated 121 agent to understand the nature of the relation. 123 The CoRAL representation of a resource contains a set of links where 124 the context of each link is the represented resource. A link in a 125 CoRAL representation serializes the link relation type, the URI of 126 the link target and the target attributes, if any. 128 In the Web, link relation types are identified by strings, such as 129 "stylesheet", "terms-of-service" or "item". In order to minimize the 130 overhead of using these relation types in constrained environments, 131 [I-D.hartke-core-apps] extends the link relation types registry with 132 a numeric identifier for each link relation type. CoRAL uses this 133 numeric identifier instead of the link relation type name. 135 The link target URI and the target attributes are encoded as options 136 in a simple format based on the option structure in CoAP [RFC7252] 137 and CBOR encoding [RFC7049]. For example, the Web link (in [RFC5988] 138 syntax) 140 ;rel=terms-of-service;type=text/plain 142 is serialized in CoRAL as follows: 144 [ /abs_link/ 0, 145 /terms-of-service/ 64, 146 [ /format/ 3, 0 /text//plain/, 147 /href.scheme/ 4, "coap", 148 /href.host.name/ 6, "example.com", 149 /href.port/ 11, 5683, 150 /href.path/ 12, "info", 151 /href.path/ 12, "tos" ]] 153 Multiple links are simply serialized one after another: 155 [ /rel_link/ 4, 156 /first/ 23, 157 [ /format/ 3, 0 /text//plain/, 158 /href.path/ 12, "page1" ]] 159 [ /rel_link/ 4, 160 /previous/ 49, 161 [ /format/ 3, 0 /text//plain/, 162 /href.path/ 12, "page6" ]] 163 [ /rel_link/ 4, 164 /next/ 38, 165 [ /format/ 3, 0 /text//plain/, 166 /href.path/ 12, "page8" ]] 167 [ /rel_link/ 4, 168 /last/ 31, 169 [ /format/ 3, 0 /text//plain/, 170 /href.path/ 12, "page42" ]] 172 The Format Option, when present, is a hint indicating what the CoAP 173 content format of the result of dereferencing the link should be. If 174 more than one format is available, the Format Option can be repeated: 176 [ /rel_link/ 4, 177 /item/ 30, 178 [ /format/ 3, 47 /application//exi/, 179 /format/ 3, 50 /application//json/, 180 /format/ 3, 60 /application//cbor/, 181 /href.path/ 12, "item1" ]] 183 2.2. Embedding 185 If a representation links to many resources, it may be inefficient to 186 retrieve a representation of each link target individually. For this 187 reason, CoRAL supports the embedding of a representation of the link 188 target in the link itself: 190 [ /rel_link/ 4, 191 /item/ 30, 192 [ /format/ 3, 50 /application//json/, 193 /href.path/ 12, "item1" ], 194 <<< 195 { 196 "task": "Return the books to the library", 197 "assignee": "Alice" 198 } 199 >>> ] 201 By embedding representations, it is possible to use CoRAL as a (very 202 basic) substitute for RDF [W3C.REC-rdf11-concepts-20140225]. For 203 example, the RDF graph (in Turtle [W3C.REC-turtle-20140225] syntax) 205 @prefix foaf: . 207 <> foaf:name "John Doe" ; 208 foaf:age 32 ; 209 foaf:homepage . 211 could be serialized in CoRAL as follows: 213 [ /anon_link/ 12, 214 /name/ -100, 215 [ /format/ 3, 0 /text//plain/ ], 216 <<< 217 John Doe 218 >>> ] 219 [ /anon_link/ 12, 220 /age/ -101, 221 [ /format/ 3, 9 /uint8/ ], 222 <<< 223 32 224 >>> ] 225 [ /abs_link/ 0, 226 /homepage/ -102, 227 [ /href.scheme/ 4, "coap", 228 /href.host.name/ 6, "www.doe.example" ]] 230 A flag in the serialized link indicates that the targets of the first 231 two links are anonymous resources that don't have their own URI, like 232 literals in RDF. 234 2.3. Namespaces 236 The link relation type in a serialized link may be from the "global" 237 or the "local" namespace. The global namespace is indicated by an 238 unsigned number and is made up of the link relation types registered 239 with IANA. The local namespace is indicated by a negative number and 240 is defined by the media type of the CoRAL representation. 242 By default, CoRAL representations have the "application/coral" media 243 type where the local namespace is empty. However, it is possible to 244 create new media types based on CoRAL and to register these with the 245 "+coral" suffix. In this case, the media type specification can fill 246 the local namespace with application-specific link relation types. 248 For example, a media type "application/example.shop+coral" could 249 define the following set of local link relation types: 251 +----+----------------------------------+ 252 | ID | Meaning | 253 +----+----------------------------------+ 254 | 80 | http://example.com/rels/order | 255 | 81 | http://example.com/rels/basket | 256 | 82 | http://example.com/rels/customer | 257 +----+----------------------------------+ 259 Similarly, a media type "application/example.foaf+coral" could define 260 the following mapping from local link relation type IDs to the FOAF 261 RDF model [FOAF]: 263 +-----+------------------------------------+ 264 | ID | Meaning | 265 +-----+------------------------------------+ 266 | 100 | http://xmlns.com/foaf/0.1/name | 267 | 101 | http://xmlns.com/foaf/0.1/age | 268 | 102 | http://xmlns.com/foaf/0.1/homepage | 269 +-----+------------------------------------+ 271 2.4. Forms 273 In addition to Web links, CoRAL also supports forms. A form is an 274 affordance that an agent can use to perform an operation on the form 275 context, such as updating a resource or creating a new item in a 276 collection. 278 In a form, the link relation type is replaced by the form relation 279 type which indicates the semantics of the form. The Href.* Options 280 encode the URI of the target resource to which the agent should 281 submit the form. A form additionally encodes the submission method 282 (POST, PUT, PATCH, DELETE) and the description of a representation 283 that the service accepts as part of form submission: 285 [ /rel_form/ 68, 286 /create-item/ 1, 287 [ /method/ 1, 2 /POST/, 288 /accept/ 2, 60 /application//cbor/, 289 /href.path/ 12, "items" ]] 291 The Accept Option specifies the content format of the accepted 292 representation. A content format may use the payload of a form to 293 describe the accepted representation in more detail, for example, by 294 specifying a set of form fields that the agent needs to fill out: 296 [ /rel_form/ 68, 297 /create-item/ 1, 298 [ /method/ 1, 2 /POST/, 299 /accept/ 2, 65535 /example//form/, 300 /href.path/ 12, "items" ], 301 <<< 302 name, age, homepage 303 >>> ] 305 2.5. Editing 307 The target resource of a link may be editable. In this case, the 308 representation of such a resource typically contains a form that 309 allows to edit the resource. However, it may be inefficient to 310 include this form in every representation of the target resource and 311 more efficient to include it in a representation that links to the 312 resource. CoRAL supports this by two flags in the link structure. 314 Setting the Updateable Flag in a link defines a form that can be used 315 to update the target resource. The context and target resource of 316 that form is the target resource of the link, the submission method 317 is PUT and the content format of the submitted representation is 318 defined by the Format Option of the link. For example, given the 319 following CoRAL representation an agent can change the recipient by 320 making a PUT request to <./to> with the new value in text/plain 321 format: 323 [ /updateable_rel_link/ 6, 324 /sender/ -120, 325 [ /format/ 3, 0 /text//plain/, 326 /href.path/ 12, "from" ], 327 <<< 328 Juliet 329 >>> ] 330 [ /updateable_rel_link/ 6, 331 /recipient/ -121, 332 [ /format/ 3, 0 /text//plain/, 333 /href.path/ 12, "to" ], 334 <<< 335 Romeo 336 >>> ] 337 [ /updateable_rel_link/ 6, 338 /message/ -122, 339 [ /format/ 3, 0 /text//plain/, 340 /href.path/ 12, "message" ], 341 <<< 342 Art thou not Romeo, and a Montague? 343 >>> ] 345 Setting the Deleteable Flag in a link likewise defines a form that 346 can be used to delete the target resource. The submission method is 347 DELETE and no representation is included in the request. 349 3. Data Format 351 A CoRAL representation consists of a sequence of zero or more links 352 and/or forms, each encoded in CBOR [RFC7049] and concatenated as a 353 byte string. Before encoding, both links and forms are arrays with 354 either three of four elements: an unsigned integer carrying flags, an 355 integer for the link or form relation type, an array that contains 356 zero or more options (as pairs of option numbers and option values, 357 ordered by option number), and optionally a payload. 359 Using the notation of [I-D.greevenbosch-appsawg-cbor-cddl], this can 360 be expressed as: 362 link_or_form = [flags, relation, options, ? payload] 363 flags = uint .bits flagbits 364 relation = int ; negative for local 365 options = [* (optionname, optionvalue)] 366 optionname = uint 367 optionvalue = uint / text / bytes 368 payload = bytes 369 flagbits = &( 370 deleteable: 0, 371 updateable: 1, 372 hreftype1: 2, 373 hreftype2: 3, 374 is_link: 6, 375 ) 377 +-+-+-+-+-+-+-+-+ 378 |_|T|_|_| H |U|D| 379 +-+-+-+-+-+-+-+-+ 381 Figure 1: Flags 383 The flags unsigned integer contains the following fields: 385 Type (T): A 1-bit unsigned integer. Indicates whether the structure 386 is a link (0) or a form (1). 388 Href Type (H): A 2-bit unsigned integer. Indicates whether the link 389 target is specified as an absolute URI (0), as a relative URI (1) 390 or as the default URI (2), or whether the target is an anonymous 391 resource (3). 393 Updateable (U): A 1-bit unsigned integer. Indicates whether the 394 link target can be updated (1) or not (0). 396 Deleteable (D): A 1-bit unsigned integer. Indicates whether the 397 link target can be deleted (1) or not (0). 399 The relation type is an integer that indicates the link or form 400 relation type. Negative integers are used for local relation types, 401 unsigned ones for global relation types. 403 The options are an array that contains a sequence of pairs of a CoRAL 404 option number and an option value, where the option numbers are in 405 ascending order. 407 The payload is an optional element of the array. 409 3.1. Option Format 411 CoRAL defines a number of options that can be included in links and 412 forms. Options are used to encode the target resource URI and the 413 target attributes. An option instance in a link or form maps the 414 option number of a defined CoRAL option to the option value. 416 4. Options 418 The CoRAL options defined in this document are summarized in Table 1 419 below and explained in the following subsections: 421 +-----+---+----------------+--------+--------+-------------+ 422 | No. | R | Name | Format | Length | Default | 423 +-----+---+----------------+--------+--------+-------------+ 424 | 0 | | Id | string | 1-255 | (none) | 425 | 1 | | Method | uint | 1 | 2 (POST) | 426 | 2 | x | Accept | uint | 0-2 | (none) | 427 | 3 | x | Format | uint | 0-2 | (none) | 428 | 4 | | Href.Scheme | string | 1-255 | (none) | 429 | 6 | | Href.Host.Name | string | 1-255 | (none) | 430 | 7 | | Href.Host.IPv4 | opaque | 4 | (none) | 431 | 8 | | Href.Host.IPv6 | opaque | 16 | (none) | 432 | 11 | | Href.Port | uint | 0-2 | (see below) | 433 | 12 | x | Href.Path | string | 0-255 | (none) | 434 | 13 | x | Href.Query | string | 0-255 | (none) | 435 | 14 | | Href.Fragment | string | 0-255 | (empty) | 436 | 15 | | Other-Href | string | 1-1034 | (none) | 437 | 20 | | Title | string | 0-255 | (none) | 438 +-----+---+----------------+--------+--------+-------------+ 440 Table 1: Options 442 The option properties are defined as follows: 444 Number: An option is identified by an option number. 446 Repeatable (R): An option that is repeatable MAY be included one or 447 more times in a link or form. An option that is not repeatable 448 MUST NOT be included more than once. If an agent encounters an 449 option with more occurrences than the option is defined for, each 450 supernumerary option occurrence MUST be ignored. 452 Format: Option values are defined to have a certain format. Similar 453 to the types defined in Section 3.2 of RFC 7252, "string" stands 454 for a text string; "opaque" for a byte string, and "uint" for an 455 unsigned integer. 457 Length: Option values are defined to have a specific length, often 458 in the form of an upper and lower bound. For unsigned integer 459 options the length is counted as the number of bytes that would be 460 needed to represent the unsigned integer as a binary number. The 461 length of an option value MUST NOT be outside the defined range. 462 If an agent encounters an option with a length outside the defined 463 range, that option MUST be ignored. 465 Default Value: Options may be defined to have a default value. If 466 the value of an option is intended to be this default value, the 467 option SHOULD NOT be included in the link or form. If the option 468 is not present, the default value MUST be assumed. 470 4.1. Accept 472 The Accept Option indicates the acceptable content formats for the 473 representation included in a form submission. Each option value is 474 one of the content format IDs defined in the CoAP Content-Formats 475 registry. If the Accept Option is absent, the service accepts any 476 content format. 478 4.2. Format 480 The Format Option, when present in a link or a form, is a hint 481 indicating what the content format of the payload of the CoAP 482 response should be when following the link or submitting the form. 483 Note that this is only a hint; it does not override the Content- 484 Format Option included in the CoAP response. 486 As an exception to this rule, the Format Option is REQUIRED if a link 487 embeds a representation. The option then indicates the CoAP content 488 format of the embedded representation. 490 Each option value is one of the content format IDs defined in the 491 CoAP Content-Formats registry. 493 4.3. Href.* 495 The Href.Scheme, Href.Host.Name, Href.Host.IPv4, Href.IPv6, 496 Href.Port, Href.Path, Href.Query and Href.Fragment Options are used 497 to specify the target resource URI in a link or form. They hold the 498 following values: 500 o the Href.Scheme Option specifies the URI scheme name, 502 o the Href.Host.Name Option specifies the host as a registered name 503 [RFC3986], 505 o the Href.Host.IPv4 Option specifies the host as a 32-bit IPv4 506 address, 508 o the Href.Host.IPv6 Option specifies the host as a 128-bit IPv6 509 address, 511 o the Href.Port Option specifies the port number, 513 o each Href.Path Option specifies one segment of the path, 515 o each Href.Query Option specifies one argument of the query string, 516 and 518 o the Href.Fragment Option specifies the fragment identifier. 520 The Href.Host.Name, Href.Host.IPv4 and Href.Host.IPv6 options are 521 mutually exclusive. 523 The default value of the Href.Port Option is the default port for the 524 URI scheme. 526 The following table lists the permitted Href.* options by Href Type. 527 A 'yes' indicates that an option of this type MAY be present; a 'no' 528 indicates that an option of this type MUST NOT be present. The 529 resolution of Href.* options against a base URI is specified in 530 Section 5. 532 +----------------+----------+----------+---------+-----------+ 533 | | Absolute | Relative | Default | Anonymous | 534 +----------------+----------+----------+---------+-----------+ 535 | Href.Scheme | yes | no | no | no | 536 | Href.Host.Name | yes | no | no | no | 537 | Href.Host.IPv4 | yes | no | no | no | 538 | Href.Host.IPv6 | yes | no | no | no | 539 | Href.Port | yes | no | no | no | 540 | Href.Path | yes | yes | no | no | 541 | Href.Query | yes | yes | no | no | 542 | Href.Fragment | yes | yes | no | no | 543 +----------------+----------+----------+---------+-----------+ 545 Table 2: Permitted Href.* Options by Href Type 547 4.4. Id 549 The Id Option specifies an unique identifier for the link or form 550 that can be used as a fragment identifier for this link or form in 551 the CoRAL representation. The option value must be unique amongst 552 all the IDs in the representation. The value must contain at least 553 one character and must not contain any space characters. 555 4.5. Method 557 The Method Option indicates the CoAP method to use for form 558 submission. The option value is one of the CoAP method codes defined 559 in the CoAP Method Codes registry. 561 4.6. Other-Href 563 In case the target resource URI cannot be expressed with the Href.* 564 Options, the URI can be specified using the Other-Href Option. 566 The option value is a string that matches the syntax of the URI- 567 reference production defined in [RFC3986]. The Other-Href Option 568 MUST take precedence over any of the Href.* Options, each of which 569 MUST NOT be included in a link or form containing the Other-Href 570 Option. 572 4.7. Title 574 The Title Option, when present, is used to label the target of a link 575 such that it can be used as a human-readable identifier (e.g., a menu 576 entry). 578 5. Reference Resolution 580 This section defines the process of resolving the sequence of Href.* 581 options in a link or a form to an absolute URI suitable for inclusion 582 in a CoAP request. The URI reference is resolved against a base URI 583 that is determined as specified in Section 5.1 of RFC 3986. The base 584 URI is assumed to be pre-parsed into a sequence of Href.* options; 585 the result is returned as a sequence of Href.* options as well. 587 The following pseudocode describes an algorithm for transforming a 588 URI reference R into its target URI T, using the Href Type H, the 589 Link or Form Relation Type S and the base URI B. 591 if (H == 3) then 592 T = [ ] 593 elif (H == 2) then 594 T = [ (k, v) | (k, v) <- B, k <= Href.Path ] ++ 595 [ (Href.Path, S) ] 596 elif (R starts with Href.Scheme) then 597 T = R 598 elif (R starts with Href.Host.*) then 599 T = [ (k, v) | (k, v) <- B, k == Href.Scheme ] ++ 600 [ (k, v) | (k, v) <- R, k > Href.Scheme ] 601 elif (R starts with Href.Port) then 602 T = [ (k, v) | (k, v) <- B, k < Href.Port ] ++ 603 [ (k, v) | (k, v) <- R, k >= Href.Port ] 604 elif (H == 1) then 605 T = [ (k, v) | (k, v) <- B, k <= Href.Path ] ++ 606 [ (k, v) | (k, v) <- R, k >= Href.Path ] 607 else 608 T = [ (k, v) | (k, v) <- B, k < Href.Path ] ++ 609 [ (k, v) | (k, v) <- R, k >= Href.Path ] 610 endif 612 6. Security Considerations 614 TODO. 616 7. IANA Considerations 618 7.1. CoRAL Option Number Registry 620 This document establishes the CoRAL Option Number registry for the 621 option numbers used in CoRAL. The registry is located within the 622 CoRE Parameters registry. 624 7.1.1. Registering New Option Numbers 626 Option numbers are registered on the advice of a Designated Expert 627 (appointed by the IESG or their delegate), with a Specification 628 Required (using terminology from [RFC5226]). 630 Registration requests consist of the completed registration template 631 below, typically published in an RFC. However, to allow for the 632 allocation of values prior to publication, the Designated Expert may 633 approve registration once they are satisfied that a specification 634 will be published. 636 The registration template is: 638 o Option Number: 640 o Option Name: 642 o Reference: 644 7.1.2. Initial Registry Contents 646 The CoRAL Option Number registry's initial contents are: 648 o Option Number: 0 649 Option Name: Id 650 Reference: [RFCXXXX] 652 o Option Number: 1 653 Option Name: Method 654 Reference: [RFCXXXX] 656 o Option Number: 2 657 Option Name: Accept 658 Reference: [RFCXXXX] 660 o Option Number: 3 661 Option Name: Format 662 Reference: [RFCXXXX] 664 o Option Number: 4 665 Option Name: Href.Scheme 666 Reference: [RFCXXXX] 668 o Option Number: 6 669 Option Name: Href.Host.Name 670 Reference: [RFCXXXX] 672 o Option Number: 7 673 Option Name: Href.Host.IPv4 674 Reference: [RFCXXXX] 676 o Option Number: 8 677 Option Name: Href.Host.IPv6 678 Reference: [RFCXXXX] 680 o Option Number: 11 681 Option Name: Href.Port 682 Reference: [RFCXXXX] 684 o Option Number: 12 685 Option Name: Href.Path 686 Reference: [RFCXXXX] 688 o Option Number: 13 689 Option Name: Href.Query 690 Reference: [RFCXXXX] 692 o Option Number: 14 693 Option Name: Href.Fragment 694 Reference: [RFCXXXX] 696 o Option Number: 15 697 Option Name: Other-Href 698 Reference: [RFCXXXX] 700 o Option Number: 20 701 Option Name: Title 702 Reference: [RFCXXXX] 704 7.2. Media Type 706 This document registers the media type "application/coral" in the 707 "Media Types" registry. 709 Type name: 710 application 712 Subtype name: 713 coral 715 Required parameters: 716 N/A 718 Optional parameters: 719 N/A 721 Encoding considerations: 722 CoRAL is a binary encoding. 724 Security considerations: 725 See Section 6 of [RFCXXXX]. 727 Interoperability considerations: 728 There are no known interoperability issues. 730 Published specification: 731 [RFCXXXX] 733 Applications that use this media type: 734 N/A 736 Fragment identifier considerations: 737 Fragment identifiers used with "application/coral" representations 738 refer to the link or form with the indicated unique identifier. 739 See Section 4.4 of [RFCXXXX] for details. 741 Additional information: 742 Deprecated alias names for this type: N/A 743 Magic number(s): N/A 744 File extension(s): N/A 745 Macintosh file type code(s): N/A 747 Person & email address to contact for further information: 748 See "Author's Address" section of [RFCXXXX]. 750 Intended usage: 751 COMMON 753 Restrictions on usage: 754 N/A 756 Author: 757 See "Author's Address" section of [RFCXXXX]. 759 Change controller: 760 IESG 762 7.3. Structured Syntax Suffix 764 This document registers the suffix "+coral" in the "Structured Syntax 765 Suffix" registry. 767 Name: 768 Constrained RESTful Application Language (CoRAL) 770 +suffix: 771 +coral 773 References: 774 [RFCXXXX] 776 Encoding considerations: 777 CoRAL is a binary encoding. 779 Interoperability considerations: 780 There are no known interoperability issues. 782 Fragment identifier considerations: 784 The syntax and semantics of fragment identifiers specified for 785 +coral are as specified for "application/coral". 787 Security considerations: 788 See Section 6 of [RFCXXXX]. 790 Contact: 791 See "Author's Address" section of [RFCXXXX]. 793 Author/Change controller: 794 IESG 796 7.4. CoAP Content-Format 798 This document registers a content format for the "application/coral" 799 media type in the "CoAP Content-Formats" registry. 801 o Media Type: application/coral 802 Encoding: - 803 ID: 70 804 Reference: [RFCXXXX] 806 8. References 808 8.1. Normative References 810 [I-D.hartke-core-apps] 811 Hartke, K., "CoRE Application Descriptions", draft-hartke- 812 core-apps-03 (work in progress), February 2016. 814 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 815 Requirement Levels", BCP 14, RFC 2119, 816 DOI 10.17487/RFC2119, March 1997, 817 . 819 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 820 Resource Identifier (URI): Generic Syntax", STD 66, 821 RFC 3986, DOI 10.17487/RFC3986, January 2005, 822 . 824 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 825 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 826 DOI 10.17487/RFC5226, May 2008, 827 . 829 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 830 DOI 10.17487/RFC5988, October 2010, 831 . 833 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 834 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 835 October 2013, . 837 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 838 Application Protocol (CoAP)", RFC 7252, 839 DOI 10.17487/RFC7252, June 2014, 840 . 842 8.2. Informative References 844 [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification 845 0.99", January 2014, 846 . 848 [I-D.greevenbosch-appsawg-cbor-cddl] 849 Vigano, C. and H. Birkholz, "CBOR data definition language 850 (CDDL): a notational convention to express CBOR data 851 structures", draft-greevenbosch-appsawg-cbor-cddl-07 (work 852 in progress), October 2015. 854 [I-D.hartke-core-lighting] 855 Hartke, K., "CoRE Lighting", draft-hartke-core-lighting-00 856 (work in progress), September 2015. 858 [I-D.kelly-json-hal] 859 Kelly, M., "JSON Hypertext Application Language", draft- 860 kelly-json-hal-07 (work in progress), July 2015. 862 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 863 Constrained-Node Networks", RFC 7228, 864 DOI 10.17487/RFC7228, May 2014, 865 . 867 [W3C.REC-rdf11-concepts-20140225] 868 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 869 Concepts and Abstract Syntax", World Wide Web Consortium 870 Recommendation REC-rdf11-concepts-20140225, February 2014, 871 . 873 [W3C.REC-turtle-20140225] 874 Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", 875 World Wide Web Consortium Recommendation REC-turtle- 876 20140225, February 2014, 877 . 879 [W3C.REC-webarch-20041215] 880 Jacobs, I. and N. Walsh, "Architecture of the World Wide 881 Web, Volume One", World Wide Web Consortium 882 Recommendation REC-webarch-20041215, December 2004, 883 . 885 [WOTPRAC] Peintner, D. and M. Kovatsch, "WoT Current Practices", 886 February 2016, . 889 Appendix A. Examples 891 A.1. CoRE Lighting 893 CoRE Lighting [I-D.hartke-core-lighting] defines a benchmark scenario 894 for the exploration of hypermedia-oriented design in constrained, 895 RESTful environments. The bulletin board example presented in 896 Section 5.2.1 of [I-D.hartke-core-lighting] could be serialized in 897 CoRAL as follows: 899 [ /rel_form/ 68, 900 /create-item/ 1, 901 [ /accept/ 2, 65200, 902 /href.path/ 12, "bulletins" ]] 903 [ /abs_link/ 0, 904 /item/ 30, 905 [ /format/ 3, 65200, 906 /href.host.name/ 6, "light-bulb.example" ], 907 <<< 908 [ /rel_link/ 4, 909 /config/ -100, 910 [ /format/ 3, 65202, 911 /href.path/ 12, "config" ]], 912 [ /anon_link/ 12, 913 /name/ -101, 914 [ /format/ 3, 0 /text//plain/ ], 915 <<< 916 Light 2 917 >>> ], 918 [ /anon_link/ 12, 919 /purpose/ -102, 920 [ /format/ 3, 0 /text//plain/ ], 921 <<< 922 Illuminates the couch. 923 >>> ], 924 [ /anon_link/ 12, 925 /location/ -103, 926 [ /format/ 3, 0 /text//plain/ ], 927 <<< 928 Living Room 929 >>> ] 930 >>> ] 931 [ /abs_link/ 0, 932 /item/ 30, 933 [ /format/ 3, 65200, 934 /href.host.name/ 6, "remote-control.example" ], 935 <<< 936 [ /rel_link/ 4, 937 /about/ 1, 938 [ /format/ 3, 65203, 939 /href.path/ 12, "state" ]], 940 [ /anon_link/ 12, 941 /name/ -101, 942 [ /format/ 3, 0 /text//plain/ ], 943 <<< 944 LRC 1 945 >>> ], 946 [ /anon_link/ 12, 947 /purpose/ -102, 948 [ /format/ 3, 0 /text//plain/ ], 949 <<< 950 Controls Light 2. 951 >>> ], 952 [ /anon_link/ 12, 953 /location/ -103, 954 [ /format/ 3, 0 /text//plain/ ], 955 <<< 956 Living Room 957 >>> ] 958 >>> ] 960 A.2. W3C WoT Thing Description 962 The W3C Web of Things (WoT) Thing Description (TD) [WOTPRAC] provides 963 a vocabulary for describing an a 'thing' based on metadata and 964 interactions. A thing description like 965 { 966 "@context": ".../w3c-wot-td-context.jsonld", 967 "interactions": [ 968 { 969 "@type": "Property", 970 "name": "colorTemperature", 971 "outputData": "xsd:unsignedShort", 972 "writable": true 973 }, { 974 "@type": "Property", 975 "name": "rgbValueRed", 976 "outputData": "xsd:unsignedByte", 977 "writable": false 978 }, { 979 "@type": "Property", 980 "name": "rgbValueGreen", 981 "outputData": "xsd:unsignedByte", 982 "writable": false 983 }, { 984 "@type": "Property", 985 "name": "rgbValueBlue", 986 "outputData": "xsd:unsignedByte", 987 "writable": false 988 } 989 ] 990 } 992 could be serialized in CoRAL as follows: 994 [ /updateable_def_link/ 10, 995 /colorTemperature/ -200, 996 [ /format/ 3, 10 /uint16/ ]] 997 [ /def_link/ 8, 998 /rgbValueRed/ -201, 999 [ /format/ 3, 9 /uint8/ ]] 1000 [ /def_link/ 8, 1001 /rgbValueGreen/ -202, 1002 [ /format/ 3, 9 /uint8/ ]] 1003 [ /def_link/ 8, 1004 /rgbValueBlue/ -203, 1005 [ /format/ 3, 9 /uint8/ ]] 1007 Each "Property" interaction in Thing Description is mapped to a link, 1008 the "name" attribute to a local link relation type, the "outputData" 1009 attribute to the Format Option, and the "writable" attribute to the 1010 Updateable Flag. 1012 (This example assumes the definition of appropriate local link 1013 relations, a media type with content format ID 9 for xsd:unsignedByte 1014 and a media type with content format ID 10 for xsd:unsignedShort.) 1016 Acknowledgements 1018 This specification is heavily inspired by the JSON Hypertext 1019 Application Language (HAL) [I-D.kelly-json-hal]; the author of and 1020 contributors to that specification are acknowledged for their great 1021 work. 1023 Yassin Nasir Hassan suggested placing the hypermedia controls for 1024 modifying a link target in the link context rather than in the 1025 representation of the link target. 1027 Carsten Bormann contributed the CDDL grammar and CBOR examples. 1029 Author's Address 1031 Klaus Hartke 1032 Universitaet Bremen TZI 1033 Postfach 330440 1034 Bremen D-28359 1035 Germany 1037 Phone: +49-421-218-63905 1038 Email: hartke@tzi.org