idnits 2.17.1 draft-hartke-t2trg-coral-03.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 (September 11, 2017) is 2412 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Experimental ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '4' on line 624 -- Looks like a reference, but probably isn't: '5' on line 627 -- Looks like a reference, but probably isn't: '6' on line 628 == Missing Reference: 'I-D.hartke-t2trg-coral' is mentioned on line 1442, but not defined == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-00 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-10) exists of draft-ietf-core-links-json-09 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7320 (Obsoleted by RFC 8820) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Thing-to-Thing Research Group K. Hartke 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Experimental September 11, 2017 5 Expires: March 15, 2018 7 The Constrained RESTful Application Language (CoRAL) 8 draft-hartke-t2trg-coral-03 10 Abstract 12 The Constrained RESTful Application Language (CoRAL) defines a data 13 model and interaction model as well as two specialized serialization 14 formats for the description of typed connections between resources on 15 the Web ("links"), possible operations on such resources ("forms"), 16 and simple resource metadata. 18 Discussion Venue 20 This Internet-Draft is discussed on the Thing-to-Thing Research Group 21 (T2TRG) mailing list . 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on March 15, 2018. 40 Copyright Notice 42 Copyright (c) 2017 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 4 59 2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 2.1. Web Linking . . . . . . . . . . . . . . . . . . . . . . . 4 61 2.2. Links, Forms, and Metadata . . . . . . . . . . . . . . . 5 62 3. Data and Interaction Model . . . . . . . . . . . . . . . . . 6 63 3.1. Browsing Context . . . . . . . . . . . . . . . . . . . . 7 64 3.2. Documents . . . . . . . . . . . . . . . . . . . . . . . . 7 65 3.3. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 7 66 3.4. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 3.5. Form Data . . . . . . . . . . . . . . . . . . . . . . . . 9 68 3.6. Navigation . . . . . . . . . . . . . . . . . . . . . . . 9 69 3.7. History Traversal . . . . . . . . . . . . . . . . . . . . 10 70 4. Binary Format . . . . . . . . . . . . . . . . . . . . . . . . 11 71 4.1. Data Structure . . . . . . . . . . . . . . . . . . . . . 11 72 4.1.1. Documents . . . . . . . . . . . . . . . . . . . . . . 11 73 4.1.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 11 74 4.1.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 12 75 4.1.4. Directives . . . . . . . . . . . . . . . . . . . . . 14 76 5. Textual Format . . . . . . . . . . . . . . . . . . . . . . . 14 77 5.1. Lexical Structure . . . . . . . . . . . . . . . . . . . . 15 78 5.1.1. Line Terminators . . . . . . . . . . . . . . . . . . 15 79 5.1.2. White Space . . . . . . . . . . . . . . . . . . . . . 15 80 5.1.3. Comments . . . . . . . . . . . . . . . . . . . . . . 15 81 5.1.4. Identifiers . . . . . . . . . . . . . . . . . . . . . 15 82 5.1.5. IRI References . . . . . . . . . . . . . . . . . . . 16 83 5.1.6. Literals . . . . . . . . . . . . . . . . . . . . . . 16 84 5.1.7. Punctuators . . . . . . . . . . . . . . . . . . . . . 19 85 5.2. Syntactic Structure . . . . . . . . . . . . . . . . . . . 19 86 5.2.1. Documents . . . . . . . . . . . . . . . . . . . . . . 20 87 5.2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 20 88 5.2.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 21 89 5.2.4. Directives . . . . . . . . . . . . . . . . . . . . . 22 90 6. Usage Considerations . . . . . . . . . . . . . . . . . . . . 23 91 6.1. Specifying CoRAL-based Applications . . . . . . . . . . . 23 92 6.1.1. Naming Resources . . . . . . . . . . . . . . . . . . 24 93 6.2. Minting New Relation Types . . . . . . . . . . . . . . . 24 94 6.3. Registering Relation Types . . . . . . . . . . . . . . . 25 95 6.4. Expressing Target Attributes . . . . . . . . . . . . . . 26 96 6.5. Embedding CoRAL in CBOR Structures . . . . . . . . . . . 26 98 7. Security Considerations . . . . . . . . . . . . . . . . . . . 27 99 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 100 8.1. Media Type "application/coral+cbor" . . . . . . . . . . . 28 101 8.2. Media Type "text/coral" . . . . . . . . . . . . . . . . . 29 102 8.3. CoAP Content Formats . . . . . . . . . . . . . . . . . . 30 103 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 104 9.1. Normative References . . . . . . . . . . . . . . . . . . 31 105 9.2. Informative References . . . . . . . . . . . . . . . . . 33 106 Appendix A. Core Vocabulary . . . . . . . . . . . . . . . . . . 35 107 A.1. Link Relation Types . . . . . . . . . . . . . . . . . . . 35 108 A.2. Form Relation Types . . . . . . . . . . . . . . . . . . . 35 109 A.3. Form Field Names . . . . . . . . . . . . . . . . . . . . 36 110 Appendix B. Default Profile . . . . . . . . . . . . . . . . . . 36 111 Appendix C. CBOR-encoded IRI References . . . . . . . . . . . . 37 112 C.1. Data Structure . . . . . . . . . . . . . . . . . . . . . 37 113 C.2. Options . . . . . . . . . . . . . . . . . . . . . . . . . 38 114 C.3. Properties . . . . . . . . . . . . . . . . . . . . . . . 39 115 C.4. Reference Resolution . . . . . . . . . . . . . . . . . . 39 116 C.5. IRI Recomposition . . . . . . . . . . . . . . . . . . . . 41 117 C.6. CoAP Encoding . . . . . . . . . . . . . . . . . . . . . . 44 118 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 46 120 1. Introduction 122 The Constrained RESTful Application Language (CoRAL) is a language 123 for the description of typed connections between resources on the Web 124 ("links"), possible operations on such resources ("forms"), as well 125 as simple resource metadata. 127 CoRAL is intended for driving automated software agents that navigate 128 a Web application based on a standardized vocabulary of link and form 129 relation types. CoRAL is designed to be used in conjunction with a 130 Web transfer protocol such as the Hypertext Transfer Protocol (HTTP) 131 [RFC7230] or the Constrained Application Protocol (CoAP) [RFC7252]. 133 This document defines the CoRAL data and interaction model as well as 134 two specialized CoRAL serialization formats. 136 The CoRAL data and interaction model is a superset of the Web linking 137 model described in RFC 5988 [I-D.nottingham-rfc5988bis]. The data 138 model consists of two elements: _links_, which describe relationships 139 between pairs of resources and the type of those relationships, and 140 _forms_, which describe possible operations on resources and the type 141 of those operations. Additionally, the model can describe simple 142 resource metadata in a style similar to the Resource Description 143 Framework (RDF) [W3C.REC-rdf11-concepts-20140225]. In contrast to 144 RDF, the focus of CoRAL however is on the interaction with resources, 145 not just on the relationships between them. The interaction model 146 derives from HTML 5 [W3C.REC-html51-20161101] and specifies how an 147 automated software agent can navigate between resources by following 148 links and perform operations on resources by submitting forms. 150 The primary CoRAL serialization format is a compact, binary encoding 151 of links and forms in Concise Binary Object Representation (CBOR) 152 [RFC7049]. It is intended for environments with constraints on 153 power, memory, and processing resources [RFC7228] and shares many 154 similarities with the message format of the Constrained Application 155 Protocol (CoAP) [RFC7252]: It uses numeric identifiers instead of 156 verbose strings for link and form relation types and pre-parses URIs 157 into (what CoAP considers to be) their components, which simplifies 158 URI processing greatly. As a result, link serializations are often 159 much more compact than equivalent serializations in CoRE Link Format 160 [RFC6690], including its CBOR variant [I-D.ietf-core-links-json]. 161 Additionally, the format supports the serialization of forms, which 162 the CoRE Link Format does not support. 164 The second serialization format is a light, textual encoding of links 165 and forms that is intended to be easy to read and write by humans. 166 The format is used for giving examples throughout the document and is 167 stylistically similar to Turtle [W3C.REC-turtle-20140225], although 168 it is not a syntax for RDF. 170 1.1. Requirements Notation 172 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 173 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 174 "OPTIONAL" in this document are to be interpreted as described in BCP 175 14 [RFC2119] [RFC8174] when, and only when, they appear in all 176 capitals, as shown here. 178 2. Examples 180 2.1. Web Linking 182 At its core, CoRAL is just yet another serialization format for Web 183 links. For example, if an HTTP client sends the following request: 185 GET /TheBook/chapter3 HTTP/1.1 186 Host: example.com 188 and receives the following response: 190 HTTP/1.1 200 OK 191 Content-Type: text/coral 193 #using 195 next <./chapter4> 196 icon 197 license 199 then the representation contains the following three links: 201 o one link of type "http://www.iana.org/assignments/relation/next" 202 from to 203 , 205 o one link of type "http://www.iana.org/assignments/relation/icon" 206 from to , and 209 o one link of type "http://www.iana.org/assignments/relation/ 210 license" from to 211 . 213 This representation is equivalent to the following Link header field 214 [I-D.nottingham-rfc5988bis]: 216 Link: <./chapter4>; rel="next", 217 ; rel="icon", 218 ; rel="license" 220 and the following HTML 5 [W3C.REC-html51-20161101] link elements: 222 223 224 227 2.2. Links, Forms, and Metadata 229 In its entirety, CoRAL is an expressive language for describing Web 230 links between resources, possible operations on these resources, and 231 simple resource metadata. For example, if an HTTP client sends the 232 following request: 234 GET /tasks HTTP/1.1 235 Host: example.com 237 and receives the following response: 239 HTTP/1.1 200 OK 240 Content-Type: text/coral 242 #using 243 #using coral = 245 task { 246 description "Pick up the kids" 247 } 249 task { 250 description "Return the books to the library" 251 coral:delete -> DELETE 252 } 254 coral:create -> POST [coral:accept "example/task"] 256 then the representation contains the following six elements: 258 o one link of type "http://example.org/vocabulary#task" from 259 to , 261 o one link of type "http://example.org/vocabulary#description" from 262 to "Pick up the kids", 264 o one link of type "http://example.org/vocabulary#task" from 265 to , 267 o one link of type "http://example.org/vocabulary#description" from 268 to "Return the books to the library", 270 o one form of type "urn:ietf:rfc:XXXX#delete" that can be used to 271 delete by making a DELETE request to 272 , and 274 o one form of type "urn:ietf:rfc:XXXX#create" that can be used to 275 create a new item in by making a POST 276 request to with an "example/task" 277 payload. 279 3. Data and Interaction Model 281 The Constrained RESTful Application Language (CoRAL) is designed for 282 building Web-based applications [W3C.REC-webarch-20041215] in which 283 automated software agents navigate between resources by following 284 links and perform operations on resources by submitting forms. 286 3.1. Browsing Context 288 Borrowing from HTML 5 [W3C.REC-html51-20161101], each such agent 289 maintains a _browsing context_ in which the representations of Web 290 resources are processed. (In HTML 5, the browsing context typically 291 corresponds to a tab or window in a Web browser.) 293 A browsing context has a _session history_, which lists the resource 294 representations that the agent has processed, is processing, or will 295 process. At any time, one representation in each browsing context is 296 designated the _active_ representation. 298 A session history consists of a flat list of session history entries. 299 Each _session history entry_ consists of a resource representation 300 and the Internationalized Resource Identifier (IRI) [RFC3987] that 301 was used to retrieve the representation. An entry may additionally 302 have other information associated with it. New entries are added to 303 the session history as the agent navigates from resource to resource. 305 3.2. Documents 307 A resource representation in one of the CoRAL serialization formats 308 is called a CoRAL _document_. The IRI that was used to retrieve a 309 document is called the document's _retrieval context_. 311 A CoRAL document consists of a list of zero or more links and forms, 312 collectively called _elements_. CoRAL serialization formats may 313 define additional types of elements for efficiency or convenience, 314 such as a base IRI for relative IRI references. 316 3.3. Links 318 A _link_ describes a relationship between two resources on the Web. 319 It consists of a _link context_, a _link relation type_, and a _link 320 target_. A link may additionally have a nested list of zero or more 321 elements, which take the place of link target attributes in CoRAL. 323 A link can be viewed as a statement of the form "_link context_ has a 324 _link relation type_ resource at _link target_", where the link 325 target may be further described by nested links and forms. 327 The link relation type identifies the semantics of a link. In HTML 5 328 and RFC 5988 Link headers, a link relation type is typically denoted 329 by a registered name, such as "stylesheet" or "icon". In CoRAL, a 330 link relation type is denoted by an IRI or an unsigned integer. IRIs 331 allow the creation of new, unique relation types in a decentralized 332 fashion, but impose some overhead on the size of representations. 333 Unsigned integers on the other hand minimize the overhead of link 334 relation types in constrained environments, but necessitate the 335 assignment of values by a registry. 337 The link context and the link target are both resources. Resources 338 in CoRAL are denoted either by an IRI reference or a literal, similar 339 to RDF. If the scheme of the IRI indicates a Web transfer protocol 340 such as HTTP or CoAP, then an agent can dereference the IRI and 341 navigate their browsing context to the referenced resource; this is 342 called _following the link_. A literal directly identifies a value. 343 CoRAL supports Boolean values, integers, floating-point values, byte 344 strings, and text strings as literals. 346 A link can occur as a top-level element in a document or as a nested 347 element within a link. When a link occurs as a top-level element in 348 a document, the link context is implicitly the document's retrieval 349 context. When a link occurs within a link, the link context of the 350 inner link is the link target of the outer link. 352 There are no restrictions on the cardinality of links; there can be 353 multiple links to and from a particular target, and multiple links of 354 the same or different types between a given link context and target. 355 However, the CoRAL data model constrains the description of a web of 356 resources to a graph in tree shape: Links between linked resources 357 can only be described by further nesting links. 359 3.4. Forms 361 A _form_ provides instructions to an agent for performing an 362 operation on a Web resource. It consists of a _form context_, a 363 _form relation type_, a _request method_, and a _submission IRI_. 364 Additionally, a form MAY be accompanied by _form data_. 366 A form can be viewed as an instruction of the form "To perform a 367 _form relation type_ operation on _form context_, make a _request 368 method_ request to _submission IRI_", where the payload of the 369 request may be further described by form data. 371 The form relation type identifies the semantics of the operation. 372 Like link relation types, the form relation type can be denoted by an 373 IRI or an unsigned integer. Link and form relation types constitute 374 different namespaces, though. 376 The form context is the resource on which an operation is ultimately 377 performed. To perform the operation, an agent must construct a 378 request with the specified request method and submission IRI. The 379 set of possible request methods is defined by the protocol identified 380 by the scheme of the submission IRI. The submission IRI typically 381 refers to the form context, but MAY refer to a different resource. 382 Constructing and sending the request is called _submitting the form_. 384 If a form is accompanied by form data (see Section 3.5 below), the 385 agent MUST also construct and include a payload in the request that 386 matches the specifications of the form data when submitting the form. 388 A form can occur as a top-level element in a document or as a nested 389 element within a link. When a form occurs as a top-level element in 390 a document, the form context is implicitly the document's retrieval 391 context. When a form occurs within a link, the form context is the 392 link target of the enclosing link. 394 3.5. Form Data 396 Form data provides instructions for agents to construct a request 397 payload. It consists of a list of zero or more _form fields_. Each 398 form field consists of a _form field name_ and a _form field value_. 400 Form fields can either directly identify data items that need to be 401 included in the request payload or reference an external resource 402 (such as a schema) that describes the data. Additionally, they can 403 provide other information, such as acceptable serialization formats. 405 The form field name identifies the semantics of the form field. Like 406 link and form relation types, a form field name is denoted by an IRI 407 or an unsigned integer. 409 The form field value can be an IRI, a Boolean value, an integer, a 410 floating-point value, a byte string, or a text string. 412 3.6. Navigation 414 An agent begins interacting with an application through a GET request 415 on an _entry point IRI_. The entry point IRI is the only IRI an agent 416 is expected to know before interacting with an application. From 417 there, the agent is expected to make all requests by following links 418 and submitting forms that are provided by the server in responses. 419 The entry point IRI can be obtained by manual configuration or some 420 discovery process. 422 If dereferencing the entry point IRI yields a CoRAL document or any 423 other representation that implements the CoRAL data and interaction 424 model, then the agent proceeds as follows: 426 1. The first step for the agent is to decide what to do next, i.e., 427 which type of link to follow or form to submit, based on the link 428 relation types and form relation types it understands. 430 2. The agent finds the link(s) or form(s) with the given relation 431 type in the active representation. This may yield one or more 432 candidates, from which the agent must select the most appropriate 433 one in the next step. The set of candidates MAY be empty, for 434 example, if a transition is not supported or allowed. 436 3. The agent selects one of the candidates based on the metadata 437 associated with the link(s) or form(s). Metadata typically 438 includes the media type of the target resource representation, 439 the IRI scheme, the request method, and other information that 440 describe the element. 442 4. The agent resolves the IRI reference in the link or form to 443 obtain the _request IRI_. Fragment identifiers are not part of 444 the request IRI and MUST be separated from the rest of the IRI 445 prior to a dereference. The request IRI may need to be converted 446 to a URI (see Section 3.1 of RFC 3987 [RFC3987]) for protocols 447 that do not support IRIs. 449 5. The agent constructs a new request with the request IRI. If the 450 agent follows a link, the request method MUST be GET. If the 451 agent submits a form, the request method MUST be the one 452 specified in the form. The agent SHOULD set HTTP header fields 453 and CoAP request options according to provided metadata (e.g., 454 set the HTTP Accept header field or the CoAP Accept option when 455 the media type of the target resource is provided). In the case 456 of a form with form data, the agent MUST include a request 457 payload that matches the specifications of the form data. 459 6. The agent sends the request and retrieves the response. 461 7. If a fragment identifier was separated from the request IRI, the 462 agent dereferences the fragment identifier within the retrieved 463 representation. 465 8. The agent _updates the session history_: It removes all the 466 entries in the browsing context's session history after the 467 current entry. Then it appends a new entry at the end of the 468 history representing the new resource. 470 9. Finally, if response contains a CoRAL document, the agent can 471 again decide what to do next. 473 3.7. History Traversal 475 An agent can additionally navigate a browsing context by traversing 476 the browsing context's session history. An agent can _traverse the 477 session history_ by updating the active representation to the that 478 entry. 480 4. Binary Format 482 This section defines the encoding of documents in the CoRAL binary 483 format. 485 A document in the binary format is a data item in Concise Binary 486 Object Representation (CBOR) [RFC7049]. The structure of this data 487 item is presented in the Concise Data Definition Language (CDDL) 488 [I-D.ietf-cbor-cddl]. 490 4.1. Data Structure 492 The data structure of a document in the binary format is made up of 493 three kinds of elements: links and forms, as defined by the CoRAL 494 data model, and base IRI directives. Base IRI directives provide a 495 way to encode IRI references with a common base more efficiently. 497 Elements are processed in the order they appear in the document. 498 Document processors need to maintain an _environment_ while iterating 499 an array of elements. The environment consists of three variables: a 500 _current context IRI_, a _current base IRI_, and a _current relation 501 type_. The current context IRI and current base IRI are initially 502 both set to the document's retrieval context. The current relation 503 type is initially set to the unsigned integer zero. 505 4.1.1. Documents 507 The body of a document in the binary format is encoded as an array of 508 zero or more links, forms, and directives. 510 body = [*(link / form / directive)] 512 4.1.2. Links 514 A link is encoded as an array that consists of the unsigned integer 515 2, followed by the link relation type and the link target, optionally 516 followed by a link body that contains nested elements. 518 link = [link: 2, relation, target, ?body] 520 The link relation type is encoded either as a text string containing 521 an absolute IRI reference or as an (unsigned or negative) integer 522 representing the difference to the current relation type. A link is 523 processed by updating the current relation type to the result of 524 adding the specified integer (or zero in the case of a text string) 525 to the current relation type. 527 relation = text / int 529 The link target is denoted by an IRI reference or represented by a 530 literal value. The IRI reference may be relative or absolute and is 531 resolved against the current base IRI. The encoding of IRI 532 references in the binary format is described in Appendix C. The link 533 target MAY be null, which indicates that the link target is an 534 unidentified resource. 536 target = iri / literal / null 538 literal = bool / int / float / bytes / text 540 The array of elements in the link body (if any) MUST be processed in 541 a fresh environment. The current context IRI and current base IRI in 542 the new environment are initially both set to the link target of the 543 enclosing link. The current relation type in the new environment is 544 initially set to the current relation type. 546 4.1.3. Forms 548 A form is encoded as an array that consists of the unsigned integer 549 3, followed by the form relation type, the submission method, and a 550 submission IRI reference, optionally followed by form data. 552 form = [form: 3, relation, method, iri, ?form-data] 554 The form relation type is encoded and processed in the same way as a 555 link relation type; see Section 4.1.2. 557 The method is encoded as a text string or an unsigned integer that 558 refers to one of the request methods defined by the protocol that is 559 identified by the scheme of the submission IRI. Method identifiers 560 in the form of text strings are constrained to the range of US-ASCII 561 characters and are case-insensitive. 563 method = text / uint 565 For HTTP [RFC7231], the method MUST be encoded as a text string; the 566 set of possible values is maintained in the IANA HTTP Method 567 Registry. For CoAP [RFC7252], the method MUST be encoded as an 568 unsigned integer (e.g., the unsigned integer 2 for the POST method); 569 the set of possible values is maintained in the IANA CoAP Method 570 Codes Registry. 572 The submission IRI reference may be relative or absolute and is 573 resolved against the current base IRI. The encoding of IRI 574 references in the binary format is described in Appendix C. 576 4.1.3.1. Form Data 578 Form data is encoded as an array of zero or more name-value pairs. 580 form-data = [*(form-field-name, form-field-value)] 582 Form data (if any) MUST be processed in a fresh environment. The 583 current context IRI and current base IRI in the new environment are 584 initially both set to the submission IRI of the enclosing form. The 585 current relation type in the new environment is initially set to the 586 current relation type. 588 A form field name is encoded and processed in the same way as a link 589 relation type; see Section 4.1.2. 591 form-field-name = text / uint 593 A form field value can be an IRI reference, Boolean value, integer, 594 floating-point value, byte string, or text string. An IRI reference 595 may be relative or absolute and is resolved against the current base 596 IRI. The encoding of IRI references in the binary format is 597 described in Appendix C. 599 form-field-value = iri / bool / int / float / bytes / text 601 4.1.3.2. Short Forms 603 Forms in certain shapes can be encoded in a more efficient manner 604 using short forms. The following short forms are available: 606 form =/ [form.create: 4, ?accept: uint .size 2] 608 form =/ [form.update: 5] 610 form =/ [form.delete: 6] 612 If the scheme of the submission IRI indicates HTTP, the short forms 613 expand as follows: 615 [4] -> [3, "urn:ietf:rfc:XXXX#create", "POST", []] 616 [4, x] -> [3, "urn:ietf:rfc:XXXX#create", "POST", [], 617 ["urn:ietf:rfc:XXXX#accept", x]] 618 [5] -> [3, "urn:ietf:rfc:XXXX#update", "PUT", []] 619 [6] -> [3, "urn:ietf:rfc:XXXX#delete", "DELETE", []] 621 If the scheme of the submission IRI indicates CoAP, the short forms 622 expand as follows: 624 [4] -> [3, "urn:ietf:rfc:XXXX#create", 2, []] 625 [4, x] -> [3, "urn:ietf:rfc:XXXX#create", 2, [], 626 ["urn:ietf:rfc:XXXX#accept", x]] 627 [5] -> [3, "urn:ietf:rfc:XXXX#update", 3, []] 628 [6] -> [3, "urn:ietf:rfc:XXXX#delete", 4, []] 630 The form relation types and form field names in the above expansions 631 are defined in Appendix A. 633 4.1.4. Directives 635 Directives provide the ability to manipulate the environment when 636 processing a list of elements. There is one directive available: the 637 Base URI directive. 639 directive = base-directive 641 4.1.4.1. Base URI Directives 643 A Base IRI directive is encoded as an array that consists of the 644 unsigned integer 1, followed by an IRI reference. 646 base-directive = [base: 1, iri] 648 The encoding of IRI references in the binary format is described in 649 Appendix C. 651 The directive is processed by resolving the IRI reference against the 652 current context IRI and assigning the result to the current base IRI. 654 5. Textual Format 656 This section defines the syntax of documents in the CoRAL textual 657 format using two grammars: The lexical grammar defines how Unicode 658 characters are combined to form line terminators, white space, 659 comments, and tokens. The syntactic grammar defines how the tokens 660 are combined to form documents. Both grammars are presented in 661 Augmented Backus-Naur Form (ABNF) [RFC5234]. 663 A document in the textual format is a Unicode string in a Unicode 664 encoding form [UNICODE]. The media type for such documents is "text/ 665 coral". The "charset" parameter is not used; charset information is 666 transported inside the document in the form of an OPTIONAL Byte Order 667 Mark (BOM). The use of the UTF-8 encoding scheme [RFC3629], without 668 a BOM, is RECOMMENDED. 670 5.1. Lexical Structure 672 The lexical structure of a document in the textual format is made up 673 of four basic elements: line terminators, white space, comments, and 674 tokens. Of these, only tokens are significant in the syntactic 675 grammar. There are four kinds of tokens: identifiers, IRI 676 references, literals, and punctuators. 678 When several lexical grammar rules match a sequence of characters in 679 a document, the longest match takes priority. 681 5.1.1. Line Terminators 683 Line terminators divide text into lines. A line terminator is any 684 Unicode character with Line_Break class BK, CR, LF, or NL. However, 685 any CR character that immediately precedes a LF character is ignored. 686 (This affects only the numbering of lines in error messages.) 688 5.1.2. White Space 690 White space is a sequence of one or more white space characters. A 691 white space character is any Unicode character with the White_Space 692 property. 694 5.1.3. Comments 696 Comments are sequences of characters that are ignored when parsing 697 text into tokens. Single-line comments begin with the characters 698 "//" and extend to the end of the line. Delimited comments begin 699 with the characters "/*" and end with the characters "*/". Delimited 700 comments can occupy a portion of a line, a single line, or multiple 701 lines. 703 Comments do not nest. The character sequences "/*" and "*/" have no 704 special meaning within a single-line comment, and the character 705 sequences "//" and "/*" have no special meaning within a delimited 706 comment. 708 5.1.4. Identifiers 710 Identifier tokens are user-defined symbolic names. The rules for 711 identifiers correspond exactly to those recommended by the Unicode 712 Standard Annex #31 [UNICODE-UAX31]: An identifier consists of a 713 Unicode character in the ID_Start class followed by zero or more 714 Unicode characters in the ID_Continue class. 716 identifier = ID_Start *ID_Continue 717 ID_Start = 719 ID_Continue = 721 All identifiers MUST be converted into Unicode Normalization Form C 722 (NFC), as defined by the Unicode Standard Annex #15 [UNICODE-UAX15]. 723 Comparison of identifiers is based on NFC and is case-sensitive 724 (unless otherwise noted). 726 5.1.5. IRI References 728 An IRI reference is a Unicode string that conforms to the syntax 729 defined in RFC 3987 [RFC3987]. An IRI reference may be absolute or 730 relative and may contain a fragment identifier. IRI references are 731 enclosed in angle brackets ("<" and ">"). 733 iri = %x3C IRI-reference %x3E 735 IRI-reference = 737 5.1.6. Literals 739 A literal is a textual representation of a value. There are six 740 types of literals: Boolean, integer, floating-point, byte string, 741 text string, and null. 743 5.1.6.1. Boolean Literals 745 The case-sensitive literals "true" and "false" denote the Boolean 746 values true and false, respectively. 748 boolean = %x74.72.75.65 / %x66.61.6C.73.65 750 5.1.6.2. Integer Literals 752 Integer literals denote integer values of unspecified precision. By 753 default, integer literals are expressed in decimal, but they can also 754 be specified in an alternate base using a prefix. Binary literals 755 begin with "0b", octal literals begin with "0o", and hexadecimal 756 literals begin with "0x". 758 Decimal literals contain the digits "0" through "9". Binary literals 759 contain "0" and "1", octal literals contain "0" through "7", and 760 hexadecimal literals contain "0" through "9" as well as "A" through 761 "F" in upper- or lowercase. 763 Negative integers are expressed by prepending a minus sign ("-"). 765 integer = [%x2D] (decimal / binary / octal / hexadecimal) 767 decimal = 1*DIGIT 769 binary = %x30 (%x42 / %x62) 1*BINDIG 771 octal = %x30 (%x4F / %x6F) 1*OCTDIG 773 hexadecimal = %x30 (%x58 / %x78) 1*HEXDIG 775 DIGIT = %x30-39 777 BINDIG = %x30-31 779 OCTDIG = %x30-37 781 HEXDIG = %x30-39 / %x41-46 / %x61-66 783 5.1.6.3. Floating-point Literals 785 Floating-point literals denote floating-point values of unspecified 786 precision. 788 Floating-point literals consist of a sequence of decimal digits 789 followed by either a fraction, an exponent, or both. The fraction 790 consists of a decimal point (".") followed by a sequence of decimal 791 digits. The exponent consists of the upper- or lowercase letter "e" 792 followed by an optional sign and a sequence of decimal digits that 793 indicate a power of 10 by which the value preceding the "e" is 794 multiplied. 796 Negative floating-point values are expressed by prepending a minus 797 sign ("-"). 799 floating-point = [%x2D] 1*DIGIT [fraction] [exponent] 801 fraction = %x2E 1*DIGIT 803 exponent = (%x45 / %x65) [%x2B / %x2D] 1*DIGIT 805 Floating-point literals can additionally denote the special "Not- 806 a-Number" (NaN) value, positive infinity, and negative infinity. The 807 NaN value is produced by the case-sensitive token "NaN". The two 808 infinite values are produced by the case-sensitive tokens "+Infinity" 809 (or simply "Infinity") and "-Infinity". 811 floating-point =/ %x4E.61.4E 812 floating-point =/ [%x2B] %x49.6E.66.69.6E.69.74.79 814 floating-point =/ %x2D.49.6E.66.69.6E.69.74.79 816 5.1.6.4. Byte String Literals 818 A byte string literal consists of a prefix and zero or more bytes 819 encoded in Base16, Base32, or Base64 [RFC4648] and enclosed in single 820 quotes. Byte string literals encoded in Base16 begin with "h" or 821 "b16", byte string literals encoded in Base32 begin with "b32", and 822 byte string literals encoded in Base64 begin with "b64". 824 bytes = base16 / base32 / base64 826 base16 = (%x68 / %x62.31.36) SQUOTE SQUOTE 828 base32 = %x62.33.32 SQUOTE SQUOTE 830 base64 = %x62.36.34 SQUOTE SQUOTE 832 SQUOTE = %x27 834 5.1.6.5. Text String Literals 836 A text string literal consists of zero or more Unicode characters 837 enclosed in double quotes. It can include simple escape sequences 838 (such as \t for the tab character) as well as hexadecimal and Unicode 839 escape sequences. 841 text = DQUOTE *(char / %x5C escape) DQUOTE 843 char = 845 escape = simple-escape / hexadecimal-escape / unicode-escape 847 simple-escape = %x30 / %x62 / %x74 / %x6E / %x76 849 simple-escape =/ %x66 / %x72 / %x22 / %x27 / %x5C 851 hexadecimal-escape = (%x78 / %x58) 2HEXDIG 853 unicode-escape = %x75 4HEXDIG / %x55 8HEXDIG 855 DQUOTE = %x22 857 An escape sequence denotes a single Unicode code point. For 858 hexadecimal and Unicode escape sequences, the code point is expressed 859 by the hexadecimal number following the "\x", "\X", "\u", or "\U" 860 prefix. Simple escape sequences indicate the code points listed in 861 Table 1. 863 +-----------------+----------------------+------------+ 864 | Escape Sequence | Character Name | Code Point | 865 +-----------------+----------------------+------------+ 866 | \0 | Null | U+0000 | 867 | \b | Backspace | U+0008 | 868 | \t | Character Tabulation | U+0009 | 869 | \n | Line Feed | U+000A | 870 | \v | Line Tabulation | U+000B | 871 | \f | Form Feed | U+000C | 872 | \r | Carriage Return | U+000D | 873 | \" | Quotation Mark | U+0022 | 874 | \' | Apostrophe | U+0027 | 875 | \\ | Reverse Solidus | U+005C | 876 +-----------------+----------------------+------------+ 878 Table 1: Simple Escape Sequences 880 5.1.6.6. Null Literal 882 The literals "null" and "?" denote the intentional absence of any 883 value. 885 null = %x6E.75.6C.6C / %x3F 887 5.1.7. Punctuators 889 Punctuator tokens are used for grouping and separating. 891 punctuator = "#" | ":" | "[" | "]" | "{" | "}" | "=" | "->" 893 5.2. Syntactic Structure 895 The syntactic structure of a document in the textual format is made 896 up of three kinds of elements: links and forms, as defined by the 897 CoRAL data model, and directives. Directives provide a way to make 898 documents easier to read and write by defining a base IRI for 899 relative IRI references and introducing shorthands for link and form 900 relation types. 902 Elements are processed in the order they appear in the document. 903 Document processors need to maintain an _environment_ while iterating 904 a list of elements. The environment consists of three variables: a 905 _current context IRI_, a _current base IRI_, and a mapping from 906 identifiers to IRIs. The current context IRI and current base IRI 907 are initially both set to the document's retrieval context. The 908 mapping from identifiers to IRIs is initially empty. 910 5.2.1. Documents 912 The body of a document in the textual format consists of zero or more 913 links, forms, and directives. 915 body = *(link / form / directive) 917 5.2.2. Links 919 A link consists of the link relation type, followed by the link 920 target, optionally followed by a link body enclosed in curly brackets 921 ("{" and "}"). 923 link = relation target ["{" body "}"] 925 The link relation type is denoted either by an absolute IRI 926 reference, a simple name, a qualified name, or an unsigned integer. 928 relation = iri / simple-name / qualified-name / integer 930 An absolute IRI reference MUST be resolved and normalized according 931 to the IRI scheme. (It doesn't matter what base IRI it is resolved 932 against, since it is always an absolute reference.) 934 A simple name consists of an identifier. It is resolved to an IRI by 935 looking up the empty string in the mapping from identifiers to IRIs 936 in the current environment and concatenating the looked up IRI with 937 the specified identifier. It is an error if the empty string is not 938 present in the mapping. 940 simple-name = identifier 942 A qualified name consists of two identifiers separated by a colon 943 (":"). It is resolved to an IRI by looking up the identifier on the 944 left hand side in the mapping from identifiers to IRIs in the current 945 environment and concatenating the looked up IRI with the identifier 946 on the right hand side. It is an error if the identifier on the left 947 hand side is not present in the mapping. 949 qualified-name = identifier ":" identifier 951 The link target is denoted by an IRI reference or represented by a 952 value literal. The IRI reference may be relative or absolute and is 953 resolved against the current base IRI. If the link target is null, 954 the link target is an unidentified resource. 956 target = iri / literal / null 958 literal = boolean / integer / floating-point / bytes / text 960 The list of elements in the link body (if any) MUST be processed in a 961 fresh environment. The current context IRI and current base IRI in 962 this environment are initially both set to the link target of the 963 enclosing link. The mapping from identifiers to IRIs is initially 964 set to a copy of the mapping from identifiers to IRIs in the current 965 environment. 967 5.2.3. Forms 969 A form consists of the form relation type, followed by a "->" token, 970 a method identifier, and a submission IRI reference, optionally 971 followed by form data enclosed in square brackets ("[" and "]"). 973 form = relation "->" method iri ["[" form-data "]"] 975 The form relation type is denoted in the same way as a link relation 976 type; see Section 5.2.2. 978 The method identifier refers to one of the request methods defined by 979 the protocol that is identified by the scheme of the submission IRI. 980 Method identifiers are constrained to the range of US-ASCII 981 characters and are case-insensitive. 983 method = identifier 985 For HTTP [RFC7231], the set of possible method identifiers is 986 maintained in the IANA HTTP Method Registry. For CoAP [RFC7252], the 987 set of possible method identifiers is maintained in the IANA CoAP 988 Method Codes Registry. 990 The submission IRI reference may be relative or absolute and is 991 resolved against the current base IRI. 993 5.2.3.1. Form Data 995 Form data consists of zero or more space-separated name-value pairs. 997 form-data = *(form-field-name form-field-value) 999 Form data MUST be processed in a fresh environment. The current 1000 context IRI and current base IRI in this environment are initially 1001 both set to the submission IRI of the enclosing form. The mapping 1002 from identifiers to IRIs is initially set to a copy of the mapping 1003 from identifiers to IRIs in the current environment. 1005 The form field name is denoted in the same way as a link relation 1006 type; see Section 5.2.2. 1008 form-field-name = iri / simple-name / qualified-name / integer 1010 The form field value can be an IRI reference, Boolean literal, 1011 integer literal, floating-point literal, byte string literal, or text 1012 string literal. An IRI reference may be relative or absolute and is 1013 resolved against the current base IRI. 1015 form-field-value = iri / boolean / integer 1017 form-field-value =/ floating-point / bytes / text 1019 5.2.4. Directives 1021 Directives provide the ability to manipulate the environment when 1022 processing a list of elements. All directives start with a number 1023 sign ("#") followed by a directive identifier. Directive identifiers 1024 are constrained to the range of US-ASCII characters and are case- 1025 insensitive. 1027 The following directives are available: Base IRI directives and Using 1028 directives. 1030 directive = base-directive / using-directive 1032 5.2.4.1. Base IRI Directives 1034 A Base IRI directive consists of a number sign ("#"), followed by the 1035 case-insensitive identifier "base", followed by an IRI reference. 1037 base-directive = "#" "base" iri 1039 The directive is processed by resolving the IRI reference against the 1040 current context IRI and assigning the result to the current base IRI. 1042 5.2.4.2. Using Directives 1044 A Using directive consists of a number sign ("#"), followed by the 1045 case-insensitive identifier "using", optionally followed by an 1046 identifier and an equals sign ("="), followed by an absolute IRI 1047 reference. If the identifier is not specified, it is assumed to be 1048 the empty string. 1050 using-directive = "#" "using" [identifier "="] iri 1052 The directive is processed by resolving the IRI reference to an IRI, 1053 normalizing the IRI according to the IRIs scheme, and adding the 1054 specified identifier and resulting IRI to the mapping from 1055 identifiers to IRIs in the current environment. (It doesn't matter 1056 what the IRI reference is resolved against, since it is always an 1057 absolute reference.) It is an error if the identifier is already 1058 present in the mapping. 1060 6. Usage Considerations 1062 This section discusses some considerations in creating CoRAL-based 1063 applications and managing link and form relation types. 1065 6.1. Specifying CoRAL-based Applications 1067 CoRAL-based applications implement the Web architecture 1068 [W3C.REC-webarch-20041215] and are centered around orthogonal 1069 specifications for identification, interaction, and representation: 1071 o Resources are identified by IRIs or represented by value literals. 1073 o Interactions are based on the hypermedia interaction model of the 1074 Web and the methods provided by the Web transfer protocol. The 1075 semantics of possible interactions are identified by link and form 1076 relation types. 1078 o Representations are CoRAL documents encoded in the binary format 1079 defined in Section 4 or the textual format defined in Section 5. 1080 Depending on the application, additional representation formats 1081 may be used. 1083 Specifications for CoRAL-based applications need to specify the 1084 specific protocols and vocabulary used in the application. This 1085 SHOULD include at least the following items: 1087 o IRI schemes identifying the Web transfer protocol(s) used by the 1088 application. 1090 o Internet media types that identify the representation format(s) 1091 used by the application, including the media type(s) of the CoRAL 1092 serialization format(s). 1094 o Link relation types that identify the semantics of links. 1096 o Form relation types that identify the semantics of forms. 1097 Additionally, for each form relation type, the permissible request 1098 method(s). 1100 o Form field names that identify the semantics of form fields. 1102 6.1.1. Naming Resources 1104 Resource names [RFC3986] [RFC3987] are a cornerstone of Web-based 1105 applications. They enable uniform identification of resources and 1106 are used every time a client interacts with a server or a resource 1107 representation needs to refer to another resource. 1109 URIs and IRIs often include structured application data in the path 1110 and query components, such as paths in a filesystem or keys in a 1111 database. It is a common practice in many HTTP-based applications to 1112 make this part of the documented application interface, i.e., to 1113 prescribe a fixed URI template that is hard-coded in implementations. 1114 However, there are a number of problems with this practice [RFC7320]. 1116 In CoRAL-based applications, resource names are not part of the 1117 application interface; they are an implementation detail. The 1118 specification of a CoRAL-based application MUST NOT mandate any 1119 particular form of resource name structure. RFC 7320 [RFC7320] 1120 describes the problematic practice of fixed URI structures in more 1121 detail and provides some acceptable alternatives. 1123 6.2. Minting New Relation Types 1125 New link relation types, form relation types, and form field names 1126 can be minted by defining an IRI [RFC3987] that uniquely identifies 1127 the item. Although the IRI can point to a resource that contains a 1128 definition of the semantics of the relation type, clients SHOULD NOT 1129 automatically access that resource to avoid overburdening its server. 1130 The IRI SHOULD be under the control of the person or party defining 1131 it, or be delegated to them. 1133 Link relation types registered in the IANA Link Relations Registry, 1134 such as collection" [RFC6573] or "icon" [W3C.REC-html51-20161101], 1135 can be used in CoRAL by prepending the IRI 1136 to the registered name: 1138 #using iana = 1140 iana:collection 1141 iana:icon 1143 A good source for link relation types for resource metadata are RDF 1144 predicates [W3C.REC-rdf11-concepts-20140225]. An RDF statement says 1145 that some relationship, indicated by a predicate, holds between two 1146 resources. RDF predicates and link relation types can therefore 1147 often be used interchangeably. For example, a CoRAL document could 1148 describe its maker using the FOAF vocabulary [FOAF] as follows: 1150 #using iana = 1151 #using foaf = 1153 foaf:maker ? { 1154 iana:type 1155 foaf:familyName "Hartke" 1156 foaf:givenName "Klaus" 1157 foaf:mbox 1158 } 1160 6.3. Registering Relation Types 1162 IRIs that identify link relation types, form relation types, and form 1163 field names do not have to be registered. The use of DNS names in 1164 them allows for decentralized creation of new IRIs without the risk 1165 of collisions. However, IRIs can be relatively verbose and can 1166 impose a high overhead in CoRAL representations. This can be a 1167 problem in constrained environments [RFC7228]. 1169 CoRAL alternatively allows the use of unsigned integers to identify 1170 link relation types, form relation types, and form field names. 1171 These impose a much smaller overhead, but need to be assigned by a 1172 registry to avoid collisions. 1174 This document does not create a registry for such integers. Instead, 1175 a "profile" parameter [RFC6906] is specified for use with the media 1176 types for CoRAL documents in the binary and textual format. The 1177 parameter specifies which registry to use. 1179 The registries are identified for this purpose by a URI [RFC3986]. 1180 For example, a CoRAL document that uses the registry identified by 1181 the URI uses the following media type: 1183 application/coral+cbor; profile="http://example.com/coral" 1185 The URI serves only as an identifier; it does not necessarily have to 1186 be dereferencable (or even use a dereferencable URI scheme). It is 1187 permissible, though, to use a dereferencable URI and serve a 1188 representation that provides information about the registry in a 1189 human- or machine-readable way. (The format of such a representation 1190 is outside the scope of this document.) 1192 For simplicity, a CoRAL document can only use at most one registry at 1193 a time. The "profile" parameter of the CoRAL media types MUST 1194 contain a single URI, not a whitespace-separated list of URIs as 1195 recommended in RFC 6906 [RFC6906]. If the "profile" parameter is 1196 absent, the profile specified in Appendix B is assumed. 1198 A registry SHOULD map each unsigned integer to the full IRI that 1199 identifies the link relation type, form relation type, or form field 1200 name. The namespaces for these three kinds of identifiers are 1201 disjoint, i.e., the same integer may be assigned to a link relation 1202 type, form relation type, and form field name without ambiguity. 1203 Once an integer has been assigned, the assignment MUST NOT be changed 1204 or removed. A registry MAY provide additional information about an 1205 assignment (for example, whether a link relation type is deprecated). 1207 In CoAP, media types (including specific values for their parameters) 1208 are encoded as a small, unsigned integer, called the content format. 1209 For use with CoAP, each CoRAL registry needs to register a new 1210 content format in the IANA CoAP Content-Formats Registry. Each such 1211 registered content format MUST specify a CoRAL media type with a 1212 "profile" parameter containing the registry URI. 1214 6.4. Expressing Target Attributes 1216 Link target attributes defined for use with RFC 6690 (e.g., "type", 1217 "hreflang", "media", "ct", "rt", "if", "sz") can be expressed in 1218 CoRAL by nesting links under the respective link and specifying the 1219 attribute name appended to the IRI as 1220 the link relation type. The target of such nested links MUST be a 1221 text string literal: 1223 #using iana = 1224 #using attr = 1226 iana:item { 1227 attr:type "application/json-patch+json" 1228 attr:ct "51" 1229 } 1231 [[NOTE TO RFC EDITOR: Please replace all occurrences of 1232 "http://www.example.org/TBD/" with a RFC-Editor-controlled IRI.]] 1234 Link target attributes that actually describe the link and not the 1235 link target (e.g., "rel", "anchor", "rev", "title", and "title*") are 1236 excluded from this provision and MUST NOT occur in a CoRAL document. 1238 6.5. Embedding CoRAL in CBOR Structures 1240 Data items in the CoRAL binary format (Section 4) can be embedded in 1241 other CBOR [RFC7049] data structures. Specifications using CDDL 1243 [I-D.ietf-cbor-cddl] SHOULD reference the following CDDL definitions 1244 for this purpose: 1246 CoRAL-Body = body 1248 CoRAL-Link = link 1250 CoRAL-Form = form 1252 CoRAL-IRI = iri 1254 7. Security Considerations 1256 Parsers of CoRAL documents must operate on input that is assumed to 1257 be untrusted. This means that parsers MUST fail gracefully in the 1258 face of malicious inputs. Additionally, parsers MUST be prepared to 1259 deal with resource exhaustion that results, for example, from the 1260 allocation of big data items or exhaustion of the stack depth (stack 1261 overflow). See Section 8 of RFC 7049 [RFC7049] for security 1262 considerations relating to parsing CBOR in particular. 1264 Implementers of the CoRAL textual format need to consider the 1265 security aspects of handling Unicode input. See the Unicode Standard 1266 Annex #36 [UNICODE-UAX36] for security considerations relating to 1267 visual spoofing and misuse of character encodings. See Section 10 of 1268 RFC 3629 [RFC3629] for security considerations relating to UTF-8. 1270 CoRAL makes extensive use of IRIs and URIs. See Section 8 of RFC 1271 3987 [RFC3987] for security considerations relating to IRIs and 1272 Section 7 of RFC 3986 [RFC3986] for security considerations relating 1273 to URIs. 1275 CoRAL is intended to be used in conjunction with a Web transfer 1276 protocol such as HTTP or CoAP. See Section 9 of RFC 7320 [RFC7230], 1277 Section of 9 of RFC 7231 [RFC7231], etc. for security considerations 1278 relating to HTTP. See Section 11 of RFC 7252 [RFC7252] for security 1279 considerations relating to CoAP. 1281 CoRAL does not define any specific mechanisms for the confidentiality 1282 and integrity of CoRAL documents. It relies on application layer or 1283 transport layer security mechanisms, such as Transport Layer Security 1284 (TLS) [RFC5246]. 1286 CoRAL documents and the structure of a web of resources revealed from 1287 automatically following links can disclose personal information and 1288 other sensitive information. Implementations need to prevent the 1289 unintentional disclosure of such information. See Section of 9 of 1290 RFC 7231 [RFC7231] for additional considerations. 1292 The security of applications using CoRAL can depend on the proper 1293 preparation and comparison of internationalized strings. For 1294 example, such strings can be used to make authentication and 1295 authorization decisions, and the security of an application could be 1296 compromised if an entity providing a given string is connected to the 1297 wrong account or online resource based on different interpretations 1298 of the string. See RFC 6943 [RFC6943] for security considerations 1299 relating to identifiers in IRIs and other locations. 1301 Applications using CoRAL ought to consider the attack vectors opened 1302 by automatically following, trusting, or otherwise using links and 1303 forms in CoRAL documents. In particular, a server that is 1304 authoritative for the CoRAL representation of a resource may not 1305 necessarily be the authoritative source for nested links and forms. 1307 8. IANA Considerations 1309 8.1. Media Type "application/coral+cbor" 1311 This document registers the media type "application/coral+cbor" 1312 according to the procedures of BCP 13 [RFC6838]. 1314 Type name: 1315 application 1317 Subtype name: 1318 coral+cbor 1320 Required parameters: 1321 N/A 1323 Optional parameters: 1324 N/A 1326 Encoding considerations: 1327 binary 1329 Security considerations: 1330 See Section 7 of [I-D.hartke-t2trg-coral]. 1332 Interoperability considerations: 1333 N/A 1335 Published specification: 1336 [I-D.hartke-t2trg-coral] 1338 Applications that use this media type: 1339 See Section 1 of [I-D.hartke-t2trg-coral]. 1341 Fragment identifier considerations: 1342 As specified for "application/cbor". 1344 Additional information: 1345 Deprecated alias names for this type: N/A 1346 Magic number(s): N/A 1347 File extension(s): N/A 1348 Macintosh file type code(s): N/A 1350 Person & email address to contact for further information: 1351 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1353 Intended usage: 1354 COMMON 1356 Restrictions on usage: 1357 N/A 1359 Author: 1360 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1362 Change controller: 1363 IESG 1365 Provisional registration? 1366 No 1368 8.2. Media Type "text/coral" 1370 This document registers the media type "text/coral" according to the 1371 procedures of BCP 13 [RFC6838] and guidelines in RFC 6657 [RFC6657]. 1373 Type name: 1374 text 1376 Subtype name: 1377 coral 1379 Required parameters: 1380 N/A 1382 Optional parameters: 1383 N/A 1385 Encoding considerations: 1386 See Section 5 of [I-D.hartke-t2trg-coral]. 1388 Security considerations: 1390 See Section 7 of [I-D.hartke-t2trg-coral]. 1392 Interoperability considerations: 1393 N/A 1395 Published specification: 1396 [I-D.hartke-t2trg-coral] 1398 Applications that use this media type: 1399 See Section 1 of [I-D.hartke-t2trg-coral]. 1401 Fragment identifier considerations: 1402 N/A 1404 Additional information: 1405 Deprecated alias names for this type: N/A 1406 Magic number(s): N/A 1407 File extension(s): .coral 1408 Macintosh file type code(s): TEXT 1410 Person & email address to contact for further information: 1411 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1413 Intended usage: 1414 COMMON 1416 Restrictions on usage: 1417 N/A 1419 Author: 1420 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1422 Change controller: 1423 IESG 1425 Provisional registration? 1426 No 1428 8.3. CoAP Content Formats 1430 This document registers CoAP content formats for the media types 1431 "application/coral+cbor" and "text/coral" according to the procedures 1432 of BCP 13 [RFC6838]. 1434 o Media Type: application/coral+cbor 1435 Content Coding: identity 1436 ID: TBD (maybe 63) 1437 Reference: [I-D.hartke-t2trg-coral] 1439 o Media Type: text/coral 1440 Content Coding: identity 1441 ID: TBD (maybe 10063) 1442 Reference: [I-D.hartke-t2trg-coral] 1444 9. References 1446 9.1. Normative References 1448 [I-D.ietf-cbor-cddl] 1449 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1450 definition language (CDDL): a notational convention to 1451 express CBOR data structures", draft-ietf-cbor-cddl-00 1452 (work in progress), July 2017. 1454 [I-D.nottingham-rfc5988bis] 1455 Nottingham, M., "Web Linking", draft-nottingham- 1456 rfc5988bis-08 (work in progress), August 2017. 1458 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1459 Requirement Levels", BCP 14, RFC 2119, 1460 DOI 10.17487/RFC2119, March 1997, . 1463 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1464 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1465 2003, . 1467 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1468 Resource Identifier (URI): Generic Syntax", STD 66, 1469 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1470 . 1472 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1473 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 1474 January 2005, . 1476 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1477 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1478 . 1480 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1481 Specifications: ABNF", STD 68, RFC 5234, 1482 DOI 10.17487/RFC5234, January 2008, . 1485 [RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding 1486 "charset" Parameter Handling in Textual Media Types", 1487 RFC 6657, DOI 10.17487/RFC6657, July 2012, 1488 . 1490 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1491 Specifications and Registration Procedures", BCP 13, 1492 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1493 . 1495 [RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for 1496 Security Purposes", RFC 6943, DOI 10.17487/RFC6943, May 1497 2013, . 1499 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1500 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1501 October 2013, . 1503 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1504 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1505 May 2017, . 1507 [UNICODE] The Unicode Consortium, "The Unicode Standard", 1508 . 1510 Note that this reference is to the latest version of 1511 Unicode, rather than to a specific release. It is not 1512 expected that future changes in the Unicode specification 1513 will have any impact on this document. 1515 [UNICODE-UAX15] 1516 The Unicode Consortium, "Unicode Standard Annex #15: 1517 Unicode Normalization Forms", 1518 . 1520 [UNICODE-UAX31] 1521 The Unicode Consortium, "Unicode Standard Annex #31: 1522 Unicode Identifier and Pattern Syntax", 1523 . 1525 [UNICODE-UAX36] 1526 The Unicode Consortium, "Unicode Standard Annex #36: 1527 Unicode Security Considerations", 1528 . 1530 9.2. Informative References 1532 [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification 1533 0.99", January 2014, 1534 . 1536 [I-D.ietf-core-links-json] 1537 Li, K., Rahman, A., and C. Bormann, "Representing 1538 Constrained RESTful Environments (CoRE) Link Format in 1539 JSON and CBOR", draft-ietf-core-links-json-09 (work in 1540 progress), July 2017. 1542 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1543 (TLS) Protocol Version 1.2", RFC 5246, 1544 DOI 10.17487/RFC5246, August 2008, . 1547 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1548 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1549 . 1551 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1552 Address Text Representation", RFC 5952, 1553 DOI 10.17487/RFC5952, August 2010, . 1556 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 1557 RFC 6573, DOI 10.17487/RFC6573, April 2012, 1558 . 1560 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1561 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1562 . 1564 [RFC6903] Snell, J., "Additional Link Relation Types", RFC 6903, 1565 DOI 10.17487/RFC6903, March 2013, . 1568 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, 1569 DOI 10.17487/RFC6906, March 2013, . 1572 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1573 Constrained-Node Networks", RFC 7228, 1574 DOI 10.17487/RFC7228, May 2014, . 1577 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1578 Protocol (HTTP/1.1): Message Syntax and Routing", 1579 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1580 . 1582 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1583 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1584 DOI 10.17487/RFC7231, June 2014, . 1587 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1588 Application Protocol (CoAP)", RFC 7252, 1589 DOI 10.17487/RFC7252, June 2014, . 1592 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 1593 RFC 7320, DOI 10.17487/RFC7320, July 2014, 1594 . 1596 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1597 FETCH Methods for the Constrained Application Protocol 1598 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1599 . 1601 [W3C.REC-html51-20161101] 1602 Faulkner, S., Eicholz, A., Leithead, T., and A. Danilo, 1603 "HTML 5.1", World Wide Web Consortium Recommendation REC- 1604 html51-20161101, November 2016, 1605 . 1607 [W3C.REC-rdf11-concepts-20140225] 1608 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 1609 Concepts and Abstract Syntax", World Wide Web Consortium 1610 Recommendation REC-rdf11-concepts-20140225, February 2014, 1611 . 1613 [W3C.REC-turtle-20140225] 1614 Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", 1615 World Wide Web Consortium Recommendation REC-turtle- 1616 20140225, February 2014, 1617 . 1619 [W3C.REC-webarch-20041215] 1620 Jacobs, I. and N. Walsh, "Architecture of the World Wide 1621 Web, Volume One", World Wide Web Consortium 1622 Recommendation REC-webarch-20041215, December 2004, 1623 . 1625 Appendix A. Core Vocabulary 1627 This section defines the core vocabulary for CoRAL. It is 1628 RECOMMENDED that all profiles assign an unsigned integer to each of 1629 these link relation types, form relation types, and form field names. 1631 [[NOTE TO RFC EDITOR: Please replace all occurrences of 1632 "urn:ietf:rfc:XXXX#" with a RFC-Editor-controlled IRI.]] 1634 A.1. Link Relation Types 1636 1637 Indicates that the link's context is an instance of the type 1638 specified as the link's target; see Section 6 of RFC 6903 1639 [RFC6903]. 1641 This link relation type serves in CoRAL the same purpose as the 1642 RDF predicate identified by the IRI . 1645 1646 Indicates that the link's context is a collection and that the 1647 link's target is a member of that collection; see Section 2.1 of 1648 RFC 6573 [RFC6573]. 1650 1651 Indicates that the link's target is a collection and that the 1652 link's context is a member of that collection; see Section 2.2 of 1653 RFC 6573 [RFC6573]. 1655 A.2. Form Relation Types 1657 1658 Indicates that the form's context is a collection and that a new 1659 item can be created in that collection by submitting the form with 1660 a representation. This form relation type is typically used with 1661 the POST method [RFC7231] [RFC7252]. 1663 1664 Indicates that the form's context can be updated by submitting a 1665 representation. This form relation type is typically used with 1666 the PUT method [RFC7231] [RFC7252] or PATCH method [RFC5789] 1667 [RFC8132]. 1669 1670 Indicates that the form's context can be deleted. This form 1671 relation type is typically used with the DELETE method [RFC7231] 1672 [RFC7252]. 1674 1675 Indicates that the form's context can be searched by submitting a 1676 search query. This form relation type is typically used with the 1677 POST method [RFC7231] [RFC7252] or FETCH method [RFC8132]. 1679 A.3. Form Field Names 1681 1682 Specifies an acceptable content type or content format for the 1683 request payload. There MAY be multiple form fields with this 1684 name. If a form does not include a form field with this name, the 1685 server accepts any or no request payload, depending on the form 1686 relation type. 1688 For HTTP, the content type MUST be specified as a text string in 1689 the format specified in Section 3.1.1.1 of RFC 7231 [RFC7231]; the 1690 set of possible values is maintained in the IANA Media Types 1691 Registry. 1693 For CoAP, the content format MUST be specified as an unsigned 1694 integer; the set of possible values is maintained in the IANA CoAP 1695 Content-Formats Registry. 1697 Appendix B. Default Profile 1699 This section defines a default registry that is assumed when a CoRAL 1700 media type without a "profile" parameter is used. 1702 Link Relation Types 1704 0 = 1705 1 = 1706 2 = 1708 Form Relation Types 1710 0 = 1711 1 = 1712 2 = 1713 3 = 1715 Form Fields 1717 0 = 1719 Appendix C. CBOR-encoded IRI References 1721 URI references [RFC3986] and, secondarily, IRI references [RFC3987] 1722 and are the most common usage of resource identifiers in hypertext 1723 representation formats such as HTML 5 [W3C.REC-html51-20161101] and 1724 the CoRE Link Format [RFC6690]. They encode the components of a 1725 resource identifier either as an absolute URI/IRI or as a relative 1726 reference that is resolved against a base URI/IRI. 1728 URI and IRI references are sequences of characters chosen from 1729 limited subsets of the repertoires of US-ASCII and Unicode 1730 characters, respectively. The individual components of a URI or IRI 1731 are delimited by several reserved characters, which necessitates the 1732 use of percent-encoding for reserved characters in a non-delimiting 1733 function. The resolution of references involves parsing URI/IRI 1734 references into their components, combining the components with those 1735 of the base URI/IRI, merging paths, removing dot segments, and 1736 recomposing the result into a URI/IRI reference string. 1738 Overall, proper URI processing can be quite complex, which can be a 1739 problem in particular in constrained environments [RFC7228] with 1740 severe code size limitations. As a result, many implementations in 1741 such environments choose to implement only an ad-hoc, informally- 1742 specified, bug-ridden, non-interoperable subset of half of RFC 3986 1743 (or less). 1745 This section specifies CBOR-encoded IRI References, a serialization 1746 format for IRI references that encodes their components as CBOR data 1747 items rather than text. Given a CBOR implementation, typical 1748 operations on IRI references such as parsing, reference resolution 1749 and comparison can be implemented much more easily than with the 1750 text-based format. A full implementation that covers all corner 1751 cases of the specification can be implemented in a relatively small 1752 amount of code. 1754 CBOR-encoded IRI References are not capable of expressing all IRI 1755 references permitted by RFC 3987 [RFC3987]. The supported subset 1756 includes all CoAP URIs [RFC7252] and most HTTP URIs [RFC7230]. 1758 C.1. Data Structure 1760 The encoding is very similar to the encoding of the request URI in 1761 CoAP messages [RFC7252]. The components of an IRI reference are 1762 encoded as a sequence of _options_. Each option consists of an 1763 _option number_ identifying the type of option (IRI scheme, host 1764 name, etc.) and the _option value_. 1766 iri = [?(scheme: 1, text), 1767 ?(host.name: 2, text // 1768 host.ip: 3, bytes .size 4 / bytes .size 16), 1769 ?(port: 4, uint .size 2), 1770 ?(path.type: 5, path-type), 1771 *(path: 6, text), 1772 *(query: 7, text), 1773 ?(fragment: 8, text)] 1775 path-type = &(absolute-path: 0, 1776 append-path: 1, 1777 relative-path: 2, 1778 append-relation: 3) 1780 C.2. Options 1782 The following options are defined: 1784 scheme 1785 Specifies the IRI scheme. The option value MUST match the 1786 "scheme" rule defined in Section 3.1 of RFC 3986. 1788 host.name 1789 Specifies the host of the IRI authority as a registered name. 1791 host.ip 1792 Specifies the host of the IRI authority as an IPv4 address 1793 (4 bytes) or an IPv6 address (16 bytes). 1795 port 1796 Specifies the port number. The option value MUST be an unsigned 1797 integer in the range 0 to 65535 (inclusive). 1799 path.type 1800 Specifies the type of the IRI path for reference resolution. 1801 Possible values are 0 (absolute-path), 1 (append-path), 2 1802 (relative-path), and 3 (append-relation). 1804 path 1805 Specifies one segment of the IRI path. This option can occur more 1806 than once. 1808 query 1809 Specifies one argument of the IRI query. This option can occur 1810 more than once. 1812 fragment 1813 Specifies the fragment identifier. 1815 The value of the "host.name", "path", "query", and "fragment" options 1816 can be any Unicode string. No percent-encoding is performed. 1818 C.3. Properties 1820 A sequence of options is considered _well-formed_ if: 1822 o the sequence of options is empty or starts with a "scheme", 1823 "host.name", "host.ip", "port", "path.type", "path", "query", or 1824 "fragment" option; 1826 o a "scheme" option is followed by either a "host.name" or "host.ip" 1827 option; 1829 o a "host.name" option is followed by a "port" option; 1831 o a "host.ip" option is followed by a "port" option; 1833 o a "port" option is followed by a "path", "query", or "fragment" 1834 option or is at the end of the sequence; 1836 o a "path.type" option is followed by a "path", "query", or 1837 "fragment" option or is at the end of the sequence; 1839 o a "path" option is followed by a "path", "query", or "fragment" 1840 option or is at the end of the sequence; 1842 o a "query" option is followed by a "query" or "fragment" option or 1843 is at the end of the sequence; and 1845 o a "fragment" option is at the end of the sequence. 1847 A well-formed sequence of options is considered _absolute_ if the 1848 sequence of options starts with a "scheme" option. A well-formed 1849 sequence of options is considered _relative_ if the sequence of 1850 options is empty or starts with an option other than the "scheme" 1851 option. 1853 An absolute sequence of options is considered _normalized_ if the 1854 result of resolving the sequence of options against any base IRI 1855 reference is equal to the input. (It doesn't matter what it is 1856 resolved against, since it is already absolute.) 1858 C.4. Reference Resolution 1860 This section defines how to resolve a CBOR-encoded IRI reference that 1861 might be relative to a given base IRI. 1863 Applications MUST resolve a well-formed sequence of options `href` 1864 against an absolute sequence of options `base` by using an algorithm 1865 that is functionally equivalent to the following Python 3.5 code. 1867 1869 def resolve(base, href, relation=None): 1870 if not is_absolute(base) or not is_well_formed(href): 1871 return None 1872 result = [] 1873 type = PathType.RELATIVE_PATH 1874 (option, value) = href[0] 1875 if option == Option.HOST_IP: 1876 option = Option.HOST_NAME 1877 elif option == Option.PATH_TYPE: 1878 href = href[1:] 1879 type = value 1880 option = Option.PATH 1881 if option != Option.PATH or type == PathType.ABSOLUTE_PATH: 1882 _copy_until(base, result, option) 1883 else: 1884 _copy_until(base, result, Option.QUERY) 1885 if type == PathType.APPEND_RELATION: 1886 _append_and_normalize(result, Option.PATH, 1887 format(relation, "x")) 1888 return result 1889 if type == PathType.RELATIVE_PATH: 1890 _remove_last_path_segment(result) 1891 _copy_until(href, result, Option.END) 1892 _append_and_normalize(href, Option.END, None) 1893 return result 1895 def _copy_until(input, output, end): 1896 for (option, value) in input: 1897 if option >= end: 1898 break 1899 _append_and_normalize(output, option, value) 1901 def _append_and_normalize(output, option, value): 1902 if option == Option.PATH: 1903 if value == ".": 1904 return 1905 if value == "..": 1906 _remove_last_path_segment(output) 1907 return 1908 elif option > Option.PATH: 1909 if len(output) >= 2 and \ 1910 output[-1] == (Option.PATH, "") and \ 1911 (output[-2][0] < Option.PATH_TYPE or \ 1912 output[-2] == (Option.PATH_TYPE, PathType.ABSOLUTE_PATH)): 1913 _remove_last_path_segment(output) 1914 if option >= Option.END: 1915 return 1916 output.append((option, value)) 1918 def _remove_last_path_segment(output): 1919 if len(output) >= 1 and output[-1][0] == Option.PATH: 1920 del output[-1] 1922 1924 C.5. IRI Recomposition 1926 This section defines how to recompose an IRI from a sequence of 1927 options that encodes an absolute IRI reference. 1929 Applications MUST recompose an IRI from a sequence of options by 1930 using an algorithm that is functionally equivalent to the following 1931 Python 3.5 code. 1933 To reduce variability, the hexadecimal notation when percent-encoding 1934 octets SHOULD use uppercase letters. The text representation of IPv6 1935 addresses SHOULD follow the recommendations in Section 4 of RFC 5952 1936 [RFC5952]. 1938 1940 def recompose(href): 1941 if not is_absolute(href): 1942 return None 1943 result = "" 1944 no_path = True 1945 first_query = True 1946 for (option, value) in href: 1947 if option == Option.SCHEME: 1948 result += value + ":" 1949 elif option == Option.HOST_NAME: 1950 result += "//" + _encode_ireg_name(value) 1951 elif option == Option.HOST_IP: 1952 result += "//" + _encode_ip_address(value) 1953 elif option == Option.PORT: 1954 result += ":" + str(value) 1955 elif option == Option.PATH: 1956 result += "/" + _encode_path_segment(value) 1957 no_path = False 1958 elif option == Option.QUERY: 1960 if no_path: 1961 result += "/" 1962 no_path = False 1963 result += "?" if first_query else "&" 1964 result += _encode_query_argument(value) 1965 first_query = False 1966 elif option == Option.FRAGMENT: 1967 if no_path: 1968 result += "/" 1969 no_path = False 1970 result += "#" + _encode_fragment(value) 1971 if no_path: 1972 result += "/" 1973 no_path = False 1974 return result 1976 def _encode_ireg_name(s): 1977 return "".join(c if _is_ireg_name_char(c) else 1978 _encode_pct(c) for c in s) 1980 def _encode_ip_address(b): 1981 if len(b) == 4: 1982 return ".".join(str(c) for c in b) 1983 elif len(b) == 16: 1984 return "[" + ... + "]" # see RFC 5952 1986 def _encode_path_segment(s): 1987 return "".join(c if _is_isegment_char(c) else 1988 _encode_pct(c) for c in s) 1990 def _encode_query_argument(s): 1991 return "".join(c if _is_iquery_char(c) and c != "&" else 1992 _encode_pct(c) for c in s) 1994 def _encode_fragment(s): 1995 return "".join(c if _is_ifragment_char(c) else 1996 _encode_pct(c) for c in s) 1998 def _encode_pct(s): 1999 return "".join( 2000 "%{0:0>2X}".format(c) for c in s.encode("utf-8")) 2002 def _is_ireg_name_char(c): 2003 return _is_iunreserved(c) or _is_sub_delim(c) 2005 def _is_isegment_char(c): 2006 return _is_ipchar(c) 2008 def _is_iquery_char(c): 2009 return _is_ipchar(c) or _is_iprivate(c) or c == "/" or c == "?" 2011 def _is_ifragment_char(c): 2012 return _is_ipchar(c) or c == "/" or c == "?" 2014 def _is_ipchar(c): 2015 return _is_iunreserved(c) or _is_sub_delim(c) or \ 2016 c == ":" or c == "@" 2018 def _is_iunreserved(c): 2019 return _is_alpha(c) or _is_digit(c) or \ 2020 c == "-" or c == "." or c == "_" or c == "~" or \ 2021 _is_ucschar(c) 2023 def _is_alpha(c): 2024 return c >= "A" and c <= "Z" or c >= "a" and c <= "z" 2026 def _is_digit(c): 2027 return c >= "0" and c <= "9" 2029 def _is_sub_delim(c): 2030 return c == "!" or c == "$" or c == "&" or c == "'" or \ 2031 c == "(" or c == ")" or c == "*" or c == "+" or \ 2032 c == "," or c == ";" or c == "=" 2034 def _is_ucschar(c): 2035 return c >= "\U000000A0" and c <= "\U0000D7FF" or \ 2036 c >= "\U0000F900" and c <= "\U0000FDCF" or \ 2037 c >= "\U0000FDF0" and c <= "\U0000FFEF" or \ 2038 c >= "\U00010000" and c <= "\U0001FFFD" or \ 2039 c >= "\U00020000" and c <= "\U0002FFFD" or \ 2040 c >= "\U00030000" and c <= "\U0003FFFD" or \ 2041 c >= "\U00040000" and c <= "\U0004FFFD" or \ 2042 c >= "\U00050000" and c <= "\U0005FFFD" or \ 2043 c >= "\U00060000" and c <= "\U0006FFFD" or \ 2044 c >= "\U00070000" and c <= "\U0007FFFD" or \ 2045 c >= "\U00080000" and c <= "\U0008FFFD" or \ 2046 c >= "\U00090000" and c <= "\U0009FFFD" or \ 2047 c >= "\U000A0000" and c <= "\U000AFFFD" or \ 2048 c >= "\U000B0000" and c <= "\U000BFFFD" or \ 2049 c >= "\U000C0000" and c <= "\U000CFFFD" or \ 2050 c >= "\U000D0000" and c <= "\U000DFFFD" or \ 2051 c >= "\U000E1000" and c <= "\U000EFFFD" 2053 def _is_iprivate(c): 2054 return c >= "\U0000E000" and c <= "\U0000F8FF" or \ 2055 c >= "\U000F0000" and c <= "\U000FFFFD" or \ 2056 c >= "\U00100000" and c <= "\U0010FFFD" 2058 2060 C.6. CoAP Encoding 2062 This section defines how to construct CoAP options from an absolute, 2063 normalized, CBOR-encoded IRI Reference. 2065 Applications MUST construct CoAP options by recomposing the sequence 2066 of options to an IRI (Appendix C.5 of this document), mapping the IRI 2067 to an URI (Section 3.1 of RFC 3987), and decomposing the URI into 2068 CoAP options (Section 6.4 of RFC 7252). 2070 The following illustrative Python 3.5 code is roughly equivalent to 2071 this. 2073 2075 def coap(href, to_proxy=False): 2076 if not is_absolute(href): 2077 return None 2078 result = b"" 2079 previous = 0 2080 for (option, value) in href: 2081 if option == Option.SCHEME: 2082 pass 2083 elif option == Option.HOST_NAME: 2084 opt = 3 # Uri-Host 2085 val = value.encode("utf-8") 2086 result += _encode_coap_option(opt - previous, val) 2087 previous = opt 2088 elif option == Option.HOST_IP: 2089 opt = 3 # Uri-Host 2090 if len(value) == 4: 2091 val = ".".join(str(c) for c in b).encode("utf-8") 2092 elif len(value) == 16: 2093 val = b"[" + ... + b"]" # see RFC 5952 2094 result += _encode_coap_option(opt - previous, val) 2095 previous = opt 2096 elif option == Option.PORT: 2097 opt = 7 # Uri-Port 2098 val = value.to_bytes((value.bit_length() + 7) // 8, "big") 2099 result += _encode_coap_option(opt - previous, val) 2100 previous = opt 2101 elif option == Option.PATH: 2102 opt = 11 # Uri-Path 2103 val = value.encode("utf-8") 2104 result += _encode_coap_option(opt - previous, val) 2105 previous = opt 2106 elif option == Option.QUERY: 2107 opt = 15 # Uri-Query 2108 val = value.encode("utf-8") 2109 result += _encode_coap_option(opt - previous, val) 2110 previous = opt 2111 elif option == Option.FRAGMENT: 2112 pass 2113 if to_proxy: 2114 (option, value) = href[0] 2115 opt = 39 # Proxy-Scheme 2116 val = value.encode("utf-8") 2117 result += _encode_coap_option(opt - previous, val) 2118 previous = opt 2119 return result 2121 def _encode_coap_option(delta, value): 2122 length = len(value) 2123 delta_nibble = _encode_coap_option_nibble(delta) 2124 length_nibble = _encode_coap_option_nibble(length) 2125 result = bytes([delta_nibble << 4 | length_nibble]) 2126 if delta_nibble == 13: 2127 delta -= 13 2128 result += bytes([delta]) 2129 elif delta_nibble == 14: 2130 delta -= 256 + 13 2131 result += bytes([delta >> 8, delta & 255]) 2132 if length_nibble == 13: 2133 length -= 13 2134 result += bytes([length]) 2135 elif length_nibble == 14: 2136 length -= 256 + 13 2137 result += bytes([length >> 8, length & 255]) 2138 result += value 2139 return result 2141 def _encode_coap_option_nibble(n): 2142 if n < 13: 2143 return n 2144 elif n < 256 + 13: 2145 return 13 2146 elif n < 65536 + 256 + 13: 2147 return 14 2149 2151 Author's Address 2153 Klaus Hartke 2154 Universitaet Bremen TZI 2155 Postfach 330440 2156 Bremen D-28359 2157 Germany 2159 Phone: +49-421-218-63905 2160 Email: hartke@tzi.org