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