idnits 2.17.1 draft-ietf-httpapi-linkset-02.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 -- The document date (June 4, 2021) is 1056 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 1195 -- Looks like a reference, but probably isn't: '2' on line 1261 ** Obsolete normative reference: RFC 822 (Obsoleted by RFC 2822) ** Obsolete normative reference: RFC 6982 (Obsoleted by RFC 7942) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Wilde 3 Internet-Draft Axway 4 Intended status: Informational H. Van de Sompel 5 Expires: December 6, 2021 Data Archiving and Networked Services 6 June 4, 2021 8 Linkset: Media Types and a Link Relation Type for Link Sets 9 draft-ietf-httpapi-linkset-02 11 Abstract 13 This specification defines two document formats and respective media 14 types for representing sets of links as stand-alone resources. One 15 format is JSON-based, the other aligned with the format for 16 representing links in the HTTP "Link" header field. This 17 specification also introduces a link relation type to support 18 discovery of sets of links. 20 Note to Readers 22 Please discuss this draft on the "Building Blocks for HTTP APIs" 23 mailing list (). 25 Online access to all versions and files is available on GitHub 26 (). 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on December 6, 2021. 45 Copyright Notice 47 Copyright (c) 2021 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 3. Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . 3 65 3.1. Third-Party Links . . . . . . . . . . . . . . . . . . . . 4 66 3.2. Challenges Writing to HTTP Link Header Field . . . . . . 5 67 3.3. Large Number of Links . . . . . . . . . . . . . . . . . . 5 68 4. Document Formats for Sets of Links . . . . . . . . . . . . . 5 69 4.1. HTTP Link Document Format: application/linkset . . . . . 6 70 4.2. JSON Document Format: application/linkset+json . . . . . 6 71 4.2.1. Set of Links . . . . . . . . . . . . . . . . . . . . 7 72 4.2.2. Link Context Object . . . . . . . . . . . . . . . . . 8 73 4.2.3. Link Target Object . . . . . . . . . . . . . . . . . 8 74 4.2.4. Link Target Attributes . . . . . . . . . . . . . . . 10 75 4.2.5. JSON Extensibility . . . . . . . . . . . . . . . . . 14 76 5. The "profile" attribute for media types to Represent Sets of 77 Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 78 6. The "linkset" Relation Type for Linking to a Set of Links . . 15 79 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 15 80 7.1. Set of Links Provided as application/linkset . . . . . . 15 81 7.2. Set of Links Provided as application/linkset+json . . . . 17 82 7.3. Discovering a Link Set via the "linkset" Link Relation 83 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 19 84 8. Implementation Status . . . . . . . . . . . . . . . . . . . . 20 85 8.1. GS1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 86 8.2. FAIR Signposting Profile . . . . . . . . . . . . . . . . 21 87 8.3. Open Journal Systems (OJS) . . . . . . . . . . . . . . . 21 88 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 89 9.1. Link Relation Type: linkset . . . . . . . . . . . . . . . 21 90 9.2. Media Type: application/linkset . . . . . . . . . . . . . 22 91 9.3. Media Type: application/linkset+json . . . . . . . . . . 23 92 10. Security Considerations . . . . . . . . . . . . . . . . . . . 24 93 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 94 11.1. Normative References . . . . . . . . . . . . . . . . . . 24 95 11.2. Informative References . . . . . . . . . . . . . . . . . 26 96 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 27 97 Appendix B. JSON-LD Context . . . . . . . . . . . . . . . . . . 27 98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 100 1. Introduction 102 Resources on the Web often use typed Web Links [RFC8288], either 103 embedded in resource representations, for example using the 104 element for HTML documents, or conveyed in the HTTP "Link" header for 105 documents of any media type. In some cases, however, providing links 106 in this manner is impractical or impossible and delivering a set of 107 links as a stand-alone document is preferable. 109 Therefore, this specification defines two document formats and 110 associated media types to represent sets of links. It also defines 111 the "linkset" relation type that supports discovery of any resource 112 that conveys a set of links as a stand-alone document. 114 2. Terminology 116 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 117 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 118 "OPTIONAL" in this document are to be interpreted as described in BCP 119 14 [RFC2119] [RFC8174] when, and only when, they appear in all 120 capitals, as shown here. 122 This specification uses the terms "link context" and "link target" as 123 defined in [RFC8288]. These terms respectively correspond with 124 "Context IRI" and "Target IRI" as used in [RFC5988]. Although 125 defined as IRIs, in common scenarios they are also URIs. 127 In the examples provided in this document, links in the HTTP "Link" 128 header are shown on separate lines in order to improve readability. 129 Note, however, that as per Section 3.2 of [RFC7230], line breaks are 130 not allowed in values for HTTP headers; only whitespaces and tabs are 131 supported as seperators. 133 3. Scenarios 135 The following sections outline scenarios in which providing links by 136 means of a standalone document instead of in an HTTP "Link" header 137 field or as links embedded in the resource representation is 138 advantageous or necessary. 140 For all scenarios, links could be provided by means of a stand-alone 141 document that is formatted according to the JSON-based serialization, 142 the serialization aligned with the HTTP "Link" header format, or 143 both. The former serialization is motivated by the widespread use of 144 JSON and related tools, which suggests that handling sets of links 145 expressed as JSON documents should be attractive to developers. The 146 latter serialization is provided for compatibility with the existing 147 serialization used in the HTTP "Link" header and to allow reuse of 148 tools created to handle it. 150 It is important to keep in mind that when providing links by means of 151 a standalone representation, other links can still be provided using 152 other approaches, i.e. it is possible combine various mechanisms to 153 convey links. 155 3.1. Third-Party Links 157 In some cases it is useful that links pertaining to a resource are 158 provided by a server other than the one that hosts the resource. For 159 example, this allows: 161 o Providing links in which the resource is involved not just as link 162 context but also as link target. 164 o Providing links pertaining to the resource that the server hosting 165 that resource is not aware of. 167 o External management of links pertaining to the resource in a 168 special-purpose link management service. 170 In such cases, links pertaining to a resource can be provided by 171 another, specific resource. That specific resource may be managed by 172 the same or by another custodian as the resource to which the links 173 pertain. For clients intent on consuming links provided in that 174 manner, it would be beneficial if the following conditions were met: 176 o Links are provided in a document that uses a well-defined media 177 type. 179 o The resource to which the provided links pertain is able to link 180 to the resource that provides these links using a well-known link 181 relation type. 183 These requirements are addressed in this specification through the 184 definition of two media types and a link relation type, respectively. 186 3.2. Challenges Writing to HTTP Link Header Field 188 In some cases, it is not straightforward to write links to the HTTP 189 "Link" header field from an application. This can, for example, be 190 the case because not all required link information is available to 191 the application or because the application does not have the 192 capability to directly write HTTP headers. In such cases, providing 193 links by means of a standalone document can be a solution. Making 194 the resource that provides these links discoverable can be achieved 195 by means of a typed link. 197 3.3. Large Number of Links 199 When conveying links in an HTTP "Link" header field, it is possible 200 for the size of the HTTP response header to become unpredictable. 201 This can be the case when links are determined dynamically dependent 202 on a range of contextual factors. It is possible to statically 203 configure a web server to correctly handle large HTTP response 204 headers by specifying an upper bound for their size. But when the 205 number of links is unpredictable, estimating a reliable upper bound 206 is challenging. 208 HTTP [RFC7231] defines error codes related to excess communication by 209 the user agent ("413 Request Entity Too Large" and "414 Request-URI 210 Too Long"), but no specific error codes are defined to indicate that 211 response header content exceeds the upper bound that can be handled 212 by the server, and thus it has been truncated. As a result, 213 applications take counter measures aimed at controlling the size of 214 the HTTP "Link" header field, for example by limiting the links they 215 provide to those with select relation types, thereby limiting the 216 value of the HTTP "Link" header field to clients. Providing links by 217 means of a standalone document overcomes challenges related to the 218 unpredictable nature of the size of HTTP "Link" header fields. 220 4. Document Formats for Sets of Links 222 This section specifies two document formats to convey a set of links. 223 Both are based on the abstract model specified in Section 2 of Web 224 Linking [RFC8288] that defines a link as consisting of a "link 225 context", a "link relation type", a "link target", and optional 226 "target attributes": 228 o The format defined in Section 4.1 is identical to the payload of 229 the HTTP "Link" header field as specified in Web Linking 230 [RFC8288]. 232 o The format defined in Section 4.2 is based on JSON [RFC8259]. 234 Note that [RFC8288] deprecates the "rev" construct that was provided 235 by [RFC5988] as a means to express links with a directionality that 236 is the inverse of direct links that use the "rel" construct. In both 237 serializations for link sets defined here, inverse links SHOULD be 238 represented as direct links using the "rel" construct and by 239 switching the position of the resources involved in the link. 241 4.1. HTTP Link Document Format: application/linkset 243 This document format is identical to the payload of the HTTP "Link" 244 header field as defined in Section 3 of [RFC8288], more specifically 245 by its ABNF production rule for "Link" and subsequent ones. Whereas 246 the HTTP "Link" Header field depends on HTTP and hence on [RFC0822] 247 for its encoding, the format specified here is encoded as UTF-8 248 [RFC3629]. 250 The assigned media type for this format is "application/linkset". 252 In order to support use cases where "application/linkset" documents 253 are re-used outside the context of an HTTP interaction, it is 254 RECOMMENDED to make them self-contained by adhering to the following 255 guidelines: 257 o For every link provided in the set of links, explicitly provide 258 the link context using the "anchor" attribute. 260 o For link context ("anchor" attribute) and link target ("href" 261 attribute), use absolute URIs (as defined in Section 4.3 of 262 [RFC3986]). 264 If these recommendations are not followed, interpretation of links in 265 "application/linkset" documents will depend on which URI is used as 266 context. 268 It should be noted that the "application/linkset" format specified 269 here is different than the "application/link-format" format specified 270 in [RFC6690] in that the former fully matches the payload of the HTTP 271 "Link" header as defined in Section 3 of [RFC8288], whereas the 272 latter introduces constraints on that definition to meet requirements 273 for Constrained RESTful Environments. 275 4.2. JSON Document Format: application/linkset+json 277 This document format uses JSON [RFC8259] as the syntax to represent a 278 set of links. The set of links follows the abstract model defined by 279 Web Linking [RFC8288]. 281 The assigned media type for this format is "application/ 282 linkset+json". 284 In order to support use cases where "application/linkset+json" 285 documents are re-used outside the context of an HTTP interaction, it 286 is RECOMMENDED to make them self-contained by adhering to the 287 following guidelines: 289 o For every link provided in the set of links, explicitly provide 290 the link context using the "anchor" member. 292 o For link context ("anchor" member) and link target ("href" 293 member), use absolute URIs (as defined in Section 4.3 of 294 [RFC3986]). 296 If these recommendations are not followed, interpretation of 297 "application/linkset+json" will depend on which URI is used as 298 context URI. 300 The "application/linkset+json" serialization is designed such that it 301 can directly be used as the content of a JSON-LD serialization by 302 adding an appropriate context. Appendix B shows an example of a 303 possible context that, when added to a JSON serialization, allows it 304 to be interpreted as RDF. 306 4.2.1. Set of Links 308 In the JSON representation of a set of links: 310 o A set of links MUST be represented as a JSON object which MUST 311 have "linkset" as its sole member. 313 o The "linkset" member is an array in which a distinct JSON object - 314 the "link context object" (see Section 4.2.2) - MUST be used to 315 represent links that have the same link context. 317 o If necessary, the "linkset" member MAY contain information in 318 addition to link context objects, in which case that information 319 MUST NOT change the semantics of the links provided by those link 320 context objects. 322 o Even if there is only one link context object, it MUST be wrapped 323 in an array. Members other than link context objects MUST NOT be 324 included in this array. 326 4.2.2. Link Context Object 328 In the JSON representation one or more links that have the same link 329 context are represented by a JSON object, the link context object. A 330 link context object adheres to the following rules: 332 o Each link context object MAY have an "anchor" member with a value 333 that represents the link context. If present, this value SHOULD 334 be an absolute URI as defined in Section 4.3 of [RFC3986]. Cases 335 where the anchor member is present, but no value is provided for 336 it (i.e. the resource providing the set of links is the link 337 context for each link in the link context object) MUST be handled 338 by providing an "anchor" member with empty string ("anchor": ""). 340 o For each distinct relation type that the link context has with 341 link targets, a link context object MUST have an additional 342 member. This member is an array in which a distinct JSON object - 343 the "link target object" (see Section 4.2.3) - MUST be used for 344 each link target for which the relationship with the link context 345 (value of the encompassing anchor member) applies. The name of 346 this member expresses the relation type of the link as follows: 348 o 350 * For registered relation types [RFC8288], the name of this 351 member is the registered name of the relation type. 353 * For extension relation types [RFC8288], the name of this member 354 is the URI that uniquely represents the relation type. 356 o Even if there is only one link target object it MUST be wrapped in 357 an array. Members other than link target objects MUST NOT be 358 included in this array. 360 4.2.3. Link Target Object 362 In the JSON representation a link target is represented by a JSON 363 object, the link target object. A link target object adheres to the 364 following rules: 366 o Each link target object MUST have an "href" member with a value 367 that represents the link target. This value SHOULD be an absolute 368 URI as defined in Section 4.3 of [RFC3986]. Cases where the href 369 member is present, but no value is provided for it (i.e. the 370 resource providing the set of links is the target of the link in 371 the link target object) MUST be handled by providing an "href" 372 member with an empty string ("href": ""). 374 o In many cases, a link target is further qualified by target 375 attributes. Various types of attributes exist and they are 376 conveyed as additional members of the link target object as 377 detailed in Section 4.2.4. 379 The following example of a JSON-serialized set of links represents 380 one link with its core components: link context, link relation type, 381 and link target. 383 { 384 "linkset": 385 [ 386 { "anchor": "http://example.net/bar", 387 "next": [ 388 {"href": "http://example.com/foo"} 389 ] 390 } 391 ] 392 } 394 The following example of a JSON-serialized set of links represents 395 two links that share link context and relation type but have 396 different link targets. 398 { 399 "linkset": 400 [ 401 { "anchor": "http://example.net/bar", 402 "item": [ 403 {"href": "http://example.com/foo1"}, 404 {"href": "http://example.com/foo2"} 405 ] 406 } 407 ] 408 } 410 The following example shows a set of links that represents two links, 411 each with a different link context, link target, and relation type. 412 One relation type is registered, the other is an extension relation 413 type. 415 { 416 "linkset": 417 [ 418 { "anchor": "http://example.net/bar", 419 "next": [ 420 {"href": "http://example.com/foo1"} 421 ] 422 }, 423 { "anchor": "http://example.net/boo", 424 "http://example.com/relations/baz" : [ 425 {"href": "http://example.com/foo2"} 426 ] 427 } 428 ] 429 } 431 4.2.4. Link Target Attributes 433 A link may be further qualified by target attributes. Three types of 434 attributes exist: 436 o Attributes defined by the serialization of Web Linking [RFC8288]. 438 o Extension attributes defined and used by communities as allowed by 439 [RFC8288]. 441 o Internationalized versions of the "title" attribute defined by 442 [RFC8288] and of extension attributes allowed by [RFC8288]. 444 The handling of these different types of attributes is described in 445 the sections below. 447 4.2.4.1. Target Attributes Defined by Web Linking 449 RFC 8288 defines the following target attributes that may be used to 450 annotate links: "hreflang", "media", "title", "title*", and "type"; 451 these target attributes follow different occurrence and value 452 patterns. In the JSON representation, these attributes MUST be 453 conveyed as additional members of the link target object as follows: 455 o "hreflang": The optional and repeatable "hreflang" target 456 attribute MUST be represented by an array (even if there only is 457 one value to be represented), and each value in that array MUST be 458 a string - representing one value of the "hreflang" target 459 attribute for a link - which follows the same model as in the 460 [RFC8288] syntax. 462 o "media": The optional and not repeatable "media" target attribute 463 MUST be represented by a "media" member in the link target object, 464 and its value MUST be a string that follows the same model as in 465 the [RFC8288] syntax. 467 o "type": The optional and not repeatable "type" target attribute 468 MUST be represented by a "type" member in the link target object, 469 and its value MUST be a string that follows the same model as in 470 the [RFC8288] syntax. 472 o "title": The optional and not repeatable "title" target attribute 473 MUST be represented by a "title" member in the link target object, 474 and its value MUST be a string that follows the same model as in 475 the [RFC8288] syntax. 477 o "title*": The optional and not repeatable "title*" target 478 attribute is motivated by character encoding and language issues 479 and follows the model defined in [RFC8187]. The details of the 480 JSON representation that applies to title* are described in 481 Section 4.2.4.2. 483 The following example illustrates how the repeatable "hreflang" and 484 the not repeatable "type" target attributes are represented in a link 485 target object. 487 { 488 "linkset": 489 [ 490 { "anchor": "http://example.net/bar", 491 "next": [ 492 {"href": "http://example.com/foo", 493 "type": "text/html", 494 "hreflang": [ "en" , "de" ] 495 } 496 ] 497 } 498 ] 499 } 501 4.2.4.2. Internationalized Target Attributes 503 In addition to the target attributes described in Section 4.2.4.1, 504 [RFC8288] also supports attributes that follow the content model of 505 [RFC8187]. In [RFC8288], these target attributes are recognizable by 506 the use of a trailing asterisk in the attribute name, such as 507 "title*". The content model of [RFC8187] uses a string-based 508 microsyntax that represents the character encoding, an optional 509 language tag, and the escaped attribute value encoded according to 510 the specified character encoding. 512 The JSON serialization for these target attributes MUST be as 513 follows: 515 o An internationalized target attribute is represented as a member 516 of the link context object with the same name (including the *) of 517 the attribute. 519 o The character encoding information as prescribed by [RFC8187] is 520 not preserved; instead, the content of the internationalized 521 attribute is represented in the character encoding used for the 522 JSON set of links. 524 o The value of the internationalized target attribute is an array 525 that contains one or more JSON objects. The name of one member of 526 such JSON object is "value" and its value is the actual content 527 (in its unescaped version) of the internationalized target 528 attribute, i.e. the value of the attribute from which the encoding 529 and language information are removed. The name of another, 530 optional, member of such JSON object is "language" and its value 531 is the language tag [RFC5646] for the language in which the 532 attribute content is conveyed. 534 The following example illustrates how the "title*" target attribute 535 defined by [RFC8288] is represented in a link target object. 537 { 538 "linkset": 539 [ 540 { "anchor": "http://example.net/bar", 541 "next": [ 542 {"href": "http://example.com/foo", 543 "type": "text/html", 544 "hreflang": [ "en" , "de" ], 545 "title": "Next chapter", 546 "title*": [ { "value": "nachstes Kapitel" , 547 "language" : "de" } ] 548 } 549 ] 550 } 551 ] 552 } 554 The above example assumes that the German title contains an umlaut 555 character (in the native syntax it would be encoded as title*=UTF- 556 8'de'n%c3%a4chstes%20Kapitel), which gets encoded in its unescaped 557 form in the JSON representation. This is not shown in the above 558 example due to the limitations of RFC publication. Implementations 559 MUST properly decode/encode internationalized target attributes that 560 follow the model of [RFC8187] when transcoding between the 561 "application/linkset" and the "application/linkset+json" formats. 563 4.2.4.3. Extension Target Attributes 565 Extension target attributes are attributes that are not defined by 566 [RFC8288] (as listed in Section 4.2.4.1), but are nevertheless used 567 to qualify links. They can be defined by communities in any way 568 deemed necessary, and it is up to them to make sure their usage is 569 understood by target applications. However, lacking standardization, 570 there is no interoperable understanding of these extension 571 attributes. One important consequence is that their cardinality is 572 unknown to generic applications. Therefore, in the JSON 573 serialization, all extension target attributes are treated as 574 repeatable. 576 The JSON serialization for these target attributes MUST be as 577 follows: 579 o An extension target attribute is represented as a member of the 580 link context object with the same name of the attribute, including 581 the * if applicable. 583 o The value of an extension attribute MUST be represented by an 584 array, even if there only is one value to be represented. 586 o If the extension target attribute does not have a name with a 587 trailing asterisk, then each value in that array MUST be a string 588 that represents one value of the attribute. 590 o If the extension attribute has a name with a trailing asterisk (it 591 follows the content model of [RFC8187]), then each value in that 592 array MUST be a JSON object. The value of each such JSON object 593 MUST be structured as described in Section 4.2.4.2. 595 The example shows a link target object with three extension target 596 attributes. The value for each extension target attribute is an 597 array. The two first are regular extension target attributes, with 598 the first one ("foo") having only one value and the second one 599 ("bar") having two. The last extension target attribute ("baz*") 600 follows the naming rule of [RFC8187] and therefore is encoded 601 according to the serialization described in Section 4.2.4.2. 603 { 604 "linkset": 605 [ 606 { "anchor": "http://example.net/bar", 607 "next": [ 608 { "href": "http://example.com/foo", 609 "type": "text/html", 610 "foo": [ "foovalue" ], 611 "bar": [ "barone", "bartwo" ], 612 "baz*": [ { "value": "bazvalue" , 613 "language" : "en" } ] 614 } 615 ] 616 } 617 ] 618 } 620 4.2.5. JSON Extensibility 622 The extensibility of the JSON document format for representing a set 623 of links is restricted to the extensibility provided by [RFC8288]. 624 The Web linking model provides for the use of extension target 625 attributes as discussed in Section 4.2.4.3. Extensions based on the 626 JSON syntax MUST NOT be used, and MUST be ignored when found in a 627 JSON linkset document. 629 This limitation of the JSON format allows to unambiguously round trip 630 between links provided in the HTTP "Link" header, sets of links 631 serialized according to the "application/linkset" format, and sets of 632 links serialized according to the "application/linkset+json" format. 634 5. The "profile" attribute for media types to Represent Sets of Links 636 As a means to convey specific constraints or conventions (as per 637 [RFC6906]) that apply to a link set document, the "profile" attribute 638 MAY be used in conjunction with the media types "application/linkset" 639 and "application/linkset+json" detailed in Section 4.1 and 640 Section 4.2, respectively. For example, the attribute could be used 641 to indicate that a link set uses a specific, limited set of link 642 relation types. 644 The value of the "profile" attribute MUST be a non-empty list of 645 space-separated URIs, each of which identifies specific constraints 646 or conventions that apply to the link set document. Profile URIs MAY 647 be registered in the IANA Profile URI Registry in the manner 648 specified by [RFC7284]. 650 The presence of a "profile" attribute in conjunction with the 651 "application/linkset" and "application/linkset+json" media types does 652 not change the semantics of a link set. As such, clients with and 653 without knowledge of profile URIs can use the same representation. 654 The profile parameter MAY be used by clients to express their 655 preferences, and, if a client does so, a server SHOULD return a 656 document that honors the profiles it recognizes, and MUST ignore the 657 profiles which it does not recognize. 659 6. The "linkset" Relation Type for Linking to a Set of Links 661 The target of a link with the "linkset" relation type provides a set 662 of links, including links in which the resource that is the link 663 context participates. 665 A link with the "linkset" relation type MAY be provided in the header 666 and/or the body of a resource's representation. It may also be 667 discovered by other means, such as through client-side information. 669 A resource MAY provide more than one link with a "linkset" relation 670 type. Multiple such links can refer to the same set of links 671 expressed using different media types, or to different sets of links, 672 potentially provided by different third-party services. 674 A user agent that follows a "linkset" link MUST be aware that the set 675 of links provided by the resource that is the target of the link can 676 contain links in which the resource that is the context of the link 677 does not participate; it MAY decide to ignore those links. 679 A user agent that follows a "linkset" link and obtains links for 680 which anchors and targets are not expressed as absolute URIs MUST 681 properly determine what the context is for these links; it SHOULD 682 ignore links for which it is unable to unambiguously make that 683 determination. 685 7. Examples 687 Section 7.1 and Section 7.2 show examples whereby a set of links is 688 provided as "application/linkset" and "application/linkset+json" 689 documents, respectively. Section 7.3 illustrates the use of the 690 "linkset" link relation type to support discovery of sets of links. 692 7.1. Set of Links Provided as application/linkset 694 Figure 1 shows a client issuing an HTTP GET request against resource 695 . 697 GET /links/resource1 HTTP/1.1 698 Host: example.org 699 Connection: close 701 Figure 1: Client HTTP GET request 703 Figure 2 shows the response to the GET request of Figure 1. The 704 response contains a Content-Type header specifying that the media 705 type of the response is "application/linkset". A set of links, 706 revealing authorship and versioning related to resource 707 , is provided in the response body. 708 The HTTP "Link" header indicates the availability of an alternate 709 representation of the set of links using media type "application/ 710 linkset+json". 712 HTTP/1.1 200 OK 713 Date: Mon, 12 Aug 2019 10:35:51 GMT 714 Server: Apache-Coyote/1.1 715 Content-Length: 1023 716 Content-Type: application/linkset; charset=UTF-8 717 Link: ; rel="alternate" 718 ; type="application/linkset+json" 719 Connection: close 720 721 ; rel="author" 722 ; type="application/rdf+xml" 723 ; anchor="https://example.org/resource1", 724 725 ; rel="latest-version" 726 ; type="text/html" 727 ; anchor="https://example.org/resource1", 728 729 ; rel="predecessor-version" 730 ; type="text/html" 731 ; anchor="https://example.org/resource1?version=3", 732 733 ; rel="predecessor-version" 734 ; type="text/html" 735 ; anchor="https://example.org/resource1?version=2", 736 737 ; rel="memento" 738 ; type="text/html" 739 ; datetime="Thu, 13 Jun 2019 09:34:33 GMT" 740 ; anchor="https://example.org/resource1", 741 742 ; rel="memento" 743 ; type="text/html" 744 ; datetime="Sun, 21 Jul 2019 12:22:04 GMT" 745 ; anchor="https://example.org/resource1", 746 747 ; rel="author" 748 ; anchor="https://example.org/resource1#comment=1" 750 Figure 2: Response to HTTP GET includes a set of links 752 7.2. Set of Links Provided as application/linkset+json 754 Figure 3 shows the client issuing an HTTP GET request against 755 . In the request, the client 756 uses an "Accept" header to indicate it prefers a response in the 757 "application/linkset+json" format. 759 GET links/resource1 HTTP/1.1 760 Host: example.org 761 Accept: application/linkset+json 762 Connection: close 764 Figure 3: Client HTTP GET request expressing preference for 765 "application/linkset+json" response 767 Figure 4 shows the response to the HTTP GET request of Figure 3. The 768 set of links is serialized according to the media type "application/ 769 linkset+json". 771 HTTP/1.1 200 OK 772 Date: Mon, 12 Aug 2019 10:46:22 GMT 773 Server: Apache-Coyote/1.1 774 Content-Type: application/linkset+json 775 Link: ; rel="alternate" 776 ; type="application/linkset" 777 Content-Length: 1349 778 { 779 "linkset": [ 780 { 781 "anchor": "https://example.org/resource1", 782 "author": [ 783 { 784 "href": "https://authors.example.net/johndoe", 785 "type": "application/rdf+xml" 786 } 787 ], 788 "memento": [ 789 { 790 "href": "https://example.org/resource1?version=1", 791 "type": "text/html", 792 "datetime": "Thu, 13 Jun 2019 09:34:33 GMT" 793 }, 794 { 795 "href": "https://example.org/resource1?version=2", 796 "type": "text/html", 797 "datetime": "Sun, 21 Jul 2019 12:22:04 GMT" 798 } 799 ], 800 "latest-version": [ 801 { 802 "href": "https://example.org/resource1?version=3", 803 "type": "text/html" 804 } 805 ] 806 }, 807 { 808 "anchor": "https://example.org/resource1?version=3", 809 "predecessor-version": [ 810 { 811 "href": "https://example.org/resource1?version=2", 812 "type": "text/html" 813 } 814 ] 815 }, 816 { 817 "anchor": "https://example.org/resource1?version=2", 818 "predecessor-version": [ 819 { 820 "href": "https://example.org/resource1?version=1", 821 "type": "text/html" 822 } 823 ] 824 }, 825 { 826 "anchor": "https://example.org/resource1#comment=1", 827 "author": [ 828 { 829 "href": "https://authors.example.net/alice" 830 } 831 ] 832 } 833 ] 834 } 836 Figure 4: Response to the client's request for the set of links 838 7.3. Discovering a Link Set via the "linkset" Link Relation Type 840 Figure 5 shows a client issuing an HTTP HEAD request against resource 841 . 843 HEAD resource1 HTTP/1.1 844 Host: example.org 845 Connection: close 847 Figure 5: Client HTTP HEAD request 849 Figure 6 shows the response to the HEAD request of Figure 5. The 850 response contains an HTTP "Link" header with a link that has the 851 "linkset" relation type. It indicates that a set of links is 852 provided by resource , which 853 provides a representation with media type "application/linkset+json". 855 HTTP/1.1 200 OK 856 Date: Mon, 12 Aug 2019 10:45:54 GMT 857 Server: Apache-Coyote/1.1 858 Link: 859 ; rel="linkset" 860 ; type="application/linkset+json" 861 Content-Length: 236 862 Content-Type: text/html;charset=utf-8 863 Connection: close 865 Figure 6: Response to HTTP HEAD request 867 Section 7.2 shows a client obtaining a set of links by issuing an 868 HTTP GET on the target of the link with the "linkset" relation type, 869 . 871 8. Implementation Status 873 Note to RFC Editor: Please remove this section before publication. 875 This section records the status of known implementations of the 876 protocol defined by this specification at the time of posting of this 877 Internet-Draft, and is based on a proposal described in RFC 6982 878 [RFC6982]. The description of implementations in this section is 879 intended to assist the IETF in its decision processes in progressing 880 drafts to RFCs. Please note that the listing of any individual 881 implementation here does not imply endorsement by the IETF. 882 Furthermore, no effort has been spent to verify the information 883 presented here that was supplied by IETF contributors. This is not 884 intended as, and must not be construed to be, a catalog of available 885 implementations or their features. Readers are advised to note that 886 other implementations may exist. 888 According to RFC 6982, "this will allow reviewers and working groups 889 to assign due consideration to documents that have the benefit of 890 running code, which may serve as evidence of valuable experimentation 891 and feedback that have made the implemented protocols more mature. 892 It is up to the individual working groups to use this information as 893 they see fit". 895 8.1. GS1 897 GS1 is a provider of barcodes (GS1 GTINs and EAN/UPC) for retail 898 products and manages an ecology of services and standards to leverage 899 them at a global scale. GS1 has indicated that it will implement 900 this "linkset" specification as a means to allow requesting and 901 representing links pertaining to products from various retailers. 903 Currently, the GS1 Digital Link specification makes an informative 904 reference to version 03 of the "linkset" I-D. GS1 expresses 905 confidence that this will become a normative reference in the next 906 iteration of that specification, likely to be ratified as a GS1 907 standard around February 2021. 909 8.2. FAIR Signposting Profile 911 The FAIR Signposting Profile is a community specification aimed at 912 improving machine navigation of scholarly objects on the web through 913 the use of typed web links pointing at e.g. web resources that are 914 part of a specific object, persistent identifiers for the object and 915 its authors, license information pertaining to the object. The 916 specification encourages the use of Linksets and initial 917 implementations are ongoing, for example, for the open source 918 Dataverse data repository platform that was initiated by Harvard 919 University and is meanwhile used by research institutions, worldwide. 921 8.3. Open Journal Systems (OJS) 923 Open Journal Systems (OJS) is an open-source software for the 924 management of peer-reviewed academic journals, and is created by the 925 Public Knowledge Project (PKP), released under the GNU General Public 926 License. Open Journal Systems (OJS) is a journal management and 927 publishing system that has been developed by PKP through its 928 federally funded efforts to expand and improve access to research. 930 The OJS platform has implemented "linkset" support as an alternative 931 way to provide links when there are more than a configured limit 932 (they consider using about 10 as a good default, for testing purpose 933 it is currently set to 8). 935 9. IANA Considerations 937 9.1. Link Relation Type: linkset 939 The link relation type below has been registered by IANA per 940 Section 6.2.1 of Web Linking [RFC8288]: 942 Relation Name: linkset 944 Description: The Target IRI of a link with the "linkset" relation 945 type provides a set of links, including links in which the Context 946 IRI of the link participates. 948 Reference: [[ This document ]] 950 9.2. Media Type: application/linkset 952 The Internet media type [RFC6838] for a natively encoded linkset is 953 application/linkset. 955 Type name: application 957 Subtype name: linkset 959 Required parameters: none 961 Optional parameters: profile 963 Encoding considerations: Linksets are encoded according to the 964 definition of [RFC8288]. The encoding of [RFC8288] is based on 965 the general encoding rules of [RFC7230], with the addition of 966 allowing indicating character encoding and language for specific 967 parameters as defined by [RFC8187]. 969 Security considerations: The security considerations of [[ This 970 document ]] apply. 972 Interoperability considerations: The interoperability 973 considerations of [RFC7230] apply. 975 Published specification: [[ This document ]] 977 Applications that use this media type: This media type is not 978 specific to any application, as it can be used by any application 979 that wants to interchange web links. 981 Additional information: 983 Magic number(s): N/A 985 File extension(s): This media type does not propose a specific 986 extension. 988 Macintosh file type code(s): TEXT 990 Person & email address to contact for further information: Erik 991 Wilde 993 Intended usage: COMMON 995 Restrictions on usage: none 997 Author: Erik Wilde 998 Change controller: IETF 1000 9.3. Media Type: application/linkset+json 1002 The Internet media type [RFC6838] for a JSON-encoded linkset is 1003 application/linkset+json. 1005 Type name: application 1007 Subtype name: linkset+json 1009 Required parameters: none 1011 Optional parameters: profile 1013 Encoding considerations: The encoding considerations of [RFC8259] 1014 apply 1016 Security considerations: The security considerations of [[ This 1017 document ]] apply. 1019 Interoperability considerations: The interoperability 1020 considerations of [RFC8259] apply. 1022 Published specification: [[ This document ]] 1024 Applications that use this media type: This media type is not 1025 specific to any application, as it can be used by any application 1026 that wants to interchange web links. 1028 Additional information: 1030 Magic number(s): N/A 1032 File extension(s): JSON documents often use ".json" as the file 1033 extension, and this media type does not propose a specific 1034 extension other than this generic one. 1036 Macintosh file type code(s): TEXT 1038 Person & email address to contact for further information: Erik 1039 Wilde 1041 Intended usage: COMMON 1043 Restrictions on usage: none 1045 Author: Erik Wilde 1046 Change controller: IETF 1048 10. Security Considerations 1050 The security considerations of Web Linking [RFC8288] apply, as long 1051 as they are not specifically discussing the risks of exposing 1052 information in HTTP header fields. 1054 In general, links may cause information leakage when they expose 1055 information (such as URIs) that can be sensitive or private. Links 1056 may expose "hidden URIs" that are not supposed to be openly shared, 1057 and may not be sufficiently protected. Ideally, none of the URIs 1058 exposed in links should be supposed to be "hidden"; instead, if these 1059 URIs are supposed to be limited to certain users, then technical 1060 measures should be put in place so that accidentally exposing them 1061 does not cause any harm. 1063 For the specific mechanisms defined in this specification, two 1064 security considerations should be taken into account: 1066 o The Web Linking model always has an "implicit context", which is 1067 the resource of the HTTP interaction. This original context can 1068 be lost or can change when self-contained link representations are 1069 moved. Changing the context can change the interpretation of 1070 links when they have no explicit anchor, or when they use relative 1071 URIs. Applications may choose to ignore links that have no 1072 explicit anchor or that use relative URIs when these are exchanged 1073 in stand-alone resources. 1075 o The model introduced in this specification supports "3rd party 1076 links", where one party can provide links that have another 1077 party's resource as an anchor. Depending on the link semantics 1078 and the application context, it is important to verify that there 1079 is sufficient trust in that 3rd party to allow it to provide these 1080 links. Applications may choose to treat 3rd party links 1081 differently than cases where a resource and the links for that 1082 resource are provided by the same party. 1084 11. References 1086 11.1. Normative References 1088 [RFC0822] Crocker, D., "STANDARD FOR THE FORMAT OF ARPA INTERNET 1089 TEXT MESSAGES", STD 11, RFC 822, DOI 10.17487/RFC0822, 1090 August 1982, . 1092 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1093 Requirement Levels", BCP 14, RFC 2119, 1094 DOI 10.17487/RFC2119, March 1997, 1095 . 1097 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1098 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1099 2003, . 1101 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1102 Resource Identifier (URI): Generic Syntax", STD 66, 1103 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1104 . 1106 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1107 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1108 September 2009, . 1110 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1111 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1112 . 1114 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1115 Specifications and Registration Procedures", BCP 13, 1116 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1117 . 1119 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, 1120 DOI 10.17487/RFC6906, March 2013, 1121 . 1123 [RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1124 Code: The Implementation Status Section", RFC 6982, 1125 DOI 10.17487/RFC6982, July 2013, 1126 . 1128 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1129 Protocol (HTTP/1.1): Message Syntax and Routing", 1130 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1131 . 1133 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1134 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1135 DOI 10.17487/RFC7231, June 2014, 1136 . 1138 [RFC7284] Lanthaler, M., "The Profile URI Registry", RFC 7284, 1139 DOI 10.17487/RFC7284, June 2014, 1140 . 1142 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1143 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1144 May 2017, . 1146 [RFC8187] Reschke, J., "Indicating Character Encoding and Language 1147 for HTTP Header Field Parameters", RFC 8187, 1148 DOI 10.17487/RFC8187, September 2017, 1149 . 1151 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1152 Interchange Format", STD 90, RFC 8259, 1153 DOI 10.17487/RFC8259, December 2017, 1154 . 1156 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1157 DOI 10.17487/RFC8288, October 2017, 1158 . 1160 11.2. Informative References 1162 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1163 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 1164 December 2005, . 1166 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 1167 DOI 10.17487/RFC5988, October 2010, 1168 . 1170 [W3C.REC-json-ld-20140116] 1171 Sporny, M., Kellogg, G., and M. Lanthaler, "JSON-LD 1.0", 1172 World Wide Web Consortium Recommendation REC-json-ld- 1173 20140116, January 2014, 1174 . 1176 11.3. URIs 1178 [1] https://www.w3.org/TR/2014/REC-json-ld-20140116/#interpreting- 1179 json-as-json-ld 1181 [2] https://tools.ietf.org/html/rfc8288#appendix-A.2 1183 Appendix A. Acknowledgements 1185 Thanks for comments and suggestions provided by Phil Archer, 1186 Dominique Guinard, Mark Nottingham, Stian Soiland-Reyes, and Sarven 1187 Capadisli. 1189 Appendix B. JSON-LD Context 1191 A set of links rendered according to the JSON serialization defined 1192 in Section 4.2 can be interpreted as RDF triples by adding a JSON-LD 1193 context [W3C.REC-json-ld-20140116] that maps the JSON keys to 1194 corresponding Linked Data terms. And, as per 1195 [W3C.REC-json-ld-20140116] section 6.8 [1], when delivering a link 1196 set that is rendered according to the "application/linkset+json" 1197 media type to a user agent, a server can convey the availability of 1198 such a JSON-LD context by using a link with the relation type 1199 "http://www.w3.org/ns/json-ld#context" in the HTTP "Link" header. 1201 Using the latter approach to support discovery of a JSON-LD Context, 1202 the response to the GET request of Figure 3 against the URI of a set 1203 of links would be as shown in Figure 7. 1205 HTTP/1.1 200 OK 1206 Date: Mon, 12 Aug 2019 10:48:22 GMT 1207 Server: Apache-Coyote/1.1 1208 Content-Type: application/linkset+json 1209 Link: 1210 ; rel="http://www.w3.org/ns/json-ld#context" 1211 ; type="application/ld+json" 1212 Content-Length: 846 1213 { 1214 "linkset": [ 1215 { 1216 "anchor": "https://example.org/article/view/7507", 1217 "author": [ 1218 { 1219 "href": "https://orcid.org/0000-0002-1825-0097" 1220 } 1221 ], 1222 "item": [ 1223 { 1224 "href": "https://example.org/article/7507/item/1", 1225 "type": "application/pdf" 1226 }, 1227 { 1228 "href": "https://example.org/article/7507/item/2", 1229 "type": "text/csv" 1230 } 1231 ], 1232 "cite-as": [ 1233 { 1234 "href": "https://doi.org/10.5555/12345680", 1235 "title": "A Methodology for the Emulation of Architecture" 1236 } 1237 ] 1238 }, 1239 { 1240 "anchor": "https://example.com/links/article/7507", 1241 "alternate": [ 1242 { 1243 "href": "https://mirror.example.com/links/article/7507", 1244 "type": "application/linkset" 1245 } 1246 ] 1247 } 1248 ] 1249 } 1251 Figure 7: Using a typed link to support discovery of a JSON-LD 1252 Context for a Set of Links 1254 In order to obtain the JSON-LD Context conveyed by the server, the 1255 user agent issues an HTTP GET against the link target of the link 1256 with the "http://www.w3.org/ns/json-ld#context" relation type. The 1257 response to this GET is shown in Figure 8. This particular JSON-LD 1258 context maps "application/linkset+json" representations of link sets 1259 to Dublin Core Terms. It also renders each link relation as an 1260 absolute URI, inspired by the same approach used for Atom [RFC4287] 1261 described in [RFC8288] appendix A.2 [2]. 1263 HTTP/1.1 200 OK 1264 Content-Type: application/ld+json 1265 Content-Length: 638 1266 { 1267 "@context": [ 1268 { 1269 "@vocab": "http://www.iana.org/assignments/relation/", 1270 "anchor": "@id", 1271 "href": "@id", 1272 "linkset": "@graph", 1273 "_linkset": "@graph", 1274 "title": { 1275 "@id": "http://purl.org/dc/terms/title" 1276 }, 1277 "title*": { 1278 "@id": "http://purl.org/dc/terms/title" 1279 }, 1280 "type": { 1281 "@id": "http://purl.org/dc/terms/format" 1282 } 1283 }, 1284 { 1285 "language": "@language", 1286 "value": "@value", 1287 "hreflang": { 1288 "@id": "http://purl.org/dc/terms/language", 1289 "@container": "@set" 1290 } 1291 } 1292 ] 1293 } 1295 Figure 8: JSON-LD Context mapping to schema.org and IANA assignments 1297 Applying the JSON-LD context of Figure 8 to the link set of Figure 7 1298 allows transforming the "application/linkset+json" link set to an RDF 1299 link set. Figure 9 shows the latter represented by means of the 1300 "text/turtle" RDF serialization. 1302 1303 1304 . 1305 1306 1307 . 1308 1309 1310 "application/pdf" . 1311 1312 1313 . 1314 1315 1316 "text/csv" . 1317 1318 1319 . 1320 1321 1322 "A Methodology for the Emulation of Architecture" . 1323 1324 1325 . 1326 1327 1328 "application/linkset" . 1330 Figure 9: RDF serialization of the link set resulting from applying 1331 the JSON-LD context 1333 Note that the JSON-LD context of Figure 8 does not handle (meta)link 1334 relations of type ""linkset"" as they are in conflict with the top- 1335 level JSON key. A workaround is to rename the top-level key to 1336 ""_linkset"" in the "application/linkset+json" before transforming a 1337 link set to JSON-LD. 1339 Authors' Addresses 1341 Erik Wilde 1342 Axway 1344 Email: erik.wilde@dret.net 1345 URI: http://dret.net/netdret/ 1346 Herbert Van de Sompel 1347 Data Archiving and Networked Services 1349 Email: herbert.van.de.sompel@dans.knaw.nl 1350 URI: https://orcid.org/0000-0002-0715-6126