idnits 2.17.00 (12 Aug 2021) /tmp/idnits28393/draft-ietf-core-coral-05.txt: -(2): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(379): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(380): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- == There are 7 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 40 instances of too long lines in the document, the longest one being 27 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document date (7 March 2022) is 68 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'I-D.ietf-core-coral' is mentioned on line 1370, but not defined == Unused Reference: 'RFC3339' is defined on line 1408, but no explicit reference was found in the text == Unused Reference: 'RFC3629' is defined on line 1412, but no explicit reference was found in the text == Unused Reference: 'RFC4648' is defined on line 1421, but no explicit reference was found in the text == Unused Reference: 'RFC5234' is defined on line 1425, but no explicit reference was found in the text == Unused Reference: 'RFC6657' is defined on line 1438, but no explicit reference was found in the text == Unused Reference: 'Unicode' is defined on line 1463, but no explicit reference was found in the text == Unused Reference: 'UAX31' is defined on line 1573, but no explicit reference was found in the text == Unused Reference: 'UTR36' is defined on line 1577, but no explicit reference was found in the text == Unused Reference: 'UTS39' is defined on line 1581, but no explicit reference was found in the text ** Downref: Normative reference to an Informational draft: draft-bormann-cbor-edn-literals (ref. 'I-D.bormann-cbor-edn-literals') == Outdated reference: A later version (-05) exists of draft-ietf-cbor-packed-04 == Outdated reference: A later version (-10) exists of draft-ietf-core-href-09 -- Possible downref: Non-RFC (?) normative reference: ref. 'Unicode' == Outdated reference: A later version (-10) exists of draft-ietf-httpapi-linkset-08 Summary: 2 errors (**), 0 flaws (~~), 14 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group C. Amsüss 3 Internet-Draft 4 Intended status: Standards Track T. Fossati 5 Expires: 8 September 2022 ARM 6 7 March 2022 8 The Constrained RESTful Application Language (CoRAL) 9 draft-ietf-core-coral-05 11 Abstract 13 The Constrained RESTful Application Language (CoRAL) defines a data 14 model and interaction model as well as a compact serialization 15 formats for the description of typed connections between resources on 16 the Web ("links"), possible operations on such resources ("forms"), 17 and simple resource metadata. 19 Note to Readers 21 This note is to be removed before publishing as an RFC. 23 The issues list for this Internet-Draft can be found at 24 . Companion material 25 for this Internet-Draft can be found at . 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on 8 September 2022. 45 Copyright Notice 47 Copyright (c) 2022 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 52 license-info) in effect on the date of publication of this document. 53 Please review these documents carefully, as they describe your rights 54 and restrictions with respect to this document. Code Components 55 extracted from this document must include Revised BSD License text as 56 described in Section 4.e of the Trust Legal Provisions and are 57 provided without warranty as described in the Revised BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.1. Data and Interaction Model . . . . . . . . . . . . . . . 4 63 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 4 64 2. Data and Interaction Model . . . . . . . . . . . . . . . . . 4 65 2.1. Browsing Context . . . . . . . . . . . . . . . . . . . . 4 66 2.2. Documents . . . . . . . . . . . . . . . . . . . . . . . . 5 67 2.3. Data model . . . . . . . . . . . . . . . . . . . . . . . 5 68 2.3.1. Observations . . . . . . . . . . . . . . . . . . . . 6 69 2.3.2. Possible variations . . . . . . . . . . . . . . . . . 7 70 2.3.3. Examples . . . . . . . . . . . . . . . . . . . . . . 7 71 2.4. Serialization Format . . . . . . . . . . . . . . . . . . 10 72 2.5. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 11 73 2.6. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 12 74 2.7. Form Fields . . . . . . . . . . . . . . . . . . . . . . . 13 75 2.8. Navigation . . . . . . . . . . . . . . . . . . . . . . . 13 76 2.9. History Traversal . . . . . . . . . . . . . . . . . . . . 15 77 2.10. Designing interactions in an Open World . . . . . . . . . 15 78 3. Binary Format . . . . . . . . . . . . . . . . . . . . . . . . 16 79 3.1. Data Structure . . . . . . . . . . . . . . . . . . . . . 16 80 3.1.1. Documents . . . . . . . . . . . . . . . . . . . . . . 16 81 3.1.2. Directives . . . . . . . . . . . . . . . . . . . . . 17 82 3.1.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . 17 83 3.1.4. Links . . . . . . . . . . . . . . . . . . . . . . . . 18 84 3.1.5. Forms . . . . . . . . . . . . . . . . . . . . . . . . 18 85 3.1.6. Form Fields . . . . . . . . . . . . . . . . . . . . . 19 86 3.2. Dictionary Compression . . . . . . . . . . . . . . . . . 19 87 3.2.1. Media Type Parameter . . . . . . . . . . . . . . . . 20 88 3.3. Export Interface . . . . . . . . . . . . . . . . . . . . 20 89 4. Document Semantics . . . . . . . . . . . . . . . . . . . . . 21 90 4.1. Submitting Documents . . . . . . . . . . . . . . . . . . 21 91 4.1.1. PUT Requests . . . . . . . . . . . . . . . . . . . . 21 92 4.1.2. POST Requests . . . . . . . . . . . . . . . . . . . . 21 93 4.2. Returning Documents . . . . . . . . . . . . . . . . . . . 22 94 4.2.1. Success Responses . . . . . . . . . . . . . . . . . . 22 95 4.2.2. Redirection Responses . . . . . . . . . . . . . . . . 22 96 4.2.3. Error Responses . . . . . . . . . . . . . . . . . . . 23 97 5. Usage Considerations . . . . . . . . . . . . . . . . . . . . 23 98 5.1. Specifying CoRAL-based Applications . . . . . . . . . . . 23 99 5.1.1. Application Interfaces . . . . . . . . . . . . . . . 23 100 5.1.2. Resource Identifiers . . . . . . . . . . . . . . . . 24 101 5.1.3. Implementation Limits . . . . . . . . . . . . . . . . 24 102 5.2. Minting Vocabulary . . . . . . . . . . . . . . . . . . . 25 103 5.3. Expressing Registered Link Relation Types . . . . . . . . 25 104 5.4. Expressing Simple RDF Statements . . . . . . . . . . . . 26 105 5.5. Expressing Natural Language Texts . . . . . . . . . . . . 26 106 5.6. Embedding Representations in CoRAL . . . . . . . . . . . 27 107 6. Security Considerations . . . . . . . . . . . . . . . . . . . 27 108 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 109 7.1. Media Type "application/coral+cbor" . . . . . . . . . . . 29 110 7.2. CoAP Content Formats . . . . . . . . . . . . . . . . . . 30 111 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 112 8.1. Normative References . . . . . . . . . . . . . . . . . . 30 113 8.2. Informative References . . . . . . . . . . . . . . . . . 32 114 Appendix A. Core Vocabulary . . . . . . . . . . . . . . . . . . 36 115 A.1. Base . . . . . . . . . . . . . . . . . . . . . . . . . . 36 116 A.2. Collections . . . . . . . . . . . . . . . . . . . . . . . 37 117 A.3. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . 37 118 A.4. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 38 119 Appendix B. Default Dictionary . . . . . . . . . . . . . . . . . 39 120 Appendix C. Mappings to other formats . . . . . . . . . . . . . 40 121 C.1. RDF . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 122 C.1.1. Example . . . . . . . . . . . . . . . . . . . . . . . 42 123 C.2. CoRE Link Format . . . . . . . . . . . . . . . . . . . . 43 124 Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 46 125 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 48 126 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 128 1. Introduction 130 The Constrained RESTful Application Language (CoRAL) is a language 131 for the description of typed connections between resources on the Web 132 ("links"), possible operations on such resources ("forms"), and 133 simple resource metadata. 135 CoRAL is intended for driving automated software agents that navigate 136 a Web application based on a standardized vocabulary of link relation 137 types and operation types. It is designed to be used in conjunction 138 with a Web transfer protocol, such as the Hypertext Transfer Protocol 139 (HTTP) [RFC7230] or the Constrained Application Protocol (CoAP) 140 [RFC7252]. 142 This document defines the CoRAL data model and interaction model as 143 well as a compact serialization format. 145 1.1. Data and Interaction Model 147 The data model is similar to the Resource Description Framework (RDF) 148 [W3C.REC-rdf11-concepts-20140225] model, with provisions to enable 149 form based interaction and to express data from Web Linking 150 ([RFC8288]) based models such as [RFC6690]'s Link Format. 152 The interaction model derives from the processing model of HTML 153 [W3C.REC-html52-20171214] and specifies how an automated software 154 agent can change the application state by navigating between 155 resources following links and performing operations on resources 156 submitting forms. 158 1.2. Notational Conventions 160 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 161 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 162 "OPTIONAL" in this document are to be interpreted as described in 163 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 164 capitals, as shown here. 166 Terms defined in this document appear in _cursive_ where they are 167 introduced (rendered in plain text as the new term surrounded by 168 underscores). 170 2. Data and Interaction Model 172 The Constrained RESTful Application Language (CoRAL) is designed for 173 building Web-based applications [W3C.REC-webarch-20041215] in which 174 automated software agents navigate between resources by following 175 links and perform operations on resources by submitting forms. 177 2.1. Browsing Context 179 Borrowing from HTML 5 [W3C.REC-html52-20171214], each such agent 180 maintains a _browsing context_ in which the representations of Web 181 resources are processed. (In HTML, the browsing context typically 182 corresponds to a tab or window in a Web browser.) 184 At any time, one representation in a browsing context is designated 185 the _active_ representation. 187 2.2. Documents 189 A resource representation in one of the CoRAL serialization formats 190 is called a CoRAL _document_. The URI that was used to retrieve such 191 a document is called the document's _retrieval context_. This URI is 192 also considered the base URI for relative URI references in the 193 document. 195 A CoRAL document consists of a list of zero or more statements that 196 can express links or (in a composition of statements) forms. CoRAL 197 serialization formats may contain additional elements for efficiency 198 or convenience, such as an embedded base URI that takes precedence 199 over the document's base URI, or to concisely represent compound 200 statements (e.g., to express forms). 202 2.3. Data model 204 The _basic CoRAL information model_ is similar to the Resource 205 Description Framework (RDF) [W3C.REC-rdf11-concepts-20140225] 206 information model: Data is expressed as an (unordered) set of triples 207 (also called statements), consisting of a subject, a predicate and an 208 object. The predicate is always a URI, the subject is a URI or a 209 blank node, and the object is either a URI, a blank node or a 210 litreal. All URIs here are limited to the syntax-based normalized 211 form of [RFC3986] Section 6.2.2. 213 Blank nodes are unnamed entities. Literals are CBOR objects. 215 These triples form a directed multigraph with the subject and object 216 being source and destination, and the predicate a description on the 217 edge. That graph is equivalent to the data. 219 To form a set and a graph, we define an equivalence relation: URIs 220 are only equal to URIs and if they are identical byte-wise. A blank 221 node is only equal to itself. A literal is equal to a different 222 literal if its value is equal to the other literal's value in the 223 CBOR generic data model. 225 Triples are equivalent to each other if their subject, predicate and 226 object are pair-wise equivalent. 228 The _CoRAL structured information model_ is a sequence of "passings" 229 of the basic model's edges, starting at a node identifying the 230 document (its retrieval context, typically URI from which it was 231 obtained) where 233 * each edge is passed at least one time in total, 234 * each edge is passed at most one time after each passing that ends 235 in its start point (with the obvious exception that edges from the 236 retrieval context can be passed once from the start), and 238 * between a passing of an edge from A to B and a later passing from 239 B to C, passings can only be along edges that can be reached from 240 B along the graph, until B is the end of a different passing. 242 For better understanding, think of the structured information model 243 as a sort of tree spanning from the retrieval context, with the 244 oddity that when a node is reached along two different edges (which a 245 normal tree doesn't do), it is up to the builder of the tree whether 246 to describe anything children of the entered node on one parent or on 247 the other parent, on both, or to describe some children at the first 248 and others at a later occasion. 250 Exceeding the RDF-like model, this represents CoRAL's focus on the 251 discovery of possivble future application states over the description 252 of a graph of resources. 254 2.3.1. Observations 256 The structured form of a data set is in general not unique: If a node 257 has more than one child, their sequence can be varied. If a node has 258 more than one parent, its children may be expressed on any non-empty 259 set of its parents to obtain a structured data set that expresses the 260 same data set. 262 In general, arbitrary basic data can not be expressed in a structured 263 data set, because 265 * There may not be a tree that covers the directed graph, or the 266 tree's root may not be the retrieval context. 268 * There may be multiple edges into a blank node. 270 In particular, the precise data from one structured information 271 document can only be expressed with the same retrieval context. 272 However, statements can be added to make a data set that is 273 expressible elsewhere (this document defines the carries-information- 274 about relation type leading to the 275 http://www.iana.org/assignments/relation/carries-information-about 276 predicate being usable here), and subsets of the data can be taken 277 and expressed. 279 Forms are not special in the information model, but are merely 280 statements around a blank node. They can be special in serialization 281 formats (which have more efficient notations for them), and are used 282 by the interaction model for special operations. 284 The structured information model contains more information than the 285 basic information model. [ TBD put this into a different context 286 because it's not an observation any more: ] Which precise structure 287 is picked is to suit the processing application, typically by 288 profiling the information and its serialization. It is recommended 289 that the information encoded in the structure (including the order) 290 be derived from data available in the general data set, even though 291 the statements that guide the structure are not necessarily encoded 292 in the subset of data that is being structured. 294 Serializations like the one in Section 3 have even more choices than 295 the structured information model: They can choose to use or not use 296 packed CBOR to compress parts, can spell out URIs in full or use 297 relative references, or can exercise freedoms of the CBOR encoding. 298 Variation there is not to have an influence on the interpretation of 299 a CoRAL document. 301 2.3.2. Possible variations 303 * Each URI is tagged with whether it is intended to be dereferenced 304 or used as an identifier. 306 2.3.3. Examples 308 This subsection illustrates the information model and serialization 309 based on an example from [RFC6690]: 311 ;ct=40;title="Sensor Index", 312 ;rt="temperature-c";if="sensor", 313 ;rt="light-lux";if="sensor", 314 ;anchor="/sensors/temp";rel="describedby", 315 ;anchor="/sensors/temp";rel="alternate" 317 Figure 1: Original example at coap://.../.well-known/core 319 After an extraction described in Appendix C.2, this list represents 320 the content of the basic information model representing the above. 321 For the basic model, the table is to be considered unsorted in the 322 first step. 324 +===================+=========================================+===============================+ 325 |Subject |Predicate |Object | 326 +===================+=========================================+===============================+ 327 |coap://.../ |rel:hosts |coap://.../sensors | 328 +-------------------+-----------------------------------------+-------------------------------+ 329 |coap://.../sensors |linkformat:ct |40 | 330 +-------------------+-----------------------------------------+-------------------------------+ 331 |coap://.../sensors |linkformat:title |"Sensor Index" | 332 +-------------------+-----------------------------------------+-------------------------------+ 333 |coap://.../ |http://www.iana.org/assignments/relation/|coap://.../sensors/temp | 334 | |hosts | | 335 +-------------------+-----------------------------------------+-------------------------------+ 336 |coap://.../sensors/|linkformat:rt |rt:temperature-c | 337 |temp | | | 338 +-------------------+-----------------------------------------+-------------------------------+ 339 |coap://.../sensors/|linkformat:if |if:sensor | 340 |temp | | | 341 +-------------------+-----------------------------------------+-------------------------------+ 342 |coap://.../sensors/|rel:describedby |http://www.example.com/sensors/| 343 |temp | |t123 | 344 +-------------------+-----------------------------------------+-------------------------------+ 345 |coap://.../sensors/|rel:alternate |coap://.../t | 346 |temp | | | 347 +-------------------+-----------------------------------------+-------------------------------+ 348 |coap://.../ |http://www.iana.org/assignments/relation/|coap://.../sensors/light | 349 | |hosts | | 350 +-------------------+-----------------------------------------+-------------------------------+ 351 |coap://.../sensors/|linkformat:rt |rt:light-lux | 352 |light | | | 353 +-------------------+-----------------------------------------+-------------------------------+ 354 |coap://.../sensors/|linkformat:if |if:sensor | 355 |light | | | 356 +-------------------+-----------------------------------------+-------------------------------+ 358 Table 1: Basic (and, through the sequence, Strucutred) 359 Information Model extracted from there (using CURIEs: rel = 360 http://www.iana.org/assignments/relation/, linkformat is TBD in 361 the conversion, if, rt is TBD with IANA). 363 During extraction, some information on item ordering was preserved 364 into the structured data. Note that while the CoRAL structured data 365 preserves some sequence aspects of the Link-Format file (like the 366 order of attributes), others (like the relative order of links from 367 different contexts) are deemed irrelevant and not preserved. 369 For serialization, the use of the packing described with the 370 conversion results in a binary CBOR file with this CBOR diagnostic 371 notation: 373 [ 374 [2, simple(10) / item 10 for rel:hosts /, cri"/sensors", [ 375 [2, 6(2) / item 20 for linkformat:ct /, 40], 376 [2, simple(15) / item 15 for linkformat:title /, "Sensor Index"] 377 ]], 378 [2, simple(10) / item 10 for rel:hosts /, cri"/sensors/temp", [ 379 [2, 6(1) / item 18 for linkformat:if /, 6(200) / cri"http:∕∕TBD∕...∕temperature-c" /], 380 [2, 6(-2) / item 19 for linkformat:rt /, 6(250) / cri"http:∕∕TBD∕...∕sensor" /], 381 [2, simple(12) / item 12 for rel:describedby /, cri"http://www.example.com/sensors/t123"], 382 [2, simple(11) / item 11 for rel:alternate /, cri"/t"] 383 ]], 384 [2, 10 / item10 for rel:hosts /, cri"/sensors/light", [ 385 [2, 6(1) / item 18 for linkformat:if /, 6(-201)], 386 [2, 6(-2) / item 19 for linkformat:rt /, 6(250)] 387 ]] 388 ] 390 Figure 2: Serialized CoRAL file in diagnostic notation. 392 [ TBD: Numbers are made up ] 394 Note that the "temperature-c" interface and "sensor" resource type 395 get code points in the link-format dictionary because they are of 396 reg-name style and thus would be registered as CoRE Parameters, and 397 be included in the packing as well. 399 2.3.3.1. Literal example 401 To illustrate non-trivial literals, a link example of [RFC8288] is 402 converted. 404 (Note that even the conversion scheme hinted at above for [RFC6690] 405 link format makes no claims at being applicable to general purpose 406 web links like the below; this is merely done to demonstrate how 407 literals can be handled. The example even so happens well illustrate 408 that point: General link attributes may only be valid on the target 409 when the link is followed in that direction ("letztes Kapitel" means 410 last chapter), whereas convertible link-format documents use titles 411 that apply to the described resource independent of which link is 412 currently being followed.) 414 Link: ; 415 rel="previous"; title*=UTF-8'de'letztes%20Kapitel, 417 Figure 3: Original link about a book chapter from RFC8288 419 The model this would be converted to is: 421 +=====================+==================+========================+ 422 | Subject | Predicate | Object | 423 +=====================+==================+========================+ 424 | http://.../ | rel:previous | http://.../TheBook/ | 425 | | | chapter2 | 426 +---------------------+------------------+------------------------+ 427 | http://.../TheBook/ | linkformat:title | "letztes Kapitel" with | 428 | chapter2 | | language tag "de" | 429 +---------------------+------------------+------------------------+ 431 Table 2: Information model extracted from above 433 In CBOR serialization, this produces: 435 [ 436 [2, 6(...) / rel:previous /, cri"/TheBook/chapter2", [ 437 [2, simple(15) / item 15 for linkformat:title /, 38(["de", "letztes Kapitel"])] 438 ]] 439 ] 441 Figure 4: Serialization of the RFC8288-based example 443 2.4. Serialization Format 445 The primary serialization format is a compact, binary encoding of 446 links and forms in Concise Binary Object Representation (CBOR) 447 [RFC8949]. This format is intended for environments with constraints 448 on power, memory, and processing resources [RFC7228] and shares many 449 similarities with the message format of CoAP: In place of verbose 450 strings, small numeric identifiers are used to encode link relation 451 types and operation types. Uniform Resource Identifiers (URIs) 452 [RFC3986] are expressed as Constrained Resource Identifier (CRI) 453 references [I-D.ietf-core-href] and thus pre-parsed for easy use with 454 CoAP. As a result, link serializations in CoRAL are often much more 455 compact and easier to process than equivalent serializations in CoRE 456 Link Format [RFC6690]. 458 For easy representation of CoRAL documents in text, CBOR diagnostic 459 notation is used. Along with indentation and comments, the notation 460 introduced in [I-D.bormann-cbor-edn-literals] is used to represent 461 CRIs. This format is not expected to be sent over the network. 463 [ To be discussed: For even better readability, the RDF Turtle 464 [W3C.REC-turtle-20140225] format can be used when only the basic 465 information model content is to be conveyed. When used like this, 466 the conversion according to the RDF appendix is implied. ] 468 2.5. Links 470 Any statement "links" a resource with a second resource or literal, 471 and is thus also referred to as a link. 473 In [RFC8288] terminology, a CoRAL link's subject is the _link 474 context_, the predicate is the _link relation type_, and the object 475 is the _link target_. 477 However, a link in CoRAL does not have target attributes. Instead, a 478 link may have a list of zero or more nested elements. These enable 479 both the description of resource metadata and the chaining of links, 480 which is done in [RFC8288] by setting the anchor of one link to the 481 target of another. 483 A link can be viewed as a statement of the form "{link context} 484 has a {link relation type} resource at {link target}" where the 485 link target may be further described by nested elements. 487 A link relation type identifies the semantics of a link. In HTML and 488 in [RFC8288], link relation types are typically denoted by an IANA- 489 registered name, such as stylesheet or type. In CoRAL, all link 490 relation types are, in contrast, denoted by a Universal Resource 491 Identifier (URI) [RFC3986], such as 492 or 493 . This allows for 494 the decentralized creation of new link relation types without the 495 risk of collisions when they come from different organizations or 496 domains of knowledge. URIs can also lead to documentation, schema, 497 and other information about a link relation type. In CoRAL 498 documents, these URIs are only used as identity tokens, though, and 499 are compared with Simple String Comparison as specified in 500 Section 6.2.1 of [RFC3986]. 502 If the link target is a URI and the URI scheme indicates a Web 503 transfer protocol like HTTP or CoAP, an agent can dereference the URI 504 and navigate the browsing context to its target resource; this is 505 called _following the link_. An anonymous resource is a resource that 506 is identified by neither a URI nor a literal representation. The 507 agent can still follow the link, but can not dereference it and is 508 limited in its next steps by the outgoing links that are expressed in 509 the current document. 511 A link can occur as a top-level element in a document or as a nested 512 element within a link. When a link occurs as a top-level element, 513 the link context implicitly is the document's retrieval context. 514 When a link occurs nested within a link, the link context of the 515 nested link is the link target of the enclosing link. 517 There are no restrictions on the cardinality of links; there can be 518 multiple links to and from a particular target, and multiple links of 519 the same or different types between a given link context and target. 520 However, the nesting nature of the data model constrains the 521 description of resource relations to a tree: Relations between linked 522 resources can only be described by further nesting links. 524 2.6. Forms 526 A _form_ provides instructions to an agent for performing an 527 operation on a resource on the Web. A form has a _form context_, an 528 _operation type_, a _request method_, and a _submission target_. 529 Additionally, a form may be accompanied by a list of zero or more 530 _form fields_. 532 In the basic information model, the form is identified with an 533 anonymous node. The form context and operation type are the subject 534 and predicate of an incoming link, respectively; request method and 535 submission target of an outgoing link. Form fields are additional 536 links from that form. 538 A form can be viewed as an instruction of the form "To perform an 539 {operation type} operation on {form context}, make a {request 540 method} request to {submission target}" where the request may be 541 further described by form fields. 543 An operation type identifies the semantics of the operation. 544 Operation types are denoted (like link relation types) by a URI. 546 Form contexts and submission targets are both denoted by a URI. The 547 form context is the resource on which the operation is ultimately 548 performed. To perform the operation, an agent needs to construct a 549 request with the specified method as the request method and the 550 specified submission target as the request URI. Usually, the 551 submission target is the same resource as the form context, but may 552 be a different resource. Constructing and sending the request is 553 called _submitting the form_. 555 A form can occur as a top-level element in a document or as a nested 556 element within a link. When a form occurs as a top-level element, 557 the form context implicitly is the document's retrieval context. 558 When a form occurs nested within a link, the form context is the link 559 target of the enclosing link. 561 2.7. Form Fields 563 Form fields can be used to provide more detailed instructions to 564 agents for constructing the request when submitting a form. For 565 example, a form field could instruct an agent to include a certain 566 payload or header field in the request. A payload could, for 567 instance, be described by form fields providing acceptable media 568 types, a reference to schema information, or a number of individual 569 data items that the agents needs to supply. Form fields can be 570 specific to the Web transfer protocol that is used for submitting the 571 form. 573 A form field is a pair of a _form field type_ and a _form field 574 value_. Additionally, a form field may have a list of zero or more 575 nested elements that further describe the form field value. 577 A form field type identifies the semantics of the form field. Form 578 field types are predicates and thus URIs. Form field values are 579 URIs, blank nodes or literals. 581 2.8. Navigation 583 An agent begins the interaction with an application by performing a 584 GET request on an _entry point URI_. The entry point URI is the only 585 URI that the agent is expected to know beforehand. From then on, the 586 agent is expected to make all requests by following links and 587 submitting forms that are provided in the responses resulting from 588 the requests. The entry point URI could be obtained through some 589 discovery process or manual configuration. 591 If dereferencing the entry point URI yields a CoRAL document (or any 592 other representation that implements the CoRAL data and interaction 593 model), the agent makes this document the active representation in 594 the browsing context and proceeds as follows: 596 1. The first step for the agent is to decide what to do next, i.e., 597 which type of link to follow or form to submit, based on the link 598 relation types and operation types it understands. 600 An agent may follow a link without understanding the link 601 relation type, e.g., for the sake of pre-fetching or building a 602 search index. However, an agent MUST NOT submit a form without 603 understanding the operation type. 605 2. The agent then finds the link(s) or form(s) with the respective 606 type in the active representation. This may yield one or more 607 candidates, from which the agent will have to select the most 608 appropriate one. The set of candidates can be empty, for 609 example, when an application state transition is not supported or 610 not allowed. 612 3. The agent selects one of the candidates based on the metadata 613 associated them (in the form of form fields and nested elements) 614 and their order of appearance in the document. Examples for 615 relevant metadata could include the indication of a media type 616 for the target resource representation, the URI scheme of a 617 target resource, or the request method of an operation. 619 4. The agent obtains the _request URI_ from the link target or 620 submission target. Fragment identifiers are not part of the 621 request URI and MUST be separated from the rest of the URI prior 622 to the next step. 624 5. The agent constructs a new request with the request URI. If the 625 agent is following a link, then the request method MUST be GET. 626 If the agent is submitting a form, then the request method MUST 627 be the one supplied by the form. 629 The agent SHOULD set HTTP header fields and CoAP request options 630 according to the metadata (e.g., set the HTTP Accept header field 631 or the CoAP Accept option when a media type for the target 632 resource is provided). Depending on the operation type of a 633 form, the agent may also have to include a request payload that 634 matches the specifications of some form fields. 636 6. The agent sends the request and receives the response. 638 7. If a fragment identifier was separated from the request URI, the 639 agent selects the fragment indicated by the fragment identifier 640 within the received representation according to the semantics of 641 its media type. 643 8. The agent updates the browsing context by making the (selected 644 fragment of the) received representation the active 645 representation. 647 9. Finally, the agent processes the representation according to the 648 semantics of its media type. If the representation is a CoRAL 649 document (or any other representation that implements the CoRAL 650 data and interaction model), the agent again has the choice of 651 what to do next. Go to step 1. 653 2.9. History Traversal 655 A browsing context has a _session history_, which lists the resource 656 representations that the agent has processed, is processing, or will 657 process. 659 A session history consists of session history entries. The number of 660 session history entries may be limited and dependent on the agent. 661 An agent with severe constraints on memory size might only have 662 enough memory for the most recent entry. 664 An entry in the session history consists of a resource representation 665 and the representation's retrieval context. New entries are added to 666 the session history as the agent navigates from resource to resource, 667 discarding entries that are no longer used. 669 An agent can decide to navigate a browsing context (in addition to 670 following links and submitting forms) by _traversing the session 671 history_. For example, when an agent receives a response with a 672 representation that does not contain any further links or forms, it 673 can navigate back to a resource representation it has visited earlier 674 and make that the active representation. 676 Traversing the history SHOULD take advantage of caches to avoid new 677 requests. An agent may reissue a safe request (e.g., a GET) when it 678 does not have a fresh representation in its cache. An agent MUST NOT 679 reissue an unsafe request (e.g., a PUT or POST) unless it actually 680 intends to perform that operation again. 682 2.10. Designing interactions in an Open World 684 CoRAL can be used to build both open world systems ("if something is 685 not said, it may or may not be true") and closed world systems ("if 686 something is not said, it is not true"). 688 In constrained environments (and the web in general), partial 689 representations are often used for efficiency. For example, a device 690 can query another for particular statements using a yet to be defined 691 FETCH version of CoRAL. It is expected that some tools (e.g., server 692 or agent libraries) require the application to be tolerant of 693 unprocessed statements. Furthermore, it can be easier to evolve 694 applications and their packing dictionaries if loss of statements 695 leads to graceful degradation. 697 Therefore, it is convenient to build applications on open world 698 assumptions. Such applications can only use statements that add 699 possibilities, and none that limit interactions. Any limitations 700 need to be encoded in statements the agent necesarily has to perform 701 an action in the first place, and can then be relaxed in additional 702 statements. 704 For example, an application built with open-world assumptions can not 705 create a form that allows feeding gremlins, and in an additional 706 statement (e.g., a form field) forbid after midnight. Instead, the 707 application needs to describe a limited-feeding form, which can only 708 be used if any of the attached conditions is met; the condition 709 "before midnight" can then be expressed in an additional statement. 711 3. Binary Format 713 This section defines the encoding of documents in the CoRAL binary 714 format. 716 A document in the binary format is encoded in Concise Binary Object 717 Representation (CBOR) [RFC8949]. 719 The CBOR structure of a document is presented in the Concise Data 720 Definition Language (CDDL) [RFC8610]. All CDDL rules not defined in 721 this document are defined in Appendix D of [RFC8610]. 723 The media type of documents in the binary format is application/ 724 coral+cbor. 726 3.1. Data Structure 728 The data structure of a document in the binary format is made up of 729 three kinds of elements: links, forms (as short hands for the 730 statements they are constructed of), and (as an extension to the 731 CoRAL data model) directives. Directives provide a way to encode URI 732 references with a common base more efficiently. 734 3.1.1. Documents 736 A document in the binary format is encoded as a CBOR array that 737 contains zero or more elements. An element is either a link, a form, 738 or a directive. 740 document = [*element] 741 element = link / form / directive 743 The elements are processed in the order they appear in the document. 744 Document processors need to maintain an _environment_ while iterating 745 an array of elements. The environment consists of two variables: the 746 _current context_ and the _current base_. The current context and the 747 current base are both initially set to the document's retrieval 748 context. 750 3.1.2. Directives 752 Directives provide the ability to manipulate the environment while 753 processing elements. 755 There is a single type of directives available: the Base directive. 757 directive = base-directive 759 It is an error if a document processor encounters any other type of 760 directive. 762 3.1.2.1. Base Directives 764 A Base directive is encoded as a CBOR array that contains the 765 unsigned integer 1 and a base URI. 767 base-directive = [1, baseURI] 769 The base URI is denoted by a Constrained Resource Identifier (CRI) 770 reference [I-D.ietf-core-href]. The CRI reference MUST be resolved 771 against the current context (not the current base). 773 baseURI = CRI-Reference 774 CRI-Reference = 776 The directive is processed by resolving the CRI reference against the 777 current context and assigning the result to the current base. 779 3.1.3. URIs 781 URIs in links and forms are encoded as CRI references. 783 URI = CRI-Reference 785 A CRI reference is processed by resolving it to a URI as specified in 786 Section 5.2 of [I-D.ietf-core-href] using the current base. 788 3.1.4. Links 790 A link is encoded as a CBOR array that contains the unsigned integer 791 2, the link relation type, the link target, and, optionally, an array 792 of zero or more nested elements. 794 link = [2, relation-type, link-target, ?[*element]] 796 The link relation type is a URI. 798 relation-type = URI 800 The link target is either a URI, a literal value, or null. 802 link-target = URI / literal / null 803 literal = bool / int / float / time / bytes / text 805 The nested elements, if any, MUST be processed in a fresh 806 environment. The current context is set to the link target of the 807 enclosing link. The current base is initially set to the link 808 target, if the link target is a URI; otherwise, it is set to the 809 current base of the current environment. 811 3.1.5. Forms 813 A form is encoded as a CBOR array that contains the unsigned integer 814 3, the operation type, the submission target, and, optionally, an 815 array of zero or more form fields. 817 form = [3, operation-type, submission-target, ?[*form-field]] 819 The operation type is a URI. 821 operation-type = URI 823 The submission target is a URI. 825 submission-target = URI 827 The request method is either implied by the operation type or encoded 828 as a form field. If both are given, the form field takes precedence 829 over the operation type. Either way, the method MUST be applicable 830 to the Web transfer protocol identified by the scheme of the 831 submission target. 833 The form fields, if any, MUST be processed in a fresh environment. 834 The current context is set to an unspecified URI that represents the 835 enclosing form. The current base is initially set to the submission 836 target of the enclosing form. 838 3.1.6. Form Fields 840 A form field is encoded as a CBOR sequence that consists of a form 841 field type, a form field value, and, optionally, an array of zero or 842 more nested elements. 844 form-field = (form-field-type, form-field-value, ?[*element]) 846 The form field type is a URI. 848 form-field-type = URI 850 The form field value is either a URI, a literal value, or null. 852 form-field-value = URI / literal / null 854 The nested elements, if any, MUST be processed in a fresh 855 environment. The current context is set to the form field value of 856 the enclosing form field. The current base is initially set to the 857 form field value, if the form field value is a URI; otherwise, it is 858 set to the current base of the current environment. 860 3.2. Dictionary Compression 862 A document in the binary format MAY reference values from an external 863 dictionary using Packed CBOR [I-D.ietf-cbor-packed]. This helps to 864 reduce representation size and processing cost. 866 Dictionary references can be used subject to [ yet to be defined ] 867 profiling. 869 Implementers should note that Packed CBOR is not designed to be 870 uncompressed, but to be used in a compressed form. In particular, 871 constrained devices may operate without even knowing what a given 872 dictionary entry expands to (as long as they know its meaning) . 874 3.2.1. Media Type Parameter 876 The application/coral+cbor media type for documents in the binary 877 format is defined to have a dictionary parameter that specifies the 878 dictionary in use. The dictionary is identified by a URI. For 879 example, a CoRAL document that uses the dictionary identified by the 880 URI would have the following content 881 type: 883 application/coral+cbor;dictionary="http://example.com/dictionary" 885 The URI serves only as an identifier; it does not necessarily have to 886 be dereferencable (or even use a dereferencable URI scheme). It is 887 permissible, though, to use a dereferencable URI and to serve a 888 representation that provides information about the dictionary in a 889 machine- or human-readable way. (The representation format and 890 security considerations of such a representation are outside the 891 scope of this document.) 893 For simplicity, a CoRAL document can reference values only from one 894 dictionary; the value of the dictionary parameter MUST be a single 895 URI. 897 The dictionary parameter is OPTIONAL. If it is absent, the default 898 dictionary specified in Appendix B of this document is assumed. 900 Once a dictionary has made an assignment, the assignment MUST NOT be 901 changed or removed. A dictionary, however, may contain additional 902 information about an assignment, which may change over time. 904 In CoAP, media types (including specific values for their parameters, 905 plus an optional content coding) are encoded as an unsigned integer 906 called the "content format" of a representation. For use with CoAP, 907 each new CoRAL dictionary therefore needs to have a new content 908 format registered in the CoAP Content Formats Registry 909 [CORE-PARAMETERS]. 911 3.3. Export Interface 913 The definition of documents, links, and forms in the CoRAL binary 914 format can be reused in other CBOR-based protocols. Specifications 915 using CDDL should reference the following rules for this purpose: 917 CoRAL-Document = document 918 CoRAL-Link = link 919 CoRAL-Form = form 921 For each embedded document, link, and form, the CBOR-based protocol 922 needs to specify the document retrieval context, link context, and 923 form context, respectively. 925 4. Document Semantics 927 4.1. Submitting Documents 929 By default, a CoRAL document is a representation that captures the 930 current state of a resource. The meaning of a CoRAL document changes 931 when it is submitted in a request. Depending on the request method, 932 the CoRAL document can capture the intended state of a resource (PUT) 933 or be subject to application-specific processing (POST). 935 4.1.1. PUT Requests 937 A PUT request with a CoRAL document enclosed in the request payload 938 requests that the state of the target resource be created or replaced 939 with the state described by the CoRAL document. A successful PUT of 940 a CoRAL document generally means that a subsequent GET on that same 941 target resource would result in an equivalent document being sent in 942 a success response. 944 An origin server SHOULD verify that a submitted CoRAL document is 945 consistent with any constraints the server has for the target 946 resource. When a document is inconsistent with the target resource, 947 the origin server SHOULD either make it consistent (e.g., by removing 948 inconsistent elements) or respond with an appropriate error message 949 containing sufficient information to explain why the document is 950 unsuitable. 952 The retrieval context and the base URI of a CoRAL document in a PUT 953 are the request URI of the request. 955 4.1.2. POST Requests 957 A POST request with a CoRAL document enclosed in the request payload 958 requests that the target resource process the CoRAL document 959 according to the resource's own specific semantics. 961 The retrieval context of a CoRAL document in a POST is defined by the 962 target resource's processing semantics; it may be an unspecified URI. 963 The base URI of the document is the request URI of the request. 965 4.2. Returning Documents 967 In a response, the meaning of a CoRAL document changes depending on 968 the request method and the response status code. For example, a 969 CoRAL document in a successful response to a GET represents the 970 current state of the target resource, whereas a CoRAL document in a 971 successful response to a POST might represent either the processing 972 result or the new resource state. A CoRAL document in an error 973 response represents the error condition, usually describing the error 974 state and what next steps are suggested for resolving it. 976 4.2.1. Success Responses 978 Success responses have a response status code that indicates that the 979 client's request was successfully received, understood, and accepted 980 (2xx in HTTP, 2.xx in CoAP). When the representation in a success 981 response does not describe the state of the target resource, it 982 describes result of processing the request. For example, when a 983 request has been fulfilled and has resulted in one or more new 984 resources being created, a CoRAL document in the response can link to 985 and describe the resource(s) created. 987 The retrieval context and the base URI of a CoRAL document 988 representing the current state of a resource are the request URI of 989 the request. 991 The retrieval context of a CoRAL document representing a processing 992 result is an unspecified URI that refers to the processing result 993 itself. The base URI of the document is the request URI of the 994 request. 996 4.2.2. Redirection Responses 998 Redirection responses have a response status code that indicates that 999 further action needs to be taken by the agent (3xx in HTTP). A 1000 redirection response, for example, might indicate that the target 1001 resource is available at a different URI or the server offers a 1002 choice of multiple matching resources, each with its own specific 1003 URI. 1005 In the latter case, the representation in the response might contain 1006 a list of resource metadata and URI references (i.e., links) from 1007 which the agent can choose the most preferred one. 1009 The retrieval context of a CoRAL document representing such multiple 1010 choices in a redirection response is an unspecified URI that refers 1011 to the redirection itself. The base URI of the document is the 1012 request URI of the request. 1014 4.2.3. Error Responses 1016 Error response have a response status code that indicates that either 1017 the request cannot be fulfilled or the server failed to fulfill an 1018 apparently valid request (4xx or 5xx in HTTP, 4.xx or 5.xx in CoAP). 1019 A representation in an error response describes the error condition. 1021 The retrieval context of a CoRAL document representing such an error 1022 condition is an unspecified URI that refers to the error condition 1023 itself. The base URI of the document is the request URI of the 1024 request. 1026 5. Usage Considerations 1028 This section discusses some considerations in creating CoRAL-based 1029 applications and vocabularies. 1031 5.1. Specifying CoRAL-based Applications 1033 CoRAL-based applications naturally implement the Web architecture 1034 [W3C.REC-webarch-20041215] and thus are centered around orthogonal 1035 specifications for identification, interaction, and representation: 1037 * Resources are identified by URIs or represented by literal values. 1039 * Interactions are based on the hypermedia interaction model of the 1040 Web and the methods provided by the Web transfer protocol. The 1041 semantics of possible interactions are identified by link relation 1042 types and operation types. 1044 * Representations are CoRAL documents encoded in the binary format 1045 defined in Section 3. Depending on the application, additional 1046 representation formats may be used. 1048 5.1.1. Application Interfaces 1050 Specifications for CoRAL-based applications need to list the specific 1051 components used in the application interface and their identifiers. 1052 This should include the following items: 1054 * The Web transfer protocols supported. 1056 * The representation formats used, identified by their Internet 1057 media types, including the CoRAL serialization formats. 1059 * The link relation types used. 1061 * The operation types used. Additionally, for each operation type, 1062 the permissible request methods. 1064 * The form field types used. Additionally, for each form field 1065 type, the permissible form field values. 1067 5.1.2. Resource Identifiers 1069 URIs are a cornerstone of Web-based applications. They enable the 1070 uniform identification of resources and are used every time a client 1071 interacts with a server or a resource representation needs to refer 1072 to another resource. 1074 URIs often include structured application data in the path and query 1075 components, such as paths in a filesystem or keys in a database. It 1076 is a common practice in HTTP-based application programming interfaces 1077 (APIs) to make this part of the application specification, i.e., to 1078 prescribe fixed URI templates that are hard-coded in implementations. 1079 However, there are a number of problems with this practice [RFC8820]. 1081 In CoRAL-based applications, resource names are therefore not part of 1082 the application specification --- they are an implementation detail. 1083 The specification of a CoRAL-based application MUST NOT mandate any 1084 particular form of resource name structure. 1086 [RFC8820] describes the problematic practice of fixed URI structures 1087 in more detail and provides some acceptable alternatives. 1089 5.1.3. Implementation Limits 1091 This document places no restrictions on the number of elements in a 1092 CoRAL document or the depth of nested elements. Applications using 1093 CoRAL (in particular those running in constrained environments) may 1094 limit these numbers and define specific implementation limits that an 1095 implementation must support at least to be interoperable. 1097 Applications may also mandate the following and other restrictions: 1099 * Use of only either HTTP or CoAP as the supported Web transfer 1100 protocol. 1102 * Use of only dictionary references in the binary format for certain 1103 vocabulary. 1105 * Use of URI references and CRI references only up to a specific 1106 length. 1108 5.2. Minting Vocabulary 1110 New link relation types, operation types, and form field types can be 1111 minted by defining a URI that uniquely identifies the item. Although 1112 the URI may point to a resource that contains a definition of the 1113 semantics, clients SHOULD NOT automatically access that resource to 1114 avoid overburdening its server. The URI SHOULD be under the control 1115 of the person or party defining it, or be delegated to them. 1117 To avoid interoperability problems, it is RECOMMENDED that only URIs 1118 are minted that are normalized according to Section 6.2 of [RFC3986]. 1119 This is easily achieved when the URIs are defined in CRI form (in 1120 which they also become part of the dictionary), as this avoids many 1121 common non-normalized forms of URIs by construction. 1123 Non-normalized forms that are still to be avoided include: 1125 * Uppercase characters in scheme names and domain names 1127 * Explicitly stated HTTP default port (e.g., 1128 is preferable over ) 1130 * Punycode-encoding of Internationalized Domain Names in URIs 1132 * URIs that are not in Unicode Normalization Form C 1134 URIs that identify vocabulary do not need to be registered. The 1135 inclusion of domain names in URIs allows for the decentralized 1136 creation of new URIs without the risk of collisions. 1138 However, URIs can be relatively verbose and impose a high overhead on 1139 a representation. This can be a problem in constrained environments 1140 [RFC7228]. Therefore, CoRAL alternatively allows the use of packed 1141 references that abbreviate CBOR data items from a dictionary, as 1142 specified in Section 3.2. These impose a much smaller overhead but 1143 instead need to be assigned by an authority to avoid collisions. 1145 5.3. Expressing Registered Link Relation Types 1147 Link relation types registered in the Link Relations Registry 1148 [LINK-RELATIONS], such as collection [RFC6573] or icon 1149 [W3C.REC-html52-20171214], can be used in CoRAL by appending the 1150 registered name to the URI : 1153 #using iana = 1155 iana:collection 1156 iana:icon 1158 The convention of appending the relation type name to the prefix 1159 to form URIs is adopted 1160 from the Atom Syndication Format [RFC4287]; see also Appendix A.2 of 1161 [RFC8288]. 1163 Note that registered relation type names are required to be lowercase 1164 ASCII letters (see Section 3.3 of [RFC8288]). 1166 5.4. Expressing Simple RDF Statements 1168 In RDF [W3C.REC-rdf11-concepts-20140225], a statement says that some 1169 relationship, indicated by a predicate, holds between two resources. 1170 Existing RDF vocabularies can therefore be a good source for link 1171 relation types that describe resource metadata. For example, a CoRAL 1172 document could use the FOAF vocabulary [FOAF] to describe the person 1173 or software that made it: 1175 #using rdf = 1176 #using foaf = 1178 foaf:maker null { 1179 rdf:type 1180 foaf:familyName "Hartke" 1181 foaf:givenName "Klaus" 1182 foaf:mbox 1183 } 1185 5.5. Expressing Natural Language Texts 1187 Text strings can be associated with a Language Tag [RFC5646] and a 1188 base text direction (right-to-left or left-to-right) by using CBOR 1189 tag 38. 1191 #using base = 1192 #using iana = 1194 iana:terms-of-service { 1195 base:title 38(["de", "Nutzungsbedingungen"]) 1196 base:title 38(["en-US", "Terms of use"]) 1197 base:title 38(["az", "ltr", "İstifadə şərtləri"]) 1198 } 1200 [ Maturity note: Whether direction will actually be expressed in an 1201 updated tag 38, how precisely that is done, or whether a new tag will 1202 be allocated for text with direction is currently still under 1203 discussion. ] 1205 5.6. Embedding Representations in CoRAL 1207 When a document links to many Web resources and an agent needs a 1208 representation of each of them, it can be inefficient to retrieve 1209 each representations individually. To minimize round-trips, 1210 documents can embed representations of resources. 1212 A representation can be embedded in a document by including a link of 1213 type : 1215 #using base = 1216 #using http = 1217 #using iana = 1219 iana:icon { 1220 base:representation 1221 b64'R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAIAOw==' { 1222 http:type "image/gif" 1223 } 1224 } 1226 An embedded representation SHOULD have a nested link of type 1227 or 1228 that indicates the content type of the representation. 1230 The link relation types , 1231 , and 1232 are defined in Appendix A. 1234 6. Security Considerations 1236 CoRAL document processors need to be fully prepared for all types of 1237 hostile input that may be designed to corrupt, overrun, or achieve 1238 control of the agent processing the document. For example, hostile 1239 input may be constructed to overrun buffers, allocate very big data 1240 structures, or exhaust the stack depth by setting up deeply nested 1241 elements. Processors need to have appropriate resource management to 1242 mitigate these attacks. 1244 CoRAL serialization formats intentionally do not feature the 1245 equivalent of XML entity references so as to preclude the entire 1246 class of attacks relating to them, such as exponential XML entity 1247 expansion ("billion laughs") [CAPEC-197] and malicious XML entity 1248 linking [CAPEC-201]. 1250 Implementers of the CoRAL binary format need to consider the security 1251 aspects of decoding CBOR. See Section 10 of [RFC8949] for security 1252 considerations relating to CBOR. In particular, different number 1253 encodings for the same numeric value are not equivalent in CoRAL 1254 (e.g., a floating-point value of 0.0 is not the same as the integer 1255 0). 1257 CoRAL makes extensive use of resource identifiers. See Section 7 of 1258 [RFC3986] for security considerations relating to URIs. See 1259 Section 7 of [I-D.ietf-core-href] for security considerations 1260 relating to CRIs. 1262 The security of applications using CoRAL can depend on the proper 1263 preparation and comparison of internationalized strings. For 1264 example, such strings can be used to make authentication and 1265 authorization decisions, and the security of an application could be 1266 compromised if an entity providing a given string is connected to the 1267 wrong account or online resource based on different interpretations 1268 of the string. See [RFC6943] for security considerations relating to 1269 identifiers in URIs and other strings. 1271 CoRAL is intended to be used in conjunction with a Web transfer 1272 protocol like HTTP or CoAP. See Section 9 of [RFC7230], Section 9 of 1273 [RFC7231], etc., for security considerations relating to HTTP. See 1274 Section 11 of [RFC7252] for security considerations relating to CoAP. 1276 CoRAL does not define any specific mechanisms for protecting the 1277 confidentiality and integrity of CoRAL documents. It relies on 1278 security mechanisms on the application layer or transport layer for 1279 this, such as Transport Layer Security (TLS) [RFC8446]. 1281 CoRAL documents and the structure of a web of resources revealed from 1282 automatically following links can disclose personal information and 1283 other sensitive information. Implementations need to prevent the 1284 unintentional disclosure of such information. See Section 9 of 1285 [RFC7231] for additional considerations. 1287 Applications using CoRAL ought to consider the attack vectors opened 1288 by automatically following, trusting, or otherwise using links and 1289 forms in CoRAL documents. See Section 5 of [RFC8288] for related 1290 considerations. 1292 In particular, when a CoRAL document is the representation of a 1293 resource, the server that is authoritative for that resource may not 1294 necessarily be authoritative for nested elements in the document. In 1295 this case, unless an application defines specific rules, any link or 1296 form where the link/form context and the document's retrieval context 1297 do not share the same Web Origin [RFC6454] should be discarded 1298 ("same-origin policy"). 1300 7. IANA Considerations 1302 7.1. Media Type "application/coral+cbor" 1304 This document registers the media type application/coral+cbor 1305 according to the procedures of [RFC6838]. 1307 Type name: 1308 application 1310 Subtype name: 1311 coral+cbor 1313 Required parameters: 1314 N/A 1316 Optional parameters: 1317 dictionary - See Section 3.2 of [I-D.ietf-core-coral]. 1319 Encoding considerations: 1320 binary - See Section 3 of [I-D.ietf-core-coral]. 1322 Security considerations: 1323 See Section 6 of [I-D.ietf-core-coral]. 1325 Interoperability considerations: 1326 N/A 1328 Published specification: 1329 [I-D.ietf-core-coral] 1331 Applications that use this media type: 1332 See Section 1 of [I-D.ietf-core-coral]. 1334 Fragment identifier considerations: 1335 As specified for application/cbor. 1337 Additional information: 1338 Deprecated alias names for this type: N/A 1339 Magic number(s): N/A 1340 File extension(s): .coral.cbor 1341 Macintosh file type code(s): N/A 1343 Person & email address to contact for further information: 1344 See the Author's Address section of [I-D.ietf-core-coral]. 1346 Intended usage: 1347 COMMON 1349 Restrictions on usage: 1350 N/A 1352 Author: 1353 See the Author's Address section of [I-D.ietf-core-coral]. 1355 Change controller: 1356 IESG 1358 Provisional registration? 1359 No 1361 7.2. CoAP Content Formats 1363 This document registers CoAP content formats for the content types 1364 application/coral+cbor and text/coral according to the procedures of 1365 [RFC7252]. 1367 * Content Type: application/coral+cbor 1368 Content Coding: identity 1369 ID: TBD3 1370 Reference: [I-D.ietf-core-coral] 1372 [[NOTE TO RFC EDITOR: Please replace all occurrences of TBD3 in this 1373 document with the code points assigned by IANA.]] 1375 [[NOTE TO IMPLEMENTERS: Experimental implementations may use content 1376 format ID 65087 for application/coral+cbor until IANA has assigned 1377 code points.]] 1379 8. References 1381 8.1. Normative References 1383 [I-D.bormann-cbor-edn-literals] 1384 Bormann, C., "Application-Oriented Literals in CBOR 1385 Extended Diagnostic Notation", Work in Progress, Internet- 1386 Draft, draft-bormann-cbor-edn-literals-00, 6 October 2021, 1387 . 1390 [I-D.ietf-cbor-packed] 1391 Bormann, C., "Packed CBOR", Work in Progress, Internet- 1392 Draft, draft-ietf-cbor-packed-04, 13 February 2022, 1393 . 1396 [I-D.ietf-core-href] 1397 Bormann, C. and H. Birkholz, "Constrained Resource 1398 Identifiers", Work in Progress, Internet-Draft, draft- 1399 ietf-core-href-09, 15 January 2022, 1400 . 1403 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1404 Requirement Levels", BCP 14, RFC 2119, 1405 DOI 10.17487/RFC2119, March 1997, 1406 . 1408 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1409 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1410 . 1412 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1413 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1414 2003, . 1416 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1417 Resource Identifier (URI): Generic Syntax", STD 66, 1418 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1419 . 1421 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1422 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1423 . 1425 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1426 Specifications: ABNF", STD 68, RFC 5234, 1427 DOI 10.17487/RFC5234, January 2008, 1428 . 1430 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1431 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1432 September 2009, . 1434 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1435 DOI 10.17487/RFC6454, December 2011, 1436 . 1438 [RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding 1439 "charset" Parameter Handling in Textual Media Types", 1440 RFC 6657, DOI 10.17487/RFC6657, July 2012, 1441 . 1443 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1444 Specifications and Registration Procedures", BCP 13, 1445 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1446 . 1448 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1449 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1450 May 2017, . 1452 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1453 Definition Language (CDDL): A Notational Convention to 1454 Express Concise Binary Object Representation (CBOR) and 1455 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1456 June 2019, . 1458 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1459 Representation (CBOR)", STD 94, RFC 8949, 1460 DOI 10.17487/RFC8949, December 2020, 1461 . 1463 [Unicode] The Unicode Consortium, "The Unicode Standard, Version 1464 13.0.0", ISBN 978-1-936213-26-9, March 2020, 1465 . 1467 8.2. Informative References 1469 [CAPEC-197] 1470 MITRE, "CAPEC-197: XML Entity Expansion", September 2019, 1471 . 1473 [CAPEC-201] 1474 MITRE, "CAPEC-201: XML Entity Linking", September 2019, 1475 . 1477 [CORE-PARAMETERS] 1478 IANA, "Constrained RESTful Environments (CoRE) 1479 Parameters", 1480 . 1482 [FOAF] Brickley, D. and L. Miller, "FOAF Vocabulary Specification 1483 0.99", January 2014, 1484 . 1486 [HAL] Kelly, M., "JSON Hypertext Application Language", Work in 1487 Progress, Internet-Draft, draft-kelly-json-hal-08, 12 May 1488 2016, . 1491 [HTTP-METHODS] 1492 IANA, "Hypertext Transfer Protocol (HTTP) Method 1493 Registry", 1494 . 1496 [I-D.ietf-httpapi-linkset] 1497 Wilde, E. and H. V. D. Sompel, "Linkset: Media Types and a 1498 Link Relation Type for Link Sets", Work in Progress, 1499 Internet-Draft, draft-ietf-httpapi-linkset-08, 8 February 1500 2022, . 1503 [LINK-RELATIONS] 1504 IANA, "Link Relations", 1505 . 1507 [MEDIA-TYPES] 1508 IANA, "Media Types", 1509 . 1511 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1512 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 1513 December 2005, . 1515 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1516 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1517 . 1519 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 1520 RFC 6573, DOI 10.17487/RFC6573, April 2012, 1521 . 1523 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1524 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1525 . 1527 [RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for 1528 Security Purposes", RFC 6943, DOI 10.17487/RFC6943, May 1529 2013, . 1531 [RFC7089] Van de Sompel, H., Nelson, M., and R. Sanderson, "HTTP 1532 Framework for Time-Based Access to Resource States -- 1533 Memento", RFC 7089, DOI 10.17487/RFC7089, December 2013, 1534 . 1536 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1537 Constrained-Node Networks", RFC 7228, 1538 DOI 10.17487/RFC7228, May 2014, 1539 . 1541 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1542 Protocol (HTTP/1.1): Message Syntax and Routing", 1543 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1544 . 1546 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1547 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1548 DOI 10.17487/RFC7231, June 2014, 1549 . 1551 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1552 Application Protocol (CoAP)", RFC 7252, 1553 DOI 10.17487/RFC7252, June 2014, 1554 . 1556 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1557 FETCH Methods for the Constrained Application Protocol 1558 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1559 . 1561 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1562 DOI 10.17487/RFC8288, October 2017, 1563 . 1565 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1566 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1567 . 1569 [RFC8820] Nottingham, M., "URI Design and Ownership", BCP 190, 1570 RFC 8820, DOI 10.17487/RFC8820, June 2020, 1571 . 1573 [UAX31] The Unicode Consortium, "Unicode Standard Annex #31: 1574 Unicode Identifier and Pattern Syntax", Revision 33, March 1575 2020, . 1577 [UTR36] The Unicode Consortium, "Unicode Technical Report #36: 1578 Unicode Security Considerations", Revision 15, September 1579 2014, . 1581 [UTS39] The Unicode Consortium, "Unicode Technical Standard #39: 1582 Unicode Security Mechanisms", Revision 22, February 2020, 1583 . 1585 [W3C.REC-html52-20171214] 1586 Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and 1587 S. Moon, "HTML 5.2", World Wide Web Consortium 1588 Recommendation REC-html52-20171214, 14 December 2017, 1589 . 1591 [W3C.REC-rdf-schema-20140225] 1592 Brickley, D. and R. Guha, "RDF Schema 1.1", World Wide Web 1593 Consortium Recommendation REC-rdf-schema-20140225, 25 1594 February 2014, 1595 . 1597 [W3C.REC-rdf11-concepts-20140225] 1598 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 1599 Concepts and Abstract Syntax", World Wide Web Consortium 1600 Recommendation REC-rdf11-concepts-20140225, 25 February 1601 2014, 1602 . 1604 [W3C.REC-turtle-20140225] 1605 Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", 1606 World Wide Web Consortium Recommendation REC-turtle- 1607 20140225, 25 February 2014, 1608 . 1610 [W3C.REC-webarch-20041215] 1611 Jacobs, I. and N. Walsh, "Architecture of the World Wide 1612 Web, Volume One", World Wide Web Consortium 1613 Recommendation REC-webarch-20041215, 15 December 2004, 1614 . 1616 Appendix A. Core Vocabulary 1618 This section defines the core vocabulary for CoRAL: a set of link 1619 relation types, operation types, and form field types. 1621 A.1. Base 1623 Link Relation Types: 1625 1626 Indicates that the link's context is an instance of the class 1627 specified as the link's target, as defined by RDF Schema 1628 [W3C.REC-rdf-schema-20140225]. 1630 1631 Indicates that the link target is a human-readable label (e.g., a 1632 menu entry). 1634 The link target MUST be a literal. The text string SHOULD be 1635 wrapped in a tag indicating language and, if necessary, direction 1636 if applicable. 1638 1639 Indicates that the link target is a representation of the link 1640 context. 1642 The link target MUST be a byte string. 1644 The representation may be a full, partial, or inconsistent version 1645 of the representation served from the URI of the resource. 1647 A link with this link relation type can occur as a top-level 1648 element in a document or as a nested element within a link. When 1649 it occurs as a top-level element, it provides an alternate 1650 representation of the document's retrieval context. When it 1651 occurs nested within a link, it provides a representation of link 1652 target of the enclosing link. 1654 Operation Types: 1656 1657 Indicates that the state of the form's context can be replaced 1658 with the state described by a representation submitted to the 1659 server. 1661 This operation type defaults to the PUT method [RFC7231] [RFC7252] 1662 for both HTTP and CoAP. Typical overrides by a form field include 1663 the PATCH method [RFC5789] [RFC8132] for HTTP and CoAP and the 1664 iPATCH method [RFC8132] for CoAP. 1666 1667 Indicates that the form's context can be searched by submitting a 1668 search query. 1670 This operation type defaults to the POST method [RFC7231] for HTTP 1671 and the FETCH method [RFC8132] for CoAP. Typical overrides by a 1672 form field include the POST method [RFC7252] for CoAP. 1674 A.2. Collections 1676 Link Relation Types: 1678 1679 Indicates that the link's context is a collection and that the 1680 link's target is a member of that collection, as defined in 1681 Section 2.1 of [RFC6573]. 1683 1684 Indicates that the link's target is a collection and that the 1685 link's context is a member of that collection, as defined in 1686 Section 2.2 of [RFC6573]. 1688 Operation Types: 1690 1691 Indicates that the form's context is a collection and that a new 1692 item can be created in that collection with the state defined by a 1693 representation submitted to the server. 1695 This operation type defaults to the POST method [RFC7231] 1696 [RFC7252] for both HTTP and CoAP. 1698 1699 Indicates that the form's context is a member of a collection and 1700 that the form's context can be removed from that collection. 1702 This operation type defaults to the DELETE method [RFC7231] 1703 [RFC7252] for both HTTP and CoAP. 1705 A.3. HTTP 1707 Form Field Types: 1709 1710 Specifies the HTTP method for the request. 1712 The form field value MUST be a text string in the format defined 1713 in Section 4.1 of [RFC7231]. The possible set of values is 1714 maintained in the HTTP Methods Registry [HTTP-METHODS]. 1716 A form field of this type MUST NOT occur more than once in a form. 1717 If absent, it defaults to the request method implied by the form's 1718 operation type. 1720 1721 Specifies an acceptable HTTP content type for the request payload. 1722 There may be multiple form fields of this type. If a form does 1723 not include a form field of this type, the server accepts any or 1724 no request payload, depending on the operation type. 1726 The form field value MUST be a text string in the format defined 1727 in Section 3.1.1.1 of [RFC7231]. The possible set of media types 1728 and their parameters is maintained in the Media Types Registry 1729 [MEDIA-TYPES]. 1731 Link Relation Types: 1733 1734 Specifies the HTTP content type of the link context. 1736 The link target MUST be a text string in the format defined in 1737 Section 3.1.1.1 of [RFC7231]. The possible set of media types and 1738 their parameters is maintained in the Media Types Registry 1739 [MEDIA-TYPES]. 1741 A.4. CoAP 1743 Form Field Types: 1745 1746 Specifies the CoAP method for the request. 1748 The form field value MUST be an integer identifying a CoAP method 1749 (e.g., the integer 2 for the POST method). The possible set of 1750 values is maintained in the CoAP Method Codes Registry 1751 [CORE-PARAMETERS]. 1753 A form field of this type MUST NOT occur more than once in a form. 1754 If absent, it defaults to the request method implied by the form's 1755 operation type. 1757 1758 Specifies an acceptable CoAP content format for the request 1759 payload. There may be multiple form fields of this type. If a 1760 form does not include a form field of this type, the server 1761 accepts any or no request payload, depending on the operation 1762 type. 1764 The form field value MUST be an integer identifying a CoAP content 1765 format. The possible set of values is maintained in the CoAP 1766 Content Formats Registry [CORE-PARAMETERS]. 1768 Link Relation Types: 1770 1771 Specifies the CoAP content format of the link context. 1773 The link target MUST be an integer identifying a CoAP content 1774 format (e.g., the integer 42 for the content type application/ 1775 octet-stream without a content coding). The possible set of 1776 values is maintained in the CoAP Content Formats Registry 1777 [CORE-PARAMETERS]. 1779 Appendix B. Default Dictionary 1781 This section defines a default dictionary that is assumed when the 1782 application/coral+cbor media type is used without a dictionary 1783 parameter. 1785 +=====+=======================================================+ 1786 | Key | Value | 1787 +=====+=======================================================+ 1788 | 0 | | 1789 +-----+-------------------------------------------------------+ 1790 | 1 | | 1791 +-----+-------------------------------------------------------+ 1792 | 2 | | 1793 +-----+-------------------------------------------------------+ 1794 | 3 | | 1795 +-----+-------------------------------------------------------+ 1796 | 4 | | 1797 +-----+-------------------------------------------------------+ 1798 | 5 | | 1799 +-----+-------------------------------------------------------+ 1800 | 6 | | 1801 +-----+-------------------------------------------------------+ 1802 | 7 | | 1803 +-----+-------------------------------------------------------+ 1804 | 8 | | 1805 +-----+-------------------------------------------------------+ 1806 | 10 | | 1807 +-----+-------------------------------------------------------+ 1808 | 14 | | 1809 +-----+-------------------------------------------------------+ 1811 Table 3: Default Dictionary 1813 Appendix C. Mappings to other formats 1815 While CoRAL has an information model of its own, its data can be 1816 converted to different extents with other data formats. 1818 Using these conversions is generally application specific, i.e., this 1819 document does not claim equivalence of (say) a given RDF its 1820 converted CoRAL document, but applications can choose use these 1821 conversions if the limitations described with the conversion are 1822 acceptable to them. 1824 C.1. RDF 1826 [ TBD: Expand / introduce the common CURIEs used here. ] 1828 RDF and the CoRAL Basic Information Model can be interconverted 1829 losslessly, as long as some basic restrictions are met: 1831 * All involved IRIs (on the RDF side) and CRIs (on the CoRAL side) 1832 can be converted; that means that round-tripping IRIs through 1833 CoRAL converts them to the equivalent URIs. 1835 The precise limitations of what CRIs can not express are described 1836 in [I-D.ietf-core-href] and out of scope of this document. 1838 A possible extension to CoRAL that allows tagged URIs in place of 1839 CRIs could remove this limitation. (CRIs that can not be 1840 expressed as URIs are not valid anyway). 1842 * A blank node of CoRAL can only have one incoming edge in 1843 serialization. RDF documents with multiply connected blank nodes 1844 need to undergo skolemization before they can be expressed in 1845 CoRAL. 1847 * CoRAL supports arbitrary literal objects, including CBOR tags. 1848 For each object that is used in a literal, a mapping to a datatype 1849 (typically XSD) needs to be defined. 1851 When literals are normalized in RDF according to XSD rules, or the 1852 literal mappings to RDF datatypes are ambiguous on the CoRAL side, 1853 round-tripping CoRAL through RDF can be lossy to the extent of the 1854 normalization or ambiguity. 1856 * As always with expressing arbitrary graphs of the Basic 1857 Information Model in serialization, if there is no directed tree 1858 spanning the directed graph, statements need to be introduced to 1859 reach some topics. 1861 Each statement in RDF is mapped to a statement in CoRAL. Any IRI it 1862 contains in RDF is mapped to an equivalent CRI in CoRAL and vice 1863 versa. Any blank node of RDF is converted to a blank node 1864 (serialized as a null) in CoRAL. (Beware that depending on the 1865 context established in Section 4, the retrieval context may be a URI 1866 or a blank node). Literals are converted as follows: 1868 * CBOR text strings are coverted to RDF string literals without a 1869 language tag. 1871 * CBOR literals from the following list are converted to their 1872 corresponding text representations of the datatype from the 1873 following table: 1875 +=========================+=========================+ 1876 | CDDL | XSD datatype | 1877 +=========================+=========================+ 1878 | bool | xsd:boolean | 1879 +-------------------------+-------------------------+ 1880 | integer | xsd:integer | 1881 +-------------------------+-------------------------+ 1882 | float | xsd:double | 1883 +-------------------------+-------------------------+ 1884 | decfrac | xsd:decimal | 1885 +-------------------------+-------------------------+ 1886 | bytes | xsd:base64Binary or | 1887 | | xsd:base64hexBinary (?) | 1888 +-------------------------+-------------------------+ 1889 | tdate | xsd:date | 1890 +-------------------------+-------------------------+ 1891 | #6.38([lang: tstr, | rdf:langString with | 1892 | text: tstr]) | lang as language tag | 1893 +-------------------------+-------------------------+ 1894 | #6.TBD([lang: tstr, | i18n:{lang}_{dir} | 1895 | dir: tstr, text: tstr]) | | 1896 +-------------------------+-------------------------+ 1898 Table 4: Mapping between CDDL types and XSD datatypes 1900 [ TBD: Check compatibilities, give type for at least the basic tags. 1901 Directional text might wind up in tag 38, ] 1903 * RDF literals are mapped to any CoRAL literal that yields an 1904 equivalent RDF literal in the opposite direction. 1906 C.1.1. Example 1908 The FOAF namespace provides this example: 1910 1911 Dan Brickley 1912 1913 1914 1915 1917 Figure 5: Original FOAF file at http://.../me.xml 1919 Converted, assuming no particular profiling or dictionary setup (and 1920 an ad-hoc table following Section 3.1 of [I-D.ietf-cbor-packed]), 1921 this could be: 1923 51([[cri'http://danbri.org/'], [<<-3, "xmlns.com", ["foaf", "0.1"], null>>], [], [ 1924 [2, cri'http://www.iana.org/assignments/relation/carries-information-about', cri'/me.xml#danbri', 1925 [2, cri'http://www.w3.org/1999/02/22-rdf-syntax-ns#type', 6(<<'Person'>>)], 1926 [2, 6(<<'name'>>), "Dan Brickley"], 1927 [2, 6(<<'homepage'>>), 6(0)], 1928 [2, 6(<<'openid'>>), 6(0)], 1929 [2, 6(<<'img'>>), cri'/images/me.jpg'] 1930 ] 1931 ]]) 1933 Figure 6: Serialized FOAF file at http://.../me.coral 1935 The TBD:talks-about statement is introduced to bridge the gap between 1936 the basic and the necessarily structured information model. [ TBD: 1937 Introduce that somewhere else more generally. ] 1939 In this packing, an invalid CRI (with trailing null leaving room for 1940 a fragment identifier to be added through packing) is added into the 1941 prefixes list. It is not sure whether this particular trick will 1942 ever be permitted by any of the profilings, or whether this is better 1943 done with base URIs. The mechanism is used because right now it 1944 works with the specifications involved without the need for further 1945 text, and is likely to be replaced by better mechanisms in later 1946 revisions of this document. 1948 C.2. CoRE Link Format 1950 Generic information in Web Links as described in [RFC8288] can not be 1951 converted to CoRAL in any practical way: Attributes are not managed, 1952 and it is not clear from the syntax whether an attribute is making a 1953 statement about the link or its target. (See Section 2.3.3.1 for an 1954 example). 1956 Applications that use links with the attribute semantics common in 1957 the CoRE ecosystem (typically used with [RFC6690] Link Format) can 1958 use this conversion. It defines terms for common properties used for 1959 discovering resources, and describes a way to compatibly extend the 1960 mapping. 1962 The same mechanism (but probably with a different mapping between 1963 names and attributes, and different rules about the necessity of 1964 packing entries) can be defined for any data model that builds on 1965 [RFC8288] semantics, e.g., the links sent in headers or payloads 1966 about [RFC7089] mementos, or applications building on 1967 [I-D.ietf-httpapi-linkset]. 1969 In several points the mapping describes URIs to necessarily have an 1970 entry in the packing table; this refers to the profiling described 1971 further down. Parts of a Link Format document that would need an 1972 entry but do not have one can not be converted; these are ignored in 1973 the conversion unless the converter is configured to be strict and 1974 fail the complete conversion in that case. 1976 This mapping from Link Format to CoRAL is performed as follows: * For 1977 each relation in a link, a statement is created mapping the link 1978 context to the subject, the link target to the object and the 1979 relation to the predicate. 1981 If the relation is of ext-rel-type, it is used as a URI as is. 1982 Otherwise it is a registered value, prefixed with 1983 http://www.iana.org/assignments/relation/ and necessarily packed 1984 using table TBD. (This is equivalent to the RPP mechanism for 1985 attribute values). 1987 * Each target attribute is converted to one or more statements by 1988 the mechanism indicated for the attribute name in the following 1989 table. Statements produced from a link have the target as its 1990 subject, the attribute name without any trailing asterisk 1991 (prefixed with https://TBD/ [ to be picked together with IANA as 1992 it'll be a registry ]) as its predicate, and the object(s) 1993 depending on the mechanism. 1995 Attributes are necessarily listed in this table. 1997 +=====+==========+=====================================+ 1998 | TN | Name | Mechanism | 1999 +=====+==========+=====================================+ 2000 | TBD | hreflang | [ do we need that? ] | 2001 +-----+----------+-------------------------------------+ 2002 | TBD | media | [ do we need that? ] | 2003 +-----+----------+-------------------------------------+ 2004 | 16 | title | string | 2005 +-----+----------+-------------------------------------+ 2006 | TBD | type | [ do we need that? ] | 2007 +-----+----------+-------------------------------------+ 2008 | 0 | rt | WSSP; RPP http://www.iana.org/TBDr/ | 2009 +-----+----------+-------------------------------------+ 2010 | 1 | if | WSSP; RPP http://www.iana.org/TBDi/ | 2011 +-----+----------+-------------------------------------+ 2012 | 2 | sz | int | 2013 +-----+----------+-------------------------------------+ 2014 | 3 | ct | WSSP; int | 2015 +-----+----------+-------------------------------------+ 2017 Table 5: Initial entries of the target attribute 2018 registry (TN = table number) 2020 Available mechanisms are: 2022 * SPSP (space split): Link format values are split at space 2023 characters (SP in the RFC6690 ABNF), and all values treated using 2024 another mechanism. 2026 * string: The attribute value is stored as a text string literal. 2027 If the Link Format attribute is language tagged (i.e. when the 2028 attribute name ends with an asterisk and the value is of ext-value 2029 shape), the literal is encapsulated in a CBOR language tag (38). 2031 * int: The target attribute is processed as an ASCII encoded number 2032 and expressed as an integer literal. A failing conversion is 2033 treated like an unknown registered value: It is ignored unless 2034 configured otherwise. 2036 * RPP (registered-prefix / packed): The input value (often the 2037 result of the SPSP mechanism) is parsed according to the relation- 2038 type ABNF production. If it is of ext-rel-type, it is expressed 2039 as that URI. If it is prefixed with the string indicated with the 2040 mechanism, and necessarily compressed through table TBD. 2042 All currently registered link attributes are used in the CoRE 2043 ecosystem as indicating a property of the target that is independent 2044 of the link being followed. If this conversion is to be extended to 2045 cover attributes that pertain to the full link being followed 2046 (typically along with one or more link relations), the relevant 2047 relations are not expressed as a single statement, but as a form, 2048 i.e. as two statements linking the context to a blank node and the 2049 blank node to the target; the attributes are attached to the blank 2050 node. The precise mechanism out of scope for this document, and left 2051 to those who first register such an attribute. 2053 Some structure can be carried over from Link Format to the structured 2054 model: The sequences of links gets reused, and the set and sequence 2055 of attributes in a particular occurrence of a link get applied to the 2056 statement produced from the link (or all the statements, if the link 2057 has multiple link relations). Statements whose subject is not the 2058 document itself are attached to the retrieval context using the 2059 necessarily packed http://www.iana.org/assignments/relation/carries- 2060 information-about property. Statements about URLs mentioned 2061 elsewhere in the document can be expressed there instead. 2063 Link relations of the reg-name form, link attributes, and attribute 2064 values from the RPP mechanism MUST be serialized using packed CBOR as 2065 initialized in table TBD. No other packing is used. A consumer MAY 2066 ignore any items compressed through the dictionary for which it does 2067 not know the expanded version: These necessarily represent statements 2068 that involve terms the consumer does not understand. 2070 [ As an alternative, packing attributes together with their URIs is 2071 considered: Rather than [2, 6(/ attr:rt /), 6(/ rt:core.rd /)] we 2072 could have 6(rt-core) right away; unregistered values would stay [2, 2073 6(/ attr:rt /), value] or maybe 254([value]) using prefix packing. ] 2075 Appendix D. Change Log 2077 This section is to be removed before publishing as an RFC. 2079 Changes from -04 to -05: 2081 * Literals can no longer have properties. The only use case was 2082 annotating languages and directions, and that can be done in CBOR. 2084 * Added section about open and close world modelling. 2086 * Information model merged with the previous data model and 2087 interaction section. 2089 Changes from -03 to -04: 2091 * Formalize information model, as basic and structured model. 2093 * Remove textual representation, using CBOR diagnostig notation 2094 instead. 2096 * Use Packed CBOR instead of custom dictionaries. 2098 * Give explicit conversions from Link Format and with RDF. 2100 * Remove references to IRIs (outside RDF) as CRIs are closer to 2101 URIs. 2103 * Remove requirement for deterministic encoding. 2105 * Many editorial changes. 2107 * Update references. 2109 * Change of authorship. 2111 Changes from -02 to -03: 2113 * Changed the binary format to express relation types, operation 2114 types and form field types using [I-D.ietf-core-href] (#2). 2116 * Clarified the current context and current base for nested elements 2117 and form fields (#53). 2119 * Minor editorial improvements (#27). 2121 Changes from -01 to -02: 2123 * Added nested elements to form fields. 2125 * Replaced the special construct for embedded representations with 2126 links. 2128 * Changed the textual format to allow simple/qualified names 2129 wherever IRI references are allowed. 2131 * Introduced predefined names in the textual format (#39). 2133 * Minor editorial improvements and bug fixes (#16 #28 #31 #37 #39). 2135 Changes from -00 to -01: 2137 * Added a section on the semantics of CoRAL documents in responses. 2139 * Minor editorial improvements. 2141 Acknowledgements 2143 The concept and original version of CoRAL (as well as CRIs) was 2144 developed by Klaus Hartke. It was heavily inspired by Mike Kelly's 2145 JSON Hypertext Application Language [HAL]. 2147 The recommendations for minting URIs have been adopted from RDF 1.1 2148 Concepts and Abstract Syntax [W3C.REC-rdf11-concepts-20140225] to 2149 ease the interoperability between RDF predicates and link relation 2150 types. 2152 Thanks to Carsten Bormann, Jaime Jiménez, Jim Schaad, Sebastian 2153 Käbisch, Ari Keränen, Michael Koster, Matthias Kovatsch and Niklas 2154 Widell for helpful comments and discussions that have shaped the 2155 document. 2157 Authors' Addresses 2159 Christian Amsüss 2160 Email: christian@amsuess.com 2162 Thomas Fossati 2163 ARM 2164 Email: thomas.fossati@arm.com