idnits 2.17.1 draft-ietf-httpapi-linkset-07.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: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. 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 17 characters in excess of 72. == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (8 February 2022) is 805 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 2 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: 12 August 2022 Data Archiving and Networked Services 6 8 February 2022 8 Linkset: Media Types and a Link Relation Type for Link Sets 9 draft-ietf-httpapi-linkset-07 11 Abstract 13 This specification defines two formats and respective media types for 14 representing sets of links as stand-alone documents. One format is 15 JSON-based, the other aligned with the format for representing links 16 in the HTTP "Link" header field. This specification also introduces 17 a link relation type to support discovery of sets of links. 19 Note to Readers 21 Please discuss this draft on the "Building Blocks for HTTP APIs" 22 mailing list (https://www.ietf.org/mailman/listinfo/httpapi). 24 Online access to all versions and files is available on GitHub 25 (https://github.com/ietf-wg-httpapi/linkset). 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on 12 August 2022. 44 Copyright Notice 46 Copyright (c) 2022 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 51 license-info) in effect on the date of publication of this document. 52 Please review these documents carefully, as they describe your rights 53 and restrictions with respect to this document. Code Components 54 extracted from this document must include Revised BSD License text as 55 described in Section 4.e of the Trust Legal Provisions and are 56 provided without warranty as described in the Revised BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 3. Use Cases and Motivation . . . . . . . . . . . . . . . . . . 3 63 3.1. Third-Party Links . . . . . . . . . . . . . . . . . . . . 4 64 3.2. Challenges Writing to HTTP Link Header Field . . . . . . 5 65 3.3. Large Number of Links . . . . . . . . . . . . . . . . . . 5 66 4. Document Formats for Sets of Links . . . . . . . . . . . . . 5 67 4.1. HTTP Link Document Format: application/linkset . . . . . 6 68 4.2. JSON Document Format: application/linkset+json . . . . . 7 69 4.2.1. Set of Links . . . . . . . . . . . . . . . . . . . . 7 70 4.2.2. Link Context Object . . . . . . . . . . . . . . . . . 8 71 4.2.3. Link Target Object . . . . . . . . . . . . . . . . . 8 72 4.2.4. Link Target Attributes . . . . . . . . . . . . . . . 10 73 4.2.5. JSON Extensibility . . . . . . . . . . . . . . . . . 14 74 5. The "profile" parameter for media types to Represent Sets of 75 Links . . . . . . . . . . . . . . . . . . . . . . . . . . 15 76 6. The "linkset" Relation Type for Linking to a Set of Links . . 15 77 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 16 78 7.1. Set of Links Provided as application/linkset . . . . . . 16 79 7.2. Set of Links Provided as application/linkset+json . . . . 17 80 7.3. Discovering a Link Set via the "linkset" Link Relation 81 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 19 82 7.4. Link Set Profiles . . . . . . . . . . . . . . . . . . . . 20 83 7.4.1. Using a "profile" Attribute with a "linkset" Link . . 20 84 7.4.2. Using a "profile" Parameter with a Link Set Media 85 Type . . . . . . . . . . . . . . . . . . . . . . . . 20 86 7.4.3. Using a Link with a "profile" Link Relation Type . . 21 87 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 88 8.1. Link Relation Type: linkset . . . . . . . . . . . . . . . 22 89 8.2. Media Type: application/linkset . . . . . . . . . . . . . 22 90 8.3. Media Type: application/linkset+json . . . . . . . . . . 23 91 9. Security Considerations . . . . . . . . . . . . . . . . . . . 24 92 10. Normative References . . . . . . . . . . . . . . . . . . . . 25 93 11. Informative References . . . . . . . . . . . . . . . . . . . 26 94 Appendix A. JSON-LD Context . . . . . . . . . . . . . . . . . . 27 95 Appendix B. Implementation Status . . . . . . . . . . . . . . . 32 96 B.1. GS1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 97 B.2. FAIR Signposting Profile . . . . . . . . . . . . . . . . 33 98 B.3. Open Journal Systems (OJS) . . . . . . . . . . . . . . . 33 99 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 33 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 102 1. Introduction 104 Resources on the Web often use typed Web Links [RFC8288], either 105 embedded in resource representations, for example using the 106 element for HTML documents, or conveyed in the HTTP "Link" header 107 field for documents of any media type. In some cases, however, 108 providing links in this manner is impractical or impossible and 109 delivering a set of links as a stand-alone document is preferable. 111 Therefore, this specification defines two formats for representing 112 sets of Web Links and their attributes as stand-alone documents. One 113 serializes links in the same format as used in HTTP the Link header 114 field, and the other serializes links in JSON. It also defines 115 associated media types to represent sets of links and the "linkset" 116 relation type that supports discovery of any resource that conveys a 117 set of links as a stand-alone document. 119 2. Terminology 121 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 123 "OPTIONAL" in this document are to be interpreted as described in BCP 124 14 [RFC2119] [RFC8174] when, and only when, they appear in all 125 capitals, as shown here. 127 This specification uses the terms "link context" and "link target" as 128 defined in [RFC8288]. 130 In the examples provided in this document, links in the HTTP "Link" 131 header field are shown on separate lines in order to improve 132 readability. Note, however, that as per Section 5.5 of 133 [I-D.ietf-httpbis-semantics], line breaks are deprecated in values 134 for HTTP fields; only whitespaces and tabs are supported as 135 separators. 137 3. Use Cases and Motivation 139 The following sections describe use cases in which providing links by 140 means of a standalone document instead of in an HTTP "Link" header 141 field or as links embedded in the resource representation is 142 advantageous or necessary. 144 For all scenarios, links could be provided by means of a stand-alone 145 document that is formatted according to the JSON-based serialization, 146 the serialization aligned with the HTTP "Link" field format, or both. 147 The former serialization is motivated by the widespread use of JSON 148 and related tools, which suggests that handling sets of links 149 expressed as JSON documents should be attractive to developers. The 150 latter serialization is provided for compatibility with the existing 151 serialization used in the HTTP "Link" field and to allow reuse of 152 tools created to handle it. 154 It is important to keep in mind that when providing links by means of 155 a standalone representation, other links can still be provided using 156 other approaches, i.e. it is possible to combine various mechanisms 157 to convey links. 159 3.1. Third-Party Links 161 In some cases it is useful that links pertaining to a resource are 162 provided by a server other than the one that hosts the resource. For 163 example, this allows: 165 * Providing links in which the resource is involved not just as link 166 context but also as link target. 168 * Providing links pertaining to the resource that the server hosting 169 that resource is not aware of. 171 * External management of links pertaining to the resource in a 172 special-purpose link management service. 174 In such cases, links pertaining to a resource can be provided by 175 another, specific resource. That specific resource may be managed by 176 the same or by another custodian as the resource to which the links 177 pertain. For clients intent on consuming links provided in that 178 manner, it would be beneficial if the following conditions were met: 180 * Links are provided in a document that uses a well-defined media 181 type. 183 * The resource to which the provided links pertain is able to link 184 to the resource that provides these links using a well-known link 185 relation type. 187 These requirements are addressed in this specification through the 188 definition of two media types and a link relation type, respectively. 190 3.2. Challenges Writing to HTTP Link Header Field 192 In some cases, it is not straightforward to write links to the HTTP 193 "Link" header field from an application. This can, for example, be 194 the case because not all required link information is available to 195 the application or because the application does not have the 196 capability to directly write HTTP fields. In such cases, providing 197 links by means of a standalone document can be a solution. Making 198 the resource that provides these links discoverable can be achieved 199 by means of a typed link. 201 3.3. Large Number of Links 203 When conveying links in an HTTP "Link" header field, it is possible 204 for the size of the HTTP response fields to become unpredictable. 205 This can be the case when links are determined dynamically dependent 206 on a range of contextual factors. It is possible to statically 207 configure a web server to correctly handle large HTTP response fields 208 by specifying an upper bound for their size. But when the number of 209 links is unpredictable, estimating a reliable upper bound is 210 challenging. 212 Section 15 of HTTP [I-D.ietf-httpbis-semantics] defines error codes 213 related to excess communication by the user agent ("413 Request 214 Entity Too Large" and "414 Request-URI Too Long"), but no specific 215 error codes are defined to indicate that response field content 216 exceeds the upper bound that can be handled by the server, and thus 217 it has been truncated. As a result, applications take counter 218 measures aimed at controlling the size of the HTTP "Link" header 219 field, for example by limiting the links they provide to those with 220 select relation types, thereby limiting the value of the HTTP "Link" 221 header field to clients. Providing links by means of a standalone 222 document overcomes challenges related to the unpredictable nature of 223 the size of HTTP "Link" header fields. 225 4. Document Formats for Sets of Links 227 This section specifies two document formats to convey a set of links. 228 Both are based on the abstract model specified in Section 2 of Web 229 Linking [RFC8288] that defines a link as consisting of a "link 230 context", a "link relation type", a "link target", and optional 231 "target attributes": 233 * The format defined in Section 4.1 is near identical to the field 234 value of the HTTP "Link" header field as specified in Web Linking 235 Section 3 of [RFC8288]. 237 * The format defined in Section 4.2 is based on JSON [RFC8259]. 239 Note that Section 3.3 of [RFC8288] deprecates the "rev" construct 240 that was provided by [RFC5988] as a means to express links with a 241 directionality that is the inverse of direct links that use the "rel" 242 construct. In both serializations for link sets defined here, 243 inverse links may be represented as direct links using the "rel" 244 construct and by switching the position of the resources involved in 245 the link. 247 4.1. HTTP Link Document Format: application/linkset 249 This document format is near identical to the field value of the HTTP 250 "Link" header field as defined in Section 3 of [RFC8288], more 251 specifically by its ABNF [RFC5234] production rule for "Link" and 252 subsequent ones. It differs only from the format for field values of 253 the HTTP "Link" header in that not only spaces and horizontal tabs 254 are allowed as separators but also newline characters as a means to 255 improve readability for humans. The use of non-ASCII characters in 256 the field value of the HTTP "Link" Header field is not allowed. 258 The assigned media type for this format is "application/linkset". 260 When converting an "application/linkset" document to a field value 261 for the HTTP "Link" header, newline characters SHOULD be removed in 262 order to comply with Section 5.5 of [I-D.ietf-httpbis-semantics]. 264 In order to support use cases where "application/linkset" documents 265 are re-used outside the context of an HTTP interaction, it is 266 RECOMMENDED to make them self-contained by adhering to the following 267 guidelines: 269 * For every link provided in the set of links, explicitly provide 270 the link context using the "anchor" attribute. 272 * For link context ("anchor" attribute) and link target ("href" 273 attribute), use URI references that are not relative references 274 (as defined in Section 4.1 of [RFC3986]). 276 If these recommendations are not followed, interpretation of links in 277 "application/linkset" documents will depend on which URI is used as 278 context. 280 It should be noted that the "application/linkset" format specified 281 here is different than the "application/link-format" format specified 282 in [RFC6690] in that the former fully matches the field value of the 283 HTTP "Link" header field as defined in Section 3 of [RFC8288], 284 whereas the latter introduces constraints on that definition to meet 285 requirements for Constrained RESTful Environments. 287 4.2. JSON Document Format: application/linkset+json 289 This document format uses JSON [RFC8259] as the syntax to represent a 290 set of links. The set of links follows the abstract model defined by 291 Web Linking Section 2 of [RFC8288]. 293 The assigned media type for this format is "application/ 294 linkset+json". 296 In order to support use cases where "application/linkset+json" 297 documents are re-used outside the context of an HTTP interaction, it 298 is RECOMMENDED to make them self-contained by adhering to the 299 following guidelines: 301 * For every link provided in the set of links, explicitly provide 302 the link context using the "anchor" member. 304 * For link context ("anchor" member) and link target ("href" 305 member), use URI references that are not relative references (as 306 defined in Section 4.1 of [RFC3986]). 308 If these recommendations are not followed, interpretation of 309 "application/linkset+json" will depend on which URI is used as 310 context URI. 312 The "application/linkset+json" serialization allows for OPTIONAL 313 support of a JSON-LD [W3C.REC-json-ld-20140116] serialization. This 314 can be achieved by adding an appropriate context to the "application/ 315 linkset+json" serialization using the approach described in 316 [W3C.REC-json-ld-20140116]. Communities of practice can decide which 317 context best meets their application needs. Appendix A shows an 318 example of a possible context that, when added to a JSON 319 serialization, allows it to be interpreted as Resource Description 320 Framework (RDF) [W3C.REC-rdf11-concepts-20140225] data. 322 4.2.1. Set of Links 324 In the JSON representation of a set of links: 326 * A set of links is represented in JSON as an object which MUST 327 contain "linkset" as its sole member. 329 * The "linkset" member is an array in which a distinct JSON object - 330 the "link context object" (see Section 4.2.2) - is used to 331 represent links that have the same link context. 333 * Even if there is only one link context object, it MUST be wrapped 334 in an array. 336 4.2.2. Link Context Object 338 In the JSON representation one or more links that have the same link 339 context are represented by a JSON object, the link context object. A 340 link context object adheres to the following rules: 342 * Each link context object MAY contain an "anchor" member with a 343 value that represents the link context. If present, this value 344 MUST be a URI reference and SHOULD NOT be a relative reference as 345 per Section 4.1 of [RFC3986]. 347 * For each distinct relation type that the link context has with 348 link targets, a link context object MUST contain an additional 349 member. This member is an array in which a distinct JSON object - 350 the "link target object" (see Section 4.2.3) - MUST be used for 351 each link target for which the relationship with the link context 352 (value of the encompassing anchor member) applies. The name of 353 this member expresses the relation type of the link as follows: 355 - For registered relation types (Section 2.1.1 of [RFC8288]), the 356 name of this member is the registered name of the relation 357 type. 359 - For extension relation types (Section 2.1.2 of [RFC8288]), the 360 name of this member is the URI that uniquely represents the 361 relation type. 363 * Even if there is only one link target object it MUST be wrapped in 364 an array. 366 4.2.3. Link Target Object 368 In the JSON representation a link target is represented by a JSON 369 object, the link target object. A link target object adheres to the 370 following rules: 372 * Each link target object MUST contain an "href" member with a value 373 that represents the link target. This value MUST be a URI 374 reference and SHOULD NOT be a relative reference as per 375 Section 4.1 of [RFC3986]. Cases where the href member is present, 376 but no value is provided for it (i.e. the resource providing the 377 set of links is the target of the link in the link target object) 378 MUST be handled by providing an "href" member with an empty string 379 ("href": ""). 381 * In many cases, a link target is further qualified by target 382 attributes. Various types of attributes exist and they are 383 conveyed as additional members of the link target object as 384 detailed in Section 4.2.4. 386 The following example of a JSON-serialized set of links represents 387 one link with its core components: link context, link relation type, 388 and link target. 390 { "linkset": 391 [ 392 { "anchor": "http://example.net/bar", 393 "next": [ 394 {"href": "http://example.com/foo"} 395 ] 396 } 397 ] 398 } 400 Figure 1 402 The following example of a JSON-serialized set of links represents 403 two links that share link context and relation type but have 404 different link targets. 406 { "linkset": 407 [ 408 { "anchor": "http://example.net/bar", 409 "item": [ 410 {"href": "http://example.com/foo1"}, 411 {"href": "http://example.com/foo2"} 412 ] 413 } 414 ] 415 } 417 Figure 2 419 The following example shows a set of links that represents two links, 420 each with a different link context, link target, and relation type. 421 One relation type is registered, the other is an extension relation 422 type. 424 { "linkset": 425 [ 426 { "anchor": "http://example.net/bar", 427 "next": [ 428 {"href": "http://example.com/foo1"} 429 ] 430 }, 431 { "anchor": "http://example.net/boo", 432 "http://example.com/relations/baz" : [ 433 {"href": "http://example.com/foo2"} 434 ] 435 } 436 ] 437 } 439 Figure 3 441 4.2.4. Link Target Attributes 443 A link may be further qualified by target attributes as defined by 444 Section 2 of Web Linking [RFC8288]. Three types of attributes exist: 446 * Serialisation-defined attributes described in Section 3.4.1 of Web 447 Linking [RFC8288]. 449 * Extension attributes defined and used by communities as allowed by 450 Section 3.4.2 of [RFC8288]. 452 * Internationalized versions of the "title" attribute defined by 453 [RFC8288] and of extension attributes allowed by Section 3.4 of 454 [RFC8288]. 456 The handling of these different types of attributes is described in 457 the sections below. 459 4.2.4.1. Target Attributes Defined by Web Linking 461 Section 3.4.1 of [RFC8288] defines the following target attributes 462 that may be used to annotate links: "hreflang", "media", "title", 463 "title*", and "type"; these target attributes follow different 464 occurrence and value patterns. In the JSON representation, these 465 attributes MUST be conveyed as additional members of the link target 466 object as follows: 468 * "hreflang": The optional and repeatable "hreflang" target 469 attribute MUST be represented by an array (even if there only is 470 one value to be represented), and each value in that array MUST be 471 a string - representing one value of the "hreflang" target 472 attribute for a link - which follows the same model as in the 473 [RFC8288] syntax. 475 * "media": The optional and not repeatable "media" target attribute 476 MUST be represented by a "media" member in the link target object, 477 and its value MUST be a string that follows the same model as in 478 the [RFC8288] syntax. 480 * "type": The optional and not repeatable "type" target attribute 481 MUST be represented by a "type" member in the link target object, 482 and its value MUST be a string that follows the same model as in 483 the [RFC8288] syntax. 485 * "title": The optional and not repeatable "title" target attribute 486 MUST be represented by a "title" member in the link target object, 487 and its value MUST be a string that follows the same model as in 488 the [RFC8288] syntax. 490 * "title*": The optional and not repeatable "title*" target 491 attribute is motivated by character encoding and language issues 492 and follows the model defined in [RFC8187]. The details of the 493 JSON representation that applies to title* are described in 494 Section 4.2.4.2. 496 The following example illustrates how the repeatable "hreflang" and 497 the not repeatable "type" target attributes are represented in a link 498 target object. 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 } 508 ] 509 } 510 ] 511 } 513 Figure 4 515 4.2.4.2. Internationalized Target Attributes 517 In addition to the target attributes described in Section 4.2.4.1, 518 Section 3.4 of [RFC8288] also supports attributes that follow the 519 content model of [RFC8187]. In [RFC8288], these target attributes 520 are recognizable by the use of a trailing asterisk in the attribute 521 name, such as "title*". The content model of [RFC8187] uses a 522 string-based microsyntax that represents the character encoding, an 523 optional language tag, and the escaped attribute value encoded 524 according to the specified character encoding. 526 The JSON serialization for these target attributes MUST be as 527 follows: 529 * An internationalized target attribute is represented as a member 530 of the link context object with the same name (including the *) of 531 the attribute. 533 * The character encoding information as prescribed by [RFC8187] is 534 not preserved; instead, the content of the internationalized 535 attribute is represented in the character encoding used for the 536 JSON set of links. 538 * The value of the internationalized target attribute is an array 539 that contains one or more JSON objects. The name of one member of 540 such JSON object is "value" and its value is the actual content 541 (in its unescaped version) of the internationalized target 542 attribute, i.e. the value of the attribute from which the encoding 543 and language information are removed. The name of another, 544 optional, member of such JSON object is "language" and its value 545 is the language tag [RFC5646] for the language in which the 546 attribute content is conveyed. 548 The following example illustrates how the "title*" target attribute 549 defined by Section 3.4.1 of [RFC8288] is represented in a link target 550 object. 552 { "linkset": 553 [ 554 { "anchor": "http://example.net/bar", 555 "next": [ 556 { "href": "http://example.com/foo", 557 "type": "text/html", 558 "hreflang": [ "en" , "de" ], 559 "title": "Next chapter", 560 "title*": [ { "value": "nächstes Kapitel" , 561 "language" : "de" } ] 562 } 563 ] 564 } 565 ] 566 } 568 Figure 5 570 The above example assumes that the German title contains an umlaut 571 character (in the native syntax it would be encoded as title*=UTF- 572 8'de'n%c3%a4chstes%20Kapitel), which gets encoded in its unescaped 573 form in the JSON representation. Implementations MUST properly 574 decode/encode internationalized target attributes that follow the 575 model of [RFC8187] when transcoding between the "application/linkset" 576 and the "application/linkset+json" formats. 578 4.2.4.3. Extension Target Attributes 580 Extension target attributes are attributes that are not defined by 581 Section 3.4.1 of [RFC8288] (as listed in Section 4.2.4.1), but are 582 nevertheless used to qualify links. They can be defined by 583 communities in any way deemed necessary, and it is up to them to make 584 sure their usage is understood by target applications. However, 585 lacking standardization, there is no interoperable understanding of 586 these extension attributes. One important consequence is that their 587 cardinality is unknown to generic applications. Therefore, in the 588 JSON serialization, all extension target attributes are treated as 589 repeatable. 591 The JSON serialization for these target attributes MUST be as 592 follows: 594 * An extension target attribute is represented as a member of the 595 link target object with the same name of the attribute, including 596 the * if applicable. 598 * The value of an extension attribute MUST be represented by an 599 array, even if there only is one value to be represented. 601 * If the extension target attribute does not have a name with a 602 trailing asterisk, then each value in that array MUST be a string 603 that represents one value of the attribute. 605 * If the extension attribute has a name with a trailing asterisk (it 606 follows the content model of [RFC8187]), then each value in that 607 array MUST be a JSON object. The value of each such JSON object 608 MUST be structured as described in Section 4.2.4.2. 610 The example shows a link target object with three extension target 611 attributes. The value for each extension target attribute is an 612 array. The two first are regular extension target attributes, with 613 the first one ("foo") having only one value and the second one 614 ("bar") having two. The last extension target attribute ("baz*") 615 follows the naming rule of [RFC8187] and therefore is encoded 616 according to the serialization described in Section 4.2.4.2. 618 { "linkset": 619 [ 620 { "anchor": "http://example.net/bar", 621 "next": [ 622 { "href": "http://example.com/foo", 623 "type": "text/html", 624 "foo": [ "foovalue" ], 625 "bar": [ "barone", "bartwo" ], 626 "baz*": [ { "value": "bazvalue" , 627 "language" : "en" } ] 628 } 629 ] 630 } 631 ] 632 } 634 Figure 6 636 4.2.5. JSON Extensibility 638 The Web linking model ([RFC8288]) provides for the use of extension 639 target attributes as discussed in Section 4.2.4.3. No other form of 640 extensions SHOULD be used. This limitation of the JSON format allows 641 to unambiguously round trip between links provided in the HTTP "Link" 642 header field, sets of links serialized according to the "application/ 643 linkset" format, and sets of links serialized according to the 644 "application/linkset+json" format. 646 Cases may exist in which the use of extensions other than those of 647 Section 4.2.4.3 may be useful. For example, when a link set 648 publishers needs to include descriptive or technical metadata for 649 internal consumption. In case such extensions are used they MUST NOT 650 change the semantics of the JSON members defined in this 651 specification. Agents that consume JSON linkset documents can safely 652 ignore such extensions. 654 5. The "profile" parameter for media types to Represent Sets of Links 656 As a means to convey specific constraints or conventions (as per 657 [RFC6906]) that apply to a link set document, the "profile" parameter 658 MAY be used in conjunction with the media types "application/linkset" 659 and "application/linkset+json" detailed in Section 4.1 and 660 Section 4.2, respectively. For example, the parameter could be used 661 to indicate that a link set uses a specific, limited set of link 662 relation types. 664 The value of the "profile" parameter MUST be a non-empty list of 665 space-separated URIs, each of which identifies specific constraints 666 or conventions that apply to the link set document. Profile URIs MAY 667 be registered in the IANA Profile URI Registry in the manner 668 specified by [RFC7284]. 670 The presence of a "profile" parameter in conjunction with the 671 "application/linkset" and "application/linkset+json" media types does 672 not change the semantics of a link set. As such, clients with and 673 without knowledge of profile URIs can use the same representation. 675 Section 7.4.2 shows an example of using the "profile" parameter in 676 conjunction with the "application/linkset+json" media type. 678 6. The "linkset" Relation Type for Linking to a Set of Links 680 The target of a link with the "linkset" relation type provides a set 681 of links, including links in which the resource that is the link 682 context participates. 684 A link with the "linkset" relation type MAY be provided in the header 685 field and/or the body of a resource's representation. It may also be 686 discovered by other means, such as through client-side information. 688 A resource MAY provide more than one link with a "linkset" relation 689 type. Multiple such links can refer to the same set of links 690 expressed using different media types, or to different sets of links, 691 potentially provided by different third-party services. 693 A user agent that follows a "linkset" link MUST be aware that the set 694 of links provided by the resource that is the target of the link can 695 contain links in which the resource that is the context of the link 696 does not participate; it MAY decide to ignore those links. 698 A user agent that follows a "linkset" link and obtains links for 699 which anchors and targets are expressed as relative references (as 700 per Section 4.1 of [RFC3986]) MUST determine what the context is for 701 these links; it SHOULD ignore links for which it is unable to 702 unambiguously make that determination. 704 As a means to convey specific constraints or conventions (as per 705 [RFC6906]) that apply to a link set document, the "profile" attribute 706 MAY be used in conjunction with the "linkset" link relation type. 707 For example, the attribute could be used to indicate that a link set 708 uses a specific, limited set of link relation types. The value of 709 the "profile" attribute MUST be a non-empty list of space-separated 710 URIs, each of which identifies specific constraints or conventions 711 that apply to the link set document. Profile URIs MAY be registered 712 in the IANA Profile URI Registry in the manner specified by 713 [RFC7284]. Section 7.4.1 shows an example of using the "profile" 714 attribute on a link with the "linkset" relation type, making both the 715 link set and the profile(s) to which it complies discoverable. 717 7. Examples 719 Section 7.1 and Section 7.2 show examples whereby a set of links is 720 provided as "application/linkset" and "application/linkset+json" 721 documents, respectively. Section 7.3 illustrates the use of the 722 "linkset" link relation type to support discovery of sets of links 723 and Section 7.4 shows how to convey profile information pertaining to 724 a links set. 726 7.1. Set of Links Provided as application/linkset 728 Figure 7 shows a client issuing an HTTP GET request against resource 729 . 731 GET /links/resource1 HTTP/1.1 732 Host: example.org 734 Figure 7: Client HTTP GET request 736 Figure 8 shows the response to the GET request of Figure 7. The 737 response contains a Content-Type header field specifying that the 738 media type of the response is "application/linkset". A set of links, 739 revealing authorship and versioning related to resource 740 , is provided in the response body. 741 The HTTP "Link" header field indicates the availability of an 742 alternate representation of the set of links using media type 743 "application/linkset+json". 745 HTTP/1.1 200 OK 746 Date: Mon, 12 Aug 2019 10:35:51 GMT 747 Server: Apache-Coyote/1.1 748 Content-Length: 1023 749 Content-Type: application/linkset 750 Link: 751 ; rel="alternate" 752 ; type="application/linkset+json" 754 755 ; rel="author" 756 ; type="application/rdf+xml" 757 ; anchor="https://example.org/resource1", 758 759 ; rel="latest-version" 760 ; type="text/html" 761 ; anchor="https://example.org/resource1", 762 763 ; rel="predecessor-version" 764 ; type="text/html" 765 ; anchor="https://example.org/resource1?version=3", 766 767 ; rel="predecessor-version" 768 ; type="text/html" 769 ; anchor="https://example.org/resource1?version=2", 770 771 ; rel="memento" 772 ; type="text/html" 773 ; datetime="Thu, 13 Jun 2019 09:34:33 GMT" 774 ; anchor="https://example.org/resource1", 775 776 ; rel="memento" 777 ; type="text/html" 778 ; datetime="Sun, 21 Jul 2019 12:22:04 GMT" 779 ; anchor="https://example.org/resource1", 780 781 ; rel="author" 782 ; anchor="https://example.org/resource1#comment=1" 784 Figure 8: Response to HTTP GET includes a set of links 786 7.2. Set of Links Provided as application/linkset+json 788 Figure 9 shows the client issuing an HTTP GET request against 789 . In the request, the client 790 uses an "Accept" header field to indicate it prefers a response in 791 the "application/linkset+json" format. 793 GET links/resource1 HTTP/1.1 794 Host: example.org 795 Accept: application/linkset+json 797 Figure 9: Client HTTP GET request expressing preference for 798 "application/ linkset+json" response 800 Figure 10 shows the response to the HTTP GET request of Figure 9. 801 The set of links is serialized according to the media type 802 "application/linkset+json". 804 HTTP/1.1 200 OK 805 Date: Mon, 12 Aug 2019 10:46:22 GMT 806 Server: Apache-Coyote/1.1 807 Content-Type: application/linkset+json 808 Link: 809 ; rel="alternate" 810 ; type="application/linkset" 811 Content-Length: 1349 813 { "linkset": 814 [ 815 { "anchor": "https://example.org/resource1", 816 "author": [ 817 { "href": "https://authors.example.net/johndoe", 818 "type": "application/rdf+xml" 819 } 820 ], 821 "memento": [ 822 { "href": "https://example.org/resource1?version=1", 823 "type": "text/html", 824 "datetime": "Thu, 13 Jun 2019 09:34:33 GMT" 825 }, 826 { "href": "https://example.org/resource1?version=2", 827 "type": "text/html", 828 "datetime": "Sun, 21 Jul 2019 12:22:04 GMT" 829 } 830 ], 831 "latest-version": [ 832 { "href": "https://example.org/resource1?version=3", 833 "type": "text/html" 834 } 835 ] 836 }, 837 { "anchor": "https://example.org/resource1?version=3", 838 "predecessor-version": [ 839 { "href": "https://example.org/resource1?version=2", 840 "type": "text/html" 842 } 843 ] 844 }, 845 { "anchor": "https://example.org/resource1?version=2", 846 "predecessor-version": [ 847 { "href": "https://example.org/resource1?version=1", 848 "type": "text/html" 849 } 850 ] 851 }, 852 { "anchor": "https://example.org/resource1#comment=1", 853 "author": [ 854 { "href": "https://authors.example.net/alice"} 855 ] 856 } 857 ] 858 } 860 Figure 10: Response to the client's request for the set of links 862 7.3. Discovering a Link Set via the "linkset" Link Relation Type 864 Figure 11 shows a client issuing an HTTP HEAD request against 865 resource . 867 HEAD resource1 HTTP/1.1 868 Host: example.org 870 Figure 11: Client HTTP HEAD request 872 Figure 12 shows the response to the HEAD request of Figure 11. The 873 response contains an HTTP "Link" header field with a link that has 874 the "linkset" relation type. It indicates that a set of links is 875 provided by resource , which 876 provides a representation with media type "application/linkset+json". 878 HTTP/1.1 200 OK 879 Date: Mon, 12 Aug 2019 10:45:54 GMT 880 Server: Apache-Coyote/1.1 881 Link: 882 ; rel="linkset" 883 ; type="application/linkset+json" 884 Content-Length: 236 885 Content-Type: text/html;charset=utf-8 887 Figure 12: Response to HTTP HEAD request 889 7.4. Link Set Profiles 891 The examples in this section illustrate the use of the "profile" 892 attribute for a link with the "linkset" link relation type and the 893 "profile" attribute for a link set media type. The examples are 894 inspired by the implementation of link sets by GS1 (the standards 895 body behind many of the world's barcodes). 897 7.4.1. Using a "profile" Attribute with a "linkset" Link 899 Figure 13 shows a client issuing an HTTP HEAD request against trade 900 item 09506000134352 at . 902 HEAD /01/9506000134352 HTTP/1.1 903 Host: id.gs1.org 905 Figure 13: Client HTTP HEAD request 907 Figure 14 shows the server's response to the request of Figure 13, 908 including a "linkset" link with a "profile" attribute that has the 909 Profile URI as its value. 910 Dereferencing that URI yields a profile document that lists all the 911 link relation types that a client can expect when requesting the link 912 set made discoverable by the "linkset" link. For posterity that 913 profile document was saved in the Internet Archive at 914 on 27 September 2021. 917 HTTP/1.1 307 Temporary Redirect 918 Date: Mon, 27 Sep 2021 16:03:07 GMT 919 Server: nginx 920 Link: https://id.gs1.org/01/9506000134352?linkType=all 921 ; rel="linkset" 922 ; type="application/linkset+json" 923 ; profile="https://www.gs1.org/voc/?show=linktypes" 924 Location: https://dalgiardino.com/risotto-rice-with-mushrooms/ 926 Figure 14: Response to the client's HEAD request including a 927 "profile" attribute for the "linkset" link 929 7.4.2. Using a "profile" Parameter with a Link Set Media Type 931 Figure 15 shows a client issuing an HTTP HEAD request against the 932 link set that was 933 discovered through the HTTP interactions shown in Section 7.4.1. 935 HEAD /01/9506000134352?linkType=all HTTP/1.1 936 Host: id.gs1.org 937 Figure 15: Client HTTP HEAD request 939 Figure 16 shows the server's response to the request of Figure 15. 940 Note the "profile" parameter for the application/linkset+json media 941 type, which has as value the same Profile URI as was used in . 944 HTTP/1.1 200 OK 945 Date: Mon, 27 Sep 2021 16:03:33 GMT 946 Server: nginx 947 Content-Type: application/linkset+json; profile="https://www.gs1.org/voc/?show=linktypes" 948 Content-Length: 396 950 Figure 16: Response to the client's HEAD request including a 951 "profile" parameter for the "application/linkset+json" media type 953 7.4.3. Using a Link with a "profile" Link Relation Type 955 Note that the response Figure 16 from the link set resource is 956 equivalent to the response shown in Figure 17, which leverages the 957 "profile" link relation type defined in [RFC6906]. 959 HTTP/1.1 200 OK 960 Date: Mon, 27 Sep 2021 16:03:33 GMT 961 Server: nginx 962 Content-Type: application/linkset+json 963 Link: https://www.gs1.org/voc/?show=linktypes; rel="profile" 964 Content-Length: 396 966 Figure 17: Response to the client's HEAD request including a 967 "profile" link 969 A link with a "profile" link relation type as shown in Figure 17 can 970 also be conveyed in the link set document itself. This is 971 illustrated by Figure 18. Following the recommendation that all 972 links in a link set document should have an explicit anchor, such a 973 link has the URI of the link set itself as anchor and the Profile URI 974 as target. Multiple Profile URIs are handled by using multiple 975 "href" members. 977 { "linkset": 978 [ 979 { "anchor": "https://id.gs1.org/01/9506000134352?linkType=all", 980 "profile": [ 981 {"href": "https://www.gs1.org/voc/?show=linktypes"} 982 ] 983 }, 984 { "anchor": "https://id.gs1.org/01/9506000134352", 985 "https://gs1.org/voc/whatsInTheBox": [ 986 {"href": "https://example.com/en/packContents/GB"} 987 ] 988 } 989 ] 990 } 992 Figure 18: A Link Set that declares the profile it complies with 993 using a "profile" link 995 8. IANA Considerations 997 8.1. Link Relation Type: linkset 999 The link relation type below should be registered by IANA per 1000 Section 4.2 of Web Linking [RFC8288]: 1002 Relation Name: linkset 1004 Description: The link target of a link with the "linkset" relation 1005 type provides a set of links, including links in which the link 1006 context of the link participates. 1008 Reference: [[ This document ]] 1010 8.2. Media Type: application/linkset 1012 The Internet media type [RFC6838] for a natively encoded linkset is 1013 application/linkset. 1015 Type name: application 1017 Subtype name: linkset 1019 Required parameters: none 1021 Optional parameters: profile 1022 Encoding considerations: Linksets are encoded according to the 1023 definition of [RFC8288]. The encoding of [RFC8288] is based on 1024 the general encoding rules of [I-D.ietf-httpbis-semantics], with 1025 the addition of allowing indicating character encoding and 1026 language for specific parameters as defined by [RFC8187]. 1028 Security considerations: The security considerations of [[ This 1029 document ]] apply. 1031 Interoperability considerations: N/A 1033 Published specification: [[ This document ]] 1035 Applications that use this media type: This media type is not 1036 specific to any application, as it can be used by any application 1037 that wants to interchange web links. 1039 Additional information: 1041 Magic number(s): N/A 1043 File extension(s): This media type does not propose a specific 1044 extension. 1046 Macintosh file type code(s): TEXT 1048 Person & email address to contact for further information: Erik 1049 Wilde 1051 Intended usage: COMMON 1053 Restrictions on usage: none 1055 Author: Erik Wilde 1057 Change controller: IETF 1059 8.3. Media Type: application/linkset+json 1061 The Internet media type [RFC6838] for a JSON-encoded linkset is 1062 application/linkset+json. 1064 Type name: application 1066 Subtype name: linkset+json 1068 Required parameters: none 1069 Optional parameters: profile 1071 Encoding considerations: The encoding considerations of [RFC8259] 1072 apply 1074 Security considerations: The security considerations of [[ This 1075 document ]] apply. 1077 Interoperability considerations: The interoperability 1078 considerations of [RFC8259] apply. 1080 Published specification: [[ This document ]] 1082 Applications that use this media type: This media type is not 1083 specific to any application, as it can be used by any application 1084 that wants to interchange web links. 1086 Additional information: 1088 Magic number(s): N/A 1090 File extension(s): JSON documents often use ".json" as the file 1091 extension, and this media type does not propose a specific 1092 extension other than this generic one. 1094 Macintosh file type code(s): TEXT 1096 Person & email address to contact for further information: Erik 1097 Wilde 1099 Intended usage: COMMON 1101 Restrictions on usage: none 1103 Author: Erik Wilde 1105 Change controller: IETF 1107 9. Security Considerations 1109 The security considerations of Web Linking [RFC8288] apply, as long 1110 as they are not specifically discussing the risks of exposing 1111 information in HTTP header fields. 1113 In general, links may cause information leakage when they expose 1114 information (such as URIs) that can be sensitive or private. Links 1115 may expose "hidden URIs" that are not supposed to be openly shared, 1116 and may not be sufficiently protected. Ideally, none of the URIs 1117 exposed in links should be supposed to be "hidden"; instead, if these 1118 URIs are supposed to be limited to certain users, then technical 1119 measures should be put in place so that accidentally exposing them 1120 does not cause any harm. 1122 For the specific mechanisms defined in this specification, two 1123 security considerations should be taken into account: 1125 * The Web Linking model always has an "implicit context", which is 1126 the resource of the HTTP interaction. This original context can 1127 be lost or can change when self-contained link representations are 1128 moved. Changing the context can change the interpretation of 1129 links when they have no explicit anchor, or when they use relative 1130 URIs. Applications may choose to ignore links that have no 1131 explicit anchor or that use relative URIs when these are exchanged 1132 in stand-alone resources. 1134 * The model introduced in this specification supports "3rd party 1135 links", where one party can provide links that have another 1136 party's resource as an anchor. Depending on the link semantics 1137 and the application context, it is important to verify that there 1138 is sufficient trust in that 3rd party to allow it to provide these 1139 links. Applications may choose to treat 3rd party links 1140 differently than cases where a resource and the links for that 1141 resource are provided by the same party. 1143 10. Normative References 1145 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1146 Requirement Levels", BCP 14, RFC 2119, 1147 DOI 10.17487/RFC2119, March 1997, 1148 . 1150 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1151 Resource Identifier (URI): Generic Syntax", STD 66, 1152 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1153 . 1155 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1156 Specifications: ABNF", STD 68, RFC 5234, 1157 DOI 10.17487/RFC5234, January 2008, 1158 . 1160 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1161 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1162 September 2009, . 1164 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1165 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1166 . 1168 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1169 Specifications and Registration Procedures", BCP 13, 1170 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1171 . 1173 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, 1174 DOI 10.17487/RFC6906, March 2013, 1175 . 1177 [RFC7284] Lanthaler, M., "The Profile URI Registry", RFC 7284, 1178 DOI 10.17487/RFC7284, June 2014, 1179 . 1181 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1182 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1183 May 2017, . 1185 [RFC8187] Reschke, J., "Indicating Character Encoding and Language 1186 for HTTP Header Field Parameters", RFC 8187, 1187 DOI 10.17487/RFC8187, September 2017, 1188 . 1190 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1191 Interchange Format", STD 90, RFC 8259, 1192 DOI 10.17487/RFC8259, December 2017, 1193 . 1195 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1196 DOI 10.17487/RFC8288, October 2017, 1197 . 1199 [I-D.ietf-httpbis-semantics] 1200 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 1201 Semantics", Work in Progress, Internet-Draft, draft-ietf- 1202 httpbis-semantics-19, 12 September 2021, 1203 . 1206 11. Informative References 1208 [W3C.REC-rdf11-concepts-20140225] 1209 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 1210 Concepts and Abstract Syntax", World Wide Web Consortium 1211 Recommendation REC-rdf11-concepts-20140225, 25 February 1212 2014, 1213 . 1215 [W3C.REC-json-ld-20140116] 1216 Sporny, M., Kellogg, G., and M. Lanthaler, "JSON-LD 1.0", 1217 World Wide Web Consortium Recommendation REC-json-ld- 1218 20140116, 16 January 2014, 1219 . 1221 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 1222 DOI 10.17487/RFC5988, October 2010, 1223 . 1225 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1226 Code: The Implementation Status Section", BCP 205, 1227 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1228 . 1230 [DCMI-TERMS] 1231 Initiative, D. C. M., "DCMI Metadata Terms", 2020, 1232 . 1235 Appendix A. JSON-LD Context 1237 A set of links rendered according to the JSON serialization defined 1238 in Section 4.2 can be interpreted as RDF triples by adding a JSON-LD 1239 context [W3C.REC-json-ld-20140116] that maps the JSON keys to 1240 corresponding Linked Data terms. And, as per 1241 [W3C.REC-json-ld-20140116] section 6.8 (https://www.w3.org/TR/2014/ 1242 REC-json-ld-20140116/#interpreting-json-as-json-ld), when delivering 1243 a link set that is rendered according to the "application/ 1244 linkset+json" media type to a user agent, a server can convey the 1245 availability of such a JSON-LD context by using a link with the 1246 relation type "http://www.w3.org/ns/json-ld#context" in the HTTP 1247 "Link" header. 1249 Figure 19 shows the response of an HTTP GET against the URI of a link 1250 set resource and illustrates this approach to support discovery of a 1251 JSON-LD Context. The example is inspired by the GS1 implementation 1252 and shows a link set that uses relation types from the GS1 vocabulary 1253 at that are expressed as HTTP URIs. 1255 HTTP/1.1 200 OK 1256 Date: Mon, 11 Oct 2021 10:48:22 GMT 1257 Server: Apache-Coyote/1.1 1258 Content-Type: application/linkset+json 1259 Link: 1260 ; rel="http://www.w3.org/ns/json-ld#context" 1261 ; type="application/ld+json" 1262 Content-Length: 1532 1264 { 1265 "linkset": [ 1266 { 1267 "anchor": "https://id.gs1.org/01/09506000149301", 1268 "https://gs1.org/voc/pip": [ 1269 { 1270 "href": "https://example.com/en/defaultPage", 1271 "hreflang": [ 1272 "en" 1273 ], 1274 "type": "text/html", 1275 "title": "Product information" 1276 }, 1277 { 1278 "href": "https://example.com/fr/defaultPage", 1279 "hreflang": [ 1280 "fr" 1281 ], 1282 "title": "Information produit" 1283 } 1284 ], 1285 "https://gs1.org/voc/whatsInTheBox": [ 1286 { 1287 "href": "https://example.com/en/packContents/GB", 1288 "hreflang": [ 1289 "en" 1290 ], 1291 "title": "What's in the box?" 1292 }, 1293 { 1294 "href": "https://example.com/fr/packContents/FR", 1295 "hreflang": [ 1296 "fr" 1297 ], 1298 "title": "Qu'y a-t-il dans la boite?" 1299 }, 1300 { 1301 "href": "https://example.com/fr/packContents/CH", 1302 "hreflang": [ 1303 "fr" 1304 ], 1305 "title": "Qu'y a-t-il dans la boite?" 1306 } 1307 ], 1308 "https://gs1.org/voc/relatedVideo": [ 1309 { 1310 "href": "https://video.example", 1311 "hreflang": [ 1312 "en", 1313 "fr" 1314 ], 1315 "title*": [ 1316 { 1317 "value": "See it in action!", 1318 "language": "en" 1319 }, 1320 { 1321 "value": "Voyez-le en action!", 1322 "language": "fr" 1323 } 1324 ] 1325 } 1326 ] 1327 } 1328 ] 1329 } 1331 Figure 19: Using a typed link to support discovery of a JSON-LD 1332 Context for a Set of Links 1334 In order to obtain the JSON-LD Context conveyed by the server, the 1335 user agent issues an HTTP GET against the link target of the link 1336 with the "http://www.w3.org/ns/json-ld#context" relation type. The 1337 response to this GET is shown in Figure 20. This particular JSON-LD 1338 context maps "application/linkset+json" representations of link sets 1339 to Dublin Core Terms [DCMI-TERMS]. Note that the "linkset" entry in 1340 the JSON-LD context is introduced to support links with the "linkset" 1341 relation type in link sets. 1343 HTTP/1.1 200 OK 1344 Content-Type: application/ld+json 1345 Content-Length: 658 1347 { 1348 "@context": [ 1349 { 1350 "@version": 1.1, 1351 "@vocab": "https://gs1.org/voc/", 1352 "anchor": "@id", 1353 "href": "@id", 1354 "linkset": { 1355 "@id": "@graph", 1356 "@context": { 1357 "linkset": "linkset" 1358 } 1359 }, 1360 "title": { 1361 "@id": "http://purl.org/dc/terms/title" 1362 }, 1363 "title*": { 1364 "@id": "http://purl.org/dc/terms/title" 1365 }, 1366 "type": { 1367 "@id": "http://purl.org/dc/terms/format" 1368 } 1369 }, 1370 { 1371 "language": "@language", 1372 "value": "@value", 1373 "hreflang": { 1374 "@id": "http://purl.org/dc/terms/language", 1375 "@container": "@set" 1376 } 1377 } 1378 ] 1379 } 1381 Figure 20: JSON-LD Context mapping to Dublin Core Terms 1383 Applying the JSON-LD context of Figure 20 to the link set of 1384 Figure 19 allows transforming the "application/linkset+json" link set 1385 to an RDF link set. Figure 21 shows the latter represented by means 1386 of the "text/turtle" RDF serialization. 1388 1389 1390 "text/html" . 1391 1392 1393 "en" . 1394 1395 1396 "Product information" . 1397 1398 1399 "en" . 1400 1401 1402 "What's in the box?" . 1403 1404 1405 "fr" . 1406 1407 1408 "Information produit" . 1409 1410 1411 "fr" . 1412 1413 1414 "Qu'y a-t-il dans la boite?" . 1415 1416 1417 "fr" . 1418 1419 1420 "Qu'y a-t-il dans la boite?" . 1421 1422 1423 . 1424 1425 1426 . 1427 1428 1429 . 1430 1431 1432 . 1433 1434 1435 . 1437 1438 1439 . 1440 1441 1442 "en" . 1443 1444 1445 "fr" . 1446 1447 1448 "See it in action!"@en . 1449 1450 1451 "Voyez-le en action!"@fr . 1453 Figure 21: RDF serialization of the link set resulting from 1454 applying the JSON-LD context 1456 Appendix B. Implementation Status 1458 This section is to be removed before publishing as an RFC. 1460 This section records the status of known implementations of the 1461 protocol defined by this specification at the time of posting of this 1462 Internet-Draft, and is based on a proposal described in RFC 7942 1463 [RFC7942]. The description of implementations in this section is 1464 intended to assist the IETF in its decision processes in progressing 1465 drafts to RFCs. Please note that the listing of any individual 1466 implementation here does not imply endorsement by the IETF. 1467 Furthermore, no effort has been spent to verify the information 1468 presented here that was supplied by IETF contributors. This is not 1469 intended as, and must not be construed to be, a catalog of available 1470 implementations or their features. Readers are advised to note that 1471 other implementations may exist. 1473 According to RFC 7942, "this will allow reviewers and working groups 1474 to assign due consideration to documents that have the benefit of 1475 running code, which may serve as evidence of valuable experimentation 1476 and feedback that have made the implemented protocols more mature. 1477 It is up to the individual working groups to use this information as 1478 they see fit". 1480 B.1. GS1 1482 GS1 is a provider of identifiers, most famously seen in EAN/UPC 1483 barcodes for retail and healthcare products, and manages an ecology 1484 of services and standards to leverage them at a global scale. GS1 1485 has indicated that it will fully implement this "linkset" 1486 specification as a means to allow requesting and representing links 1487 pertaining to products, shipments, assets and locations. The current 1488 GS1 Digital Link specification makes an informative reference to 1489 version 03 of the "linkset" I-D, mentions the formal adoption of that 1490 I-D by the IETF HTTPAPI Working Group, and indicates it being on 1491 track to achieve RFC status. The GS1 Digital Link specification 1492 adopts the JSON format specified by the I-D and mentions future plans 1493 to also support the Link header format as well as their respective 1494 media types, neither of which have changed since version 03. 1496 B.2. FAIR Signposting Profile 1498 The FAIR Signposting Profile is a community specification aimed at 1499 improving machine navigation of scholarly objects on the web through 1500 the use of typed web links pointing at e.g. web resources that are 1501 part of a specific object, persistent identifiers for the object and 1502 its authors, license information pertaining to the object. The 1503 specification encourages the use of Linksets and initial 1504 implementations are ongoing, for example, for the open source 1505 Dataverse data repository platform that was initiated by Harvard 1506 University and is meanwhile used by research institutions, worldwide. 1508 B.3. Open Journal Systems (OJS) 1510 Open Journal Systems (OJS) is an open-source software for the 1511 management of peer-reviewed academic journals, and is created by the 1512 Public Knowledge Project (PKP), released under the GNU General Public 1513 License. Open Journal Systems (OJS) is a journal management and 1514 publishing system that has been developed by PKP through its 1515 federally funded efforts to expand and improve access to research. 1517 The OJS platform has implemented "linkset" support as an alternative 1518 way to provide links when there are more than a configured limit 1519 (they consider using about 10 as a good default, for testing purpose 1520 it is currently set to 8). 1522 Acknowledgements 1524 Thanks for comments and suggestions provided by Phil Archer, 1525 Dominique Guinard, Mark Nottingham, Julian Reschke, Rob Sanderson, 1526 Stian Soiland-Reyes, and Sarven Capadisli. 1528 Authors' Addresses 1530 Erik Wilde 1531 Axway 1533 Email: erik.wilde@dret.net 1534 URI: http://dret.net/netdret/ 1536 Herbert Van de Sompel 1537 Data Archiving and Networked Services 1539 Email: herbert.van.de.sompel@dans.knaw.nl 1540 URI: https://orcid.org/0000-0002-0715-6126