idnits 2.17.1 draft-montoya-xrel-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** There are 3 instances of too long lines in the document, the longest one being 22 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 26, 2019) is 1858 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: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 448 -- Looks like a reference, but probably isn't: '2' on line 450 -- Looks like a reference, but probably isn't: '3' on line 452 -- Looks like a reference, but probably isn't: '4' on line 454 == Unused Reference: 'RFC1738' is defined on line 391, but no explicit reference was found in the text == Unused Reference: 'RFC6901' is defined on line 405, but no explicit reference was found in the text == Unused Reference: 'RFC7320' is defined on line 410, but no explicit reference was found in the text == Unused Reference: 'REST' is defined on line 428, but no explicit reference was found in the text == Unused Reference: 'RFC8288' is defined on line 434, but no explicit reference was found in the text ** Obsolete normative reference: RFC 1738 (Obsoleted by RFC 4248, RFC 4266) ** Obsolete normative reference: RFC 7320 (Obsoleted by RFC 8820) Summary: 4 errors (**), 0 flaws (~~), 6 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Montoya 3 Internet-Draft Mountain State Software Solutions 4 Intended status: Informational February 26, 2019 5 Expires: August 30, 2019 7 Extended Link Relationships 8 draft-montoya-xrel-00 10 Abstract 12 This document defines XREL, a data format for describing extended 13 hypermedia relationships identified by Uniform Resource Locators. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at https://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on August 30, 2019. 32 Copyright Notice 34 Copyright (c) 2019 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (https://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 50 1.1. Definitions and Terminology . . . . . . . . . . . . . . . 2 51 1.1.1. Terminology and Conformance Language . . . . . . . . 3 52 1.1.2. General . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1.3. Documents description . . . . . . . . . . . . . . . . 4 54 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . 4 55 2. XREL Documents . . . . . . . . . . . . . . . . . . . . . . . 4 56 2.1. Format . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 2.2. Relationship Object . . . . . . . . . . . . . . . . . . . 5 58 2.2.1. Properties . . . . . . . . . . . . . . . . . . . . . 5 59 2.3. XREL Document . . . . . . . . . . . . . . . . . . . . . . 5 60 2.3.1. Document Example . . . . . . . . . . . . . . . . . . 5 61 2.4. XREL Collection Document . . . . . . . . . . . . . . . . 6 62 2.4.1. Document Example . . . . . . . . . . . . . . . . . . 6 63 2.5. Identifying XREL Documents . . . . . . . . . . . . . . . 6 64 2.6. Fragment identifiers . . . . . . . . . . . . . . . . . . 6 65 2.7. Identifying XREL Relationships . . . . . . . . . . . . . 6 66 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 67 3.1. application/xrel . . . . . . . . . . . . . . . . . . . . 7 68 4. Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . 8 69 5. Appendix B. Frequently Asked Questions . . . . . . . . . . . 8 70 5.1. How can I submit comments or feedback to the editors? . . 8 71 5.2. Why not include target attributes as defined by RFC8288 72 'Web Linking'? . . . . . . . . . . . . . . . . . . . . . 8 73 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 6.1. Normative References . . . . . . . . . . . . . . . . . . 9 75 6.2. Informative References . . . . . . . . . . . . . . . . . 10 76 6.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 10 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 79 1. Introduction 81 This document defines XREL, a data format for describing extended 82 hypermedia relationships identified by Uniform Resource Locators. 84 This document registers a media-type identifier with the IANA: 85 "application/xrel". This registration is for community review and 86 will be submitted to the IESG for review, approval, and registration 87 with IANA. 89 1.1. Definitions and Terminology 90 1.1.1. Terminology and Conformance Language 92 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 93 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 94 "OPTIONAL" in this document are to be interpreted as described in 95 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 96 capitals, as shown here. 98 1.1.2. General 100 Representational State Transfer, or *REST*, is an architectural style 101 for distributed hypermedia systems. Introduced and first defined in 102 2000 in Chapter 5, REST, of the doctoral dissertation "Architectural 103 Styles and the Design of Network-based Software Architecture" by Roy 104 Fielding. 106 *Hypermedia*, or hypertext, is defined by the presence of application 107 control information embedded within, or as a layer above, the 108 presentation of information. Hypermedia allows for a virtually 109 unbound network of resources while also guiding users through an 110 application as they navigate said relationships. 112 A *hypermedia relationship*, also known as a link relation, describes 113 the semantics behind a virtual uni-directional association between 114 two resources. 116 A *hypermedia relationship name* is an identifier for a hypermedia 117 relationship. 119 A *resource* is the intended conceptual target of a hypertext 120 reference. 122 *Representational state* indicates the current state of the requested 123 resource, the desired state for the requested resource, or the value 124 of some other resource, such as a representation of the input data 125 within a client's query form, or a representation of some error 126 condition for a response. 128 *Application state* is the state of the user's application of 129 computing to a given task, controlled and stored by the user agent 130 and can be composed of representations from multiple servers. 132 This document and the specification documented in it are heavily 133 influenced by the RAML 1.0 Spec [RAML]. 135 1.1.3. Documents description 137 A trailing question mark, for example *description?*, indicates an 138 optional property. 140 Throughout this specification, *markdown* means GitHub-Flavored 141 Markdown [github.md]. Tooling MAY choose to ignore some Markdown 142 features to address security concerns. 144 1.2. Motivation 146 The Uniform Interface constraint of the REST architectural style 147 dictates that hypermedia be the engine of application state. This 148 means that the state of the application and its potential transitions 149 are dictated by the presence of hypermedia relationships in-band and 150 by the navigation of those relationships by an user (human or 151 automated). In order for users to evaluate and select the 152 appropriate relationships to navigate they must rely on an out-band 153 understanding of relationships by their names. 155 While humans can derive meaning from relationship names in natural 156 language, automated agents have relied on a central repository of 157 standard names maintained by the Internet Assigned Numbers Authority 158 (IANA). Instead of creating and registering entirely new link 159 relations (i.e. "patient", "appointment", "schedulingService", etc.) 160 with a central repository, authors can choose to create an XREL 161 document; one that explains the vital, perhaps domain-specific, 162 semantics of the relationship and which is identified by an URL 163 controlled by the author. 165 This decentralization allows for a much lower entry barrier, which is 166 not inconsistent with the general concept of the web, and enables 167 different use cases. For example, a private organization is fully 168 capable of defining their own repository of XREL definitions outside 169 of the open Internet, after all standards are a byproduct of 170 authority. Conversely, public XREL definitions would allow for 171 serendipitous reuse, where useful relationships backed by stable URLs 172 might be discovered and possibly become de facto standard. 174 2. XREL Documents 176 2.1. Format 178 Following RAML conventions, XREL documents are YAML documents. The 179 file extension ".yaml" SHALL be used to designate files containing 180 XREL documents. 182 This specification uses YAML 1.2 [W3C.yaml] as its underlying format. 183 YAML is a human-readable data format that aligns well with the design 184 goals of this specification. As in YAML, all nodes such as keys, 185 values, and tags, are case-sensitive. 187 To facilitate the automated processing of XREL documents, XREL 188 imposes the following restrictions and requirements in addition to 189 the core YAML 1.2 specification: 191 o The first line of a XREL file consists of a YAML comment that 192 specifies the XREL version and document type. Therefore, XREL 193 processors cannot completely ignore all YAML comments. 195 2.2. Relationship Object 197 Explains the semantics of a hypermedia relationship. 199 2.2.1. Properties 201 +-------------+--------+--------------------------------------------+ 202 | Name | Type | Description | 203 +-------------+--------+--------------------------------------------+ 204 | description | string | Describes the semantics of a hypermedia | 205 | | | relationship. The semantics SHOULD | 206 | | | describe the relationship of the target | 207 | | | resource to the context resource, and not | 208 | | | any particular representation formats. | 209 | | | Markdown MAY be used for rich text | 210 | | | representation. | 211 +-------------+--------+--------------------------------------------+ 213 2.3. XREL Document 215 Defines a single Relationship Object. 217 The first line of a XREL document MUST begin with the text "#%XREL 218 1.0" followed by nothing but the end of the line. 220 2.3.1. Document Example 222 #%XREL 1.0 224 description: Refers to an event scheduling service resource related to the context resource. 226 2.4. XREL Collection Document 228 Defines a map where the keys are the document scoped relationship 229 names and the values are Relationship Objects. XREL Collections can 230 be used to combine any collection of Relationship Objects. 232 The first line of a collection document MUST begin with the text 233 "#%XREL 1.0 Collection" followed by nothing but the end of the line. 235 2.4.1. Document Example 237 #%XREL 1.0 Collection 239 schedulingService: 240 description: Refers to an event scheduling service resource related to the context resource. 241 patient: 242 description: Refers to a patient resource related to the context resource. 244 2.5. Identifying XREL Documents 246 XREL documents are identified by unique URLs, this URL SHOULD be 247 dereferenceable. 249 In order to reduce load on servers responding to XREL document 250 requests, it is RECOMMENDED that servers use cache control directives 251 that instruct client apps to locally cache the results. Clients 252 making these XREL document requests SHOULD honor the server's caching 253 directives. 255 2.6. Fragment identifiers 257 When applied to an XREL document, a URI fragment identifier MUST be a 258 JSON Pointer [1] and be computed as such. 260 2.7. Identifying XREL Relationships 262 In the case of XREL Documents as specified in Section 2.3, the URL 263 that identifies that document also identifies the hypermedia 264 relationship described in that document. For example, if the 265 document example in Section 2.3.1 is served at 266 *http://docs.example.org/xrels/shedulingService* then this URL is the 267 identifier for the relationship described in that document. 269 In the case of XREL Collection Documents as specified in Section 2.4, 270 fragment identifiers MUST be used for the relationships objects 271 described in that document. For example, if the document example in 272 Section 2.4.1 is served at *http://docs.example.org/xrels/clinical* 273 then *http://docs.example.org/xrels/clinical#/shedulingService* and 274 *http://docs.example.org/xrels/clinical#/patient* identify the first 275 and second Relationship Object, respectively. 277 3. IANA Considerations 279 This specification establishes the media type "application/xrel" for 280 community review and will be submitted to the IESG for review, 281 approval, and registration with IANA. 283 3.1. application/xrel 285 *Type name:* application 287 *Subtype name:* xrel 289 *Required parameters:* none 291 *Optional parameters:* 293 *profile:*: A whitespace-separated list of URIs identifying 294 specific constraints or conventions that apply to an XREL 295 document. A profile must not change the semantics of the resource 296 representation when processed without profile knowledge, so that 297 clients both with and without knowledge of a profiled resource can 298 safely use the same representation. The profile parameter may 299 also be used by clients to express their preferences in the 300 content negotiation process. It is recommended that profile URIs 301 are dereferenceable and provide useful documentation at that URI. 303 *Encoding considerations:* 305 *binary:* Because of YAML's relation to JSON the same encoding 306 considerations of application/json as specified in JavaScript 307 Object Notation [RFC3986] apply. 309 *Security considerations:* 311 Because of YAML's relation to JSON this format shares security 312 issues common to all JSON content types. The security issues of 313 JavaScript Object Notation [RFC3986], section 6, should be 314 considered. 316 *Interoperability considerations:* none 318 *Fragment identifier considerations:* 320 Fragment identifiers are to be computed as defined by the JSON 321 Pointer [2] specification. 323 *Published specification:* This Document 325 *Applications that use this media type:* Various 327 *Additional information:* 329 *magic number(s):* none 331 *file extensions:* .yaml 333 *macintosh type file code:* TEXT 335 *object idenfiers:* none 337 *Person to contact for further information:* 339 *Name:* Jose Montoya 341 *Email:* jmontoya@ms3-inc.com 343 *Intended usage:* Common 345 *Author/change controller:* Jose Montoya 347 4. Appendix A. Acknowledgments 349 Many thanks to Mike Amundsen, Jeff Michaud, Stu Charlton, Eric Wilde 350 and Darrel Miller for their contributions in this space, even if not 351 directly related to XREL documents. 353 5. Appendix B. Frequently Asked Questions 355 5.1. How can I submit comments or feedback to the editors? 357 The issues list for this draft can be found at https://github.com/ 358 phtal-org/internet-draft-xrel/issues [3]. For additional 359 information, see https://phtal-org.github.io/internet-draft-xrel/ 360 [4]. 362 To provide feedback, use this issue tracker, the communication 363 methods listed on the homepage, or email the document editors. 365 5.2. Why not include target attributes as defined by RFC8288 'Web 366 Linking'? 368 Link relations are universal, they describe an _association_ to a 369 conceptual target and not the targets themselves nor their 370 representations. It is the responsibility of the application authors 371 to communicate to their clients what data types are necessary to 372 navigate a relationship and/or the data types that might be expected 373 as a result. 375 This level of abstraction has value because it's easier to 376 standardize representations (HTML Microformats, RAML data types, 377 etc.) and link relations than it is to standardize objects and 378 object-specific interfaces. Application servers are free to combine 379 representations and link relations in any way they wish and to 380 provide them in any order, all while remaining understandable to the 381 client. 383 6. References 385 6.1. Normative References 387 [github.md] 388 McFarlane, J., "GitHub Flavored Markdown Spec", n.d., 389 . 391 [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform 392 Resource Locators (URL)", RFC 1738, DOI 10.17487/RFC1738, 393 December 1994, . 395 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 396 Requirement Levels", BCP 14, RFC 2119, 397 DOI 10.17487/RFC2119, March 1997, 398 . 400 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 401 Resource Identifier (URI): Generic Syntax", STD 66, 402 RFC 3986, DOI 10.17487/RFC3986, January 2005, 403 . 405 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 406 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 407 DOI 10.17487/RFC6901, April 2013, 408 . 410 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 411 RFC 7320, DOI 10.17487/RFC7320, July 2014, 412 . 414 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 415 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 416 May 2017, . 418 [W3C.yaml] 419 Ben Kiki, O, ., Evans, C, ., and I. Net, "YAML Aint Markup 420 Language", 2009, . 422 6.2. Informative References 424 [RAML] The RAML Workgroup, "RAML Specification", n.d., 425 . 428 [REST] Fielding, R., "Architectural Styles and the Design of 429 Network-based Software Architectures", Ph.D. Dissertation, 430 University of California, Irvine, 2000, 431 . 434 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 435 DOI 10.17487/RFC8288, October 2017, 436 . 438 [untangled] 439 Fielding, R., "Untangled, musings of Roy T. Fielding", 440 n.d., . 442 [yahoo.rest] 443 "The REST Architectural Style List", n.d., 444 . 446 6.3. URIs 448 [1] RFC6901 450 [2] RFC6901 452 [3] https://github.com/phtal-org/internet-draft-xrel/issues 454 [4] https://phtal-org.github.io/internet-draft-xrel/ 456 Author's Address 458 Jose Montoya 459 Mountain State Software Solutions 461 Email: jmontoya@ms3-inc.com