idnits 2.17.1 draft-wparad-json-links-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: The media type "application/links+json" MUST utilize only the canonical representation of a link. This means that a link provided in the "links" SHOULD not be duplicated and provided under a different link relation for the purpose of changing the representation. Each rel points to the semantic definition of the resource, while the resource can be duplicated in the "links" object, to vary the representation of a resource the "type" property of the "template" object should be utilized. To provide canonical URL links to resource representations each representation MUST utilize a different link relation. Because of the complexitiy associated with expectation on the "default" representation of a resource, to adhere to this RFC the "type" property SHOULD be used and summarily the "ACCEPT" header to request the appropriate representation, and the "links" object SHOULD NOT contain different representations of the same resource. Since resources are linked to and not necessarily representations it often does not make sense to iterate the representation links, but instead provide a list of representations for a link. -- The document date (September 1, 2018) is 2035 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 380 -- Looks like a reference, but probably isn't: '2' on line 382 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group W. Parad 3 Internet-Draft 4 Intended status: Standards Track I. Sowinski 5 Expires: March 5, 2019 6 R. Nowosielski 7 September 1, 2018 9 JSON Hypermedia Links Notation 10 draft-wparad-json-links-03 12 Abstract 14 This document proposes the application/links+json media type for 15 representing resources and their relations with hyperlinks. It 16 treats hypermedia links as first class object which can appear 17 throughout a JSON document. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on March 5, 2019. 36 Copyright Notice 38 Copyright (c) 2018 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2.1. Link-Relation . . . . . . . . . . . . . . . . . . . . . . 3 56 2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2.3. JSON Link Property Name . . . . . . . . . . . . . . . . . 3 58 2.4. JSON Link Property Value Object . . . . . . . . . . . . . 3 59 3. Reserved Words . . . . . . . . . . . . . . . . . . . . . . . 4 60 4. Links Notation Document . . . . . . . . . . . . . . . . . . . 4 61 5. Link Resources . . . . . . . . . . . . . . . . . . . . . . . 4 62 5.1. rel . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 5.2. href . . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 5.3. templates . . . . . . . . . . . . . . . . . . . . . . . . 5 65 6. Discoverability . . . . . . . . . . . . . . . . . . . . . . . 5 66 7. Links Example . . . . . . . . . . . . . . . . . . . . . . . . 6 67 8. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 7 68 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 69 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 70 11. Security Considerations . . . . . . . . . . . . . . . . . . . 8 71 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 72 12.1. Normative References . . . . . . . . . . . . . . . . . . 8 73 12.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 76 1. Introduction 78 This document introduces the media type "application/links+json" to 79 support hypermedia linking inside JSON as defined by [RFC6838] and 80 [RFC8259]. Hypermedia linking provides a dynamic way to navigate 81 from one JSON representation to another JSON representation by 82 following a URI in the form of a navigatable URL. To ensure URLs are 83 discoverable this standard creates the notion of a first class 84 "links" JSON object name. This property MUST adhere to the format in 85 this document, and provides an a priori discoverability to 86 representations which are of the media type "application/links+json". 88 The "links" JSON object name becomes a reserved word and cannot be 89 used without implying the semantics of this document. The "links" 90 can be found at multiple depths of a JSON representation and always 91 implying the same meaning with regards to the context. It is a 92 dictionary which provides web linking [RFC8288] by defining the 93 semanitcs of a linked representation. 95 The design of "application/links+json" proposes a straightforward 96 model which combines the simplicity of JSON object with a predefined 97 "links" structure. 99 This document is being discussed in the draft-wparad-json-links 100 Gitter room [1]. 102 2. Terminology 104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 106 document are to be interpreted as described in [RFC2119]. 108 Following the JSON standard conventions defined in [RFC8259], the 109 Links Notation will define specific definitions to each of the follow 110 terms, as they are reused through the document. 112 2.1. Link-Relation 114 Also known as web linking [RFC8288], is the relationship between the 115 current JSON resource representation and a related one. The related 116 resource can be discovered by navigating from the representation 117 through the "links" object to the "href" of the relevant "rel". 119 2.2. Links 121 The "links" JSON name or hereafter called "links" property is the 122 JSON property name "links" and the associated "links" property value 123 object. The property object will be known as the "links" object. 124 The property name MUST be "links", and is a reserved word. 126 2.3. JSON Link Property Name 128 The "links" object contains a set of JSON name properties, each of 129 these properties will be known simply as a "link". Its JSON property 130 name may be anything other than "links", including the value "link". 131 The JSON property value of the "link", is a "Link Object". The 132 property name is unique value within all the "links" objects in the 133 whole JSON document. 135 2.4. JSON Link Property Value Object 137 The Link Value Object is the JSON value object which is the member 138 value for the JSON property defined by a "link" property. It is a 139 "resource" link relation used to navigate to another hypermedia link. 141 3. Reserved Words 143 The application/links+json reserves the following words which 144 maintain their definition and no other value can replace them. The 145 are as follows: 147 * "links": any other value will assume its meaning from the media 148 type of the JSON body representation, except for the reserved word 149 "links". "links" has the semantic meaning as defined by this 150 document. 152 4. Links Notation Document 154 A JSON Links Document uses the format described in [RFC8259] and has 155 the media type "application/links+json". The media type provides a 156 polymorphic transform on JSON and introduces only a Hypermedia Links 157 Notation for expanding a "links" object value. Therefore 158 "application/links+json" is of media type "application/json". 160 The "links" object in a JSON object. The object contains "link" 161 properties which each uniquely define a related resource. The JSON 162 values associated with those names MUST be a JSON object which 163 explain how to navigate to that resource. 165 5. Link Resources 167 Each JSON "link" name specified in the "links" object is a link 168 relation and the related representation resource MUST be a different 169 hypermedia resource. Additionally, each "resource" or "link" MUST be 170 a JSON object which contains ONLY these predefined fields. 172 5.1. rel 174 The "rel" JSON name is OPTIONAL when the "link" property name is a 175 link relation per [RFC8288], if not, then the "rel" property MUST be 176 provided. The "rel" MUST be either an "absolute-URI" or a predefined 177 link relation. 179 When not defined the link relation is assumed from the "link" JSON 180 object name. To provide conformant JSON property names, the "rel" 181 JSON name can be used, and an improved "link" JSON object name can be 182 provided as the "link" property name. The "rel" context applies to 183 the relation of the immediate links object which contains it. The 184 "self" link relation inside a nested "links" object provides a 185 different semantic meaning then the "self" link relation inside a 186 "links" object specified at the top level of a resource object. Link 187 relations apply to the context that link relation is found within. 188 This means that the same link relation MAY be present in a JSON 189 representation multiple times and each it SHOULD specify a different 190 "href". 192 5.2. href 194 The "href" JSON name MUST be provided and defines a the URL for a 195 resource and MUST be an "absolute-URI" per [RFC7230]. When not 196 defined the link relation is assumed from the "link" JSON object 197 name. 199 5.3. templates 201 The "templates" JSON name SHOULD be provided. When present it shows 202 the semantics on how to follow the defined the URL specified in the 203 "href" property. The "templates" JSON value is a JSON object. The 204 JSON property names of the JSON object MUST be HTTP method verbs as 205 defined by [RFC7231]. When not provided, the implicit default is 206 that only GET is supported. The JSON property value of each of these 207 templated verbs contains the following fields: 209 * "type": OPTIONAL, Type is the media type or documentation URL 210 location which points to the documented semantics of the type 211 required to follow the link. When the verb is "GET", the "type" 212 field MUST NOT be provided. When the type is not a media type, 213 the documentation location URL is specified the location must 214 point to either to the semantics of the object or an Open API 215 Schema [2] object. 217 6. Discoverability 219 To ensure discoverability and meaning to each link relation in a 220 "links" object. Each "links" object MUST be specified at with the 221 most specific child JSON object value as relates to the link 222 relation. When a JSON property name "item" exists and a "link" to 223 that "item" needs to be specified, the "link" should contain a "self" 224 and be present inside the "item" JSON object value. The "item" link 225 SHALL NOT be provided in the top most "link" object. The "item" 226 "link" SHALL NOT be specified in a top level "links" object which 227 contains a link relation name "item" and a "rel" 228 https://example.org/rels/v1/item. 230 If no JSON property with the "item" property name exists, then the 231 "item" SHALL be added to the "links" object at the top level. Once 232 this link is located here, a JSON property "item" MUST NOT be created 233 in the representation. 235 7. Links Example 237 Here is an example: 239 { 240 "resourceId": "123", 241 "other_resource": { 242 "otherResourceId": "abc", 243 "links": { 244 "self": { 245 "href": "https://example.org/v1/resources/abc", 246 "templates": { 247 "GET": {} 248 } 249 }, 250 "create": { 251 "rel": "https://example.org/rels/v1/create", 252 "href": "https://example.org/v1/other_resources", 253 "templates": { 254 "POST": { 255 "type": "https://example.org/rels/v1/other_resources" 256 } 257 } 258 } 259 } 260 }, 261 "links": { 262 "self": { 263 "href": "https://example.org/v1/resources/123", 264 "templates": { 265 "GET": {} 266 } 267 }, 268 "hypermedia_other_relation": { 269 "rel": "https://example.org/rels/v1/hypermedia_other_relation", 270 "href": "https://example.org/resources/456", 271 "templates": { 272 "GET": {} 273 } 274 } 275 } 276 } 278 To include a collection of links, it MUST be presented as a first 279 class JSON array of JSON objects. Each object containing its own 280 "links" object: 282 { 283 "collectionId": "collection-1", 284 "resourceCollection": [ 285 { 286 "itemId": "item-1", 287 "links": { 288 "self": { 289 "href": "https://example.org/v1/items/item-1" 290 } 291 } 292 }, 293 { 294 "itemId": "item-2", 295 "links": { 296 "self": { 297 "href": "https://example.org/v1/items/item-2" 298 } 299 } 300 } 301 ], 302 "links": { 303 "self": { 304 "href": "https://example.org/v1/collections/collection-1" 305 } 306 } 307 } 309 8. Backwards Compatibility 311 The "links" value MUST be statically bound to the JSON "link" name. 312 If the semantics of the "links" object changes, then a new "link" 313 name must be created. When using the short abbreviations instead of 314 a "rel" for the "link" name, when the semantics of the object is 315 changed, eg a new version is available, a new short abbreviation must 316 be created for the new href. If changing any of the "rel", "link" 317 name, or "href" media type, then the resource MUST define a new 318 "link" name to use. 320 The media type "application/links+json" MUST utilize only the 321 canonical representation of a link. This means that a link provided 322 in the "links" SHOULD not be duplicated and provided under a 323 different link relation for the purpose of changing the 324 representation. Each rel points to the semantic definition of the 325 resource, while the resource can be duplicated in the "links" object, 326 to vary the representation of a resource the "type" property of the 327 "template" object should be utilized. To provide canonical URL links 328 to resource representations each representation MUST utilize a 329 different link relation. Because of the complexitiy associated with 330 expectation on the "default" representation of a resource, to adhere 331 to this RFC the "type" property SHOULD be used and summarily the 332 "ACCEPT" header to request the appropriate representation, and the 333 "links" object SHOULD NOT contain different representations of the 334 same resource. Since resources are linked to and not necessarily 335 representations it often does not make sense to iterate the 336 representation links, but instead provide a list of representations 337 for a link. 339 9. Acknowledgements 341 10. IANA Considerations 343 11. Security Considerations 345 12. References 347 12.1. Normative References 349 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 350 Requirement Levels", BCP 14, RFC 2119, 351 DOI 10.17487/RFC2119, March 1997, 352 . 354 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 355 Specifications and Registration Procedures", BCP 13, 356 RFC 6838, DOI 10.17487/RFC6838, January 2013, 357 . 359 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 360 Protocol (HTTP/1.1): Message Syntax and Routing", 361 RFC 7230, DOI 10.17487/RFC7230, June 2014, 362 . 364 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 365 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 366 DOI 10.17487/RFC7231, June 2014, 367 . 369 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 370 Interchange Format", STD 90, RFC 8259, 371 DOI 10.17487/RFC8259, December 2017, 372 . 374 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 375 DOI 10.17487/RFC8288, October 2017, 376 . 378 12.2. URIs 380 [1] https://gitter.im/wparad/draft-wparad-json-links 382 [2] https://github.com/OAI/OpenAPI-Specification 384 Authors' Addresses 386 Warren Parad 388 Email: rfc@warrenparad.net 390 Igor Sowinski 392 Email: igorsowinski.mail@gmail.com 394 Rafal Nowosielski 396 Email: rafal@nowosielski.email