idnits 2.17.1 draft-hartke-t2trg-coral-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 30, 2017) is 2363 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 622 -- Looks like a reference, but probably isn't: '5' on line 625 -- Looks like a reference, but probably isn't: '6' on line 628 == Missing Reference: 'I-D.hartke-t2trg-coral' is mentioned on line 1463, 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 October 30, 2017 5 Expires: May 3, 2018 7 The Constrained RESTful Application Language (CoRAL) 8 draft-hartke-t2trg-coral-04 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 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on May 3, 2018. 35 Copyright Notice 37 Copyright (c) 2017 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 4 54 2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 2.1. Web Linking . . . . . . . . . . . . . . . . . . . . . . . 4 56 2.2. Links, Forms, and Metadata . . . . . . . . . . . . . . . 5 57 3. Data and Interaction Model . . . . . . . . . . . . . . . . . 6 58 3.1. Browsing Context . . . . . . . . . . . . . . . . . . . . 7 59 3.2. Documents . . . . . . . . . . . . . . . . . . . . . . . . 7 60 3.3. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 3.4. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 3.5. Form Data . . . . . . . . . . . . . . . . . . . . . . . . 9 63 3.6. Navigation . . . . . . . . . . . . . . . . . . . . . . . 9 64 3.7. History Traversal . . . . . . . . . . . . . . . . . . . . 11 65 4. Binary Format . . . . . . . . . . . . . . . . . . . . . . . . 11 66 4.1. Data Structure . . . . . . . . . . . . . . . . . . . . . 11 67 4.1.1. Documents . . . . . . . . . . . . . . . . . . . . . . 11 68 4.1.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 11 69 4.1.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 12 70 4.1.4. Directives . . . . . . . . . . . . . . . . . . . . . 14 71 5. Textual Format . . . . . . . . . . . . . . . . . . . . . . . 15 72 5.1. Lexical Structure . . . . . . . . . . . . . . . . . . . . 15 73 5.1.1. Line Terminators . . . . . . . . . . . . . . . . . . 15 74 5.1.2. White Space . . . . . . . . . . . . . . . . . . . . . 15 75 5.1.3. Comments . . . . . . . . . . . . . . . . . . . . . . 15 76 5.1.4. Identifiers . . . . . . . . . . . . . . . . . . . . . 16 77 5.1.5. IRI References . . . . . . . . . . . . . . . . . . . 16 78 5.1.6. Literals . . . . . . . . . . . . . . . . . . . . . . 16 79 5.1.7. Punctuators . . . . . . . . . . . . . . . . . . . . . 19 80 5.2. Syntactic Structure . . . . . . . . . . . . . . . . . . . 20 81 5.2.1. Documents . . . . . . . . . . . . . . . . . . . . . . 20 82 5.2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 20 83 5.2.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 21 84 5.2.4. Directives . . . . . . . . . . . . . . . . . . . . . 22 85 6. Usage Considerations . . . . . . . . . . . . . . . . . . . . 23 86 6.1. Specifying CoRAL-based Applications . . . . . . . . . . . 23 87 6.1.1. Naming Resources . . . . . . . . . . . . . . . . . . 24 88 6.1.2. Implementation Limits . . . . . . . . . . . . . . . . 24 89 6.2. Minting New Relation Types . . . . . . . . . . . . . . . 25 90 6.3. Registering Relation Types . . . . . . . . . . . . . . . 26 91 6.4. Expressing Link Target Attributes . . . . . . . . . . . . 27 92 6.5. Embedding CoRAL in CBOR Structures . . . . . . . . . . . 27 93 7. Security Considerations . . . . . . . . . . . . . . . . . . . 28 94 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 95 8.1. Media Type "application/coral+cbor" . . . . . . . . . . . 29 96 8.2. Media Type "text/coral" . . . . . . . . . . . . . . . . . 30 97 8.3. CoAP Content Formats . . . . . . . . . . . . . . . . . . 31 99 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 100 9.1. Normative References . . . . . . . . . . . . . . . . . . 32 101 9.2. Informative References . . . . . . . . . . . . . . . . . 33 102 Appendix A. Core Vocabulary . . . . . . . . . . . . . . . . . . 35 103 A.1. Link Relation Types . . . . . . . . . . . . . . . . . . . 36 104 A.2. Form Relation Types . . . . . . . . . . . . . . . . . . . 36 105 A.3. Form Field Names . . . . . . . . . . . . . . . . . . . . 37 106 Appendix B. Default Profile . . . . . . . . . . . . . . . . . . 37 107 Appendix C. CBOR-encoded IRI References . . . . . . . . . . . . 37 108 C.1. Data Structure . . . . . . . . . . . . . . . . . . . . . 38 109 C.2. Options . . . . . . . . . . . . . . . . . . . . . . . . . 39 110 C.3. Properties . . . . . . . . . . . . . . . . . . . . . . . 40 111 C.4. Reference Resolution . . . . . . . . . . . . . . . . . . 41 112 C.5. IRI Recomposition . . . . . . . . . . . . . . . . . . . . 42 113 C.6. CoAP Encoding . . . . . . . . . . . . . . . . . . . . . . 45 114 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 47 116 1. Introduction 118 The Constrained RESTful Application Language (CoRAL) is a language 119 for the description of typed connections between resources on the Web 120 ("links"), possible operations on such resources ("forms"), as well 121 as simple resource metadata. 123 CoRAL is intended for driving automated software agents that navigate 124 a Web application based on a standardized vocabulary of link and form 125 relation types. It is designed to be used in conjunction with a Web 126 transfer protocol such as the Hypertext Transfer Protocol (HTTP) 127 [RFC7230] or the Constrained Application Protocol (CoAP) [RFC7252]. 129 This document defines the CoRAL data and interaction model as well as 130 two specialized CoRAL serialization formats. 132 The CoRAL data and interaction model is a superset of the Web Linking 133 model described in RFC 8288 [RFC8288]. The CoRAL data model consists 134 of two elements: _links_ that describe the relationships between 135 pairs of resources and the type of those relationships, and _forms_ 136 that describe possible operations on resources and the type of those 137 operations. In addition, the model can describe simple resource 138 metadata in a way similar to the Resource Description Framework (RDF) 139 [W3C.REC-rdf11-concepts-20140225]. However, in contrast to RDF, the 140 focus of CoRAL is on the interaction with resources, not just on the 141 relationships between them. The CoRAL interaction model derives from 142 HTML 5 [W3C.REC-html51-20161101] and specifies how an automated 143 software agent can navigate between resources by following links and 144 perform operations on resources by submitting forms. 146 The primary CoRAL serialization format is a compact, binary encoding 147 of links and forms in Concise Binary Object Representation (CBOR) 148 [RFC7049]. It is intended for environments with constraints on 149 power, memory, and processing resources [RFC7228] and shares many 150 similarities with the message format of the Constrained Application 151 Protocol (CoAP) [RFC7252]: It uses numeric identifiers instead of 152 verbose strings for link and form relation types, and pre-parses URIs 153 into (what CoAP considers to be) their components, which simplifies 154 URI processing greatly. As a result, link serializations are often 155 much more compact than equivalent serializations in CoRE Link Format 156 [RFC6690], including its CBOR variant [I-D.ietf-core-links-json]. 157 Additionally, CoRAL supports the serialization of forms, which CoRE 158 Link Format does not support. 160 The second CoRAL serialization format is a lightweight, textual 161 encoding of links and forms that is intended to be easy to read and 162 write by humans. The format is loosely inspired by the syntax of 163 Turtle [W3C.REC-turtle-20140225] and is used for giving examples 164 throughout the document. 166 1.1. Requirements Notation 168 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 169 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 170 "OPTIONAL" in this document are to be interpreted as described in BCP 171 14 [RFC2119] [RFC8174] when, and only when, they appear in all 172 capitals, as shown here. 174 2. Examples 176 2.1. Web Linking 178 At its core, CoRAL is just yet another serialization format for Web 179 links. For example, if an HTTP client sends the following request: 181 GET /TheBook/chapter3 HTTP/1.1 182 Host: example.com 184 and receives the following response: 186 HTTP/1.1 200 OK 187 Content-Type: text/coral 189 #using 191 next <./chapter4> 192 icon 193 license 195 then the representation contains the following three links: 197 o one link of type "http://www.iana.org/assignments/relation/next" 198 from to 199 , 201 o one link of type "http://www.iana.org/assignments/relation/icon" 202 from to , and 205 o one link of type "http://www.iana.org/assignments/relation/ 206 license" from to 207 . 209 This representation is equivalent to the following Link header field 210 [RFC8288]: 212 Link: <./chapter4>; rel="next", 213 ; rel="icon", 214 ; rel="license" 216 and the following HTML 5 [W3C.REC-html51-20161101] link elements: 218 219 220 223 2.2. Links, Forms, and Metadata 225 In its entirety, CoRAL is an expressive language for describing Web 226 links between resources, possible operations on these resources, and 227 simple resource metadata. For example, if an HTTP client sends the 228 following request: 230 GET /tasks HTTP/1.1 231 Host: example.com 233 and receives the following response: 235 HTTP/1.1 200 OK 236 Content-Type: text/coral 238 #using 239 #using coral = 241 task { 242 description "Pick up the kids" 243 } 245 task { 246 description "Return the books to the library" 247 coral:delete -> DELETE 248 } 250 coral:create -> POST [coral:accept "example/task"] 252 then the representation contains the following six elements: 254 o one link of type "http://example.org/vocabulary#task" from 255 to , 257 o one link of type "http://example.org/vocabulary#description" from 258 to "Pick up the kids", 260 o one link of type "http://example.org/vocabulary#task" from 261 to , 263 o one link of type "http://example.org/vocabulary#description" from 264 to "Return the books to the library", 266 o one form of type "urn:ietf:rfc:XXXX#delete" that can be used to 267 delete by making a DELETE request to 268 , and 270 o one form of type "urn:ietf:rfc:XXXX#create" that can be used to 271 create a new item in by making a POST 272 request to with an "example/task" 273 payload. 275 3. Data and Interaction Model 277 The Constrained RESTful Application Language (CoRAL) is designed for 278 building Web-based applications [W3C.REC-webarch-20041215] in which 279 automated software agents navigate between resources by following 280 links and perform operations on resources by submitting forms. 282 3.1. Browsing Context 284 Borrowing from HTML 5 [W3C.REC-html51-20161101], each such agent 285 maintains a _browsing context_ in which the representations of Web 286 resources are processed. (In HTML 5, the browsing context typically 287 corresponds to a tab or window in a Web browser.) 289 A browsing context has a _session history_ that lists the resource 290 representations that the agent has processed, is processing, or will 291 process. At any time, one representation in each browsing context is 292 designated the _active_ representation. 294 A session history consists of a flat list of session history entries. 295 Each _session history entry_ consists of a resource representation 296 and the Internationalized Resource Identifier (IRI) [RFC3987] that 297 was used to retrieve the representation. An entry can additionally 298 have other information associated with it. New entries are added to 299 the session history as the agent navigates from resource to resource. 301 3.2. Documents 303 A resource representation in one of the CoRAL serialization formats 304 is called a CoRAL _document_. The IRI that was used to retrieve such 305 a document is called the document's _retrieval context_. 307 A CoRAL document consists of a list of zero or more links and forms, 308 collectively called _elements_. CoRAL serialization formats may 309 define additional types of elements for efficiency or convenience, 310 such as a base IRI for relative IRI references. 312 3.3. Links 314 A _link_ describes a relationship between two resources on the Web 315 [RFC8288]. It consists of a _link context_, a _link relation type_, 316 and a _link target_. A link can additionally have a nested list of 317 zero or more elements, which take the place of link target attributes 318 in CoRAL. 320 A link can be viewed as a statement of the form "_link context_ has a 321 _link relation type_ resource at _link target_" where the link target 322 may be further described by nested links and forms. 324 The link relation type identifies the semantics of a link. In HTML 5 325 and the RFC 8288 Link header field, a link relation type is typically 326 denoted by a registered name, such as "stylesheet" or "icon". In 327 CoRAL, a link relation type is denoted by an IRI or an unsigned 328 integer. IRIs allow the creation of new, unique relation types in a 329 decentralized fashion but can incur a high overhead in terms of 330 message size. Small, unsigned integers on the other hand minimize 331 the overhead of link relation types in constrained environments, but 332 require the assignment of values by a registry to avoid collisions. 334 The link context and the link target are both resources on the Web. 335 Resources are denoted in CoRAL either by an IRI reference [RFC3987] 336 or (similar to RDF) by a literal. If the IRI scheme indicates a Web 337 transfer protocol such as HTTP or CoAP, then an agent can dereference 338 the IRI and navigate the browsing context to the referenced resource; 339 this is called _following the link_. A literal directly identifies a 340 value, which can be Boolean, an integer, a floating-point number, a 341 byte string, or a text string. 343 A link can occur as a top-level element in a document or as a nested 344 element within a link. When a link occurs as a top-level element, 345 the link context is implicitly the document's retrieval context. 346 When a link occurs nested within a link, the link context of the 347 inner link is the link target of the outer link. 349 There are no restrictions on the cardinality of links; there can be 350 multiple links to and from a particular target, and multiple links of 351 the same or different types between a given link context and target. 352 However, the CoRAL data model constrains the description of a web of 353 resources to a tree: Links between linked resources can only be 354 described by further nesting links. 356 3.4. Forms 358 A _form_ provides instructions to an agent for performing an 359 operation on a Web resource. It consists of a _form context_, a 360 _form relation type_, a _request method_, and a _submission IRI_. 361 Additionally, a form can be accompanied by _form data_. 363 A form can be viewed as an instruction of the form "To perform a 364 _form relation type_ operation on _form context_, make a _request 365 method_ request to _submission IRI_" where the payload of the request 366 may be further described by form data. 368 The form relation type identifies the semantics of the operation. 369 Like link relation types, the form relation type is denoted by an IRI 370 or an unsigned integer. 372 The form context is the resource on which an operation is ultimately 373 performed. To perform the operation, an agent must construct a 374 request with the specified request method and submission IRI. The 375 submission IRI typically refers to the form context, but MAY refer to 376 another resource. Constructing and sending the request is called 377 _submitting the form_. 379 If a form is accompanied by form data (Section 3.5), the agent MUST 380 also construct a payload that matches the specifications of the form 381 data, and include it in the same request when submitting the form. 383 A form can occur as a top-level element in a document or as a nested 384 element within a link. When a form occurs as a top-level element, 385 the form context is implicitly the document's retrieval context. 386 When a form occurs nested within a link, the form context is the link 387 target of the enclosing link. 389 3.5. Form Data 391 Form data provides instructions for agents to construct a request 392 payload. It consists of a list of zero or more _form fields_. Each 393 form field consists of a _form field name_ and a _form field value_. 395 Form fields can either directly identify data items that need to be 396 included in the request payload or reference an external resource 397 (such as a schema) that describes the data. They can also provide 398 other information, such as acceptable data formats. 400 The form field name identifies the semantics of the form field. Like 401 link and form relation types, a form field name is denoted by an IRI 402 or an unsigned integer. 404 The form field value can be an IRI, a Boolean value, an integer, a 405 floating-point number, a byte string, or a text string. 407 3.6. Navigation 409 An agent begins interacting with an application by performing a GET 410 request on an _entry point IRI_. The entry point IRI is the only IRI 411 an agent is expected to know before interacting with an application. 412 From there, the agent is expected to make all requests by following 413 links and submitting forms provided by the server in responses. The 414 entry point IRI can be obtained by manual configuration or through 415 some discovery process. 417 If dereferencing the entry point IRI yields a CoRAL document or any 418 other representation that implements the CoRAL data and interaction 419 model, then the agent proceeds as follows: 421 1. The first step for the agent is to decide what to do next, i.e., 422 which type of link to follow or form to submit, based on the link 423 relation types and form relation types it understands. 425 2. The agent finds the link(s) or form(s) with the given relation 426 type in the active representation. This may yield one or more 427 candidates, from which the agent must select the most appropriate 428 one in the next step. The set of candidates MAY be empty, for 429 example, if a transition is not supported or not allowed. 431 3. The agent selects one of the candidates based on the metadata 432 associated with the link(s) or form(s). Metadata typically 433 includes the media type of the target resource representation, 434 the IRI scheme, the request method, and other information that is 435 provided as nested elements in a link and form data in a form. 437 4. The agent resolves the IRI reference in the link or form as 438 specified in Section 5 of RFC 3986 [RFC3986] to obtain the 439 _request IRI_. Fragment identifiers are not part of the request 440 IRI and MUST be separated from the rest of the IRI prior to a 441 dereference. The request IRI may need to be converted to a URI 442 (Section 3.1 of RFC 3987 [RFC3987]) for protocols that do not 443 support IRIs. 445 5. The agent constructs a new request with the request IRI. If the 446 agent follows a link, the request method MUST be GET. If the 447 agent submits a form, the request method MUST be the one 448 specified in the form. The agent SHOULD set HTTP header fields 449 and CoAP request options according to provided metadata (e.g., 450 set the HTTP Accept header field or the CoAP Accept option when 451 the media type of the target resource is provided). In case of a 452 form with form data, the agent MUST include a request payload 453 that matches the specifications of the form data. 455 6. The agent sends the request and retrieves the response. 457 7. If a fragment identifier was separated from the request IRI, the 458 agent dereferences the fragment identifier within the retrieved 459 representation. 461 8. The agent _updates the session history_: It removes all the 462 entries in the browsing context's session history after the 463 current entry. Then it appends a new entry at the end of the 464 history representing the new resource. 466 9. Finally, if response contains a CoRAL document or any other 467 representation that implements the CoRAL data and interaction 468 model, the agent can again decide what to do next and the cycle 469 repeats. 471 3.7. History Traversal 473 An agent can also navigate a browsing context by traversing the 474 browsing context's session history. An agent can _traverse the 475 session history_ by updating the active representation to the that 476 entry. 478 4. Binary Format 480 This section defines the encoding of documents in the CoRAL binary 481 format. 483 A document in the binary format is a data item in Concise Binary 484 Object Representation (CBOR) [RFC7049]. The structure of this data 485 item is presented in the Concise Data Definition Language (CDDL) 486 [I-D.ietf-cbor-cddl]. The media type is "application/coral+cbor". 488 4.1. Data Structure 490 The data structure of a document in the binary format is made up of 491 three kinds of elements: links and forms, as defined by the CoRAL 492 data model, and base IRI directives. Base IRI directives provide a 493 way to encode IRI references with a common base more efficiently. 495 Elements are processed in the order they appear in the document. 496 Document processors need to maintain an _environment_ while iterating 497 an array of elements. The environment consists of three variables: a 498 _current context IRI_, a _current base IRI_, and a _current relation 499 type_. The current context IRI and current base IRI are initially 500 both set to the document's retrieval context. The current relation 501 type is initially set to the unsigned integer zero. 503 4.1.1. Documents 505 The body of a document in the binary format is encoded as an array of 506 zero or more links, forms, and directives. 508 body = [*(link / form / directive)] 510 4.1.2. Links 512 A link is encoded as an array that consists of the unsigned integer 513 2, followed by the link relation type and the link target, optionally 514 followed by a link body that contains nested elements. 516 link = [link: 2, relation, target, ?body] 518 The link relation type is encoded either as a text string containing 519 an absolute IRI reference or as an (unsigned or negative) integer 520 representing the difference to the current relation type. A link is 521 processed by updating the current relation type to the result of 522 adding the specified integer (or zero in the case of a text string) 523 to the current relation type. 525 relation = text / int 527 The link target is denoted by an IRI reference or represented by a 528 literal value. The IRI reference MAY be relative or absolute and 529 MUST be resolved against the current base IRI. The encoding of IRI 530 references in the binary format is described in Appendix C. The link 531 target MAY be null, which indicates that the link target is an 532 unidentified resource. 534 target = iri / literal / null 536 literal = bool / int / float / bytes / text 538 The array of elements in the link body (if any) MUST be processed in 539 a fresh environment. The current context IRI and current base IRI in 540 the new environment are initially both set to the link target of the 541 enclosing link. The current relation type in the new environment is 542 initially set to the current relation type. 544 4.1.3. Forms 546 A form is encoded as an array that consists of the unsigned integer 547 3, followed by the form relation type, the submission method, and a 548 submission IRI reference, optionally followed by form data. 550 form = [form: 3, relation, method, iri, ?form-data] 552 The form relation type is encoded and processed in the same way as a 553 link relation type (Section 4.1.2). 555 The method MUST refer to one of the request methods defined by the 556 Web transfer protocol identified by the scheme of the submission IRI. 557 It is encoded either as a text string or an unsigned integer. 559 method = text / uint 561 For HTTP [RFC7230], the method MUST be encoded as a text string in 562 the format defined in Section 4.1 of RFC 7231 [RFC7231]; the set of 563 possible values is maintained in the IANA HTTP Method Registry. For 564 CoAP [RFC7252], the method MUST be encoded as an unsigned integer 565 (e.g., the unsigned integer 2 for the POST method); the set of 566 possible values is maintained in the IANA CoAP Method Codes Registry. 568 The submission IRI reference MAY be relative or absolute and MUST be 569 resolved against the current base IRI. The encoding of IRI 570 references in the binary format is described in Appendix C. 572 4.1.3.1. Form Data 574 Form data is encoded as an array of zero or more name-value pairs. 576 form-data = [*(form-field-name, form-field-value)] 578 Form data (if any) MUST be processed in a fresh environment. The 579 current context IRI and current base IRI in the new environment are 580 initially both set to the submission IRI of the enclosing form. The 581 current relation type in the new environment is initially set to the 582 current relation type. 584 A form field name is encoded and processed in the same way as a link 585 relation type (Section 4.1.2). 587 form-field-name = text / uint 589 A form field value can be an IRI reference, a Boolean value, an 590 integer, a floating-point number, a byte string, a text string, or 591 null. An IRI reference MAY be relative or absolute and MUST be 592 resolved against the current base IRI. The encoding of IRI 593 references in the binary format is described in Appendix C. 595 form-field-value = iri / bool / int / float / bytes / text / null 597 4.1.3.2. Short Forms 599 Forms in certain shapes can be encoded in a more efficient manner 600 using short forms. The following short forms are available: 602 form =/ [form.create: 4, ?accept: uint .size 2] 604 form =/ [form.update: 5, ?accept: uint .size 2] 606 form =/ [form.delete: 6] 608 If the scheme of the submission IRI indicates HTTP, the short forms 609 expand as follows: 611 [4] -> [3, "urn:ietf:rfc:XXXX#create", "POST", []] 612 [4, x] -> [3, "urn:ietf:rfc:XXXX#create", "POST", [], 613 ["urn:ietf:rfc:XXXX#accept", x]] 614 [5] -> [3, "urn:ietf:rfc:XXXX#update", "PUT", []] 615 [5, x] -> [3, "urn:ietf:rfc:XXXX#update", "PUT", [], 616 ["urn:ietf:rfc:XXXX#accept", x]] 617 [6] -> [3, "urn:ietf:rfc:XXXX#delete", "DELETE", []] 619 If the scheme of the submission IRI indicates CoAP, the short forms 620 expand as follows: 622 [4] -> [3, "urn:ietf:rfc:XXXX#create", 2, []] 623 [4, x] -> [3, "urn:ietf:rfc:XXXX#create", 2, [], 624 ["urn:ietf:rfc:XXXX#accept", x]] 625 [5] -> [3, "urn:ietf:rfc:XXXX#update", 3, []] 626 [5, x] -> [3, "urn:ietf:rfc:XXXX#update", 3, [], 627 ["urn:ietf:rfc:XXXX#accept", x]] 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 IRI reference MAY be relative or absolute and MUST be resolved 649 against the current context IRI. The encoding of IRI references in 650 the binary format is described in Appendix C. 652 The directive is processed by resolving the IRI reference against the 653 current context IRI and assigning the result to the current base IRI. 655 5. Textual Format 657 This section defines the syntax of documents in the CoRAL textual 658 format using two grammars: The lexical grammar defines how Unicode 659 characters are combined to form line terminators, white space, 660 comments, and tokens. The syntactic grammar defines how the tokens 661 are combined to form documents. Both grammars are presented in 662 Augmented Backus-Naur Form (ABNF) [RFC5234]. 664 A document in the textual format is a Unicode string in a Unicode 665 encoding form [UNICODE]. The media type for such documents is "text/ 666 coral". The "charset" parameter is not used; charset information is 667 transported inside the document in the form of an OPTIONAL Byte Order 668 Mark (BOM). The use of the UTF-8 encoding scheme [RFC3629], without 669 a BOM, is RECOMMENDED. 671 5.1. Lexical Structure 673 The lexical structure of a document in the textual format is made up 674 of four basic elements: line terminators, white space, comments, and 675 tokens. Of these, only tokens are significant in the syntactic 676 grammar. There are four kinds of tokens: identifiers, IRI 677 references, literals, and punctuators. 679 When several lexical grammar rules match a sequence of characters in 680 a document, the longest match takes priority. 682 5.1.1. Line Terminators 684 Line terminators divide text into lines. A line terminator is any 685 Unicode character with Line_Break class BK, CR, LF, or NL. However, 686 any CR character that immediately precedes a LF character is ignored. 687 (This affects only the numbering of lines in error messages.) 689 5.1.2. White Space 691 White space is a sequence of one or more white space characters. A 692 white space character is any Unicode character with the White_Space 693 property. 695 5.1.3. Comments 697 Comments are sequences of characters that are ignored when parsing 698 text into tokens. Single-line comments begin with the characters 699 "//" and extend to the end of the line. Delimited comments begin 700 with the characters "/*" and end with the characters "*/". Delimited 701 comments can occupy a portion of a line, a single line, or multiple 702 lines. 704 Comments do not nest. The character sequences "/*" and "*/" have no 705 special meaning within a single-line comment; the character sequences 706 "//" and "/*" have no special meaning within a delimited comment. 708 5.1.4. Identifiers 710 An identifier tokens is a user-defined symbolic name. The rules for 711 identifiers correspond to those recommended by the Unicode Standard 712 Annex #31 [UNICODE-UAX31] using the following profile: 714 identifier = start *continue *(medial 1*continue) 716 start = 718 continue = 720 medial = "-" / "." / "~" / %xB7 / %x58A / %xF0B 722 medial =/ %x2010 / %x2027 / %x30A0 / %x30FB 724 All identifiers MUST be converted into Unicode Normalization Form C 725 (NFC), as defined by the Unicode Standard Annex #15 [UNICODE-UAX15]. 726 Comparison of identifiers is based on NFC and is case-sensitive 727 (unless otherwise noted). 729 5.1.5. IRI References 731 An IRI reference is a Unicode string that conforms to the syntax 732 defined in RFC 3987 [RFC3987]. An IRI reference can be absolute or 733 relative and can contain a fragment identifier. IRI references are 734 enclosed in angle brackets ("<" and ">"). 736 iri = "<" IRI-reference ">" 738 IRI-reference = 740 5.1.6. Literals 742 A literal is a textual representation of a value. There are six 743 types of literals: Boolean, integer, floating-point, byte string, 744 text string, and null. 746 5.1.6.1. Boolean Literals 748 The case-insensitive tokens "true" and "false" denote the Boolean 749 values true and false, respectively. 751 boolean = "true" / "false" 753 5.1.6.2. Integer Literals 755 Integer literals denote integer values of unspecified precision. By 756 default, integer literals are expressed in decimal, but they can also 757 be specified in an alternate base using a prefix. Binary literals 758 begin with "0b", octal literals begin with "0o", and hexadecimal 759 literals begin with "0x". 761 Decimal literals contain the digits "0" through "9". Binary literals 762 contain "0" and "1", octal literals contain "0" through "7", and 763 hexadecimal literals contain "0" through "9" as well as "A" through 764 "F" in upper- or lowercase. 766 Negative integers are expressed by prepending a minus sign ("-"). 768 integer = ["+" / "-"] (decimal / binary / octal / hexadecimal) 770 decimal = 1*DIGIT 772 binary = %x30 (%x42 / %x62) 1*BINDIG 774 octal = %x30 (%x4F / %x6F) 1*OCTDIG 776 hexadecimal = %x30 (%x58 / %x78) 1*HEXDIG 778 DIGIT = %x30-39 780 BINDIG = %x30-31 782 OCTDIG = %x30-37 784 HEXDIG = %x30-39 / %x41-46 / %x61-66 786 5.1.6.3. Floating-point Literals 788 Floating-point literals denote floating-point numbers of unspecified 789 precision. 791 Floating-point literals consist of a sequence of decimal digits 792 followed by a fraction, an exponent, or both. The fraction consists 793 of a decimal point (".") followed by a sequence of decimal digits. 794 The exponent consists of the letter "e" in upper- or lowercase, 795 followed by an optional sign and a sequence of decimal digits that 796 indicate a power of 10 by which the value preceding the "e" is 797 multiplied. 799 Negative floating-point values are expressed by prepending a minus 800 sign ("-"). 802 floating-point = ["+" / "-"] 1*DIGIT [fraction] [exponent] 804 fraction = "." 1*DIGIT 806 exponent = (%x45 / %x65) ["+" / "-"] 1*DIGIT 808 Floating-point literals can additionally denote the special "Not- 809 a-Number" (NaN) value, positive infinity, and negative infinity. The 810 NaN value is produced by the case-insensitive token "NaN". The two 811 infinite values are produced by the case-insensitive tokens 812 "+Infinity" (or simply "Infinity") and "-Infinity". 814 floating-point =/ "NaN" 816 floating-point =/ ["+" / "-"] "Infinity" 818 5.1.6.4. Byte String Literals 820 A byte string literal consists of a prefix and zero or more bytes 821 encoded in Base16, Base32, or Base64 [RFC4648] and enclosed in single 822 quotes. Byte string literals encoded in Base16 begin with "h" or 823 "b16", byte string literals encoded in Base32 begin with "b32", and 824 byte string literals encoded in Base64 begin with "b64". 826 bytes = base16 / base32 / base64 828 base16 = (%x68 / %x62.31.36) SQUOTE SQUOTE 830 base32 = %x62.33.32 SQUOTE SQUOTE 832 base64 = %x62.36.34 SQUOTE SQUOTE 834 SQUOTE = %x27 836 5.1.6.5. Text String Literals 838 A text string literal consists of zero or more Unicode characters 839 enclosed in double quotes. It can include simple escape sequences 840 (such as \t for the tab character) as well as hexadecimal and Unicode 841 escape sequences. 843 text = DQUOTE *(char / %x5C escape) DQUOTE 845 char = 847 escape = simple-escape / hexadecimal-escape / unicode-escape 849 simple-escape = %x30 / %x62 / %x74 / %x6E / %x76 850 simple-escape =/ %x66 / %x72 / %x22 / %x27 / %x5C 852 hexadecimal-escape = (%x78 / %x58) 2HEXDIG 854 unicode-escape = %x75 4HEXDIG / %x55 8HEXDIG 856 DQUOTE = %x22 858 An escape sequence denotes a single Unicode code point. For 859 hexadecimal and Unicode escape sequences, the code point is expressed 860 by the hexadecimal number following the "\x", "\X", "\u", or "\U" 861 prefix. Simple escape sequences indicate the code points listed in 862 Table 1. 864 +-----------------+------------+----------------------+ 865 | Escape Sequence | Code Point | Character Name | 866 +-----------------+------------+----------------------+ 867 | \0 | U+0000 | Null | 868 | \b | U+0008 | Backspace | 869 | \t | U+0009 | Character Tabulation | 870 | \n | U+000A | Line Feed | 871 | \v | U+000B | Line Tabulation | 872 | \f | U+000C | Form Feed | 873 | \r | U+000D | Carriage Return | 874 | \" | U+0022 | Quotation Mark | 875 | \' | U+0027 | Apostrophe | 876 | \\ | U+005C | Reverse Solidus | 877 +-----------------+------------+----------------------+ 879 Table 1: Simple Escape Sequences 881 5.1.6.6. Null Literal 883 The case-insensitive tokens "null" and "_" denote the intentional 884 absence of any value. 886 null = "null" / "_" 888 5.1.7. Punctuators 890 Punctuator tokens are used for grouping and separating. 892 punctuator = "#" | ":" | "[" | "]" | "{" | "}" | "=" | "->" 894 5.2. Syntactic Structure 896 The syntactic structure of a document in the textual format is made 897 up of three kinds of elements: links and forms, as defined by the 898 CoRAL data model, and directives. Directives provide a way to make 899 documents easier to read and write by defining a base IRI for 900 relative IRI references and introducing shorthands for IRIs. 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 _current mapping 906 from identifiers to IRIs_. The current context IRI and current base 907 IRI are initially both set to the document's retrieval context. The 908 current 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 A simple name consists of an identifier. It is resolved to an IRI by 931 looking up the empty string in the current mapping from identifiers 932 to IRIs and appending the specified identifier to the result. It is 933 an error if the empty string is not present in the mapping. 935 simple-name = identifier 937 A qualified name consists of two identifiers separated by a colon 938 (":"). It is resolved to an IRI by looking up the identifier on the 939 left hand side in the current mapping from identifiers to IRIs and 940 appending the identifier on the right hand side to the result. It is 941 an error if the identifier on the left hand side is not present in 942 the mapping. 944 qualified-name = identifier ":" identifier 946 The link target is denoted by an IRI reference or represented by a 947 value literal. The IRI reference MAY be relative or absolute and 948 MUST be resolved against the current base IRI. If the link target is 949 null, the link target is an unidentified resource. 951 target = iri / literal / null 953 literal = boolean / integer / floating-point / bytes / text 955 The list of elements in the link body (if any) MUST be processed in a 956 fresh environment. The current context IRI and current base IRI in 957 this environment are initially both set to the link target of the 958 enclosing link. The mapping from identifiers to IRIs is initially 959 set to a copy of the mapping from identifiers to IRIs in the current 960 environment. 962 5.2.3. Forms 964 A form consists of the form relation type, followed by a "->" token, 965 a method identifier, and a submission IRI reference, optionally 966 followed by form data enclosed in square brackets ("[" and "]"). 968 form = relation "->" method iri ["[" form-data "]"] 970 The form relation type is denoted in the same way as a link relation 971 type (Section 5.2.2). 973 The method identifier refers to one of the request methods defined by 974 the Web transfer protocol identified by the scheme of the submission 975 IRI. Method identifiers are case-insensitive and constrained to 976 Unicode characters in the Basic Latin block. 978 method = identifier 980 For HTTP [RFC7230], the set of possible method identifiers is 981 maintained in the IANA HTTP Method Registry. For CoAP [RFC7252], the 982 set of possible method identifiers is maintained in the IANA CoAP 983 Method Codes Registry. 985 The submission IRI reference MAY be relative or absolute and MUST be 986 resolved against the current base IRI. 988 5.2.3.1. Form Data 990 Form data consists of zero or more name-value pairs. 992 form-data = *(form-field-name form-field-value) 994 Form data MUST be processed in a fresh environment. The current 995 context IRI and current base IRI in this environment are initially 996 both set to the submission IRI of the enclosing form. The mapping 997 from identifiers to IRIs is initially set to a copy of the mapping 998 from identifiers to IRIs in the current environment. 1000 The form field name is denoted in the same way as a link relation 1001 type (Section 5.2.2). 1003 form-field-name = iri / simple-name / qualified-name / integer 1005 The form field value can be an IRI reference, Boolean literal, 1006 integer literal, floating-point literal, byte string literal, text 1007 string literal, or null. An IRI reference MAY be relative or 1008 absolute and MUST be resolved against the current base IRI. 1010 form-field-value = iri / boolean / integer 1012 form-field-value =/ floating-point / bytes / text / null 1014 5.2.4. Directives 1016 Directives provide the ability to manipulate the environment when 1017 processing a list of elements. All directives start with a number 1018 sign ("#") followed by a directive identifier. Directive identifiers 1019 are case-insensitive and constrained to Unicode characters in the 1020 Basic Latin block. 1022 The following directives are available: Base IRI directives and Using 1023 directives. 1025 directive = base-directive / using-directive 1027 5.2.4.1. Base IRI Directives 1029 A Base IRI directive consists of a number sign ("#"), followed by the 1030 case-insensitive identifier "base", followed by an IRI reference. 1032 base-directive = "#" "base" iri 1034 The IRI reference MAY be relative or absolute and MUST be resolved 1035 against the current context IRI. 1037 The directive is processed by resolving the IRI reference against the 1038 current context IRI and assigning the result to the current base IRI. 1040 5.2.4.2. Using Directives 1042 A Using directive consists of a number sign ("#"), followed by the 1043 case-insensitive identifier "using", optionally followed by an 1044 identifier and an equals sign ("="), finally followed by an absolute 1045 IRI reference. If the identifier is not specified, it is assumed to 1046 be the empty string. 1048 using-directive = "#" "using" [identifier "="] iri 1050 The IRI reference MUST be absolute. 1052 The directive is processed by adding the specified identifier and IRI 1053 to the current mapping from identifiers to IRIs. It is an error if 1054 the identifier is already present in the mapping. 1056 6. Usage Considerations 1058 This section discusses some considerations in creating CoRAL-based 1059 applications and managing link and form relation types. 1061 6.1. Specifying CoRAL-based Applications 1063 CoRAL-based applications naturally implement the Web architecture 1064 [W3C.REC-webarch-20041215] and thus are centered around orthogonal 1065 specifications for identification, interaction, and representation: 1067 o Resources are identified by IRIs or represented by value literals. 1069 o Interactions are based on the hypermedia interaction model of the 1070 Web and the methods provided by the Web transfer protocol. The 1071 semantics of possible interactions are identified by link and form 1072 relation types. 1074 o Representations are CoRAL documents encoded in the binary format 1075 defined in Section 4 or the textual format defined in Section 5. 1076 Depending on the application, additional representation formats 1077 can be used. 1079 Specifications for CoRAL-based applications need to list the specific 1080 components used in the application and their identifiers. This 1081 SHOULD include at least the following items: 1083 o IRI schemes that identify the Web transfer protocol(s) used in the 1084 application. 1086 o Internet media types that identify the representation format(s) 1087 used in the application, including the media type(s) of the CoRAL 1088 serialization format(s). 1090 o Link relation types that identify the semantics of links. 1092 o Form relation types that identify the semantics of forms. 1093 Additionally, for each form relation type, the permissible request 1094 method(s). 1096 o Form field names that identify the semantics of form fields. 1097 Additionally, for each form field name, the permissible form field 1098 value(s) or type(s). 1100 6.1.1. Naming Resources 1102 Resource names -- i.e., URIs [RFC3986] and IRIs [RFC3987] -- are a 1103 cornerstone of Web-based applications. They enable uniform 1104 identification of resources and are used every time a client 1105 interacts with a server or a resource representation needs to refer 1106 to another resource. 1108 URIs and IRIs often include structured application data in the path 1109 and query components, such as paths in a filesystem or keys in a 1110 database. It is a common practice in many HTTP-based applications to 1111 make this part of the application specification, i.e., they prescribe 1112 fixed URI templates that are hard-coded in implementations. However, 1113 there are a number of problems with this practice [RFC7320]. 1115 In CoRAL-based applications, resource names are not part of the 1116 application specification; they are an implementation detail. The 1117 specification of a CoRAL-based application MUST NOT mandate any 1118 particular form of resource name structure. BCP 190 [RFC7320] 1119 describes the problematic practice of fixed URI structures in more 1120 detail and provides some acceptable alternatives. 1122 6.1.2. Implementation Limits 1124 This document places no restrictions on the number of elements in a 1125 CoRAL document or the depth of nested elements. Applications using 1126 CoRAL (in particular those that run in constrained environments) MAY 1127 wish to limit these numbers and specify implementation limits that an 1128 application implementation MUST at least support to be interoperable. 1129 Implementation limits MAY also include the following as well as other 1130 items: 1132 o use of only either the binary format or the text format; 1133 o use of only either HTTP or CoAP as the Web transfer protocol; 1135 o use of only either IRIs or unsigned integers to denote link 1136 relation types, form relation types, and form field names; 1138 o use of only either short forms or long forms in the binary format; 1140 o use of IRI references only up to a specific length; 1142 o use of CBOR in a canonical format (Section 3.9 of RFC 7049 1143 [RFC7049]). 1145 6.2. Minting New Relation Types 1147 New link relation types, form relation types, and form field names 1148 can be minted by defining an IRI [RFC3987] that uniquely identifies 1149 the item. Although the IRI can point to a resource that contains a 1150 definition of the semantics of the relation type, clients SHOULD NOT 1151 automatically access that resource to avoid overburdening its server. 1152 The IRI SHOULD be under the control of the person or party defining 1153 it, or be delegated to them. 1155 Link relation types registered in the IANA Link Relations Registry, 1156 such as "collection" [RFC6573] or "icon" [W3C.REC-html51-20161101], 1157 can be used in CoRAL by appending the registered name to the IRI 1158 : 1160 #using iana = 1162 iana:collection 1163 iana:icon 1165 A good source for link relation types for resource metadata are RDF 1166 predicates [W3C.REC-rdf11-concepts-20140225]. An RDF statement says 1167 that some relationship, indicated by a predicate, holds between two 1168 resources. RDF predicates and link relation types can therefore 1169 often be used interchangeably. For example, a CoRAL document could 1170 describe its creator by using the FOAF vocabulary [FOAF]: 1172 #using iana = 1173 #using foaf = 1175 foaf:maker _ { 1176 iana:type 1177 foaf:familyName "Hartke" 1178 foaf:givenName "Klaus" 1179 foaf:mbox 1180 } 1182 6.3. Registering Relation Types 1184 IRIs that identify link relation types, form relation types, and form 1185 field names do not need to be registered. The inclusion of DNS names 1186 in IRIs allows for the decentralized creation of new IRIs without the 1187 risk of collisions. 1189 However, IRIs can be relatively verbose and impose a high overhead on 1190 representations. This can be a problem in constrained environments 1191 [RFC7228]. Therefore, CoRAL alternatively allows the use of unsigned 1192 integers to identify link relation types, form relation types, and 1193 form field names. These impose a much smaller overhead but instead 1194 need to be assigned by a registry to avoid collisions. 1196 This document does not create a registry for such integers. Instead, 1197 the media types for CoRAL documents in the binary and textual format 1198 are defined to have a "profile" parameter [RFC6906] that determines 1199 the registry in use. The registry is identified by a URI [RFC3986]. 1200 For example, a CoRAL document that uses the registry identified by 1201 the URI can use the following media 1202 type: 1204 application/coral+cbor; profile="http://example.com/registry" 1206 The URI serves only as an identifier; it does not necessarily have to 1207 be dereferencable (or even use a dereferencable URI scheme). It is 1208 permissible, though, to use a dereferencable URI and serve a 1209 representation that provides information about the registry in a 1210 human- or machine-readable way. (The format of such a representation 1211 is outside the scope of this document.) 1213 For simplicity, a CoRAL document can use unsigned integers from at 1214 most one registry. The "profile" parameter of the CoRAL media types 1215 MUST contain a single URI, not a white space separated list of URIs 1216 as recommended in RFC 6906 [RFC6906]. If the "profile" parameter is 1217 absent, the default profile specified in Appendix B is assumed. 1219 A CoRAL registry SHOULD map each unsigned integer to a full IRI that 1220 identifies a link relation type, form relation type, or form field 1221 name. The namespaces for these three kinds of identifiers are 1222 disjoint, i.e., the same integer MAY be assigned to a link relation 1223 type, form relation type, and form field name without ambiguity. 1224 Once an integer has been assigned, the assignment MUST NOT be changed 1225 or removed. A registry MAY provide additional information about an 1226 assignment (for example, whether a link relation type is deprecated). 1228 In CoAP [RFC7252], media types (including specific values for their 1229 parameters) are encoded as a small, unsigned integer called the 1230 content format. For use with CoAP, each CoRAL registry needs to 1231 register a new content format in the IANA CoAP Content-Formats 1232 Registry. Each such registered content format MUST specify a CoRAL 1233 media type with a "profile" parameter that contains the registry URI. 1235 6.4. Expressing Link Target Attributes 1237 Link target attributes defined for use with CoRE Link Format 1238 [RFC6690] (such as "type", "hreflang", "media", "ct", "rt", "if", and 1239 "sz") can be expressed in CoRAL by nesting links under the respective 1240 link and specifying the attribute name appended to the IRI 1241 as the link relation type. The target of such nested 1242 links MUST be a text string literal: 1244 #using iana = 1245 #using attr = 1247 iana:item { 1248 attr:type "application/json-patch+json" 1249 attr:ct "51" 1250 } 1252 [[NOTE TO RFC EDITOR: Please replace all occurrences of "http://TBD/" 1253 with a RFC-Editor-controlled IRI.]] 1255 Link target attributes that do not actually describe the link target 1256 but the link itself (such as "rel", "anchor", "rev", "title", and 1257 "title*") are excluded from this provision and MUST NOT occur in a 1258 CoRAL document. 1260 6.5. Embedding CoRAL in CBOR Structures 1262 Data items in the CoRAL binary format (Section 4) MAY be embedded in 1263 other CBOR [RFC7049] data structures. Specifications using CDDL 1264 [I-D.ietf-cbor-cddl] SHOULD reference the following CDDL definitions 1265 for this purpose: 1267 CoRAL-Body = body 1269 CoRAL-Link = link 1271 CoRAL-Form = form 1273 CoRAL-IRI = iri 1275 7. Security Considerations 1277 Parsers of CoRAL documents must operate on input that is assumed to 1278 be untrusted. This means that parsers MUST fail gracefully in the 1279 face of malicious inputs. Additionally, parsers MUST be prepared to 1280 deal with resource exhaustion (e.g., resulting from the allocation of 1281 big data items) or exhaustion of the stack depth (stack overflow). 1282 See Section 8 of RFC 7049 [RFC7049] for security considerations 1283 relating to parsing CBOR. 1285 Implementers of the CoRAL textual format need to consider the 1286 security aspects of handling Unicode input. See the Unicode Standard 1287 Annex #36 [UNICODE-UAX36] for security considerations relating to 1288 visual spoofing and misuse of character encodings. See Section 10 of 1289 RFC 3629 [RFC3629] for security considerations relating to UTF-8. 1291 CoRAL makes extensive use of IRIs and URIs. See Section 8 of RFC 1292 3987 [RFC3987] for security considerations relating to IRIs. See 1293 Section 7 of RFC 3986 [RFC3986] for security considerations relating 1294 to URIs. 1296 The security of applications using CoRAL can depend on the proper 1297 preparation and comparison of internationalized strings. For 1298 example, such strings can be used to make authentication and 1299 authorization decisions, and the security of an application could be 1300 compromised if an entity providing a given string is connected to the 1301 wrong account or online resource based on different interpretations 1302 of the string. See RFC 6943 [RFC6943] for security considerations 1303 relating to identifiers in IRIs and other locations. 1305 CoRAL is intended to be used in conjunction with a Web transfer 1306 protocol such as HTTP or CoAP. See Section 9 of RFC 7320 [RFC7230], 1307 Section 9 of RFC 7231 [RFC7231], etc. for security considerations 1308 relating to HTTP. See Section 11 of RFC 7252 [RFC7252] for security 1309 considerations relating to CoAP. 1311 CoRAL does not define any specific mechanisms for protecting the 1312 confidentiality and integrity of CoRAL documents. It relies on 1313 application layer or transport layer mechanisms for this, such as 1314 Transport Layer Security (TLS) [RFC5246]. 1316 CoRAL documents and the structure of a web of resources revealed from 1317 automatically following links can disclose personal information and 1318 other sensitive information. Implementations need to prevent the 1319 unintentional disclosure of such information. See Section of 9 of 1320 RFC 7231 [RFC7231] for additional considerations. 1322 Applications using CoRAL ought to consider the attack vectors opened 1323 by automatically following, trusting, or otherwise using links and 1324 forms in CoRAL documents. In particular, a server that is 1325 authoritative for the CoRAL representation of a resource may not 1326 necessarily be the authoritative source for nested links and forms. 1328 8. IANA Considerations 1330 8.1. Media Type "application/coral+cbor" 1332 This document registers the media type "application/coral+cbor" 1333 according to the procedures of BCP 13 [RFC6838]. 1335 Type name: 1336 application 1338 Subtype name: 1339 coral+cbor 1341 Required parameters: 1342 N/A 1344 Optional parameters: 1345 profile - See Section 6.3 of [I-D.hartke-t2trg-coral]. 1347 Encoding considerations: 1348 binary - See Section 4 of [I-D.hartke-t2trg-coral]. 1350 Security considerations: 1351 See Section 7 of [I-D.hartke-t2trg-coral]. 1353 Interoperability considerations: 1354 N/A 1356 Published specification: 1357 [I-D.hartke-t2trg-coral] 1359 Applications that use this media type: 1360 See Section 1 of [I-D.hartke-t2trg-coral]. 1362 Fragment identifier considerations: 1363 As specified for "application/cbor". 1365 Additional information: 1366 Deprecated alias names for this type: N/A 1367 Magic number(s): N/A 1368 File extension(s): N/A 1369 Macintosh file type code(s): N/A 1371 Person & email address to contact for further information: 1372 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1374 Intended usage: 1375 COMMON 1377 Restrictions on usage: 1378 N/A 1380 Author: 1381 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1383 Change controller: 1384 IESG 1386 Provisional registration? 1387 No 1389 8.2. Media Type "text/coral" 1391 This document registers the media type "text/coral" according to the 1392 procedures of BCP 13 [RFC6838] and guidelines in RFC 6657 [RFC6657]. 1394 Type name: 1395 text 1397 Subtype name: 1398 coral 1400 Required parameters: 1401 N/A 1403 Optional parameters: 1404 profile - See Section 6.3 of [I-D.hartke-t2trg-coral]. 1406 Encoding considerations: 1407 binary - See Section 5 of [I-D.hartke-t2trg-coral]. 1409 Security considerations: 1410 See Section 7 of [I-D.hartke-t2trg-coral]. 1412 Interoperability considerations: 1413 N/A 1415 Published specification: 1416 [I-D.hartke-t2trg-coral] 1418 Applications that use this media type: 1420 See Section 1 of [I-D.hartke-t2trg-coral]. 1422 Fragment identifier considerations: 1423 N/A 1425 Additional information: 1426 Deprecated alias names for this type: N/A 1427 Magic number(s): N/A 1428 File extension(s): .coral 1429 Macintosh file type code(s): TEXT 1431 Person & email address to contact for further information: 1432 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1434 Intended usage: 1435 COMMON 1437 Restrictions on usage: 1438 N/A 1440 Author: 1441 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1443 Change controller: 1444 IESG 1446 Provisional registration? 1447 No 1449 8.3. CoAP Content Formats 1451 This document registers CoAP content formats for the media types 1452 "application/coral+cbor" and "text/coral" according to the procedures 1453 of RFC 7252 [RFC7252]. 1455 o Media Type: application/coral+cbor 1456 Content Coding: identity 1457 ID: TBD (maybe 63) 1458 Reference: [I-D.hartke-t2trg-coral] 1460 o Media Type: text/coral 1461 Content Coding: identity 1462 ID: TBD (maybe 10063) 1463 Reference: [I-D.hartke-t2trg-coral] 1465 9. References 1467 9.1. Normative References 1469 [I-D.ietf-cbor-cddl] 1470 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1471 definition language (CDDL): a notational convention to 1472 express CBOR data structures", draft-ietf-cbor-cddl-00 1473 (work in progress), July 2017. 1475 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1476 Requirement Levels", BCP 14, RFC 2119, 1477 DOI 10.17487/RFC2119, March 1997, . 1480 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1481 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1482 2003, . 1484 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1485 Resource Identifier (URI): Generic Syntax", STD 66, 1486 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1487 . 1489 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1490 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 1491 January 2005, . 1493 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1494 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1495 . 1497 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1498 Specifications: ABNF", STD 68, RFC 5234, 1499 DOI 10.17487/RFC5234, January 2008, . 1502 [RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding 1503 "charset" Parameter Handling in Textual Media Types", 1504 RFC 6657, DOI 10.17487/RFC6657, July 2012, 1505 . 1507 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1508 Specifications and Registration Procedures", BCP 13, 1509 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1510 . 1512 [RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for 1513 Security Purposes", RFC 6943, DOI 10.17487/RFC6943, May 1514 2013, . 1516 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1517 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1518 October 2013, . 1520 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1521 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1522 May 2017, . 1524 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1525 DOI 10.17487/RFC8288, October 2017, . 1528 [UNICODE] The Unicode Consortium, "The Unicode Standard", 1529 . 1531 Note that this reference is to the latest version of 1532 Unicode, rather than to a specific release. It is not 1533 expected that future changes in the Unicode specification 1534 will have any impact on this document. 1536 [UNICODE-UAX15] 1537 The Unicode Consortium, "Unicode Standard Annex #15: 1538 Unicode Normalization Forms", 1539 . 1541 [UNICODE-UAX31] 1542 The Unicode Consortium, "Unicode Standard Annex #31: 1543 Unicode Identifier and Pattern Syntax", 1544 . 1546 [UNICODE-UAX36] 1547 The Unicode Consortium, "Unicode Standard Annex #36: 1548 Unicode Security Considerations", 1549 . 1551 9.2. Informative References 1553 [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification 1554 0.99", January 2014, 1555 . 1557 [I-D.ietf-core-links-json] 1558 Li, K., Rahman, A., and C. Bormann, "Representing 1559 Constrained RESTful Environments (CoRE) Link Format in 1560 JSON and CBOR", draft-ietf-core-links-json-09 (work in 1561 progress), July 2017. 1563 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1564 (TLS) Protocol Version 1.2", RFC 5246, 1565 DOI 10.17487/RFC5246, August 2008, . 1568 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1569 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1570 . 1572 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1573 Address Text Representation", RFC 5952, 1574 DOI 10.17487/RFC5952, August 2010, . 1577 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 1578 RFC 6573, DOI 10.17487/RFC6573, April 2012, 1579 . 1581 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1582 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1583 . 1585 [RFC6903] Snell, J., "Additional Link Relation Types", RFC 6903, 1586 DOI 10.17487/RFC6903, March 2013, . 1589 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, 1590 DOI 10.17487/RFC6906, March 2013, . 1593 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1594 Constrained-Node Networks", RFC 7228, 1595 DOI 10.17487/RFC7228, May 2014, . 1598 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1599 Protocol (HTTP/1.1): Message Syntax and Routing", 1600 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1601 . 1603 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1604 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1605 DOI 10.17487/RFC7231, June 2014, . 1608 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1609 Application Protocol (CoAP)", RFC 7252, 1610 DOI 10.17487/RFC7252, June 2014, . 1613 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 1614 RFC 7320, DOI 10.17487/RFC7320, July 2014, 1615 . 1617 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1618 FETCH Methods for the Constrained Application Protocol 1619 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1620 . 1622 [W3C.REC-html51-20161101] 1623 Faulkner, S., Eicholz, A., Leithead, T., and A. Danilo, 1624 "HTML 5.1", World Wide Web Consortium Recommendation REC- 1625 html51-20161101, November 2016, 1626 . 1628 [W3C.REC-rdf11-concepts-20140225] 1629 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 1630 Concepts and Abstract Syntax", World Wide Web Consortium 1631 Recommendation REC-rdf11-concepts-20140225, February 2014, 1632 . 1634 [W3C.REC-turtle-20140225] 1635 Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", 1636 World Wide Web Consortium Recommendation REC-turtle- 1637 20140225, February 2014, 1638 . 1640 [W3C.REC-webarch-20041215] 1641 Jacobs, I. and N. Walsh, "Architecture of the World Wide 1642 Web, Volume One", World Wide Web Consortium 1643 Recommendation REC-webarch-20041215, December 2004, 1644 . 1646 Appendix A. Core Vocabulary 1648 This section defines the core vocabulary for CoRAL. It is 1649 RECOMMENDED that all CoRAL registries assign an unsigned integer to 1650 each of these link relation types, form relation types, and form 1651 field names. 1653 [[NOTE TO RFC EDITOR: Please replace all occurrences of 1654 "urn:ietf:rfc:XXXX#" with a RFC-Editor-controlled IRI.]] 1656 A.1. Link Relation Types 1658 1659 Indicates that the link's context is an instance of the type 1660 specified as the link's target; see Section 6 of RFC 6903 1661 [RFC6903]. 1663 This link relation type serves in CoRAL the same purpose as the 1664 RDF predicate identified by the IRI . 1667 1668 Indicates that the link's context is a collection and that the 1669 link's target is a member of that collection; see Section 2.1 of 1670 RFC 6573 [RFC6573]. 1672 1673 Indicates that the link's target is a collection and that the 1674 link's context is a member of that collection; see Section 2.2 of 1675 RFC 6573 [RFC6573]. 1677 A.2. Form Relation Types 1679 1680 Indicates that the form's context is a collection and that a new 1681 item can be created in that collection by submitting a suitable 1682 representation. This form relation type is typically used with 1683 the POST method [RFC7231] [RFC7252]. 1685 1686 Indicates that the form's context can be updated by submitting a 1687 suitable representation. This form relation type is typically 1688 used with the PUT method [RFC7231] [RFC7252] or PATCH method 1689 [RFC5789] [RFC8132]. 1691 1692 Indicates that the form's context can be deleted. This form 1693 relation type is typically used with the DELETE method [RFC7231] 1694 [RFC7252]. 1696 1697 Indicates that the form's context can be searched by submitting a 1698 search query. This form relation type is typically used with the 1699 POST method [RFC7231] [RFC7252] or FETCH method [RFC8132]. 1701 A.3. Form Field Names 1703 1704 Specifies an acceptable HTTP content type or CoAP content format 1705 for the request payload. There MAY be multiple form fields with 1706 this name. If a form does not include a form field with this 1707 name, the server accepts any or no request payload, depending on 1708 the form relation type. 1710 For HTTP, the content type MUST be specified as a text string in 1711 the format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the 1712 set of possible values is maintained in the IANA Media Types 1713 Registry. For CoAP, the content format MUST be specified as an 1714 unsigned integer; the set of possible values is maintained in the 1715 IANA CoAP Content-Formats Registry. 1717 Appendix B. Default Profile 1719 This section defines a default registry that is assumed when a CoRAL 1720 media type without a "profile" parameter is used. 1722 Link Relation Types 1724 0 = 1725 1 = 1726 2 = 1728 Form Relation Types 1730 0 = 1731 1 = 1732 2 = 1733 3 = 1735 Form Fields 1737 0 = 1739 Appendix C. CBOR-encoded IRI References 1741 URI references [RFC3986] and, secondarily, IRI references [RFC3987] 1742 and are the most common usage of resource identifiers in hypertext 1743 representation formats such as HTML 5 [W3C.REC-html51-20161101] and 1744 the CoRE Link Format [RFC6690]. They encode the components of a 1745 resource identifier either as an absolute URI/IRI or as a relative 1746 reference that is resolved against a base URI/IRI. 1748 URI and IRI references are sequences of characters chosen from 1749 limited subsets of the repertoires of US-ASCII characters and Unicode 1750 characters, respectively. The individual components of a URI or IRI 1751 are delimited by several reserved characters, which necessitates the 1752 use of percent-encoding for reserved characters in a non-delimiting 1753 function. The resolution of references involves parsing URI/IRI 1754 references into their components, combining the components with those 1755 of the base URI/IRI, merging paths, removing dot segments, and 1756 recomposing the result into a URI/IRI reference string. 1758 Altogether, proper processing of URIs is quite complex. This can be 1759 a problem in particular in constrained environments [RFC7228] with 1760 severe code size limitations. As a result, many implementations in 1761 these environments choose to implement only an ad-hoc, informally- 1762 specified, bug-ridden, non-interoperable subset of half of RFC 3986. 1764 This section specifies CBOR-encoded IRI References, a serialization 1765 format for IRI references that encodes the IRI components as CBOR 1766 data items rather than text. Assuming that a CBOR implementation is 1767 already present, typical operations on CBOR-encoded IRI references 1768 such as parsing, reference resolution, and comparison can be 1769 implemented much more easily than with the text-based format. A full 1770 implementation that covers all corner cases of the specification can 1771 be implemented in a relatively small amount of code. 1773 CBOR-encoded IRI References are not capable of expressing all IRI 1774 references permitted by the syntax of RFC 3987 [RFC3987]. The 1775 supported subset covers all CoAP URIs [RFC7252] and most HTTP URIs 1776 [RFC7230]. 1778 C.1. Data Structure 1780 The encoding is very similar to the encoding of the request URI in 1781 CoAP messages [RFC7252]. The components of an IRI reference are 1782 encoded as a sequence of _options_. Each option consists of an 1783 _option number_ identifying the type of option (scheme, host name, 1784 etc.) and the _option value_. 1786 iri = [?(scheme: 1, text), 1787 ?(host.name: 2, text // 1788 host.ip: 3, bytes .size 4 / bytes .size 16), 1789 ?(port: 4, uint .size 2), 1790 ?(path.type: 5, path-type), 1791 *(path: 6, text), 1792 *(query: 7, text), 1793 ?(fragment: 8, text)] 1795 path-type = &(absolute-path: 0, 1796 append-path: 1, 1797 relative-path: 2, 1798 append-relation: 3) 1800 C.2. Options 1802 The following options are defined: 1804 scheme 1805 Specifies the IRI scheme. IRI schemes have the same syntax as URI 1806 schemes. The option value therefore MUST match the "scheme" rule 1807 defined in Section 3.1 of RFC 3986. 1809 host.name 1810 Specifies the host of the IRI authority as a registered name. 1812 host.ip 1813 Specifies the host of the IRI authority as an IPv4 address 1814 (4 bytes) or an IPv6 address (16 bytes). 1816 port 1817 Specifies the port number. The option value MUST be an unsigned 1818 integer in the range 0 to 65535 (inclusive). 1820 path.type 1821 Specifies the type of the IRI path for reference resolution. 1822 Possible values are 0 (absolute-path), 1 (append-path), 2 1823 (relative-path), and 3 (append-relation). 1825 path 1826 Specifies one segment of the IRI path. This option can occur more 1827 than once. 1829 query 1830 Specifies one argument of the IRI query. This option can occur 1831 more than once. 1833 fragment 1834 Specifies the fragment identifier. 1836 The value of a "host.name", "path", "query", and "fragment" option 1837 can be any Unicode string. No percent-encoding is performed. 1839 C.3. Properties 1841 A sequence of options is considered _well-formed_ if: 1843 o the sequence of options is empty or starts with a "scheme", 1844 "host.name", "host.ip", "port", "path.type", "path", "query", or 1845 "fragment" option; 1847 o a "scheme" option is followed by either a "host.name" or a 1848 "host.ip" option; 1850 o a "host.name" option is followed by a "port" option; 1852 o a "host.ip" option is followed by a "port" option; 1854 o a "port" option is followed by a "path", "query", or "fragment" 1855 option or is at the end of the sequence; 1857 o a "path.type" option is followed by a "path", "query", or 1858 "fragment" option or is at the end of the sequence; 1860 o a "path" option is followed by a "path", "query", or "fragment" 1861 option or is at the end of the sequence; 1863 o a "query" option is followed by a "query" or "fragment" option or 1864 is at the end of the sequence; and 1866 o a "fragment" option is at the end of the sequence. 1868 A well-formed sequence of options is considered _absolute_ if the 1869 sequence of options starts with a "scheme" option. A well-formed 1870 sequence of options is considered _relative_ if the sequence of 1871 options is empty or starts with an option other than the "scheme" 1872 option. 1874 An absolute sequence of options is considered _normalized_ if the 1875 result of resolving the sequence of options against any base IRI 1876 reference is equal to the input. (It doesn't matter what it is 1877 resolved against, since it is already absolute.) 1879 C.4. Reference Resolution 1881 This section defines how to resolve a CBOR-encoded IRI reference that 1882 might be relative to a given base IRI. 1884 Applications MUST resolve a well-formed sequence of options `href` 1885 against an absolute sequence of options `base` by using an algorithm 1886 that is functionally equivalent to the following Python 3.5 code. 1888 1890 def resolve(base, href, relation=None): 1891 if not is_absolute(base) or not is_well_formed(href): 1892 return None 1893 result = [] 1894 type = PathType.RELATIVE_PATH 1895 (option, value) = href[0] 1896 if option == Option.HOST_IP: 1897 option = Option.HOST_NAME 1898 elif option == Option.PATH_TYPE: 1899 href = href[1:] 1900 type = value 1901 option = Option.PATH 1902 if option != Option.PATH or type == PathType.ABSOLUTE_PATH: 1903 _copy_until(base, result, option) 1904 else: 1905 _copy_until(base, result, Option.QUERY) 1906 if type == PathType.APPEND_RELATION: 1907 _append_and_normalize(result, Option.PATH, 1908 format(relation, "x")) 1909 return result 1910 if type == PathType.RELATIVE_PATH: 1911 _remove_last_path_segment(result) 1912 _copy_until(href, result, Option.END) 1913 _append_and_normalize(href, Option.END, None) 1914 return result 1916 def _copy_until(input, output, end): 1917 for (option, value) in input: 1918 if option >= end: 1919 break 1920 _append_and_normalize(output, option, value) 1922 def _append_and_normalize(output, option, value): 1923 if option == Option.PATH: 1924 if value == ".": 1925 return 1926 if value == "..": 1928 _remove_last_path_segment(output) 1929 return 1930 elif option > Option.PATH: 1931 if len(output) >= 2 and \ 1932 output[-1] == (Option.PATH, "") and \ 1933 (output[-2][0] < Option.PATH_TYPE or \ 1934 output[-2] == (Option.PATH_TYPE, PathType.ABSOLUTE_PATH)): 1935 _remove_last_path_segment(output) 1936 if option >= Option.END: 1937 return 1938 output.append((option, value)) 1940 def _remove_last_path_segment(output): 1941 if len(output) >= 1 and output[-1][0] == Option.PATH: 1942 del output[-1] 1944 1946 C.5. IRI Recomposition 1948 This section defines how to recompose an IRI from a sequence of 1949 options that encodes an absolute IRI reference. 1951 Applications MUST recompose an IRI from a sequence of options by 1952 using an algorithm that is functionally equivalent to the following 1953 Python 3.5 code. 1955 To reduce variability, the hexadecimal notation when percent-encoding 1956 octets SHOULD use uppercase letters. The text representation of IPv6 1957 addresses SHOULD follow the recommendations in Section 4 of RFC 5952 1958 [RFC5952]. 1960 1962 def recompose(href): 1963 if not is_absolute(href): 1964 return None 1965 result = "" 1966 no_path = True 1967 first_query = True 1968 for (option, value) in href: 1969 if option == Option.SCHEME: 1970 result += value + ":" 1971 elif option == Option.HOST_NAME: 1972 result += "//" + _encode_ireg_name(value) 1973 elif option == Option.HOST_IP: 1974 result += "//" + _encode_ip_address(value) 1975 elif option == Option.PORT: 1977 result += ":" + str(value) 1978 elif option == Option.PATH: 1979 result += "/" + _encode_path_segment(value) 1980 no_path = False 1981 elif option == Option.QUERY: 1982 if no_path: 1983 result += "/" 1984 no_path = False 1985 result += "?" if first_query else "&" 1986 result += _encode_query_argument(value) 1987 first_query = False 1988 elif option == Option.FRAGMENT: 1989 if no_path: 1990 result += "/" 1991 no_path = False 1992 result += "#" + _encode_fragment(value) 1993 if no_path: 1994 result += "/" 1995 no_path = False 1996 return result 1998 def _encode_ireg_name(s): 1999 return "".join(c if _is_ireg_name_char(c) else 2000 _encode_pct(c) for c in s) 2002 def _encode_ip_address(b): 2003 if len(b) == 4: 2004 return ".".join(str(c) for c in b) 2005 elif len(b) == 16: 2006 return "[" + ... + "]" # see RFC 5952 2008 def _encode_path_segment(s): 2009 return "".join(c if _is_isegment_char(c) else 2010 _encode_pct(c) for c in s) 2012 def _encode_query_argument(s): 2013 return "".join(c if _is_iquery_char(c) and c != "&" else 2014 _encode_pct(c) for c in s) 2016 def _encode_fragment(s): 2017 return "".join(c if _is_ifragment_char(c) else 2018 _encode_pct(c) for c in s) 2020 def _encode_pct(s): 2021 return "".join( 2022 "%{0:0>2X}".format(c) for c in s.encode("utf-8")) 2024 def _is_ireg_name_char(c): 2026 return _is_iunreserved(c) or _is_sub_delim(c) 2028 def _is_isegment_char(c): 2029 return _is_ipchar(c) 2031 def _is_iquery_char(c): 2032 return _is_ipchar(c) or _is_iprivate(c) or c == "/" or c == "?" 2034 def _is_ifragment_char(c): 2035 return _is_ipchar(c) or c == "/" or c == "?" 2037 def _is_ipchar(c): 2038 return _is_iunreserved(c) or _is_sub_delim(c) or \ 2039 c == ":" or c == "@" 2041 def _is_iunreserved(c): 2042 return _is_alpha(c) or _is_digit(c) or \ 2043 c == "-" or c == "." or c == "_" or c == "~" or \ 2044 _is_ucschar(c) 2046 def _is_alpha(c): 2047 return c >= "A" and c <= "Z" or c >= "a" and c <= "z" 2049 def _is_digit(c): 2050 return c >= "0" and c <= "9" 2052 def _is_sub_delim(c): 2053 return c == "!" or c == "$" or c == "&" or c == "'" or \ 2054 c == "(" or c == ")" or c == "*" or c == "+" or \ 2055 c == "," or c == ";" or c == "=" 2057 def _is_ucschar(c): 2058 return c >= "\U000000A0" and c <= "\U0000D7FF" or \ 2059 c >= "\U0000F900" and c <= "\U0000FDCF" or \ 2060 c >= "\U0000FDF0" and c <= "\U0000FFEF" or \ 2061 c >= "\U00010000" and c <= "\U0001FFFD" or \ 2062 c >= "\U00020000" and c <= "\U0002FFFD" or \ 2063 c >= "\U00030000" and c <= "\U0003FFFD" or \ 2064 c >= "\U00040000" and c <= "\U0004FFFD" or \ 2065 c >= "\U00050000" and c <= "\U0005FFFD" or \ 2066 c >= "\U00060000" and c <= "\U0006FFFD" or \ 2067 c >= "\U00070000" and c <= "\U0007FFFD" or \ 2068 c >= "\U00080000" and c <= "\U0008FFFD" or \ 2069 c >= "\U00090000" and c <= "\U0009FFFD" or \ 2070 c >= "\U000A0000" and c <= "\U000AFFFD" or \ 2071 c >= "\U000B0000" and c <= "\U000BFFFD" or \ 2072 c >= "\U000C0000" and c <= "\U000CFFFD" or \ 2073 c >= "\U000D0000" and c <= "\U000DFFFD" or \ 2074 c >= "\U000E1000" and c <= "\U000EFFFD" 2076 def _is_iprivate(c): 2077 return c >= "\U0000E000" and c <= "\U0000F8FF" or \ 2078 c >= "\U000F0000" and c <= "\U000FFFFD" or \ 2079 c >= "\U00100000" and c <= "\U0010FFFD" 2081 2083 C.6. CoAP Encoding 2085 This section defines how to construct CoAP options from an absolute, 2086 normalized, CBOR-encoded IRI Reference. 2088 Applications MUST construct CoAP options by recomposing the sequence 2089 of options to an IRI (Appendix C.5 of this document), mapping the IRI 2090 to an URI (Section 3.1 of RFC 3987), and decomposing the URI into 2091 CoAP options (Section 6.4 of RFC 7252). 2093 The following illustrative Python 3.5 code is roughly equivalent to 2094 this. 2096 2098 def coap(href, to_proxy=False): 2099 if not is_absolute(href): 2100 return None 2101 result = b"" 2102 previous = 0 2103 for (option, value) in href: 2104 if option == Option.SCHEME: 2105 pass 2106 elif option == Option.HOST_NAME: 2107 opt = 3 # Uri-Host 2108 val = value.encode("utf-8") 2109 result += _encode_coap_option(opt - previous, val) 2110 previous = opt 2111 elif option == Option.HOST_IP: 2112 opt = 3 # Uri-Host 2113 if len(value) == 4: 2114 val = ".".join(str(c) for c in b).encode("utf-8") 2115 elif len(value) == 16: 2116 val = b"[" + ... + b"]" # see RFC 5952 2117 result += _encode_coap_option(opt - previous, val) 2118 previous = opt 2119 elif option == Option.PORT: 2120 opt = 7 # Uri-Port 2121 val = value.to_bytes((value.bit_length() + 7) // 8, "big") 2122 result += _encode_coap_option(opt - previous, val) 2123 previous = opt 2124 elif option == Option.PATH: 2125 opt = 11 # Uri-Path 2126 val = value.encode("utf-8") 2127 result += _encode_coap_option(opt - previous, val) 2128 previous = opt 2129 elif option == Option.QUERY: 2130 opt = 15 # Uri-Query 2131 val = value.encode("utf-8") 2132 result += _encode_coap_option(opt - previous, val) 2133 previous = opt 2134 elif option == Option.FRAGMENT: 2135 pass 2136 if to_proxy: 2137 (option, value) = href[0] 2138 opt = 39 # Proxy-Scheme 2139 val = value.encode("utf-8") 2140 result += _encode_coap_option(opt - previous, val) 2141 previous = opt 2142 return result 2144 def _encode_coap_option(delta, value): 2145 length = len(value) 2146 delta_nibble = _encode_coap_option_nibble(delta) 2147 length_nibble = _encode_coap_option_nibble(length) 2148 result = bytes([delta_nibble << 4 | length_nibble]) 2149 if delta_nibble == 13: 2150 delta -= 13 2151 result += bytes([delta]) 2152 elif delta_nibble == 14: 2153 delta -= 256 + 13 2154 result += bytes([delta >> 8, delta & 255]) 2155 if length_nibble == 13: 2156 length -= 13 2157 result += bytes([length]) 2158 elif length_nibble == 14: 2159 length -= 256 + 13 2160 result += bytes([length >> 8, length & 255]) 2161 result += value 2162 return result 2164 def _encode_coap_option_nibble(n): 2165 if n < 13: 2166 return n 2167 elif n < 256 + 13: 2168 return 13 2169 elif n < 65536 + 256 + 13: 2171 return 14 2173 2175 Author's Address 2177 Klaus Hartke 2178 Universitaet Bremen TZI 2179 Postfach 330440 2180 Bremen D-28359 2181 Germany 2183 Phone: +49-421-218-63905 2184 Email: hartke@tzi.org