idnits 2.17.1 draft-wilde-linkset-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 8 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 (August 28, 2019) is 1702 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 6982 (Obsoleted by RFC 7942) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Wilde 3 Internet-Draft 4 Intended status: Informational H. Van de Sompel 5 Expires: February 29, 2020 Data Archiving and Networked Services 6 August 28, 2019 8 Linkset: Media Types and a Link Relation Type for Link Sets 9 draft-wilde-linkset-04 11 Abstract 13 This specification defines two media types and a link relation type 14 for sets of links. The media types can be used to represents links 15 in a standalone fashion, in one case in the native format as used in 16 the HTTP Link header, and in the other case in a JSON-based format. 17 The link relation type can be used by a resource to point at another 18 resource that provides a set of links, including links in which the 19 former resource participates. One typical scenario is when the 20 number of links to put in an HTTP Link header becomes too big, and 21 thus these links should be provided in another way. 23 Note to Readers 25 Please discuss this draft on the ART mailing list 26 (). 28 Online access to all versions and files is available on GitHub 29 (). 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at https://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on February 29, 2020. 48 Copyright Notice 50 Copyright (c) 2019 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (https://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 67 3. Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . 3 68 3.1. Third-Party Links . . . . . . . . . . . . . . . . . . . . 3 69 3.2. Challenges Writing to HTTP Link Header Field . . . . . . 4 70 3.3. Large Number of Links . . . . . . . . . . . . . . . . . . 4 71 4. Document Formats for Sets of Links . . . . . . . . . . . . . 5 72 4.1. HTTP Link Document Format: application/linkset . . . . . 5 73 4.2. JSON Document Format: application/linkset+json . . . . . 6 74 4.2.1. Set of Links . . . . . . . . . . . . . . . . . . . . 6 75 4.2.2. Link Context Object . . . . . . . . . . . . . . . . . 7 76 4.2.3. Link Target Object . . . . . . . . . . . . . . . . . 7 77 4.2.4. Link Target Attributes . . . . . . . . . . . . . . . 9 78 5. The "linkset" Relation Type for Linking to a Set of Links . . 13 79 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 14 80 6.1. Set of Links Provided By Value as application/linkset . . 14 81 6.2. Set of Links Provided By Reference as 82 application/linkset+json . . . . . . . . . . . . . . . . 15 83 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 18 84 7.1. Open Journal Systems (OJS) . . . . . . . . . . . . . . . 18 85 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 86 8.1. Link Relation Type: linkset . . . . . . . . . . . . . . . 18 87 8.2. Media Type: application/linkset . . . . . . . . . . . . . 19 88 8.2.1. IANA Considerations . . . . . . . . . . . . . . . . . 19 89 8.3. Media Type: application/linkset+json . . . . . . . . . . 20 90 9. Security Considerations . . . . . . . . . . . . . . . . . . . 21 91 10. Normative References . . . . . . . . . . . . . . . . . . . . 21 92 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 22 93 Appendix B. JSON-LD Context . . . . . . . . . . . . . . . . . . 22 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 96 1. Introduction 98 Resources on the Web often convey typed Web Links [RFC8288] as a part 99 of resource representations, for example, using the element 100 for HTML representations, or the "Link" header field in HTTP response 101 headers for representations of any media type. In some cases, 102 however, providing links in this manner is impractical or impossible. 104 To that end, this specification defines two document formats and 105 associated media types to represent a set of links. It also defines 106 the "linkset" relation type that a resource can use to support 107 discovery of another resource that conveys links, including links in 108 which the former resource participates. 110 2. Terminology 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 114 "OPTIONAL" in this document are to be interpreted as described in BCP 115 14 [RFC2119] [RFC8174] when, and only when, they appear in all 116 capitals, as shown here. 118 This specification uses the terms "link context" and "link target" as 119 defined in [RFC8288]. These terms respectively correspond with 120 "Context IRI" and "Target IRI" as used in RFC 5988 [RFC5988]. 121 Although defined as IRIs, in common scenarios they are also URIs. 123 3. Scenarios 125 The following sections outline scenarios in which providing links by 126 means of a standalone document instead of via an HTTP Link header or 127 via elements in HTML is advantageous or necessary. It is 128 important to keep in mind that, when providing links by means of a 129 standalone, other links can still be provided by value. 131 3.1. Third-Party Links 133 In some cases, it is useful that links pertaining to a resource are 134 provided by a server other than the one that hosts the resource. For 135 example, this allows: 137 o Providing links in which the resource is involved not just as link 138 context but also as link target. 140 o Providing links pertaining to the resource that the server hosting 141 that resource is not aware of. 143 o External management of links pertaining to the resource in a 144 special-purpose link management service. 146 In such cases, a third-party resource can provide a set of links 147 pertaining to the resource. This third-party resource may be managed 148 by the same or by another custodian as the resource. For clients 149 intent on consuming links pertaining to the resource, it would be 150 beneficial if: 152 o The resource would be able to unambiguously point at the third- 153 party resource that provides the links using a registered link 154 relation type. 156 o The third-party resource would provide the links in a document 157 that is compliant with a registered media type. 159 3.2. Challenges Writing to HTTP Link Header Field 161 In some cases, it is not straightforward to write links to the HTTP 162 Link header field from an application. This can, for example, be the 163 case because not all required link information is available to the 164 application or because the application does not have the capability 165 to directly write HTTP headers. In such cases, providing links by 166 means of a standalone document can be a solution. Making the third- 167 party resource that provides these links discoverable can be achieved 168 by means of an unambiguously typed link, which can typically 169 straightforwardly be added by means of a web server rewrite rule that 170 leverages the resource's URI. 172 3.3. Large Number of Links 174 When conveying links in the HTTP "Link" header, it is possible for 175 the size of the HTTP response header to become unpredictable. This 176 can be the case when links are determined dynamically dependent on a 177 range of contextual factors. It is possible to statically configure 178 a web server to correctly handle large HTTP response headers by 179 specifying an upper boundary for their size. But when the number of 180 links is unpredictable, estimating a reliable upper boundary is 181 challenging. 183 HTTP [RFC7231] defines error codes related to excess communication by 184 the user agent ("413 Request Entity Too Large" and "414 Request-URI 185 Too Long"), but no specific error codes are defined to indicate that 186 response header content exceeds the upper boundary that can be 187 handled by the server, and thus it has been truncated. As a result, 188 applications take counter measures aimed at controlling the size of 189 the HTTP "Link" header, for example by limiting the links they 190 provide to those with select relation types, thereby limiting the 191 value of the HTTP "Link" header to clients. Providing links by means 192 of a standalone document overcomes challenges related to the 193 unpredictable nature of the extent of HTTP "Link" headers. 195 In more extreme scenarios it is conceivable that the number of links 196 to be conveyed becomes so large that even a standalone document would 197 become too large. This could be the case for highly popular 198 resources, and when links are provided in which such resources 199 participates as both link context and link target. In such cases, 200 the links could be delivered incrementally, for example, by means of 201 a paged resource model that uses links with the "next" link relation 202 type. 204 4. Document Formats for Sets of Links 206 A set of links can be represented by serializations that support 207 conveying both link contexts and link targets. This section 208 specifies two document formats based on the abstract model specified 209 in Section 2 of [RFC8288] that defines a link as consisting of a 210 "link context", a "link relation type", a "link target", and optional 211 "target attributes". 213 The format defined in Section 4.1 is identical to the payload of the 214 HTTP Link header as specified in [RFC8288]. 216 The format defined in Section 4.2 is based on JSON and thus does not 217 have the character encoding limitations of HTTP header fields. 219 4.1. HTTP Link Document Format: application/linkset 221 This document format is identical to the payload of the HTTP Link 222 header as defined in Section 3 of [RFC8288], more specifically by its 223 ABNF production rule for "Link" and subsequent ones. 225 The assigned media type for this format is "application/linkset". 227 In order to support use cases where "application/linkset" documents 228 are re-used outside the context of an HTTP interaction, it is 229 RECOMMENDED to make them self-contained by adhering to the following 230 guidelines: 232 o For every link provided in the set of links, explicitly provide 233 the link context using the "anchor" attribute. 235 o For link context ("anchor" attribute) and link target ("href" 236 attribute), use absolute URIs (as defined in Section 4.3 of 237 [RFC3986]). 239 4.2. JSON Document Format: application/linkset+json 241 This document format uses JSON [RFC8259] as the syntax to represent a 242 set of links. It is described in this section. 244 The assigned media type for this format is "application/ 245 linkset+json". 247 In order to support use cases where "application/linkset+json" 248 documents are re-used outside the context of an HTTP interaction, it 249 is RECOMMENDED to make them self-contained by adhering to the 250 following guidelines: 252 o For every link provided in the set of links, explicitly provide 253 the link context using the "anchor" member. 255 o For link context ("anchor" member) and link target ("href" 256 member), use absolute URIs (as defined in Section 4.3 of 257 [RFC3986]). 259 The "application/linkset+json" serialization was designed such that 260 it can directly be used as the content of a JSON-LD serialization by 261 adding an appropriate context. Appendix B shows an example of a 262 possible context that, when added to the a JSON serialization, allows 263 it to be interpreted as RDF. 265 4.2.1. Set of Links 267 In the JSON representation of a set of links: 269 o A set of links MUST be represented as a JSON object, which MUST 270 have "linkset" as its sole member. 272 o The "linkset" member is an array in which a distinct JSON object - 273 the "link context object" (see Section 4.2.2) - MUST be used to 274 represent links that have the same link context. 276 o If necessary, the "linkset" member MAY contain information in 277 addition to link context objects, in which case that information 278 MUST NOT change the semantics of the links provided by those link 279 context objects. 281 o Even if there is only one link context object, it MUST be wrapped 282 in an array. Members other than link context objects MUST NOT be 283 included in this array. 285 4.2.2. Link Context Object 287 In the JSON representation, one or more links that have the same link 288 context, are represented by a JSON object, the link context object. 289 A link context object adheres to the following rules: 291 o Each link context object MUST have an "anchor" member with a value 292 that represents the link context. This value SHOULD be an 293 absolute URI as defined in Section 4.3 of [RFC3986]. Cases 294 whereby no value is to be provided for the "anchor" member (i.e. 295 the resource providing the set of links is the link context for 296 each link in the link context object), MUST be handled by 297 providing an "anchor" member with null value ("anchor":""). 299 o For each distinct relation type that the link context has with 300 link targets, a link context object MUST have an additional 301 member. This member is an array in which a distinct JSON object - 302 the " link target object" (see Section 4.2.3) - MUST be used for 303 each link target for which the relationship with the link context 304 (value of the encompassing anchor member) applies. The name of 305 this member expresses the relation type of the link as follows: 307 o 309 * For registered relation types [RFC8288], the name of this 310 member is the registered name of the relation type. 312 * For extension relation types [RFC8288], the name of this member 313 is the URI that uniquely represents the relation type. 315 o Even if there is only one link target object, it MUST be wrapped 316 in an array. Members other than link target objects MUST NOT be 317 included in this array. 319 4.2.3. Link Target Object 321 In the JSON representation, a link target is represented by a JSON 322 object, the link target object. A link target object adheres to the 323 following rules: 325 o Each link target object MUST have an "href" member with a value 326 that represents the link target. This value SHOULD be an absolute 327 URI as defined in Section 4.3 of [RFC3986]. Cases whereby no 328 value is to be provided for the "href" member (i.e. the resource 329 providing the set of links is the target of the link in the link 330 target object), MUST be handled by providing an "href" member with 331 null value ("href":""). 333 o In many cases, a link target is further qualified by attributes, 334 either defined by the serialization of [RFC8288] or extension 335 attributes defined and used by communities. These attributes are 336 conveyed as additional members of the link target object, as 337 detailed in Section 4.2.4.1, Section 4.2.4.2, and Section 4.2.4.3. 339 Note that the JSON representation does not use the "rel" or "rev" 340 constructs used by [RFC8288] and the above specified HTTP Link 341 document format. Rather: 343 o A link that uses the "rel" construct in those approaches is 344 conveyed using the URI of the link context as the value for 345 "anchor" and the URI of the link target as the value for "href". 347 o A link that uses the "rev" construct in those approaches is 348 conveyed using the URI of the link target as the value for 349 "anchor" and the URI of the link context as the value for "href". 351 The following example of a JSON-serialized set of links represents 352 one link with its core components: link context, link relation type, 353 and link target. 355 { 356 "linkset": 357 [ 358 { "anchor":"http://example.net/bar", 359 "next": [ 360 {"href":"http://example.com/foo"} 361 ] 362 } 363 ] 364 } 366 The following example of a JSON-serialized set of links represents 367 two links that share link context and relation type but have 368 different link targets. 370 { 371 "linkset": 372 [ 373 { "anchor":"http://example.net/bar", 374 "item": [ 375 {"href":"http://example.com/foo1"}, 376 {"href":"http://example.com/foo2"} 377 ] 378 } 379 ] 380 } 382 The following example shows a set of links that represents two links, 383 each with a different link context, link target, and relation type. 384 One relation type is registered, the other is an extension relation 385 type. 387 { 388 "linkset": 389 [ 390 { "anchor":"http://example.net/bar", 391 "next": [ 392 {"href":"http://example.com/foo1"} 393 ] 394 }, 395 { "anchor":"http://example.net/boo", 396 "http://example.com/relations/baz" : [ 397 {"href": "http://example.com/foo2"} 398 ] 399 } 400 ] 401 } 403 4.2.4. Link Target Attributes 405 In many cases, a link is further qualified by target attributes, 406 either defined by the serialization of [RFC8288] or extension 407 attributes defined and used by communities. 409 4.2.4.1. Target Attributes Defined by RFC 8288 411 RFC 8288 defines the following target attributes that may be used to 412 annotate links: "hreflang", "media", "title", "title*", and "type"; 413 these target attributes follow different occurrence and value 414 patterns. In the JSON representation, these attributes MUST be 415 conveyed as additional members of the link target object as follows: 417 o "hreflang": The optional and repeatable "hreflang" target 418 attribute MUST be represented by an array (even if there only is 419 one value to be represented), and each value in that array MUST be 420 a string - representing one value of the "hreflang" target 421 attribute for a link - which follows the same model as in the 422 [RFC8288] syntax. 424 o "media": The optional and not repeatable "media" target attribute 425 MUST be represented by a "media" member in the link target object, 426 and its value MUST be a string that follows the same model as in 427 the [RFC8288] syntax. 429 o "type": The optional and not repeatable "type" target attribute 430 MUST be represented by a "type" member in the link target object, 431 and its value MUST be a string that follows the same model as in 432 the [RFC8288] syntax. 434 o "title": The optional and not repeatable "title" target attribute 435 MUST be represented by a "title" member in the link target object, 436 and its value MUST be a string that follows the same model as in 437 the [RFC8288] syntax. 439 o "title*": The optional and not repeatable "title*" target 440 attribute is motivated by character encoding and language issues 441 and follows the model defined in [RFC8187]. The details of the 442 JSON representation that applies to title* are described in 443 Section 4.2.4.2. 445 The following example illustrates how the repeatable "hreflang" and 446 the not repeatable "type" target attributes are represented in a link 447 target object. 449 { 450 "linkset": 451 [ 452 { "anchor":"http://example.net/bar", 453 "next": [ 454 {"href":"http://example.com/foo", 455 "type":"text/html", 456 "hreflang": [ "en" , "de" ] 457 } 458 ] 459 } 460 ] 461 } 463 4.2.4.2. Internationalized Target Attributes 465 In addition to the target attributes described in Section 4.2.4.1, 466 [RFC8288] also supports attributes that follow the content model of 467 [RFC8187]. In [RFC8288], these target attributes are recognizable by 468 the use of a trailing asterisk in the attribute name, such as 469 "title*". The content model of [RFC8187] uses a string-based 470 microsyntax that represents the character encoding, an optional 471 language tag, and the escaped attribute value encoded according to 472 the specified character encoding. 474 The JSON serialization for these target attributes MUST be as 475 follows: 477 o An internationalized target attribute is represented as a member 478 of the link context object with the same name (including the *) of 479 the attribute. 481 o The character encoding information as prescribed by [RFC8187] is 482 not preserved; instead, the content of the internationalized 483 attribute is represented in the character encoding used for the 484 JSON set of links. 486 o The value of the internationalized target attribute is an array 487 that contains one or more JSON objects. The name of the first 488 member of such JSON object is "value" and its value is the actual 489 content (in its unescaped version) of the internationalized target 490 attribute, i.e. the value of the attribute from which the encoding 491 and language information are removed. The name of the optional 492 second member of such JSON object is "language" and its value is 493 the language tag [RFC5646] for the language in which the attribute 494 content is conveyed. 496 The following example illustrates how the "title*" target attribute 497 defined by [RFC8288] is represented in a link target object. 499 { 500 "linkset": 501 [ 502 { "anchor":"http://example.net/bar", 503 "next": [ 504 {"href":"http://example.com/foo", 505 "type":"text/html", 506 "hreflang": [ "en" , "de" ], 507 "title":"Next chapter", 508 "title*": [ { "value": "nachstes Kapitel" , "language" : "de" } ] 509 } 510 ] 511 } 512 ] 513 } 515 The above example assumes that the German title contains an umlaut 516 character (in the native syntax it would be encoded as title*=UTF- 517 8'de'n%c3%a4chstes%20Kapitel), which gets encoded in its unescaped 518 form in the JSON representation. This is not shown in the above 519 example due to the limitations of RFC publication. Implementations 520 MUST properly decode/encode internationalized target attributes that 521 follow the model of [RFC8187] when transcoding between the 522 "application/linkset" and the "application/linkset+json" formats. 524 4.2.4.3. Extension Target Attributes 526 Extension target attributes are attributes that are not defined by 527 RFC 8288 (as listed in Section 4.2.4.1), but are nevertheless used to 528 qualify links. They can be defined by communities in any way deemed 529 necessary, and it is up to them to make sure their usage is 530 understood by target applications. However, lacking standardization, 531 there is no interoperable understanding of these extension 532 attributes. One important consequence is that their cardinality is 533 unknown to generic applications. Therefore, in the JSON 534 serialization, all extension target attributes are treated as 535 repeatable. 537 The JSON serialization for these target attributes MUST be as 538 follows: 540 o An extension target attribute is represented as a member of the 541 link context object with the same name of the attribute, including 542 the * if applicable. 544 o The value of an extension attribute MUST be represented by an 545 array, even if there only is one value to be represented. 547 o If the extension target attribute does not have a name with a 548 trailing asterisk, then each value in that array MUST be a string 549 that represents one value of the attribute. 551 o If the extension attribute has a name with a trailing asterisk (it 552 follows the content model of [RFC8187]), then each value in that 553 array MUST be a JSON object. The value of each such JSON object 554 MUST be structured as described in Section 4.2.4.2. 556 The example shows a link target object with three extension target 557 attributes. The value for each extension target attribute is an 558 array. The two first are regular extension target attributes, with 559 the first one ("foo") having only one value and the second one 560 ("bar") having two. The last extension target attribute ("baz*") 561 follows the naming rule of [RFC8187] and therefore is encoded 562 according to the serialization described in Section 4.2.4.2. 564 { 565 "linkset": 566 [ 567 { "anchor":"http://example.net/bar", 568 "next": [ 569 {"href":"http://example.com/foo", 570 "type":"text/html", 571 "foo": [ "foovalue" ], 572 "bar": [ "barone", "bartwo" ], 573 "baz*": [ { "value": "bazvalue" , "language" : "en" } ] 574 } 575 ] 576 } 577 ] 578 } 580 5. The "linkset" Relation Type for Linking to a Set of Links 582 The target of a link with the "linkset" relation type provides a set 583 of links, including links in which the resource that is the link 584 context participates. 586 A link with the "linkset" relation type MAY be provided in the header 587 and/or the body of a resource's representation. It may also be 588 discovered by other means, such as through client-side information. 590 A resource MAY provide more than one link with a "linkset" relation 591 type. Multiple such links can refer to the same set of links 592 expressed using different media types, or to different sets of links, 593 potentially provided by different third-party services. 595 The use of a link with the "linkset" relation type does not preclude 596 the provision of links with other relation types, i.e. the resource 597 that is the link context can provide typed links other than a 598 "linkset" link. 600 A user agent that follows a "linkset" link MUST be aware that the set 601 of links provided by the resource that is the target of the link can 602 contain links in which the resource that is the context of the link 603 does not participate; it MAY decide to ignore those links. 605 A user agent that follows a "linkset" link, and obtains links for 606 which anchors and targets are not expressed as absolute URIs, MUST 607 determine what the context is for these links; it SHOULD ignore links 608 for which it is unable to unambiguously make that determination. 610 There is no constraint on the target URI of a link with the "linkset" 611 relation type; designing and using these URIs is left to the 612 discretion of implementers. 614 6. Examples 616 Section 6.1 and Section 6.2 show examples whereby the set of links 617 are provided as "application/linkset" and "application/linkset+json" 618 documents, respectively. 620 6.1. Set of Links Provided By Value as application/linkset 622 Figure 1 shows a client issuing an HTTP GET request against resource 623 http://example.org/resource1. 625 GET /resource1 HTTP/1.1 626 Host: example.org 627 Connection: close 629 Figure 1: Client HTTP GET request 631 Figure 2 shows the response to the GET request of Figure 1. The 632 response contains a Content-Type header with as value application/ 633 linkset. A set of links, including links that pertain to the 634 responding resource, is provided in the body of the response. 636 HTTP/1.1 200 OK 637 Date: Mon, 12 Aug 2019 10:35:51 GMT 638 Server: Apache-Coyote/1.1 639 Content-Length: 729 640 Content-Type: application/linkset 641 Connection: close 643 644 ; rel="author" 645 ; type="application/rdf+xml" 646 ; anchor="http://example.org/resource1", 647 648 ; rel="author" 649 ; type="application/rdf+xml" 650 ; anchor="http://example.org/resource1", 651 652 ; rel="item" 653 ; type="application/pdf" 654 ; anchor="http://example.org/resource1", 655 656 ; rel="item" 657 ; type="text/html" 658 ; anchor="http://example.org/resource1", 659 660 ; rel="latest-version" 661 ; anchor="http://example.org/resource41/", 662 663 ; rel="prev" 664 ; anchor="http://example.org/resource41/" 666 Figure 2: Response to HTTP GET includes a set of links 668 6.2. Set of Links Provided By Reference as application/linkset+json 670 Figure 3 shows a client issuing an HTTP HEAD request against resource 671 http://example.org/article/view/7507 673 HEAD article/view/7507 HTTP/1.1 674 Host: example.org 675 Connection: close 677 Figure 3: Client HTTP HEAD request 679 Figure 4 shows the response to the HEAD request of Figure 3. The 680 response contains a Link header with a link that has the "linkset" 681 relation type. It indicates that a set of links is provided by 682 resource http://example.com/links/article/7507, which provides a 683 representation with media type application/linkset+json. 685 HTTP/1.1 200 OK 686 Date: Mon, 12 Aug 2019 10:45:54 GMT 687 Server: Apache-Coyote/1.1 688 Link: 689 ; rel="linkset" 690 ; type="application/linkset+json" 691 Content-Length: 236 692 Content-Type: text/html;charset=utf-8 693 Connection: close 695 Figure 4: Response to HTTP HEAD request 697 Figure 5 shows the client issuing an HTTP GET request against the 698 target IRI of the "linkset" link provided in Figure 4. In the 699 request, the client uses an Accept header to indicate it requests a 700 response in "application/linkset+json" format. 702 GET links/article/7507 HTTP/1.1 703 Host: example.com 704 Accept: application/linkset+json 705 Connection: close 707 Figure 5: Client issues HTTP GET to obtain set of links 709 Figure 6 shows the response to the HTTP GET request of Figure 5. The 710 set of links is serialized according to the media type "application/ 711 linkset+json" and includes links in which the Context IRI of the 712 "linkset" link of Figure 4 participates. It also includes a link in 713 which it does not. That link actually points at an alternate 714 representation of the set of links. 716 HTTP/1.1 200 OK 717 Date: Mon, 12 Aug 2019 10:46:22 GMT 718 Server: Apache-Coyote/1.1 719 Content-Type: application/linkset+json 720 Content-Length: 802 722 { 723 "linkset": [ 724 { 725 "anchor": "https://example.org/article/view/7507", 726 "author": [ 727 { 728 "href": "https://orcid.org/0000-0002-4311-0897", 729 "type": "rdf/xml" 730 } 731 ], 732 "item": [ 733 { 734 "href": "https://example.org/article/7507/item/1", 735 "type": "application/pdf" 736 }, 737 { 738 "href": "https://example.org/article/7507/item/2", 739 "type": "text/csv" 740 } 741 ], 742 "cite-as": [ 743 { 744 "href": "https://doi.org/10.841/zk2557" 745 } 746 ] 747 }, 748 { 749 "anchor": "https://example.com/links/article/7507", 750 "alternate": [ 751 { 752 "href": "https://mirror.example.com/links/article/7507", 753 "type": "application/linkset" 754 } 755 ] 756 } 757 ] 758 } 760 Figure 6: Response to the client's request for the set of links 762 7. Implementation Status 764 Note to RFC Editor: Please remove this section before publication. 766 This section records the status of known implementations of the 767 protocol defined by this specification at the time of posting of this 768 Internet-Draft, and is based on a proposal described in RFC 6982 769 [RFC6982]. The description of implementations in this section is 770 intended to assist the IETF in its decision processes in progressing 771 drafts to RFCs. Please note that the listing of any individual 772 implementation here does not imply endorsement by the IETF. 773 Furthermore, no effort has been spent to verify the information 774 presented here that was supplied by IETF contributors. This is not 775 intended as, and must not be construed to be, a catalog of available 776 implementations or their features. Readers are advised to note that 777 other implementations may exist. 779 According to RFC 6982, "this will allow reviewers and working groups 780 to assign due consideration to documents that have the benefit of 781 running code, which may serve as evidence of valuable experimentation 782 and feedback that have made the implemented protocols more mature. 783 It is up to the individual working groups to use this information as 784 they see fit". 786 7.1. Open Journal Systems (OJS) 788 Open Journal Systems (OJS) is an open-source software for the 789 management of peer-reviewed academic journals, and is created by the 790 Public Knowledge Project (PKP), released under the GNU General Public 791 License. Open Journal Systems (OJS) is a journal management and 792 publishing system that has been developed by PKP through its 793 federally funded efforts to expand and improve access to research. 795 The OJS platform has implemented "linkset" support as an alternative 796 way to provide links when there are more than a configured limit 797 (they consider using about 10 as a good default, for testing purpose 798 it is currently set to 8). 800 8. IANA Considerations 802 8.1. Link Relation Type: linkset 804 The link relation type below has been registered by IANA per 805 Section 6.2.1 of Web Linking [RFC8288]: 807 Relation Name: linkset 808 Description: The Target IRI of a link with the "linkset" relation 809 type provides a set of links, including links in which the Context 810 IRI of the link participates. 812 Reference: [[ This document ]] 814 8.2. Media Type: application/linkset 816 8.2.1. IANA Considerations 818 The Internet media type [RFC6838] for a natively encoded link set is 819 application/linkset. 821 Type name: application 823 Subtype name: linkset 825 Required parameters: none 827 Optional parameters: none 829 Encoding considerations: ... 831 Security considerations: ... 833 Interoperability considerations: ... 835 Published specification: [[ This document ]] 837 Applications that use this media type: ... 839 Additional information: 841 Magic number(s): N/A 843 File extension(s): This media type does not propose a specific 844 extension. 846 Macintosh file type code(s): TEXT 848 Person & email address to contact for further information: Erik 849 Wilde 851 Intended usage: COMMON 853 Restrictions on usage: none 855 Author: Erik Wilde 856 Change controller: IETF 858 8.3. Media Type: application/linkset+json 860 The Internet media type [RFC6838] for a JSON-encoded link set is 861 application/linkset+json. 863 Type name: application 865 Subtype name: linkset+json 867 Required parameters: none 869 Optional parameters: none 871 Encoding considerations: ... 873 Security considerations: ... 875 Interoperability considerations: ... 877 Published specification: [[ This document ]] 879 Applications that use this media type: ... 881 Additional information: 883 Magic number(s): N/A 885 File extension(s): JSON documents often use ".json" as the file 886 extension, and this media type does not propose a specific 887 extension other than this generic one. 889 Macintosh file type code(s): TEXT 891 Person & email address to contact for further information: Erik 892 Wilde 894 Intended usage: COMMON 896 Restrictions on usage: none 898 Author: Erik Wilde 900 Change controller: IETF 902 9. Security Considerations 904 ... 906 10. Normative References 908 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 909 Requirement Levels", BCP 14, RFC 2119, 910 DOI 10.17487/RFC2119, March 1997, 911 . 913 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 914 Resource Identifier (URI): Generic Syntax", STD 66, 915 RFC 3986, DOI 10.17487/RFC3986, January 2005, 916 . 918 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 919 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 920 September 2009, . 922 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 923 DOI 10.17487/RFC5988, October 2010, 924 . 926 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 927 Specifications and Registration Procedures", BCP 13, 928 RFC 6838, DOI 10.17487/RFC6838, January 2013, 929 . 931 [RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 932 Code: The Implementation Status Section", RFC 6982, 933 DOI 10.17487/RFC6982, July 2013, 934 . 936 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 937 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 938 DOI 10.17487/RFC7231, June 2014, 939 . 941 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 942 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 943 May 2017, . 945 [RFC8187] Reschke, J., "Indicating Character Encoding and Language 946 for HTTP Header Field Parameters", RFC 8187, 947 DOI 10.17487/RFC8187, September 2017, 948 . 950 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 951 Interchange Format", STD 90, RFC 8259, 952 DOI 10.17487/RFC8259, December 2017, 953 . 955 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 956 DOI 10.17487/RFC8288, October 2017, 957 . 959 Appendix A. Acknowledgements 961 Thanks for comments and suggestions provided by Mark Nottingham, 962 Stian Soiland-Reyes, Sarven Capadisli, ... 964 Appendix B. JSON-LD Context 966 When adding the below context to the representation of a link set 967 rendered according to the JSON serialization defined in Section 4.2, 968 it can be interpreted as RDF. 970 { 971 "@context": [ 972 { 973 "@vocab": "https://www.iana.org/assignments/link-relations/", 974 "anchor": "@id", 975 "href": "@id", 976 "dct": "http://purl.org/dc/terms/", 977 "link": "https://www.iana.org/assignments/link-relations#", 978 "title": { 979 "@id": "http://purl.org/dc/terms/title" 980 }, 981 "title*": { 982 "@id": "http://purl.org/dc/terms/title" 983 }, 984 "type": { 985 "@id": "dct:format", 986 "@type": "@vocab" 987 } 988 }, 989 { 990 "language": "@language", 991 "value": "@value", 992 "hreflang": { 993 "@id": "https://www.w3.org/ns/activitystreams#hreflang", 994 "@container": "@set" 995 } 996 } 997 ] 998 } 1000 Figure 7: Context for JSON-LD that could be used with the JSON 1001 serialization 1003 Authors' Addresses 1005 Erik Wilde 1007 Email: erik.wilde@dret.net 1008 URI: http://dret.net/netdret/ 1010 Herbert Van de Sompel 1011 Data Archiving and Networked Services 1013 Email: herbert.van.de.sompel@dans.knaw.nl 1014 URI: https://orcid.org/0000-0002-0715-6126