idnits 2.17.1 draft-hartke-t2trg-coral-05.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 == Line 1340 has weird spacing: '...ttr:obs true...' -- The document date (April 25, 2018) is 2194 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 654 -- Looks like a reference, but probably isn't: '5' on line 657 -- Looks like a reference, but probably isn't: '6' on line 660 -- Looks like a reference, but probably isn't: '7' on line 661 == Missing Reference: 'I-D.hartke-t2trg-coral' is mentioned on line 1555, but not defined == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-02 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) -- 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 (==), 10 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 April 25, 2018 5 Expires: October 27, 2018 7 The Constrained RESTful Application Language (CoRAL) 8 draft-hartke-t2trg-coral-05 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 https://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 October 27, 2018. 35 Copyright Notice 37 Copyright (c) 2018 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 (https://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. Representations . . . . . . . . . . . . . . . . . . . . . 9 64 3.7. Navigation . . . . . . . . . . . . . . . . . . . . . . . 10 65 3.8. History Traversal . . . . . . . . . . . . . . . . . . . . 11 66 4. Binary Format . . . . . . . . . . . . . . . . . . . . . . . . 11 67 4.1. Data Structure . . . . . . . . . . . . . . . . . . . . . 11 68 4.1.1. Documents . . . . . . . . . . . . . . . . . . . . . . 12 69 4.1.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 12 70 4.1.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 13 71 4.1.4. Representations . . . . . . . . . . . . . . . . . . . 15 72 4.1.5. Directives . . . . . . . . . . . . . . . . . . . . . 15 73 5. Textual Format . . . . . . . . . . . . . . . . . . . . . . . 15 74 5.1. Lexical Structure . . . . . . . . . . . . . . . . . . . . 16 75 5.1.1. Line Terminators . . . . . . . . . . . . . . . . . . 16 76 5.1.2. White Space . . . . . . . . . . . . . . . . . . . . . 16 77 5.1.3. Comments . . . . . . . . . . . . . . . . . . . . . . 16 78 5.1.4. Identifiers . . . . . . . . . . . . . . . . . . . . . 17 79 5.1.5. IRI References . . . . . . . . . . . . . . . . . . . 17 80 5.1.6. Literals . . . . . . . . . . . . . . . . . . . . . . 17 81 5.1.7. Punctuators . . . . . . . . . . . . . . . . . . . . . 20 82 5.2. Syntactic Structure . . . . . . . . . . . . . . . . . . . 21 83 5.2.1. Documents . . . . . . . . . . . . . . . . . . . . . . 21 84 5.2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 21 85 5.2.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 22 86 5.2.4. Representations . . . . . . . . . . . . . . . . . . . 23 87 5.2.5. Directives . . . . . . . . . . . . . . . . . . . . . 24 88 6. Usage Considerations . . . . . . . . . . . . . . . . . . . . 25 89 6.1. Specifying CoRAL-based Applications . . . . . . . . . . . 25 90 6.1.1. Naming Resources . . . . . . . . . . . . . . . . . . 26 91 6.1.2. Implementation Limits . . . . . . . . . . . . . . . . 26 92 6.2. Minting New Relation Types . . . . . . . . . . . . . . . 27 93 6.3. Registering Relation Types . . . . . . . . . . . . . . . 27 94 6.4. Expressing Link Target Attributes . . . . . . . . . . . . 28 95 6.5. Embedding CoRAL in CBOR Structures . . . . . . . . . . . 29 96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 29 97 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 98 8.1. Media Type "application/coral+cbor" . . . . . . . . . . . 31 99 8.2. Media Type "text/coral" . . . . . . . . . . . . . . . . . 32 100 8.3. CoAP Content Formats . . . . . . . . . . . . . . . . . . 33 101 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 102 9.1. Normative References . . . . . . . . . . . . . . . . . . 33 103 9.2. Informative References . . . . . . . . . . . . . . . . . 35 104 Appendix A. Core Vocabulary . . . . . . . . . . . . . . . . . . 37 105 A.1. Link Relation Types . . . . . . . . . . . . . . . . . . . 37 106 A.2. Form Relation Types . . . . . . . . . . . . . . . . . . . 38 107 A.3. Form Field Names . . . . . . . . . . . . . . . . . . . . 38 108 Appendix B. Default Profile . . . . . . . . . . . . . . . . . . 39 109 Appendix C. CBOR-encoded IRI References . . . . . . . . . . . . 39 110 C.1. Data Structure . . . . . . . . . . . . . . . . . . . . . 40 111 C.2. Options . . . . . . . . . . . . . . . . . . . . . . . . . 40 112 C.3. Properties . . . . . . . . . . . . . . . . . . . . . . . 41 113 C.4. Reference Resolution . . . . . . . . . . . . . . . . . . 42 114 C.5. IRI Recomposition . . . . . . . . . . . . . . . . . . . . 43 115 C.6. CoAP Encoding . . . . . . . . . . . . . . . . . . . . . . 46 116 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 48 118 1. Introduction 120 The Constrained RESTful Application Language (CoRAL) is a language 121 for the description of typed connections between resources on the Web 122 ("links"), possible operations on such resources ("forms"), as well 123 as simple resource metadata. 125 CoRAL is intended for driving automated software agents that navigate 126 a Web application based on a standardized vocabulary of link and form 127 relation types. It is designed to be used in conjunction with a Web 128 transfer protocol such as the Hypertext Transfer Protocol (HTTP) 129 [RFC7230] or the Constrained Application Protocol (CoAP) [RFC7252]. 131 This document defines the CoRAL data and interaction model, as well 132 as two specialized CoRAL serialization formats. 134 The CoRAL data and interaction model is a superset of the Web Linking 135 model described in RFC 8288 [RFC8288]. The CoRAL data model consists 136 of two elements: _links_ that describe the relationships between 137 pairs of resources and the type of those relationships, and _forms_ 138 that describe possible operations on resources and the type of those 139 operations. In addition, the data model can describe simple resource 140 metadata in a way similar to the Resource Description Framework (RDF) 141 [W3C.REC-rdf11-concepts-20140225]. However, in contrast to RDF, the 142 focus of CoRAL is on the interaction with resources, not just on the 143 relationships between them. The CoRAL interaction model derives from 144 HTML 5 [W3C.REC-html52-20171214] and specifies how an automated 145 software agent can navigate between resources by following links and 146 perform operations on resources by submitting forms. 148 The primary CoRAL serialization format is a compact, binary encoding 149 of links and forms in Concise Binary Object Representation (CBOR) 150 [RFC7049]. It is intended for environments with constraints on 151 power, memory, and processing resources [RFC7228], and shares many 152 similarities with the message format of the Constrained Application 153 Protocol (CoAP) [RFC7252]: It uses numeric identifiers instead of 154 verbose strings for link and form relation types, and pre-parses URIs 155 into (what CoAP considers to be) their components, which simplifies 156 URI processing greatly. As a result, link serializations are often 157 much more compact than equivalent serializations in CoRE Link Format 158 [RFC6690], including its CBOR variant [I-D.ietf-core-links-json]. 159 Additionally, CoRAL supports the serialization of forms, which CoRE 160 Link Format does not support. 162 The secondary CoRAL serialization format is a lightweight, textual 163 encoding of links and forms that is intended to be easy to read and 164 write by humans. The format is loosely inspired by the syntax of 165 Turtle [W3C.REC-turtle-20140225] and is used for giving examples 166 throughout the document. 168 1.1. Requirements Notation 170 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 171 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 172 "OPTIONAL" in this document are to be interpreted as described in BCP 173 14 [RFC2119] [RFC8174] when, and only when, they appear in all 174 capitals, as shown here. 176 2. Examples 178 2.1. Web Linking 180 At its core, CoRAL is just yet another serialization format for Web 181 links. For example, if an HTTP client sends the following request: 183 GET /TheBook/chapter3 HTTP/1.1 184 Host: example.com 186 and receives the following response: 188 HTTP/1.1 200 OK 189 Content-Type: text/coral 191 #using 193 next <./chapter4> 194 icon 195 license 197 then the representation contains the following three links: 199 o one link of type "http://www.iana.org/assignments/relation/next" 200 from to 201 , 203 o one link of type "http://www.iana.org/assignments/relation/icon" 204 from to , and 207 o one link of type "http://www.iana.org/assignments/relation/ 208 license" from to 209 . 211 This representation is equivalent to the following Link header field 212 [RFC8288]: 214 Link: <./chapter4>; rel="next", 215 ; rel="icon", 216 ; rel="license" 218 and the following HTML 5 [W3C.REC-html52-20171214] link elements: 220 221 222 225 2.2. Links, Forms, and Metadata 227 In its entirety, CoRAL is an expressive language for describing Web 228 links between resources, possible operations on these resources, and 229 simple resource metadata. For example, if an HTTP client sends the 230 following request: 232 GET /tasks HTTP/1.1 233 Host: example.com 235 and receives the following response: 237 HTTP/1.1 200 OK 238 Content-Type: text/coral 240 #using 241 #using coral = 243 task { 244 description "Pick up the kids" 245 } 247 task { 248 description "Return the books to the library" 249 coral:delete -> DELETE 250 } 252 coral:create -> POST [coral:accept "example/task"] 254 then the representation contains the following six elements: 256 o one link of type "http://example.org/vocabulary#task" from 257 to , 259 o one link of type "http://example.org/vocabulary#description" from 260 to "Pick up the kids", 262 o one link of type "http://example.org/vocabulary#task" from 263 to , 265 o one link of type "http://example.org/vocabulary#description" from 266 to "Return the books to the library", 268 o one form of type "urn:ietf:rfc:XXXX#delete" that can be used to 269 delete by making a DELETE request to 270 , and 272 o one form of type "urn:ietf:rfc:XXXX#create" that can be used to 273 create a new item in by making a POST 274 request to with an "example/task" 275 payload. 277 3. Data and Interaction Model 279 The Constrained RESTful Application Language (CoRAL) is designed for 280 building Web-based applications [W3C.REC-webarch-20041215] in which 281 automated software agents navigate between resources by following 282 links and perform operations on resources by submitting forms. 284 3.1. Browsing Context 286 Borrowing from HTML 5 [W3C.REC-html52-20171214], each such agent 287 maintains a _browsing context_ in which the representations of Web 288 resources are processed. (In HTML 5, the browsing context typically 289 corresponds to a tab or window in a Web browser.) 291 A browsing context has a _session history_ that lists the resource 292 representations that the agent has processed, is processing, or will 293 process. At any time, one representation in each browsing context is 294 designated the _active_ representation. 296 A session history consists of a flat list of session history entries. 297 Each _session history entry_ consists of a resource representation 298 and the Internationalized Resource Identifier (IRI) [RFC3987] that 299 was used to retrieve the representation. An entry can additionally 300 have other information associated with it. New entries are added to 301 the session history as the agent navigates from resource to resource. 303 3.2. Documents 305 A resource representation in one of the CoRAL serialization formats 306 is called a CoRAL _document_. The IRI that was used to retrieve such 307 a document is called the document's _retrieval context_. 309 A CoRAL document consists of a list of zero or more links, forms, and 310 embedded resource representations, collectively called _elements_. 311 CoRAL serialization formats may define additional types of elements 312 for efficiency or convenience, such as base IRIs for relative IRI 313 references. 315 3.3. Links 317 A _link_ describes a relationship between two resources on the Web 318 [RFC8288]. As defined in RFC 8288, it consists of a _link context_, 319 a _link relation type_, and a _link target_. A link can additionally 320 have a nested list of zero or more elements, which takes the place of 321 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 target 325 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 the RFC 8288 Link header field, a link relation type is typically 329 denoted by a registered name, such as "stylesheet" or "icon". In 330 CoRAL, a link relation type is denoted in contrast by an IRI or an 331 unsigned integer. IRIs on the one hand allow for the creation of 332 new, unique relation types in a decentralized fashion, but can incur 333 a high overhead in terms of message size. Small, unsigned integers 334 on the other hand minimize the overhead of link relation types in 335 constrained environments, but require the assignment of values by a 336 registry to avoid collisions. 338 The link context and the link target are both resources on the Web. 339 Resources are denoted in CoRAL either by an IRI reference [RFC3987] 340 or (similar to RDF) by a literal. If the IRI scheme indicates a Web 341 transfer protocol such as HTTP or CoAP, then an agent can dereference 342 the IRI and navigate the browsing context to the referenced resource; 343 this is called _following the link_. A literal directly identifies a 344 value, which in CoRAL can be a Boolean value, an integer, a floating- 345 point number, a byte string, or a text string. 347 A link can occur as a top-level element in a document or as a nested 348 element within a link. When a link occurs as a top-level element, 349 the link context is implicitly the document's retrieval context. 350 When a link occurs nested within a link, the link context of the 351 inner link is the link target of the outer link. 353 There are no restrictions on the cardinality of links; there can be 354 multiple links to and from a particular target, and multiple links of 355 the same or different types between a given link context and target. 356 However, the CoRAL data model constrains the description of a 357 resource graph to a tree: Links between linked resources can only be 358 described by further nesting links. 360 3.4. Forms 362 A _form_ provides instructions to an agent for performing an 363 operation on a Web resource. It consists of a _form context_, a 364 _form relation type_, a _request method_, and a _submission IRI_. 365 Additionally, a form may be accompanied by _form data_. 367 A form can be viewed as an instruction of the form "To perform a 368 _form relation type_ operation on _form context_, make a _request 369 method_ request to _submission IRI_" where the payload of the request 370 may be further described by form data. 372 The form relation type identifies the semantics of the operation. 373 Like a link relation type, it is denoted by an IRI or an unsigned 374 integer. 376 The form context is the resource on which an operation is ultimately 377 performed. To perform the operation, an agent needs to construct a 378 request with the specified request method and submission IRI. The 379 submission IRI typically refers to the form context, but MAY refer to 380 different resource. Constructing and sending the request is called 381 _submitting the form_. 383 If a form is accompanied by form data (Section 3.5), the agent MUST 384 also construct a payload that matches the specifications of the form 385 data and include it in the request when submitting the form. 387 A form can occur as a top-level element in a document or as a nested 388 element within a link. When a form occurs as a top-level element, 389 the form context is implicitly the document's retrieval context. 390 When a form occurs nested within a link, the form context is the link 391 target of the enclosing link. 393 3.5. Form Data 395 Form data provides instructions for agents to construct a request 396 payload. It consists of a list of zero or more _form fields_. Each 397 form field consists of a _form field name_ and a _form field value_. 399 Form fields can either directly identify data items that need to be 400 included in the request payload or reference another resource (such 401 as a schema) that describes the data items. Form fields may also 402 provide other information, such as acceptable representation formats. 404 The form field name identifies the semantics of the form field. Like 405 a link or form relation type, a form field name is denoted by an IRI 406 or an unsigned integer. 408 The form field value can be an IRI, a Boolean value, an integer, a 409 floating-point number, a byte string, or a text string. 411 3.6. Representations 413 If a representation links to many resources and an agent requires a 414 representation of each link target, it may be inefficient to retrieve 415 each representation individually. To alleviate this, CoRAL supports 416 the embedding of a _representation_ of a resource in a document. 418 An embedded representation consists of a sequence of bytes, plus 419 _representation metadata_ to describe those bytes. It may be a full, 420 partial, or inconsistent version of the representation served from 421 the IRI of the represented resource. 423 An embedded representation can occur as a top-level element in a 424 document or as a nested element within a link. When it occurs as a 425 top-level element, it provides an alternate representation of the 426 document's retrieval context. When it occurs nested within a link, 427 it provides a representation of link target of the enclosing link. 429 3.7. Navigation 431 An agent begins interacting with an application by performing a GET 432 request on an _entry point IRI_. The entry point IRI is the only IRI 433 an agent is expected to know before interacting with an application. 434 From there, the agent is expected to make all requests by following 435 links and submitting forms provided by the server in responses. The 436 entry point IRI can be obtained by manual configuration or through 437 some discovery process. 439 If dereferencing the entry point IRI yields a CoRAL document or any 440 other representation that implements the CoRAL data and interaction 441 model, then the agent proceeds as follows: 443 1. The first step for the agent is to decide what to do next, i.e., 444 which type of link to follow or form to submit, based on the link 445 relation types and form relation types it understands. 447 2. The agent finds the link(s) or form(s) with the given relation 448 type in the active representation. This may yield one or more 449 candidates, from which the agent must select the most appropriate 450 one in the next step. The set of candidates MAY be empty, for 451 example, if a transition is not supported or not allowed. 453 3. The agent selects one of the candidates based on the metadata 454 associated with the link(s) or form(s). Metadata typically 455 includes the media type of the target resource representation, 456 the IRI scheme, the request method, and other information that is 457 provided as nested elements in a link and form data in a form. 459 If the selected candidate contains an embedded representation, 460 then the agent MAY skip the following steps and immediately 461 proceed with step 8. 463 4. The agent resolves the IRI reference in the link or form as 464 specified in Section 5 of RFC 3986 [RFC3986] to obtain the 465 _request IRI_. Fragment identifiers are not part of the request 466 IRI and MUST be separated from the rest of the IRI prior to a 467 dereference. The request IRI may need to be converted to a URI 468 (Section 3.1 of RFC 3987 [RFC3987]) for protocols that do not 469 support IRIs. 471 5. The agent constructs a new request with the request IRI. If the 472 agent follows a link, the request method MUST be GET. If the 473 agent submits a form, the request method MUST be the one 474 specified in the form. The agent SHOULD set HTTP header fields 475 and CoAP request options according to provided metadata (e.g., 476 set the HTTP Accept header field or the CoAP Accept option when 477 the media type of the target resource is provided). In case of a 478 form with form data, the agent MUST include a request payload 479 that matches the specifications of the form data. 481 6. The agent sends the request and retrieves the response. 483 7. If a fragment identifier was separated from the request IRI, the 484 agent dereferences the fragment identifier within the retrieved 485 representation. 487 8. The agent _updates the session history_: It removes all the 488 entries in the browsing context's session history after the 489 current entry. Then it appends a new entry at the end of the 490 history representing the new resource. 492 9. Finally, the agent processes the representation. In case of a 493 CoRAL document or any other representation that implements the 494 CoRAL data and interaction model, this means the agent decides 495 again what to do next and the cycle repeats. 497 3.8. History Traversal 499 An agent can also navigate a browsing context by traversing the 500 browsing context's session history. An agent can _traverse the 501 session history_ by updating the active representation to the that 502 entry. 504 4. Binary Format 506 This section defines the encoding of documents in the CoRAL binary 507 format. 509 A document in the binary format is a data item in Concise Binary 510 Object Representation (CBOR) [RFC7049]. The structure of this data 511 item is presented in the Concise Data Definition Language (CDDL) 512 [I-D.ietf-cbor-cddl]. The media type is "application/coral+cbor". 514 4.1. Data Structure 516 The data structure of a document in the binary format is made up of 517 four kinds of elements: links, forms, embedded representations, and 518 (as an extension to the CoRAL data model) base IRI directives. Base 519 IRI directives provide a way to encode IRI references that have a 520 common base more efficiently. 522 Elements are processed in the order they appear in the document. 523 Document processors need to maintain an _environment_ while iterating 524 an array of elements. The environment consists of three variables: a 525 _current context IRI_, a _current base IRI_, and a _current relation 526 type_. The current context IRI and current base IRI are initially 527 both set to the document's retrieval context. The current relation 528 type is initially set to the unsigned integer zero. 530 4.1.1. Documents 532 The body of a document in the binary format is encoded as an array of 533 zero or more links, forms, embedded representations, and directives. 535 body = [*(link / form / representation / directive)] 537 4.1.2. Links 539 A link is encoded as an array that consists of the unsigned integer 540 2, followed by the link relation type and the link target, optionally 541 followed by a link body that contains nested elements. 543 link = [link: 2, relation, target, ?body] 545 The link relation type is encoded either as a text string containing 546 an absolute IRI reference or as an (unsigned or negative) integer 547 representing the difference to the current relation type. A link is 548 processed by updating the current relation type to the result of 549 adding the specified integer (or zero in the case of a text string) 550 to the current relation type. 552 relation = text / int 554 The link target is denoted by an IRI reference or represented by a 555 literal value. The IRI reference MAY be relative or absolute and 556 MUST be resolved against the current base IRI. The encoding of IRI 557 references in the binary format is described in Appendix C. The link 558 target MAY be null, which indicates that the link target is an 559 unidentified resource. 561 target = iri / literal / null 563 literal = bool / int / float / bytes / text 565 The array of elements in the link body (if any) MUST be processed in 566 a fresh environment. The current context IRI and current base IRI in 567 the new environment are initially both set to the link target of the 568 enclosing link. The current relation type in the new environment is 569 initially set to the current relation type. 571 4.1.3. Forms 573 A form is encoded as an array that consists of the unsigned integer 574 3, followed by the form relation type, the submission method, and a 575 submission IRI reference, optionally followed by form data. 577 form = [form: 3, relation, method, iri, ?form-data] 579 The form relation type is encoded and processed in the same way as a 580 link relation type (Section 4.1.2). 582 The method MUST refer to one of the request methods defined by the 583 Web transfer protocol identified by the scheme of the submission IRI. 584 It is encoded either as a text string or an unsigned integer. 586 method = text / uint 588 For HTTP [RFC7230], the method MUST be encoded as a text string in 589 the format defined in Section 4.1 of RFC 7231 [RFC7231]; the set of 590 possible values is maintained in the IANA HTTP Method Registry. For 591 CoAP [RFC7252], the method MUST be encoded as an unsigned integer 592 (e.g., the unsigned integer 2 for the POST method); the set of 593 possible values is maintained in the IANA CoAP Method Codes Registry. 595 The submission IRI reference MAY be relative or absolute and MUST be 596 resolved against the current base IRI. The encoding of IRI 597 references in the binary format is described in Appendix C. 599 4.1.3.1. Form Data 601 Form data is encoded as an array of zero or more name-value pairs. 603 form-data = [*(form-field-name, form-field-value)] 605 Form data (if any) MUST be processed in a fresh environment. The 606 current context IRI and current base IRI in the new environment are 607 initially both set to the submission IRI of the enclosing form. The 608 current relation type in the new environment is initially set to the 609 current relation type. 611 A form field name is encoded and processed in the same way as a link 612 relation type (Section 4.1.2). 614 form-field-name = text / uint 616 A form field value can be an IRI reference, a Boolean value, an 617 integer, a floating-point number, a byte string, a text string, or 618 null. An IRI reference MAY be relative or absolute and MUST be 619 resolved against the current base IRI. The encoding of IRI 620 references in the binary format is described in Appendix C. 622 form-field-value = iri / bool / int / float / bytes / text / null 624 4.1.3.2. Short Forms 626 Forms in certain shapes can be encoded in a more efficient manner 627 using short forms. The following short forms are available: 629 form /= [form.create: 4, ?accept: uint .size 2] 631 form /= [form.update: 5, ?accept: uint .size 2] 633 form /= [form.delete: 6] 635 form /= [form.search: 7, ?accept: uint .size 2] 637 If the scheme of the submission IRI indicates HTTP, the short forms 638 expand as follows: 640 [4] -> [3, "urn:ietf:rfc:XXXX#create", "POST", []] 641 [4, x] -> [3, "urn:ietf:rfc:XXXX#create", "POST", [], 642 ["urn:ietf:rfc:XXXX#accept", x]] 643 [5] -> [3, "urn:ietf:rfc:XXXX#update", "PUT", []] 644 [5, x] -> [3, "urn:ietf:rfc:XXXX#update", "PUT", [], 645 ["urn:ietf:rfc:XXXX#accept", x]] 646 [6] -> [3, "urn:ietf:rfc:XXXX#delete", "DELETE", []] 647 [7] -> [3, "urn:ietf:rfc:XXXX#search", "POST", []] 648 [7, x] -> [3, "urn:ietf:rfc:XXXX#search", "POST", [], 649 ["urn:ietf:rfc:XXXX#accept", x]] 651 If the scheme of the submission IRI indicates CoAP, the short forms 652 expand as follows: 654 [4] -> [3, "urn:ietf:rfc:XXXX#create", 2, []] 655 [4, x] -> [3, "urn:ietf:rfc:XXXX#create", 2, [], 656 ["urn:ietf:rfc:XXXX#accept", x]] 657 [5] -> [3, "urn:ietf:rfc:XXXX#update", 3, []] 658 [5, x] -> [3, "urn:ietf:rfc:XXXX#update", 3, [], 659 ["urn:ietf:rfc:XXXX#accept", x]] 660 [6] -> [3, "urn:ietf:rfc:XXXX#delete", 4, []] 661 [7] -> [3, "urn:ietf:rfc:XXXX#create", 5, []] 662 [7, x] -> [3, "urn:ietf:rfc:XXXX#create", 5, [], 663 ["urn:ietf:rfc:XXXX#accept", x]] 665 The form relation types and form field names used in the above 666 expansions are defined in Appendix A. 668 4.1.4. Representations 670 An embedded representation is encoded as an array that consists of 671 the unsigned integer 0, followed by the HTTP content type or CoAP 672 content format of the representation and a byte string containing the 673 representation data. 675 representation = [representation: 0, text / uint, bytes] 677 For HTTP, the content type MUST be specified as a text string in the 678 format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the set of 679 possible values is maintained in the IANA Media Types Registry. For 680 CoAP, the content format MUST be specified as an unsigned integer; 681 the set of possible values is maintained in the IANA CoAP Content- 682 Formats Registry. 684 4.1.5. Directives 686 Directives provide the ability to manipulate the environment when 687 processing a list of elements. There is one directive available: the 688 Base URI directive. 690 directive = base-directive 692 4.1.5.1. Base URI Directives 694 A Base IRI directive is encoded as an array that consists of the 695 unsigned integer 1, followed by an IRI reference. 697 base-directive = [base: 1, iri] 699 The IRI reference MAY be relative or absolute and MUST be resolved 700 against the current context IRI. The encoding of IRI references in 701 the binary format is described in Appendix C. 703 The directive is processed by resolving the IRI reference against the 704 current context IRI and assigning the result to the current base IRI. 706 5. Textual Format 708 This section defines the syntax of documents in the CoRAL textual 709 format using two grammars: The lexical grammar defines how Unicode 710 characters are combined to form line terminators, white space, 711 comments, and tokens. The syntactic grammar defines how the tokens 712 are combined to form documents. Both grammars are presented in 713 Augmented Backus-Naur Form (ABNF) [RFC5234]. 715 A document in the textual format is a Unicode string in a Unicode 716 encoding form [UNICODE]. The media type for such documents is "text/ 717 coral". The "charset" parameter is not used; charset information is 718 transported inside the document in the form of an OPTIONAL Byte Order 719 Mark (BOM). The use of the UTF-8 encoding scheme [RFC3629], without 720 a BOM, is RECOMMENDED. 722 5.1. Lexical Structure 724 The lexical structure of a document in the textual format is made up 725 of four basic elements: line terminators, white space, comments, and 726 tokens. Of these, only tokens are significant in the syntactic 727 grammar. There are four kinds of tokens: identifiers, IRI 728 references, literals, and punctuators. 730 When several lexical grammar rules match a sequence of characters in 731 a document, the longest match takes priority. 733 5.1.1. Line Terminators 735 Line terminators divide text into lines. A line terminator is any 736 Unicode character with Line_Break class BK, CR, LF, or NL. However, 737 any CR character that immediately precedes a LF character is ignored. 738 (This affects only the numbering of lines in error messages.) 740 5.1.2. White Space 742 White space is a sequence of one or more white space characters. A 743 white space character is any Unicode character with the White_Space 744 property. 746 5.1.3. Comments 748 Comments are sequences of characters that are ignored when parsing 749 text into tokens. Single-line comments begin with the characters 750 "//" and extend to the end of the line. Delimited comments begin 751 with the characters "/*" and end with the characters "*/". Delimited 752 comments can occupy a portion of a line, a single line, or multiple 753 lines. 755 Comments do not nest. The character sequences "/*" and "*/" have no 756 special meaning within a single-line comment; the character sequences 757 "//" and "/*" have no special meaning within a delimited comment. 759 5.1.4. Identifiers 761 An identifier tokens is a user-defined symbolic name. The rules for 762 identifiers correspond to those recommended by the Unicode Standard 763 Annex #31 [UNICODE-UAX31] using the following profile: 765 identifier = start *continue *(medial 1*continue) 767 start = 769 continue = 771 medial = "-" / "." / "~" / %xB7 / %x58A / %xF0B 773 medial =/ %x2010 / %x2027 / %x30A0 / %x30FB 775 All identifiers MUST be converted into Unicode Normalization Form C 776 (NFC), as defined by the Unicode Standard Annex #15 [UNICODE-UAX15]. 777 Comparison of identifiers is based on NFC and is case-sensitive 778 (unless otherwise noted). 780 5.1.5. IRI References 782 An IRI reference is a Unicode string that conforms to the syntax 783 defined in RFC 3987 [RFC3987]. An IRI reference can be absolute or 784 relative and can contain a fragment identifier. IRI references are 785 enclosed in angle brackets ("<" and ">"). 787 iri = "<" IRI-reference ">" 789 IRI-reference = 791 5.1.6. Literals 793 A literal is a textual representation of a value. There are six 794 types of literals: Boolean, integer, floating-point, byte string, 795 text string, and null. 797 5.1.6.1. Boolean Literals 799 The case-insensitive tokens "true" and "false" denote the Boolean 800 values true and false, respectively. 802 boolean = "true" / "false" 804 5.1.6.2. Integer Literals 806 Integer literals denote integer values of unspecified precision. By 807 default, integer literals are expressed in decimal, but they can also 808 be specified in an alternate base using a prefix. Binary literals 809 begin with "0b", octal literals begin with "0o", and hexadecimal 810 literals begin with "0x". 812 Decimal literals contain the digits "0" through "9". Binary literals 813 contain "0" and "1", octal literals contain "0" through "7", and 814 hexadecimal literals contain "0" through "9" as well as "A" through 815 "F" in upper- or lowercase. 817 Negative integers are expressed by prepending a minus sign ("-"). 819 integer = ["+" / "-"] (decimal / binary / octal / hexadecimal) 821 decimal = 1*DIGIT 823 binary = %x30 (%x42 / %x62) 1*BINDIG 825 octal = %x30 (%x4F / %x6F) 1*OCTDIG 827 hexadecimal = %x30 (%x58 / %x78) 1*HEXDIG 829 DIGIT = %x30-39 831 BINDIG = %x30-31 833 OCTDIG = %x30-37 835 HEXDIG = %x30-39 / %x41-46 / %x61-66 837 5.1.6.3. Floating-point Literals 839 Floating-point literals denote floating-point numbers of unspecified 840 precision. 842 Floating-point literals consist of a sequence of decimal digits 843 followed by a fraction, an exponent, or both. The fraction consists 844 of a decimal point (".") followed by a sequence of decimal digits. 845 The exponent consists of the letter "e" in upper- or lowercase, 846 followed by an optional sign and a sequence of decimal digits that 847 indicate a power of 10 by which the value preceding the "e" is 848 multiplied. 850 Negative floating-point values are expressed by prepending a minus 851 sign ("-"). 853 floating-point = ["+" / "-"] 1*DIGIT [fraction] [exponent] 855 fraction = "." 1*DIGIT 857 exponent = (%x45 / %x65) ["+" / "-"] 1*DIGIT 859 Floating-point literals can additionally denote the special "Not- 860 a-Number" (NaN) value, positive infinity, and negative infinity. The 861 NaN value is produced by the case-insensitive token "NaN". The two 862 infinite values are produced by the case-insensitive tokens 863 "+Infinity" (or simply "Infinity") and "-Infinity". 865 floating-point =/ "NaN" 867 floating-point =/ ["+" / "-"] "Infinity" 869 5.1.6.4. Byte String Literals 871 A byte string literal consists of a prefix and zero or more bytes 872 encoded in Base16, Base32, or Base64 [RFC4648] and enclosed in single 873 quotes. Byte string literals encoded in Base16 begin with "h" or 874 "b16", byte string literals encoded in Base32 begin with "b32", and 875 byte string literals encoded in Base64 begin with "b64". 877 bytes = base16 / base32 / base64 879 base16 = (%x68 / %x62.31.36) SQUOTE SQUOTE 881 base32 = %x62.33.32 SQUOTE SQUOTE 883 base64 = %x62.36.34 SQUOTE SQUOTE 885 SQUOTE = %x27 887 5.1.6.5. Text String Literals 889 A text string literal consists of zero or more Unicode characters 890 enclosed in double quotes. It can include simple escape sequences 891 (such as \t for the tab character) as well as hexadecimal and Unicode 892 escape sequences. 894 text = DQUOTE *(char / %x5C escape) DQUOTE 896 char = 898 escape = simple-escape / hexadecimal-escape / unicode-escape 900 simple-escape = %x30 / %x62 / %x74 / %x6E / %x76 901 simple-escape =/ %x66 / %x72 / %x22 / %x27 / %x5C 903 hexadecimal-escape = (%x78 / %x58) 2HEXDIG 905 unicode-escape = %x75 4HEXDIG / %x55 8HEXDIG 907 DQUOTE = %x22 909 An escape sequence denotes a single Unicode code point. For 910 hexadecimal and Unicode escape sequences, the code point is expressed 911 by the hexadecimal number following the "\x", "\X", "\u", or "\U" 912 prefix. Simple escape sequences indicate the code points listed in 913 Table 1. 915 +-----------------+------------+----------------------+ 916 | Escape Sequence | Code Point | Character Name | 917 +-----------------+------------+----------------------+ 918 | \0 | U+0000 | Null | 919 | \b | U+0008 | Backspace | 920 | \t | U+0009 | Character Tabulation | 921 | \n | U+000A | Line Feed | 922 | \v | U+000B | Line Tabulation | 923 | \f | U+000C | Form Feed | 924 | \r | U+000D | Carriage Return | 925 | \" | U+0022 | Quotation Mark | 926 | \' | U+0027 | Apostrophe | 927 | \\ | U+005C | Reverse Solidus | 928 +-----------------+------------+----------------------+ 930 Table 1: Simple Escape Sequences 932 5.1.6.6. Null Literal 934 The case-insensitive tokens "null" and "_" denote the intentional 935 absence of any value. 937 null = "null" / "_" 939 5.1.7. Punctuators 941 Punctuator tokens are used for grouping and separating. 943 punctuator = "#" | ":" | "*" | "[" | "]" | "{" | "}" | "=" | "->" 945 5.2. Syntactic Structure 947 The syntactic structure of a document in the textual format is made 948 up of four kinds of elements: links, forms, embedded representations, 949 and (as an extension to the CoRAL data model) directives. Directives 950 provide a way to make documents easier to read and write by defining 951 base IRIs for relative IRI references and introducing shorthands for 952 IRIs. 954 Elements are processed in the order they appear in the document. 955 Document processors need to maintain an _environment_ while iterating 956 a list of elements. The environment consists of three variables: a 957 _current context IRI_, a _current base IRI_, and a _current mapping 958 from identifiers to IRIs_. The current context IRI and current base 959 IRI are initially both set to the document's retrieval context. The 960 current mapping from identifiers to IRIs is initially empty. 962 5.2.1. Documents 964 The body of a document in the textual format consists of zero or more 965 links, forms, and directives. 967 body = *(link / form / representation / directive) 969 5.2.2. Links 971 A link consists of the link relation type, followed by the link 972 target, optionally followed by a link body enclosed in curly brackets 973 ("{" and "}"). 975 link = relation target ["{" body "}"] 977 The link relation type is denoted either by an absolute IRI 978 reference, a simple name, a qualified name, or an integer. 980 relation = iri / simple-name / qualified-name / integer 982 A simple name consists of an identifier. It is resolved to an IRI by 983 looking up the empty string in the current mapping from identifiers 984 to IRIs and appending the specified identifier to the result. It is 985 an error if the empty string is not present in the mapping. 987 simple-name = identifier 989 A qualified name consists of two identifiers separated by a colon 990 (":"). It is resolved to an IRI by looking up the identifier on the 991 left hand side in the current mapping from identifiers to IRIs and 992 appending the identifier on the right hand side to the result. It is 993 an error if the identifier on the left hand side is not present in 994 the mapping. 996 qualified-name = identifier ":" identifier 998 The link target is denoted by an IRI reference or represented by a 999 value literal. The IRI reference MAY be relative or absolute and 1000 MUST be resolved against the current base IRI. If the link target is 1001 null, the link target is an unidentified resource. 1003 target = iri / literal / null 1005 literal = boolean / integer / floating-point / bytes / text 1007 The list of elements in the link body (if any) MUST be processed in a 1008 fresh environment. The current context IRI and current base IRI in 1009 this environment are initially both set to the link target of the 1010 enclosing link. The mapping from identifiers to IRIs is initially 1011 set to a copy of the mapping from identifiers to IRIs in the current 1012 environment. 1014 5.2.3. Forms 1016 A form consists of the form relation type, followed by a "->" token, 1017 a method identifier, and a submission IRI reference, optionally 1018 followed by form data enclosed in square brackets ("[" and "]"). 1020 form = relation "->" method iri ["[" form-data "]"] 1022 The form relation type is denoted in the same way as a link relation 1023 type (Section 5.2.2). 1025 The method identifier refers to one of the request methods defined by 1026 the Web transfer protocol identified by the scheme of the submission 1027 IRI. Method identifiers are case-insensitive and constrained to 1028 Unicode characters in the Basic Latin block. 1030 method = identifier 1032 For HTTP [RFC7230], the set of possible method identifiers is 1033 maintained in the IANA HTTP Method Registry. For CoAP [RFC7252], the 1034 set of possible method identifiers is maintained in the IANA CoAP 1035 Method Codes Registry. 1037 The submission IRI reference MAY be relative or absolute and MUST be 1038 resolved against the current base IRI. 1040 5.2.3.1. Form Data 1042 Form data consists of zero or more name-value pairs. 1044 form-data = *(form-field-name form-field-value) 1046 Form data MUST be processed in a fresh environment. The current 1047 context IRI and current base IRI in this environment are initially 1048 both set to the submission IRI of the enclosing form. The mapping 1049 from identifiers to IRIs is initially set to a copy of the mapping 1050 from identifiers to IRIs in the current environment. 1052 The form field name is denoted in the same way as a link relation 1053 type (Section 5.2.2). 1055 form-field-name = iri / simple-name / qualified-name / integer 1057 The form field value can be an IRI reference, Boolean literal, 1058 integer literal, floating-point literal, byte string literal, text 1059 string literal, or null. An IRI reference MAY be relative or 1060 absolute and MUST be resolved against the current base IRI. 1062 form-field-value = iri / boolean / integer 1064 form-field-value =/ floating-point / bytes / text / null 1066 5.2.4. Representations 1068 An embedded representation consists of a "*" token, followed by the 1069 representation data, optionally followed by representation metadata 1070 enclosed in square brackets ("[" and "]"). 1072 representation = "*" bytes ["[" representation-metadata "]"] 1074 Representation metadata consists of zero or more name-value pairs. 1076 representation-metadata = *(metadata-name metadata-value) 1078 This document specifies only one kind of metadata item, labeled with 1079 the name "type": the HTTP content type or CoAP content format of the 1080 representation. 1082 metadata-name = "type" 1084 metadata-value = text / integer 1086 For HTTP, the content type MUST be specified as a text string in the 1087 format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the set of 1088 possible values is maintained in the IANA Media Types Registry. For 1089 CoAP, the content format MUST be specified as an integer; the set of 1090 possible values is maintained in the IANA CoAP Content-Formats 1091 Registry. 1093 A metadata item with the name "type" MUST NOT occur more than once. 1094 If absent, its value defaults to content type "application/octet- 1095 stream" or content format 42. 1097 5.2.5. Directives 1099 Directives provide the ability to manipulate the environment when 1100 processing a list of elements. All directives start with a number 1101 sign ("#") followed by a directive identifier. Directive identifiers 1102 are case-insensitive and constrained to Unicode characters in the 1103 Basic Latin block. 1105 The following directives are available: Base IRI directives and Using 1106 directives. 1108 directive = base-directive / using-directive 1110 5.2.5.1. Base IRI Directives 1112 A Base IRI directive consists of a number sign ("#"), followed by the 1113 case-insensitive identifier "base", followed by an IRI reference. 1115 base-directive = "#" "base" iri 1117 The IRI reference MAY be relative or absolute and MUST be resolved 1118 against the current context IRI. 1120 The directive is processed by resolving the IRI reference against the 1121 current context IRI and assigning the result to the current base IRI. 1123 5.2.5.2. Using Directives 1125 A Using directive consists of a number sign ("#"), followed by the 1126 case-insensitive identifier "using", optionally followed by an 1127 identifier and an equals sign ("="), finally followed by an absolute 1128 IRI reference. If the identifier is not specified, it is assumed to 1129 be the empty string. 1131 using-directive = "#" "using" [identifier "="] iri 1133 The IRI reference MUST be absolute. 1135 The directive is processed by adding the specified identifier and IRI 1136 to the current mapping from identifiers to IRIs. It is an error if 1137 the identifier is already present in the mapping. 1139 6. Usage Considerations 1141 This section discusses some considerations in creating CoRAL-based 1142 applications and managing link and form relation types. 1144 6.1. Specifying CoRAL-based Applications 1146 CoRAL-based applications naturally implement the Web architecture 1147 [W3C.REC-webarch-20041215] and thus are centered around orthogonal 1148 specifications for identification, interaction, and representation: 1150 o Resources are identified by IRIs or represented by value literals. 1152 o Interactions are based on the hypermedia interaction model of the 1153 Web and the methods provided by the Web transfer protocol. The 1154 semantics of possible interactions are identified by link and form 1155 relation types. 1157 o Representations are CoRAL documents encoded in the binary format 1158 defined in Section 4 or the textual format defined in Section 5. 1159 Depending on the application, additional representation formats 1160 can be used. 1162 Specifications for CoRAL-based applications need to list the specific 1163 components used in the application and their identifiers. This 1164 SHOULD include at least the following items: 1166 o IRI schemes that identify the Web transfer protocol(s) used in the 1167 application. 1169 o Internet media types that identify the representation format(s) 1170 used in the application, including the media type(s) of the CoRAL 1171 serialization format(s). 1173 o Link relation types that identify the semantics of links. 1175 o Form relation types that identify the semantics of forms. 1176 Additionally, for each form relation type, the permissible request 1177 method(s). 1179 o Form field names that identify the semantics of form fields. 1180 Additionally, for each form field name, the permissible form field 1181 value(s) or type(s). 1183 6.1.1. Naming Resources 1185 Resource names -- i.e., URIs [RFC3986] and IRIs [RFC3987] -- are a 1186 cornerstone of Web-based applications. They enable uniform 1187 identification of resources and are used every time a client 1188 interacts with a server or a resource representation needs to refer 1189 to another resource. 1191 URIs and IRIs often include structured application data in the path 1192 and query components, such as paths in a filesystem or keys in a 1193 database. It is a common practice in many HTTP-based applications to 1194 make this part of the application specification, i.e., they prescribe 1195 fixed URI templates that are hard-coded in implementations. However, 1196 there are a number of problems with this practice [RFC7320]. 1198 In CoRAL-based applications, resource names are not part of the 1199 application specification; they are an implementation detail. The 1200 specification of a CoRAL-based application MUST NOT mandate any 1201 particular form of resource name structure. BCP 190 [RFC7320] 1202 describes the problematic practice of fixed URI structures in more 1203 detail and provides some acceptable alternatives. 1205 6.1.2. Implementation Limits 1207 This document places no restrictions on the number of elements in a 1208 CoRAL document or the depth of nested elements. Applications using 1209 CoRAL (in particular those that run in constrained environments) MAY 1210 wish to limit these numbers and specify implementation limits that an 1211 application implementation MUST at least support to be interoperable. 1212 Implementation limits MAY also include the following as well as other 1213 items: 1215 o use of only either the binary format or the text format; 1217 o use of only either HTTP or CoAP as the Web transfer protocol; 1219 o use of only either IRIs or unsigned integers to denote link 1220 relation types, form relation types, and form field names; 1222 o use of only either short forms or long forms in the binary format; 1224 o use of only either HTTP content types or CoAP content formats; 1226 o use of IRI references only up to a specific length; 1228 o use of CBOR in a canonical format (Section 3.9 of RFC 7049 1229 [RFC7049]). 1231 6.2. Minting New Relation Types 1233 New link relation types, form relation types, and form field names 1234 can be minted by defining an IRI [RFC3987] that uniquely identifies 1235 the item. Although the IRI can point to a resource that contains a 1236 definition of the semantics of the relation type, clients SHOULD NOT 1237 automatically access that resource to avoid overburdening its server. 1238 The IRI SHOULD be under the control of the person or party defining 1239 it, or be delegated to them. 1241 Link relation types registered in the IANA Link Relations Registry, 1242 such as "collection" [RFC6573] or "icon" [W3C.REC-html52-20171214], 1243 can be used in CoRAL by appending the registered name to the IRI 1244 : 1246 #using iana = 1248 iana:collection 1249 iana:icon 1251 A good source for link relation types for resource metadata are RDF 1252 predicates [W3C.REC-rdf11-concepts-20140225]. An RDF statement says 1253 that some relationship, indicated by a predicate, holds between two 1254 resources. RDF predicates and link relation types can therefore 1255 often be used interchangeably. For example, a CoRAL document could 1256 describe its creator by using the FOAF vocabulary [FOAF]: 1258 #using iana = 1259 #using foaf = 1261 foaf:maker _ { 1262 iana:type 1263 foaf:familyName "Hartke" 1264 foaf:givenName "Klaus" 1265 foaf:mbox 1266 } 1268 6.3. Registering Relation Types 1270 IRIs that identify link relation types, form relation types, and form 1271 field names do not need to be registered. The inclusion of DNS names 1272 in IRIs allows for the decentralized creation of new IRIs without the 1273 risk of collisions. 1275 However, IRIs can be relatively verbose and impose a high overhead on 1276 representations. This can be a problem in constrained environments 1277 [RFC7228]. Therefore, CoRAL alternatively allows the use of unsigned 1278 integers to identify link relation types, form relation types, and 1279 form field names. These impose a much smaller overhead but instead 1280 need to be assigned by a registry to avoid collisions. 1282 This document does not create a registry for such integers. Instead, 1283 the media types for CoRAL documents in the binary and textual format 1284 are defined to have a "profile" parameter [RFC6906] that determines 1285 the registry in use. The registry is identified by a URI [RFC3986]. 1286 For example, a CoRAL document that uses the registry identified by 1287 the URI can use the following media 1288 type: 1290 application/coral+cbor; profile="http://example.com/registry" 1292 The URI serves only as an identifier; it does not necessarily have to 1293 be dereferencable (or even use a dereferencable URI scheme). It is 1294 permissible, though, to use a dereferencable URI and serve a 1295 representation that provides information about the registry in a 1296 human- or machine-readable way. (The format of such a representation 1297 is outside the scope of this document.) 1299 For simplicity, a CoRAL document can use unsigned integers from at 1300 most one registry. The "profile" parameter of the CoRAL media types 1301 MUST contain a single URI, not a white space separated list of URIs 1302 as recommended in RFC 6906 [RFC6906]. If the "profile" parameter is 1303 absent, the default profile specified in Appendix B is assumed. 1305 A CoRAL registry SHOULD map each unsigned integer to a full IRI that 1306 identifies a link relation type, form relation type, or form field 1307 name. The namespaces for these three kinds of identifiers are 1308 disjoint, i.e., the same integer MAY be assigned to a link relation 1309 type, form relation type, and form field name without ambiguity. 1310 Once an integer has been assigned, the assignment MUST NOT be changed 1311 or removed. A registry MAY provide additional information about an 1312 assignment (for example, whether a link relation type is deprecated). 1314 In CoAP [RFC7252], media types (including specific values for their 1315 parameters) are encoded as a small, unsigned integer called the 1316 content format. For use with CoAP, each CoRAL registry needs to 1317 register a new content format in the IANA CoAP Content-Formats 1318 Registry. Each such registered content format MUST specify a CoRAL 1319 media type with a "profile" parameter that contains the registry URI. 1321 6.4. Expressing Link Target Attributes 1323 Link target attributes defined for use with CoRE Link Format 1324 [RFC6690] (such as "type", "hreflang", "media", "ct", "rt", "if", 1325 "sz", and "obs") can be expressed in CoRAL by nesting links under the 1326 respective link and specifying the attribute name appended to the IRI 1327 as the link relation type. 1329 If the expressed link target attribute has a value, the target of the 1330 nested link MUST be a text string; otherwise, the target MUST be the 1331 Boolean value "true": 1333 #using iana = 1334 #using attr = 1336 iana:item { 1337 attr:type "application/json-patch+json" 1338 attr:ct "51" 1339 attr:sz "247" 1340 attr:obs true 1341 } 1343 [[NOTE TO RFC EDITOR: Please replace all occurrences of "http://TBD/" 1344 with a RFC-Editor-controlled IRI.]] 1346 Link target attributes that do not actually describe the link target 1347 but the link itself (such as "rel", "anchor", "rev", "title", and 1348 "title*") are excluded from this provision and MUST NOT occur in a 1349 CoRAL document. 1351 6.5. Embedding CoRAL in CBOR Structures 1353 Data items in the CoRAL binary format (Section 4) MAY be embedded in 1354 other CBOR [RFC7049] data structures. Specifications using CDDL 1355 [I-D.ietf-cbor-cddl] SHOULD reference the following CDDL definitions 1356 for this purpose: 1358 CoRAL-Body = body 1360 CoRAL-Link = link 1362 CoRAL-Form = form 1364 CoRAL-IRI = iri 1366 7. Security Considerations 1368 Parsers of CoRAL documents must operate on input that is assumed to 1369 be untrusted. This means that parsers MUST fail gracefully in the 1370 face of malicious inputs. Additionally, parsers MUST be prepared to 1371 deal with resource exhaustion (e.g., resulting from the allocation of 1372 big data items) or exhaustion of the stack depth (stack overflow). 1374 See Section 8 of RFC 7049 [RFC7049] for security considerations 1375 relating to parsing CBOR. 1377 Implementers of the CoRAL textual format need to consider the 1378 security aspects of handling Unicode input. See the Unicode Standard 1379 Annex #36 [UNICODE-UAX36] for security considerations relating to 1380 visual spoofing and misuse of character encodings. See Section 10 of 1381 RFC 3629 [RFC3629] for security considerations relating to UTF-8. 1383 CoRAL makes extensive use of IRIs and URIs. See Section 8 of RFC 1384 3987 [RFC3987] for security considerations relating to IRIs. See 1385 Section 7 of RFC 3986 [RFC3986] for security considerations relating 1386 to URIs. 1388 The security of applications using CoRAL can depend on the proper 1389 preparation and comparison of internationalized strings. For 1390 example, such strings can be used to make authentication and 1391 authorization decisions, and the security of an application could be 1392 compromised if an entity providing a given string is connected to the 1393 wrong account or online resource based on different interpretations 1394 of the string. See RFC 6943 [RFC6943] for security considerations 1395 relating to identifiers in IRIs and other locations. 1397 CoRAL is intended to be used in conjunction with a Web transfer 1398 protocol such as HTTP or CoAP. See Section 9 of RFC 7320 [RFC7230], 1399 Section 9 of RFC 7231 [RFC7231], etc. for security considerations 1400 relating to HTTP. See Section 11 of RFC 7252 [RFC7252] for security 1401 considerations relating to CoAP. 1403 CoRAL does not define any specific mechanisms for protecting the 1404 confidentiality and integrity of CoRAL documents. It relies on 1405 application layer or transport layer mechanisms for this, such as 1406 Transport Layer Security (TLS) [RFC5246]. 1408 CoRAL documents and the structure of a web of resources revealed from 1409 automatically following links can disclose personal information and 1410 other sensitive information. Implementations need to prevent the 1411 unintentional disclosure of such information. See Section of 9 of 1412 RFC 7231 [RFC7231] for additional considerations. 1414 Applications using CoRAL ought to consider the attack vectors opened 1415 by automatically following, trusting, or otherwise using links and 1416 forms in CoRAL documents. In particular, a server that is 1417 authoritative for the CoRAL representation of a resource may not 1418 necessarily be the authoritative source for nested links and forms. 1420 8. IANA Considerations 1422 8.1. Media Type "application/coral+cbor" 1424 This document registers the media type "application/coral+cbor" 1425 according to the procedures of BCP 13 [RFC6838]. 1427 Type name: 1428 application 1430 Subtype name: 1431 coral+cbor 1433 Required parameters: 1434 N/A 1436 Optional parameters: 1437 profile - See Section 6.3 of [I-D.hartke-t2trg-coral]. 1439 Encoding considerations: 1440 binary - See Section 4 of [I-D.hartke-t2trg-coral]. 1442 Security considerations: 1443 See Section 7 of [I-D.hartke-t2trg-coral]. 1445 Interoperability considerations: 1446 N/A 1448 Published specification: 1449 [I-D.hartke-t2trg-coral] 1451 Applications that use this media type: 1452 See Section 1 of [I-D.hartke-t2trg-coral]. 1454 Fragment identifier considerations: 1455 As specified for "application/cbor". 1457 Additional information: 1458 Deprecated alias names for this type: N/A 1459 Magic number(s): N/A 1460 File extension(s): N/A 1461 Macintosh file type code(s): N/A 1463 Person & email address to contact for further information: 1464 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1466 Intended usage: 1467 COMMON 1469 Restrictions on usage: 1470 N/A 1472 Author: 1473 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1475 Change controller: 1476 IESG 1478 Provisional registration? 1479 No 1481 8.2. Media Type "text/coral" 1483 This document registers the media type "text/coral" according to the 1484 procedures of BCP 13 [RFC6838] and guidelines in RFC 6657 [RFC6657]. 1486 Type name: 1487 text 1489 Subtype name: 1490 coral 1492 Required parameters: 1493 N/A 1495 Optional parameters: 1496 profile - See Section 6.3 of [I-D.hartke-t2trg-coral]. 1498 Encoding considerations: 1499 binary - See Section 5 of [I-D.hartke-t2trg-coral]. 1501 Security considerations: 1502 See Section 7 of [I-D.hartke-t2trg-coral]. 1504 Interoperability considerations: 1505 N/A 1507 Published specification: 1508 [I-D.hartke-t2trg-coral] 1510 Applications that use this media type: 1511 See Section 1 of [I-D.hartke-t2trg-coral]. 1513 Fragment identifier considerations: 1514 N/A 1516 Additional information: 1518 Deprecated alias names for this type: N/A 1519 Magic number(s): N/A 1520 File extension(s): .coral 1521 Macintosh file type code(s): TEXT 1523 Person & email address to contact for further information: 1524 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1526 Intended usage: 1527 COMMON 1529 Restrictions on usage: 1530 N/A 1532 Author: 1533 See the Author's Address section of [I-D.hartke-t2trg-coral]. 1535 Change controller: 1536 IESG 1538 Provisional registration? 1539 No 1541 8.3. CoAP Content Formats 1543 This document registers CoAP content formats for the media types 1544 "application/coral+cbor" and "text/coral" according to the procedures 1545 of RFC 7252 [RFC7252]. 1547 o Media Type: application/coral+cbor 1548 Content Coding: identity 1549 ID: TBD (maybe 63) 1550 Reference: [I-D.hartke-t2trg-coral] 1552 o Media Type: text/coral 1553 Content Coding: identity 1554 ID: TBD (maybe 10063) 1555 Reference: [I-D.hartke-t2trg-coral] 1557 9. References 1559 9.1. Normative References 1561 [I-D.ietf-cbor-cddl] 1562 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1563 definition language (CDDL): a notational convention to 1564 express CBOR data structures", draft-ietf-cbor-cddl-02 1565 (work in progress), February 2018. 1567 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1568 Requirement Levels", BCP 14, RFC 2119, 1569 DOI 10.17487/RFC2119, March 1997, 1570 . 1572 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1573 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1574 2003, . 1576 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1577 Resource Identifier (URI): Generic Syntax", STD 66, 1578 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1579 . 1581 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1582 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 1583 January 2005, . 1585 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1586 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1587 . 1589 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1590 Specifications: ABNF", STD 68, RFC 5234, 1591 DOI 10.17487/RFC5234, January 2008, 1592 . 1594 [RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding 1595 "charset" Parameter Handling in Textual Media Types", 1596 RFC 6657, DOI 10.17487/RFC6657, July 2012, 1597 . 1599 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1600 Specifications and Registration Procedures", BCP 13, 1601 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1602 . 1604 [RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for 1605 Security Purposes", RFC 6943, DOI 10.17487/RFC6943, May 1606 2013, . 1608 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1609 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1610 October 2013, . 1612 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1613 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1614 May 2017, . 1616 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1617 DOI 10.17487/RFC8288, October 2017, 1618 . 1620 [UNICODE] The Unicode Consortium, "The Unicode Standard", 1621 . 1623 Note that this reference is to the latest version of 1624 Unicode, rather than to a specific release. It is not 1625 expected that future changes in the Unicode specification 1626 will have any impact on this document. 1628 [UNICODE-UAX15] 1629 The Unicode Consortium, "Unicode Standard Annex #15: 1630 Unicode Normalization Forms", 1631 . 1633 [UNICODE-UAX31] 1634 The Unicode Consortium, "Unicode Standard Annex #31: 1635 Unicode Identifier and Pattern Syntax", 1636 . 1638 [UNICODE-UAX36] 1639 The Unicode Consortium, "Unicode Standard Annex #36: 1640 Unicode Security Considerations", 1641 . 1643 9.2. Informative References 1645 [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification 1646 0.99", January 2014, 1647 . 1649 [I-D.ietf-core-links-json] 1650 Li, K., Rahman, A., and C. Bormann, "Representing 1651 Constrained RESTful Environments (CoRE) Link Format in 1652 JSON and CBOR", draft-ietf-core-links-json-10 (work in 1653 progress), February 2018. 1655 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1656 (TLS) Protocol Version 1.2", RFC 5246, 1657 DOI 10.17487/RFC5246, August 2008, 1658 . 1660 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1661 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1662 . 1664 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1665 Address Text Representation", RFC 5952, 1666 DOI 10.17487/RFC5952, August 2010, 1667 . 1669 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 1670 RFC 6573, DOI 10.17487/RFC6573, April 2012, 1671 . 1673 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1674 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1675 . 1677 [RFC6903] Snell, J., "Additional Link Relation Types", RFC 6903, 1678 DOI 10.17487/RFC6903, March 2013, 1679 . 1681 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, 1682 DOI 10.17487/RFC6906, March 2013, 1683 . 1685 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1686 Constrained-Node Networks", RFC 7228, 1687 DOI 10.17487/RFC7228, May 2014, 1688 . 1690 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1691 Protocol (HTTP/1.1): Message Syntax and Routing", 1692 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1693 . 1695 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1696 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1697 DOI 10.17487/RFC7231, June 2014, 1698 . 1700 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1701 Application Protocol (CoAP)", RFC 7252, 1702 DOI 10.17487/RFC7252, June 2014, 1703 . 1705 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 1706 RFC 7320, DOI 10.17487/RFC7320, July 2014, 1707 . 1709 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1710 FETCH Methods for the Constrained Application Protocol 1711 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1712 . 1714 [W3C.REC-html52-20171214] 1715 Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and 1716 S. Moon, "HTML 5.2", World Wide Web Consortium 1717 Recommendation REC-html52-20171214, December 2017, 1718 . 1720 [W3C.REC-rdf11-concepts-20140225] 1721 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 1722 Concepts and Abstract Syntax", World Wide Web Consortium 1723 Recommendation REC-rdf11-concepts-20140225, February 2014, 1724 . 1726 [W3C.REC-turtle-20140225] 1727 Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", 1728 World Wide Web Consortium Recommendation REC-turtle- 1729 20140225, February 2014, 1730 . 1732 [W3C.REC-webarch-20041215] 1733 Jacobs, I. and N. Walsh, "Architecture of the World Wide 1734 Web, Volume One", World Wide Web Consortium 1735 Recommendation REC-webarch-20041215, December 2004, 1736 . 1738 Appendix A. Core Vocabulary 1740 This section defines the core vocabulary for CoRAL. It is 1741 RECOMMENDED that all CoRAL registries assign an unsigned integer to 1742 each of these link relation types, form relation types, and form 1743 field names. 1745 [[NOTE TO RFC EDITOR: Please replace all occurrences of 1746 "urn:ietf:rfc:XXXX#" with a RFC-Editor-controlled IRI.]] 1748 A.1. Link Relation Types 1750 1751 Indicates that the link's context is an instance of the type 1752 specified as the link's target; see Section 6 of RFC 6903 1753 [RFC6903]. 1755 This link relation type serves in CoRAL the same purpose as the 1756 RDF predicate identified by the IRI . 1759 1760 Indicates that the link's context is a collection and that the 1761 link's target is a member of that collection; see Section 2.1 of 1762 RFC 6573 [RFC6573]. 1764 1765 Indicates that the link's target is a collection and that the 1766 link's context is a member of that collection; see Section 2.2 of 1767 RFC 6573 [RFC6573]. 1769 A.2. Form Relation Types 1771 1772 Indicates that the form's context is a collection and that a new 1773 item can be created in that collection by submitting a suitable 1774 representation. This form relation type is typically used with 1775 the POST method [RFC7231] [RFC7252]. 1777 1778 Indicates that the form's context can be updated by submitting a 1779 suitable representation. This form relation type is typically 1780 used with the PUT method [RFC7231] [RFC7252], PATCH method 1781 [RFC5789] [RFC8132], or iPATCH method [RFC8132]. 1783 1784 Indicates that the form's context can be deleted. This form 1785 relation type is typically used with the DELETE method [RFC7231] 1786 [RFC7252]. 1788 1789 Indicates that the form's context can be searched by submitting a 1790 search query. This form relation type is typically used with the 1791 POST method [RFC7231] [RFC7252] or FETCH method [RFC8132]. 1793 A.3. Form Field Names 1795 1796 Specifies an acceptable HTTP content type or CoAP content format 1797 for the request payload. There MAY be multiple form fields with 1798 this name. If a form does not include a form field with this 1799 name, the server accepts any or no request payload, depending on 1800 the form relation type. 1802 For HTTP, the content type MUST be specified as a text string in 1803 the format defined in Section 3.1.1.1 of RFC 7231 [RFC7231]; the 1804 set of possible values is maintained in the IANA Media Types 1805 Registry. For CoAP, the content format MUST be specified as an 1806 unsigned integer; the set of possible values is maintained in the 1807 IANA CoAP Content-Formats Registry. 1809 Appendix B. Default Profile 1811 This section defines a default registry that is assumed when a CoRAL 1812 media type without a "profile" parameter is used. 1814 Link Relation Types 1816 0 = 1817 1 = 1818 2 = 1820 Form Relation Types 1822 0 = 1823 1 = 1824 2 = 1825 3 = 1827 Form Fields 1829 0 = 1831 Appendix C. CBOR-encoded IRI References 1833 URI references [RFC3986] and, secondarily, IRI references [RFC3987] 1834 and are the most common usage of resource identifiers in hypertext 1835 representation formats such as HTML 5 [W3C.REC-html52-20171214] and 1836 the CoRE Link Format [RFC6690]. They encode the components of a 1837 resource identifier either as an absolute URI/IRI or as a relative 1838 reference that is resolved against a base URI/IRI. 1840 URI and IRI references are sequences of characters chosen from 1841 limited subsets of the repertoires of US-ASCII characters and Unicode 1842 characters, respectively. The individual components of a URI or IRI 1843 are delimited by several reserved characters, which necessitates the 1844 use of percent-encoding for reserved characters in a non-delimiting 1845 function. The resolution of references involves parsing URI/IRI 1846 references into their components, combining the components with those 1847 of the base URI/IRI, merging paths, removing dot segments, and 1848 recomposing the result into a URI/IRI reference string. 1850 Altogether, proper processing of URIs is quite complex. This can be 1851 a problem in particular in constrained environments [RFC7228] with 1852 severe code size limitations. As a result, many implementations in 1853 these environments choose to implement only an ad-hoc, informally- 1854 specified, bug-ridden, non-interoperable subset of half of RFC 3986. 1856 This section specifies CBOR-encoded IRI References, a serialization 1857 format for IRI references that encodes the IRI components as CBOR 1858 data items rather than text. Assuming that a CBOR implementation is 1859 already present, typical operations on CBOR-encoded IRI references 1860 such as parsing, reference resolution, and comparison can be 1861 implemented much more easily than with the text-based format. A full 1862 implementation that covers all corner cases of the specification can 1863 be implemented in a relatively small amount of code. 1865 CBOR-encoded IRI References are not capable of expressing all IRI 1866 references permitted by the syntax of RFC 3987 [RFC3987]. The 1867 supported subset covers all CoAP URIs [RFC7252] and most HTTP URIs 1868 [RFC7230]. 1870 C.1. Data Structure 1872 The encoding is very similar to the encoding of the request URI in 1873 CoAP messages [RFC7252]. The components of an IRI reference are 1874 encoded as a sequence of _options_. Each option consists of an 1875 _option number_ identifying the type of option (scheme, host name, 1876 etc.) and the _option value_. 1878 iri = [?(scheme: 1, text), 1879 ?(host.name: 2, text // 1880 host.ip: 3, bytes .size 4 / bytes .size 16), 1881 ?(port: 4, uint .size 2), 1882 ?(path.type: 5, path-type), 1883 *(path: 6, text), 1884 *(query: 7, text), 1885 ?(fragment: 8, text)] 1887 path-type = &(absolute-path: 0, 1888 append-path: 1, 1889 relative-path: 2, 1890 append-relation: 3) 1892 C.2. Options 1894 The following options are defined: 1896 scheme 1897 Specifies the IRI scheme. IRI schemes have the same syntax as URI 1898 schemes. The option value therefore MUST match the "scheme" rule 1899 defined in Section 3.1 of RFC 3986. 1901 host.name 1902 Specifies the host of the IRI authority as a registered name. 1904 host.ip 1905 Specifies the host of the IRI authority as an IPv4 address 1906 (4 bytes) or an IPv6 address (16 bytes). 1908 port 1909 Specifies the port number. The option value MUST be an unsigned 1910 integer in the range 0 to 65535 (inclusive). 1912 path.type 1913 Specifies the type of the IRI path for reference resolution. 1914 Possible values are 0 (absolute-path), 1 (append-path), 2 1915 (relative-path), and 3 (append-relation). 1917 path 1918 Specifies one segment of the IRI path. This option can occur more 1919 than once. 1921 query 1922 Specifies one argument of the IRI query. This option can occur 1923 more than once. 1925 fragment 1926 Specifies the fragment identifier. 1928 The value of a "host.name", "path", "query", and "fragment" option 1929 can be any Unicode string. No percent-encoding is performed. 1931 C.3. Properties 1933 A sequence of options is considered _well-formed_ if: 1935 o the sequence of options is empty or starts with a "scheme", 1936 "host.name", "host.ip", "port", "path.type", "path", "query", or 1937 "fragment" option; 1939 o a "scheme" option is followed by either a "host.name" or a 1940 "host.ip" option; 1942 o a "host.name" option is followed by a "port" option; 1944 o a "host.ip" option is followed by a "port" option; 1945 o a "port" option is followed by a "path", "query", or "fragment" 1946 option or is at the end of the sequence; 1948 o a "path.type" option is followed by a "path", "query", or 1949 "fragment" option or is at the end of the sequence; 1951 o a "path" option is followed by a "path", "query", or "fragment" 1952 option or is at the end of the sequence; 1954 o a "query" option is followed by a "query" or "fragment" option or 1955 is at the end of the sequence; and 1957 o a "fragment" option is at the end of the sequence. 1959 A well-formed sequence of options is considered _absolute_ if the 1960 sequence of options starts with a "scheme" option. A well-formed 1961 sequence of options is considered _relative_ if the sequence of 1962 options is empty or starts with an option other than the "scheme" 1963 option. 1965 An absolute sequence of options is considered _normalized_ if the 1966 result of resolving the sequence of options against any base IRI 1967 reference is equal to the input. (It doesn't matter what it is 1968 resolved against, since it is already absolute.) 1970 C.4. Reference Resolution 1972 This section defines how to resolve a CBOR-encoded IRI reference that 1973 might be relative to a given base IRI. 1975 Applications MUST resolve a well-formed sequence of options `href` 1976 against an absolute sequence of options `base` by using an algorithm 1977 that is functionally equivalent to the following Python 3.5 code. 1979 1981 def resolve(base, href, relation=None): 1982 if not is_absolute(base) or not is_well_formed(href): 1983 return None 1984 result = [] 1985 type = PathType.RELATIVE_PATH 1986 (option, value) = href[0] 1987 if option == Option.HOST_IP: 1988 option = Option.HOST_NAME 1989 elif option == Option.PATH_TYPE: 1990 href = href[1:] 1991 type = value 1992 option = Option.PATH 1994 if option != Option.PATH or type == PathType.ABSOLUTE_PATH: 1995 _copy_until(base, result, option) 1996 else: 1997 _copy_until(base, result, Option.QUERY) 1998 if type == PathType.APPEND_RELATION: 1999 _append_and_normalize(result, Option.PATH, 2000 format(relation, "x")) 2001 return result 2002 if type == PathType.RELATIVE_PATH: 2003 _remove_last_path_segment(result) 2004 _copy_until(href, result, Option.END) 2005 _append_and_normalize(href, Option.END, None) 2006 return result 2008 def _copy_until(input, output, end): 2009 for (option, value) in input: 2010 if option >= end: 2011 break 2012 _append_and_normalize(output, option, value) 2014 def _append_and_normalize(output, option, value): 2015 if option == Option.PATH: 2016 if value == ".": 2017 return 2018 if value == "..": 2019 _remove_last_path_segment(output) 2020 return 2021 elif option > Option.PATH: 2022 if len(output) >= 2 and \ 2023 output[-1] == (Option.PATH, "") and \ 2024 (output[-2][0] < Option.PATH_TYPE or \ 2025 output[-2] == (Option.PATH_TYPE, PathType.ABSOLUTE_PATH)): 2026 _remove_last_path_segment(output) 2027 if option >= Option.END: 2028 return 2029 output.append((option, value)) 2031 def _remove_last_path_segment(output): 2032 if len(output) >= 1 and output[-1][0] == Option.PATH: 2033 del output[-1] 2035 2037 C.5. IRI Recomposition 2039 This section defines how to recompose an IRI from a sequence of 2040 options that encodes an absolute IRI reference. 2042 Applications MUST recompose an IRI from a sequence of options by 2043 using an algorithm that is functionally equivalent to the following 2044 Python 3.5 code. 2046 To reduce variability, the hexadecimal notation when percent-encoding 2047 octets SHOULD use uppercase letters. The text representation of IPv6 2048 addresses SHOULD follow the recommendations in Section 4 of RFC 5952 2049 [RFC5952]. 2051 2053 def recompose(href): 2054 if not is_absolute(href): 2055 return None 2056 result = "" 2057 no_path = True 2058 first_query = True 2059 for (option, value) in href: 2060 if option == Option.SCHEME: 2061 result += value + ":" 2062 elif option == Option.HOST_NAME: 2063 result += "//" + _encode_ireg_name(value) 2064 elif option == Option.HOST_IP: 2065 result += "//" + _encode_ip_address(value) 2066 elif option == Option.PORT: 2067 result += ":" + str(value) 2068 elif option == Option.PATH: 2069 result += "/" + _encode_path_segment(value) 2070 no_path = False 2071 elif option == Option.QUERY: 2072 if no_path: 2073 result += "/" 2074 no_path = False 2075 result += "?" if first_query else "&" 2076 result += _encode_query_argument(value) 2077 first_query = False 2078 elif option == Option.FRAGMENT: 2079 if no_path: 2080 result += "/" 2081 no_path = False 2082 result += "#" + _encode_fragment(value) 2083 if no_path: 2084 result += "/" 2085 no_path = False 2086 return result 2088 def _encode_ireg_name(s): 2089 return "".join(c if _is_ireg_name_char(c) else 2090 _encode_pct(c) for c in s) 2092 def _encode_ip_address(b): 2093 if len(b) == 4: 2094 return ".".join(str(c) for c in b) 2095 elif len(b) == 16: 2096 return "[" + ... + "]" # see RFC 5952 2098 def _encode_path_segment(s): 2099 return "".join(c if _is_isegment_char(c) else 2100 _encode_pct(c) for c in s) 2102 def _encode_query_argument(s): 2103 return "".join(c if _is_iquery_char(c) and c != "&" else 2104 _encode_pct(c) for c in s) 2106 def _encode_fragment(s): 2107 return "".join(c if _is_ifragment_char(c) else 2108 _encode_pct(c) for c in s) 2110 def _encode_pct(s): 2111 return "".join( 2112 "%{0:0>2X}".format(c) for c in s.encode("utf-8")) 2114 def _is_ireg_name_char(c): 2115 return _is_iunreserved(c) or _is_sub_delim(c) 2117 def _is_isegment_char(c): 2118 return _is_ipchar(c) 2120 def _is_iquery_char(c): 2121 return _is_ipchar(c) or _is_iprivate(c) or c == "/" or c == "?" 2123 def _is_ifragment_char(c): 2124 return _is_ipchar(c) or c == "/" or c == "?" 2126 def _is_ipchar(c): 2127 return _is_iunreserved(c) or _is_sub_delim(c) or \ 2128 c == ":" or c == "@" 2130 def _is_iunreserved(c): 2131 return _is_alpha(c) or _is_digit(c) or \ 2132 c == "-" or c == "." or c == "_" or c == "~" or \ 2133 _is_ucschar(c) 2135 def _is_alpha(c): 2136 return c >= "A" and c <= "Z" or c >= "a" and c <= "z" 2138 def _is_digit(c): 2139 return c >= "0" and c <= "9" 2141 def _is_sub_delim(c): 2142 return c == "!" or c == "$" or c == "&" or c == "'" or \ 2143 c == "(" or c == ")" or c == "*" or c == "+" or \ 2144 c == "," or c == ";" or c == "=" 2146 def _is_ucschar(c): 2147 return c >= "\U000000A0" and c <= "\U0000D7FF" or \ 2148 c >= "\U0000F900" and c <= "\U0000FDCF" or \ 2149 c >= "\U0000FDF0" and c <= "\U0000FFEF" or \ 2150 c >= "\U00010000" and c <= "\U0001FFFD" or \ 2151 c >= "\U00020000" and c <= "\U0002FFFD" or \ 2152 c >= "\U00030000" and c <= "\U0003FFFD" or \ 2153 c >= "\U00040000" and c <= "\U0004FFFD" or \ 2154 c >= "\U00050000" and c <= "\U0005FFFD" or \ 2155 c >= "\U00060000" and c <= "\U0006FFFD" or \ 2156 c >= "\U00070000" and c <= "\U0007FFFD" or \ 2157 c >= "\U00080000" and c <= "\U0008FFFD" or \ 2158 c >= "\U00090000" and c <= "\U0009FFFD" or \ 2159 c >= "\U000A0000" and c <= "\U000AFFFD" or \ 2160 c >= "\U000B0000" and c <= "\U000BFFFD" or \ 2161 c >= "\U000C0000" and c <= "\U000CFFFD" or \ 2162 c >= "\U000D0000" and c <= "\U000DFFFD" or \ 2163 c >= "\U000E1000" and c <= "\U000EFFFD" 2165 def _is_iprivate(c): 2166 return c >= "\U0000E000" and c <= "\U0000F8FF" or \ 2167 c >= "\U000F0000" and c <= "\U000FFFFD" or \ 2168 c >= "\U00100000" and c <= "\U0010FFFD" 2170 2172 C.6. CoAP Encoding 2174 This section defines how to construct CoAP options from an absolute, 2175 normalized, CBOR-encoded IRI Reference. 2177 Applications MUST construct CoAP options by recomposing the sequence 2178 of options to an IRI (Appendix C.5 of this document), mapping the IRI 2179 to an URI (Section 3.1 of RFC 3987), and decomposing the URI into 2180 CoAP options (Section 6.4 of RFC 7252). 2182 The following illustrative Python 3.5 code is roughly equivalent to 2183 this. 2185 2186 def coap(href, to_proxy=False): 2187 if not is_absolute(href): 2188 return None 2189 result = b"" 2190 previous = 0 2191 for (option, value) in href: 2192 if option == Option.SCHEME: 2193 pass 2194 elif option == Option.HOST_NAME: 2195 opt = 3 # Uri-Host 2196 val = value.encode("utf-8") 2197 result += _encode_coap_option(opt - previous, val) 2198 previous = opt 2199 elif option == Option.HOST_IP: 2200 opt = 3 # Uri-Host 2201 if len(value) == 4: 2202 val = ".".join(str(c) for c in b).encode("utf-8") 2203 elif len(value) == 16: 2204 val = b"[" + ... + b"]" # see RFC 5952 2205 result += _encode_coap_option(opt - previous, val) 2206 previous = opt 2207 elif option == Option.PORT: 2208 opt = 7 # Uri-Port 2209 val = value.to_bytes((value.bit_length() + 7) // 8, "big") 2210 result += _encode_coap_option(opt - previous, val) 2211 previous = opt 2212 elif option == Option.PATH: 2213 opt = 11 # Uri-Path 2214 val = value.encode("utf-8") 2215 result += _encode_coap_option(opt - previous, val) 2216 previous = opt 2217 elif option == Option.QUERY: 2218 opt = 15 # Uri-Query 2219 val = value.encode("utf-8") 2220 result += _encode_coap_option(opt - previous, val) 2221 previous = opt 2222 elif option == Option.FRAGMENT: 2223 pass 2224 if to_proxy: 2225 (option, value) = href[0] 2226 opt = 39 # Proxy-Scheme 2227 val = value.encode("utf-8") 2228 result += _encode_coap_option(opt - previous, val) 2229 previous = opt 2230 return result 2232 def _encode_coap_option(delta, value): 2233 length = len(value) 2234 delta_nibble = _encode_coap_option_nibble(delta) 2235 length_nibble = _encode_coap_option_nibble(length) 2236 result = bytes([delta_nibble << 4 | length_nibble]) 2237 if delta_nibble == 13: 2238 delta -= 13 2239 result += bytes([delta]) 2240 elif delta_nibble == 14: 2241 delta -= 256 + 13 2242 result += bytes([delta >> 8, delta & 255]) 2243 if length_nibble == 13: 2244 length -= 13 2245 result += bytes([length]) 2246 elif length_nibble == 14: 2247 length -= 256 + 13 2248 result += bytes([length >> 8, length & 255]) 2249 result += value 2250 return result 2252 def _encode_coap_option_nibble(n): 2253 if n < 13: 2254 return n 2255 elif n < 256 + 13: 2256 return 13 2257 elif n < 65536 + 256 + 13: 2258 return 14 2260 2262 Author's Address 2264 Klaus Hartke 2265 Universitaet Bremen TZI 2266 Postfach 330440 2267 Bremen D-28359 2268 Germany 2270 Phone: +49-421-218-63905 2271 Email: hartke@tzi.org