idnits 2.17.00 (12 Aug 2021) /tmp/idnits44712/draft-ietf-httpapi-linkset-10.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 are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document date (5 May 2022) is 9 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-httpbis-semantics' -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Wilde 3 Internet-Draft Axway 4 Intended status: Standards Track H. Van de Sompel 5 Expires: 6 November 2022 Data Archiving and Networked Services 6 5 May 2022 8 Linkset: Media Types and a Link Relation Type for Link Sets 9 draft-ietf-httpapi-linkset-10 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 6 November 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 . . . . . 7 68 4.2. JSON Document Format: application/linkset+json . . . . . 7 69 4.2.1. Set of Links . . . . . . . . . . . . . . . . . . . . 8 70 4.2.2. Link Context Object . . . . . . . . . . . . . . . . . 8 71 4.2.3. Link Target Object . . . . . . . . . . . . . . . . . 9 72 4.2.4. Link Target Attributes . . . . . . . . . . . . . . . 10 73 4.2.5. JSON Extensibility . . . . . . . . . . . . . . . . . 15 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 . . 16 77 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 17 78 7.1. Set of Links Provided as application/linkset . . . . . . 17 79 7.2. Set of Links Provided as application/linkset+json . . . . 18 80 7.3. Discovering a Link Set via the "linkset" Link Relation 81 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 20 82 7.4. Link Set Profiles . . . . . . . . . . . . . . . . . . . . 21 83 7.4.1. Using a "profile" Attribute with a "linkset" Link . . 21 84 7.4.2. Using a "profile" Parameter with a Link Set Media 85 Type . . . . . . . . . . . . . . . . . . . . . . . . 21 86 7.4.3. Using a Link with a "profile" Link Relation Type . . 22 87 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 88 8.1. Link Relation Type: linkset . . . . . . . . . . . . . . . 23 89 8.2. Media Type: application/linkset . . . . . . . . . . . . . 23 90 8.3. Media Type: application/linkset+json . . . . . . . . . . 24 91 9. Security Considerations . . . . . . . . . . . . . . . . . . . 25 92 10. Normative References . . . . . . . . . . . . . . . . . . . . 26 93 11. Informative References . . . . . . . . . . . . . . . . . . . 27 94 Appendix A. JSON-LD Context . . . . . . . . . . . . . . . . . . 28 95 Appendix B. Implementation Status . . . . . . . . . . . . . . . 33 96 B.1. GS1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 97 B.2. FAIR Signposting Profile . . . . . . . . . . . . . . . . 34 98 B.3. Open Journal Systems (OJS) . . . . . . . . . . . . . . . 34 99 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 34 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 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 the HTTP 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" in 128 the same manner as [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, with a different resource being 167 the link context. 169 * Providing links pertaining to the resource that the server hosting 170 that resource is not aware of. 172 * External management of links pertaining to the resource in a 173 special-purpose link management service. 175 In such cases, links pertaining to a resource can be provided by 176 another, specific resource. That specific resource may be managed by 177 the same or by another custodian as the resource to which the links 178 pertain. For clients intent on consuming links provided in that 179 manner, it would be beneficial if the following conditions were met: 181 * Links are provided in a document that uses a well-defined media 182 type. 184 * The resource to which the provided links pertain is able to link 185 to the resource that provides these links using a well-known link 186 relation type. 188 These requirements are addressed in this specification through the 189 definition of two media types and a link relation type, respectively. 191 3.2. Challenges Writing to HTTP Link Header Field 193 In some cases, it is not straightforward to write links to the HTTP 194 "Link" header field from an application. This can, for example, be 195 the case because not all required link information is available to 196 the application or because the application does not have the 197 capability to directly write HTTP fields. In such cases, providing 198 links by means of a standalone document can be a solution. Making 199 the resource that provides these links discoverable can be achieved 200 by means of a typed link. 202 3.3. Large Number of Links 204 When conveying links in an HTTP "Link" header field, it is possible 205 for the size of the HTTP response fields to become unpredictable. 206 This can be the case when links are determined dynamically in a 207 manner dependent on a range of contextual factors. It is possible to 208 statically configure a web server to correctly handle large HTTP 209 response fields by specifying an upper bound for their size. But 210 when the number of links is unpredictable, estimating a reliable 211 upper bound is challenging. 213 Section 15 of HTTP [I-D.ietf-httpbis-semantics] defines error codes 214 related to excess communication by the user agent ("413 Request 215 Entity Too Large" and "414 Request-URI Too Long"), but no specific 216 error codes are defined to indicate that response field content 217 exceeds the upper bound that can be handled by the server and thus 218 has been truncated. As a result, applications take counter measures 219 aimed at controlling the size of the HTTP "Link" header field, for 220 example by limiting the links they provide to those with select 221 relation types, thereby limiting the value of the HTTP "Link" header 222 field to clients. Providing links by means of a standalone document 223 overcomes challenges related to the unpredictable (to the web server 224 implementation) nature of the size of HTTP "Link" header fields. 226 4. Document Formats for Sets of Links 228 This section specifies two document formats to convey a set of links. 229 Both are based on the abstract model specified in Section 2 of Web 230 Linking [RFC8288] that defines a link as consisting of a "link 231 context", a "link relation type", a "link target", and optional 232 "target attributes": 234 * The format defined in Section 4.1 is nearly identical to the field 235 value of the HTTP "Link" header field as specified in Section 3 of 236 [RFC8288]. 238 * The format defined in Section 4.2 is expressed in JSON [RFC8259]. 240 Links provided in the HTTP Link header are intended to be used in the 241 context of an HTTP interaction and contextual information that is 242 available during an interaction is used to correctly interpret them. 243 Links provided in link sets, however, can be re-used outside of an 244 HTTP interaction, when no such contextual information is available. 245 As a result, implementers of link sets should strive to make them 246 self-contained by adhering to the following recommendations. 248 For links provided in the HTTP Link header that have no anchor or 249 that use relative references, the URI of the resource that delivers 250 the links provides the contextual information that is needed for 251 their correct interpretation. In order to support use cases where 252 link set documents are re-used outside the context of an HTTP 253 interaction, it is RECOMMENDED to make them self-contained by 254 adhering to the following guidelines: 256 * For every link provided in the set of links, explicitly provide 257 the link context using the "anchor" attribute. 259 * For link context ("anchor" attribute) and link target ("href" 260 attribute), use URI references that are not relative references 261 (as defined in Section 4.1 of [RFC3986]). 263 If these recommendations are not followed, interpretation of links in 264 link set documents will depend on which URI is used as context. 266 For a "title" attribute provided on a link in the HTTP Link header, 267 the language in which the title is expressed is provided by the 268 Content-Language header of the HTTP interaction with the resource 269 that delivers the links. This does not apply to "title" attributes 270 provided for links in link set documents because that would constrain 271 all links in a link set to having a single title language and would 272 not support determining title languages when a link set is used 273 outside of an HTTP interaction. In order to support use cases where 274 link set documents are re-used outside the context of an HTTP 275 interaction, it is RECOMMENDED to make them self-contained by using 276 the "title*" attribute instead of the "title" attribute because 277 "title*" allows expressing the title language as part of its value by 278 means of a language tag. With this regard, note that language tags 279 are matched case-insensitively (see Section 2.1.1 of [RFC5646]). If 280 this recommendation is not followed, accurately determining the 281 language of titles provided on links in link set documents will not 282 be possible. 284 Note also that Section 3.3 of [RFC8288] deprecates the "rev" 285 construct that was provided by [RFC5988] as a means to express links 286 with a directionality that is the inverse of direct links that use 287 the "rel" construct. In both serializations for link sets defined 288 here, inverse links may be represented as direct links using the 289 "rel" construct and by switching the roles of the resources involved 290 in the link. 292 4.1. HTTP Link Document Format: application/linkset 294 This document format is nearly identical to the field value of the 295 HTTP "Link" header field as defined in Section 3 of [RFC8288], more 296 specifically by its ABNF [RFC5234] production rule for "Link" and 297 subsequent ones. It differs from the format for field values of the 298 HTTP "Link" header only in that not only spaces and horizontal tabs 299 are allowed as separators but also newline characters as a means to 300 improve readability for humans. The use of non-ASCII characters in 301 the field value of the HTTP "Link" Header field is not allowed, and 302 as such is also not allowed in "application/linkset" link sets. 304 The assigned media type for this format is "application/linkset". 306 When converting an "application/linkset" document to a field value 307 for the HTTP "Link" header, newline characters MUST be removed or 308 MUST be replaced by white space (SP) in order to comply with 309 Section 5.5 of [I-D.ietf-httpbis-semantics]. 311 Implementers of "application/linkset" link sets should strive to make 312 them self-contained by following the recommendations regarding their 313 use outside the context of an HTTP interaction provided in Section 4. 315 It should be noted that the "application/linkset" format specified 316 here is different from the "application/link-format" format specified 317 in [RFC6690] in that the former fully matches the field value of the 318 HTTP "Link" header field as defined in Section 3 of [RFC8288], 319 whereas the latter introduces constraints on that definition to meet 320 requirements for Constrained RESTful Environments (CoRE). 322 4.2. JSON Document Format: application/linkset+json 324 This document format uses JSON [RFC8259] as the syntax to represent a 325 set of links. The set of links follows the abstract model defined by 326 Web Linking Section 2 of [RFC8288]. 328 The assigned media type for this format is "application/ 329 linkset+json". 331 In the interests of interoperability "application/linkset+json" link 332 sets MUST be encoded using UTF-8 as per Section 8.1 of [RFC8259]. 334 Implementers of "application/linkset+json" link sets should strive to 335 make them self-contained by following the recommendations regarding 336 their use outside the context of an HTTP interaction provided in 337 Section 4. 339 The "application/linkset+json" serialization allows for OPTIONAL 340 support of a JSON-LD serialization. This can be achieved by adding 341 an appropriate context to the "application/linkset+json" 342 serialization using the approach described in Section 6.8. of 343 [W3C.REC-json-ld-20140116]. Communities of practice can decide which 344 context best meets their application needs. Appendix A shows an 345 example of a possible context that, when added to a JSON 346 serialization, allows it to be interpreted as Resource Description 347 Framework (RDF) [W3C.REC-rdf11-concepts-20140225] data. 349 4.2.1. Set of Links 351 In the JSON representation of a set of links: 353 * A set of links is represented in JSON as an object which MUST 354 contain "linkset" as its sole member. 356 * The value of the "linkset" member is an array in which a distinct 357 JSON object - the "link context object" (see Section 4.2.2) - is 358 used to represent links that have the same link context. 360 * Even if there is only one link context object, it MUST be wrapped 361 in an array. 363 4.2.2. Link Context Object 365 In the JSON representation one or more links that have the same link 366 context are represented by a JSON object, the link context object. A 367 link context object adheres to the following rules: 369 * Each link context object MAY contain an "anchor" member with a 370 value that represents the link context. If present, this value 371 MUST be a URI reference and SHOULD NOT be a relative reference as 372 defined in Section 4.1 of [RFC3986]. 374 * For each distinct relation type that the link context has with 375 link targets, a link context object MUST contain an additional 376 member. The value of this member is an array in which a distinct 377 JSON object - the "link target object" (see Section 4.2.3) - MUST 378 be used for each link target for which the relationship with the 379 link context (value of the encompassing anchor member) applies. 380 The name of this member expresses the relation type of the link as 381 follows: 383 - For registered relation types (Section 2.1.1 of [RFC8288]), the 384 name of this member is the registered name of the relation 385 type. 387 - For extension relation types (Section 2.1.2 of [RFC8288]), the 388 name of this member is the URI that uniquely represents the 389 relation type. 391 * Even if there is only one link target object it MUST be wrapped in 392 an array. 394 4.2.3. Link Target Object 396 In the JSON representation a link target is represented by a JSON 397 object, the link target object. A link target object adheres to the 398 following rules: 400 * Each link target object MUST contain an "href" member with a value 401 that represents the link target. This value MUST be a URI 402 reference and SHOULD NOT be a relative reference as defined in 403 Section 4.1 of [RFC3986]. Cases where the href member is present, 404 but no value is provided for it (i.e. the resource providing the 405 set of links is the target of the link in the link target object) 406 MUST be handled by providing an "href" member with an empty string 407 as its value ("href": ""). 409 * In many cases, a link target is further qualified by target 410 attributes. Various types of attributes exist and they are 411 conveyed as additional members of the link target object as 412 detailed in Section 4.2.4. 414 The following example of a JSON-serialized set of links represents 415 one link with its core components: link context, link relation type, 416 and link target. 418 { "linkset": 419 [ 420 { "anchor": "https://example.net/bar", 421 "next": [ 422 {"href": "https://example.com/foo"} 423 ] 424 } 425 ] 426 } 428 Figure 1 430 The following example of a JSON-serialized set of links represents 431 two links that share link context and relation type but have 432 different link targets. 434 { "linkset": 435 [ 436 { "anchor": "https://example.net/bar", 437 "item": [ 438 {"href": "https://example.com/foo1"}, 439 {"href": "https://example.com/foo2"} 440 ] 441 } 442 ] 443 } 445 Figure 2 447 The following example shows a set of links that represents two links, 448 each with a different link context, link target, and relation type. 449 One relation type is registered, the other is an extension relation 450 type. 452 { "linkset": 453 [ 454 { "anchor": "https://example.net/bar", 455 "next": [ 456 {"href": "https://example.com/foo1"} 457 ] 458 }, 459 { "anchor": "https://example.net/boo", 460 "https://example.com/relations/baz" : [ 461 {"href": "https://example.com/foo2"} 462 ] 463 } 464 ] 465 } 467 Figure 3 469 4.2.4. Link Target Attributes 471 A link may be further qualified by target attributes as defined by 472 Section 2 of Web Linking [RFC8288]. Three types of attributes exist: 474 * Serialisation-defined attributes described in Section 3.4.1 of Web 475 Linking [RFC8288]. 477 * Extension attributes defined and used by communities as allowed by 478 Section 3.4.2 of [RFC8288]. 480 * Internationalized versions of the "title" attribute defined by 481 [RFC8288] and of extension attributes allowed by Section 3.4 of 482 [RFC8288]. 484 The handling of these different types of attributes is described in 485 the sections below. 487 4.2.4.1. Target Attributes Defined by Web Linking 489 Section 3.4.1 of [RFC8288] defines the following target attributes 490 that may be used to annotate links: "hreflang", "media", "title", 491 "title*", and "type"; these target attributes follow different 492 occurrence and value patterns. In the JSON representation, these 493 attributes MUST be conveyed as additional members of the link target 494 object as follows: 496 * "hreflang": The "hreflang" target attribute, defined as optional 497 and repeatable by [RFC8288], MUST be represented by an "hreflang" 498 member, and its value MUST be an array (even if there only is one 499 value to be represented), and each value in that array MUST be a 500 string - representing one value of the "hreflang" target attribute 501 for a link - which follows the same model as in the [RFC8288] 502 syntax. 504 * "media": The "media" target attribute, defined as optional and not 505 repeatable by [RFC8288], MUST be represented by a "media" member 506 in the link target object, and its value MUST be a string that 507 follows the same model as in the [RFC8288] syntax. 509 * "type": The "type" target attribute, defined as optional and not 510 repeatable by [RFC8288], MUST be represented by a "type" member in 511 the link target object, and its value MUST be a string that 512 follows the same model as in the [RFC8288] syntax. 514 * "title": The "title" target attribute, defined as optional and not 515 repeatable by [RFC8288], MUST be represented by a "title" member 516 in the link target object, and its value MUST be a JSON string. 518 * "title*": The "title*" target attribute, defined as optional and 519 not repeatable by [RFC8288], is motivated by character encoding 520 and language issues and follows the model defined in [RFC8187]. 521 The details of the JSON representation that applies to title* are 522 described in Section 4.2.4.2. 524 The following example illustrates how the repeatable "hreflang" and 525 the not repeatable "type" target attributes are represented in a link 526 target object. 528 { "linkset": 529 [ 530 { "anchor": "https://example.net/bar", 531 "next": [ 532 { "href": "https://example.com/foo", 533 "type": "text/html", 534 "hreflang": [ "en" , "de" ] 535 } 536 ] 537 } 538 ] 539 } 541 Figure 4 543 4.2.4.2. Internationalized Target Attributes 545 In addition to the target attributes described in Section 4.2.4.1, 546 Section 3.4 of [RFC8288] also supports attributes that follow the 547 content model of [RFC8187]. In [RFC8288], these target attributes 548 are recognizable by the use of a trailing asterisk in the attribute 549 name, such as "title*". The content model of [RFC8187] uses a 550 string-based microsyntax that represents the character encoding, an 551 optional language tag, and the escaped attribute value encoded 552 according to the specified character encoding. 554 The JSON serialization for these target attributes MUST be as 555 follows: 557 * An internationalized target attribute is represented as a member 558 of the link context object with the same name (including the *) as 559 the attribute. 561 * The character encoding information as prescribed by [RFC8187] is 562 not preserved; instead, the content of the internationalized 563 attribute is represented as a JSON string. 565 * The value of the internationalized target attribute is an array 566 that contains one or more JSON objects. The name of one member of 567 such JSON object is "value" and its value is the actual content 568 (in its unescaped version) of the internationalized target 569 attribute, i.e. the value of the attribute from which the encoding 570 and language information are removed. The name of another, 571 optional, member of such JSON object is "language" and its value 572 is the language tag [RFC5646] for the language in which the 573 attribute content is conveyed. 575 The following example illustrates how the "title*" target attribute 576 defined by Section 3.4.1 of [RFC8288] is represented in a link target 577 object. 579 { "linkset": 580 [ 581 { "anchor": "https://example.net/bar", 582 "next": [ 583 { "href": "https://example.com/foo", 584 "type": "text/html", 585 "hreflang": [ "en" , "de" ], 586 "title": "Next chapter", 587 "title*": [ { "value": "nächstes Kapitel" , 588 "language" : "de" } ] 589 } 590 ] 591 } 592 ] 593 } 595 Figure 5 597 The above example assumes that the German title contains an umlaut 598 character (in the original syntax it would be encoded as title*=UTF- 599 8'de'n%c3%a4chstes%20Kapitel), which gets encoded in its unescaped 600 form in the JSON representation. Implementations MUST properly 601 decode/encode internationalized target attributes that follow the 602 model of [RFC8187] when transcoding between the "application/linkset" 603 and the "application/linkset+json" formats. 605 4.2.4.3. Extension Target Attributes 607 Extension target attributes are attributes that are not defined by 608 Section 3.4.1 of [RFC8288] (as listed in Section 4.2.4.1), but are 609 nevertheless used to qualify links. They can be defined by 610 communities in any way deemed necessary, and it is up to them to make 611 sure their usage is understood by target applications. However, 612 lacking standardization, there is no interoperable understanding of 613 these extension attributes. One important consequence is that their 614 cardinality is unknown to generic applications. Therefore, in the 615 JSON serialization, all extension target attributes are treated as 616 repeatable. 618 The JSON serialization for these target attributes MUST be as 619 follows: 621 * An extension target attribute is represented as a member of the 622 link target object with the same name as the attribute, including 623 the * if applicable. 625 * The value of an extension attribute MUST be represented by an 626 array, even if there only is one value to be represented. 628 * If the extension target attribute does not have a name with a 629 trailing asterisk, then each value in that array MUST be a JSON 630 string that represents one value of the attribute. 632 * If the extension attribute has a name with a trailing asterisk (it 633 follows the content model of [RFC8187]), then each value in that 634 array MUST be a JSON object. The value of each such JSON object 635 MUST be structured as described in Section 4.2.4.2. 637 The example shows a link target object with three extension target 638 attributes. The value for each extension target attribute is an 639 array. The two first are regular extension target attributes, with 640 the first one ("foo") having only one value and the second one 641 ("bar") having two. The last extension target attribute ("baz*") 642 follows the naming rule of [RFC8187] and therefore is encoded 643 according to the serialization described in Section 4.2.4.2. 645 { "linkset": 646 [ 647 { "anchor": "https://example.net/bar", 648 "next": [ 649 { "href": "https://example.com/foo", 650 "type": "text/html", 651 "foo": [ "foovalue" ], 652 "bar": [ "barone", "bartwo" ], 653 "baz*": [ { "value": "bazvalue" , 654 "language" : "en" } ] 655 } 656 ] 657 } 658 ] 659 } 660 Figure 6 662 4.2.5. JSON Extensibility 664 The Web linking model ([RFC8288]) provides for the use of extension 665 target attributes as discussed in Section 4.2.4.3. The use of other 666 forms of extensions is NOT RECOMMENDED. Limiting the JSON format in 667 this way allows to unambiguously round trip between links provided in 668 the HTTP "Link" header field, sets of links serialized according to 669 the "application/linkset" format, and sets of links serialized 670 according to the "application/linkset+json" format. 672 Cases may exist in which the use of extensions other than those of 673 Section 4.2.4.3 may be useful. For example, when a link set 674 publisher needs to include descriptive or technical metadata for 675 internal consumption. In case such extensions are used they MUST NOT 676 change the semantics of the JSON members defined in this 677 specification. Agents that consume JSON linkset documents can safely 678 ignore such extensions. 680 5. The "profile" parameter for media types to Represent Sets of Links 682 As a means to convey specific constraints or conventions (as per 683 [RFC6906]) that apply to a link set document, the "profile" parameter 684 MAY be used in conjunction with the media types "application/linkset" 685 and "application/linkset+json" detailed in Section 4.1 and 686 Section 4.2, respectively. For example, the parameter could be used 687 to indicate that a link set uses a specific, limited set of link 688 relation types. 690 The value of the "profile" parameter MUST be a non-empty list of 691 space-separated URIs, each of which identifies specific constraints 692 or conventions that apply to the link set document. When providing 693 multiple profile URIs, care should be taken that the corresponding 694 profiles are not conflicting. Profile URIs MAY be registered in the 695 IANA Profile URI Registry in the manner specified by [RFC7284]. 697 The presence of a "profile" parameter in conjunction with the 698 "application/linkset" and "application/linkset+json" media types does 699 not change the semantics of a link set. As such, clients with and 700 without knowledge of profile URIs can use the same representation. 702 Section 7.4.2 shows an example of using the "profile" parameter in 703 conjunction with the "application/linkset+json" media type. 705 6. The "linkset" Relation Type for Linking to a Set of Links 707 The target of a link with the "linkset" relation type provides a set 708 of links, including links in which the resource that is the link 709 context participates. 711 A link with the "linkset" relation type MAY be provided in the header 712 field and/or the body of a resource's representation. It may also be 713 discovered by other means, such as through client-side information. 715 A resource MAY provide more than one link with a "linkset" relation 716 type. Multiple such links can refer to the same set of links 717 expressed using different media types, or to different sets of links, 718 potentially provided by different third-party services. 720 The set of links provided by the resource that is the target of a 721 "linkset" link may contain links in which the resource that is the 722 context of the "linkset" link does not participate. User agents MUST 723 process each link in the link set independently, including processing 724 of link context and link target, and MAY ignore links from the link 725 set in which the context of the "linkset" link does not participate. 727 A user agent that follows a "linkset" link and obtains links for 728 which anchors and targets are expressed as relative references (as 729 per Section 4.1 of [RFC3986]) MUST determine what the context is for 730 these links; it SHOULD ignore links for which it is unable to 731 unambiguously make that determination. 733 As a means to convey specific constraints or conventions (as per 734 [RFC6906]) that apply to a link set document, the "profile" attribute 735 MAY be used in conjunction with the "linkset" link relation type. 736 For example, the attribute could be used to indicate that a link set 737 uses a specific, limited set of link relation types. The value of 738 the "profile" attribute MUST be a non-empty list of space-separated 739 URIs, each of which identifies specific constraints or conventions 740 that apply to the link set document. Profile URIs MAY be registered 741 in the IANA Profile URI Registry in the manner specified by 742 [RFC7284]. Section 7.4.1 shows an example of using the "profile" 743 attribute on a link with the "linkset" relation type, making both the 744 link set and the profile(s) to which it complies discoverable. 746 7. Examples 748 Section 7.1 and Section 7.2 show examples whereby a set of links is 749 provided as "application/linkset" and "application/linkset+json" 750 documents, respectively. Section 7.3 illustrates the use of the 751 "linkset" link relation type to support discovery of sets of links 752 and Section 7.4 shows how to convey profile information pertaining to 753 a link set. 755 7.1. Set of Links Provided as application/linkset 757 Figure 7 shows a client issuing an HTTP GET request against resource 758 . 760 GET /links/resource1 HTTP/1.1 761 Host: example.org 763 Figure 7: Client HTTP GET request 765 Figure 8 shows the response to the GET request of Figure 7. The 766 response contains a Content-Type header field specifying that the 767 media type of the response is "application/linkset". A set of links, 768 revealing authorship and versioning related to resource 769 , is provided in the response body. 770 The HTTP "Link" header field indicates the availability of an 771 alternate representation of the set of links using media type 772 "application/linkset+json". 774 HTTP/1.1 200 OK 775 Date: Mon, 12 Aug 2019 10:35:51 GMT 776 Server: Apache-Coyote/1.1 777 Content-Length: 1023 778 Content-Type: application/linkset 779 Link: 780 ; rel="alternate" 781 ; type="application/linkset+json" 783 784 ; rel="author" 785 ; type="application/rdf+xml" 786 ; anchor="https://example.org/resource1", 787 788 ; rel="latest-version" 789 ; type="text/html" 790 ; anchor="https://example.org/resource1", 791 792 ; rel="predecessor-version" 793 ; type="text/html" 794 ; anchor="https://example.org/resource1?version=3", 795 796 ; rel="predecessor-version" 797 ; type="text/html" 798 ; anchor="https://example.org/resource1?version=2", 799 800 ; rel="memento" 801 ; type="text/html" 802 ; datetime="Thu, 13 Jun 2019 09:34:33 GMT" 803 ; anchor="https://example.org/resource1", 804 805 ; rel="memento" 806 ; type="text/html" 807 ; datetime="Sun, 21 Jul 2019 12:22:04 GMT" 808 ; anchor="https://example.org/resource1", 809 810 ; rel="author" 811 ; anchor="https://example.org/resource1#comment=1" 813 Figure 8: Response to HTTP GET includes a set of links 815 7.2. Set of Links Provided as application/linkset+json 817 Figure 9 shows the client issuing an HTTP GET request against 818 . In the request, the client 819 uses an "Accept" header field to indicate it prefers a response in 820 the "application/linkset+json" format. 822 GET links/resource1 HTTP/1.1 823 Host: example.org 824 Accept: application/linkset+json 826 Figure 9: Client HTTP GET request expressing preference for 827 "application/ linkset+json" response 829 Figure 10 shows the response to the HTTP GET request of Figure 9. 830 The set of links is serialized according to the media type 831 "application/linkset+json". 833 HTTP/1.1 200 OK 834 Date: Mon, 12 Aug 2019 10:46:22 GMT 835 Server: Apache-Coyote/1.1 836 Content-Type: application/linkset+json 837 Link: 838 ; rel="alternate" 839 ; type="application/linkset" 840 Content-Length: 1246 842 { "linkset": 843 [ 844 { "anchor": "https://example.org/resource1", 845 "author": [ 846 { "href": "https://authors.example.net/johndoe", 847 "type": "application/rdf+xml" 848 } 849 ], 850 "memento": [ 851 { "href": "https://example.org/resource1?version=1", 852 "type": "text/html", 853 "datetime": "Thu, 13 Jun 2019 09:34:33 GMT" 854 }, 855 { "href": "https://example.org/resource1?version=2", 856 "type": "text/html", 857 "datetime": "Sun, 21 Jul 2019 12:22:04 GMT" 858 } 859 ], 860 "latest-version": [ 861 { "href": "https://example.org/resource1?version=3", 862 "type": "text/html" 863 } 864 ] 865 }, 866 { "anchor": "https://example.org/resource1?version=3", 867 "predecessor-version": [ 868 { "href": "https://example.org/resource1?version=2", 869 "type": "text/html" 871 } 872 ] 873 }, 874 { "anchor": "https://example.org/resource1?version=2", 875 "predecessor-version": [ 876 { "href": "https://example.org/resource1?version=1", 877 "type": "text/html" 878 } 879 ] 880 }, 881 { "anchor": "https://example.org/resource1#comment=1", 882 "author": [ 883 { "href": "https://authors.example.net/alice"} 884 ] 885 } 886 ] 887 } 889 Figure 10: Response to the client's request for the set of links 891 7.3. Discovering a Link Set via the "linkset" Link Relation Type 893 Figure 11 shows a client issuing an HTTP HEAD request against 894 resource . 896 HEAD resource1 HTTP/1.1 897 Host: example.org 899 Figure 11: Client HTTP HEAD request 901 Figure 12 shows the response to the HEAD request of Figure 11. The 902 response contains an HTTP "Link" header field with a link that has 903 the "linkset" relation type. It indicates that a set of links is 904 provided by resource , which 905 provides a representation with media type "application/linkset+json". 907 HTTP/1.1 200 OK 908 Date: Mon, 12 Aug 2019 10:45:54 GMT 909 Server: Apache-Coyote/1.1 910 Link: 911 ; rel="linkset" 912 ; type="application/linkset+json" 913 Content-Length: 236 914 Content-Type: text/html;charset=utf-8 916 Figure 12: Response to HTTP HEAD request 918 7.4. Link Set Profiles 920 The examples in this section illustrate the use of the "profile" 921 attribute for a link with the "linkset" link relation type and the 922 "profile" attribute for a link set media type. The examples are 923 inspired by the implementation of link sets by GS1 (the standards 924 body behind many of the world's barcodes). 926 7.4.1. Using a "profile" Attribute with a "linkset" Link 928 Figure 13 shows a client issuing an HTTP HEAD request against trade 929 item 09506000134352 at . 931 HEAD /01/9506000134352 HTTP/1.1 932 Host: id.gs1.org 934 Figure 13: Client HTTP HEAD request 936 Figure 14 shows the server's response to the request of Figure 13, 937 including a "linkset" link with a "profile" attribute that has the 938 Profile URI as its value. 939 Dereferencing that URI yields a profile document that lists all the 940 link relation types that a client can expect when requesting the link 941 set made discoverable by the "linkset" link. The link relation types 942 are presented in abbreviated form, e.g. , whereas 943 the actual link relation type URIs are available as hyperlinks on the 944 abbreviations, e.g. . For 945 posterity that profile document was saved in the Internet Archive at 946 on 27 September 2021. 949 HTTP/1.1 307 Temporary Redirect 950 Date: Mon, 27 Sep 2021 16:03:07 GMT 951 Server: nginx 952 Link: https://id.gs1.org/01/9506000134352?linkType=all 953 ; rel="linkset" 954 ; type="application/linkset+json" 955 ; profile="https://www.gs1.org/voc/?show=linktypes" 956 Location: https://example.com/risotto-rice-with-mushrooms/ 958 Figure 14: Response to the client's HEAD request including a 959 "profile" attribute for the "linkset" link 961 7.4.2. Using a "profile" Parameter with a Link Set Media Type 963 Figure 15 shows a client issuing an HTTP HEAD request against the 964 link set that was 965 discovered through the HTTP interactions shown in Section 7.4.1. 967 HEAD /01/9506000134352?linkType=all HTTP/1.1 968 Host: id.gs1.org 970 Figure 15: Client HTTP HEAD request 972 Figure 16 shows the server's response to the request of Figure 15. 973 Note the "profile" parameter for the application/linkset+json media 974 type, which has as value the same Profile URI as was used in . 977 HTTP/1.1 200 OK 978 Date: Mon, 27 Sep 2021 16:03:33 GMT 979 Server: nginx 980 Content-Type: application/linkset+json; 981 profile="https://www.gs1.org/voc/?show=linktypes" 982 Content-Length: 396 984 Figure 16: Response to the client's HEAD request including a 985 "profile" parameter for the "application/linkset+json" media type 987 7.4.3. Using a Link with a "profile" Link Relation Type 989 Note that the response Figure 16 from the link set resource is 990 equivalent to the response shown in Figure 17, which leverages the 991 "profile" link relation type defined in [RFC6906]. 993 HTTP/1.1 200 OK 994 Date: Mon, 27 Sep 2021 16:03:33 GMT 995 Server: nginx 996 Content-Type: application/linkset+json 997 Link: https://www.gs1.org/voc/?show=linktypes; rel="profile" 998 Content-Length: 396 1000 Figure 17: Response to the client's HEAD request including a 1001 "profile" link 1003 A link with a "profile" link relation type as shown in Figure 17 can 1004 also be conveyed in the link set document itself. This is 1005 illustrated by Figure 18. Following the recommendation that all 1006 links in a link set document should have an explicit anchor, such a 1007 link has the URI of the link set itself as anchor and the Profile URI 1008 as target. Multiple Profile URIs are handled by using multiple 1009 "href" members. 1011 { "linkset": 1012 [ 1013 { "anchor": "https://id.gs1.org/01/9506000134352?linkType=all", 1014 "profile": [ 1015 {"href": "https://www.gs1.org/voc/?show=linktypes"} 1016 ] 1017 }, 1018 { "anchor": "https://id.gs1.org/01/9506000134352", 1019 "https://gs1.org/voc/whatsInTheBox": [ 1020 {"href": "https://example.com/en/packContents/GB"} 1021 ] 1022 } 1023 ] 1024 } 1026 Figure 18: A Link Set that declares the profile it complies with 1027 using a "profile" link 1029 8. IANA Considerations 1031 8.1. Link Relation Type: linkset 1033 The link relation type below should be registered by IANA in the Link 1034 Relation Type Registry as per Section 4.2 of Web Linking [RFC8288]: 1036 Relation Name: linkset 1038 Description: The link target of a link with the "linkset" relation 1039 type provides a set of links, including links in which the link 1040 context of the link participates. 1042 Reference: [[ This document ]] 1044 8.2. Media Type: application/linkset 1046 The Internet media type application/linkset for a linkset encoded as 1047 described in Section 4.1 should be registered by IANA in the Media 1048 Type Registry as per [RFC6838]. 1050 Type name: application 1052 Subtype name: linkset 1054 Required parameters: N/A 1056 Optional parameters: profile 1057 Encoding considerations: Linksets are encoded according to the 1058 definition of [RFC8288]. The encoding of [RFC8288] is based on 1059 the general encoding rules of [I-D.ietf-httpbis-semantics], with 1060 the addition of allowing indicating character encoding and 1061 language for specific parameters as defined by [RFC8187]. 1063 Security considerations: The security considerations of [[ This 1064 document ]] apply. 1066 Interoperability considerations: N/A 1068 Published specification: [[ This document ]] 1070 Applications that use this media type: This media type is not 1071 specific to any application, as it can be used by any application 1072 that wants to interchange web links. 1074 Additional information: 1076 Magic number(s): N/A 1078 File extension(s): This media type does not propose a specific 1079 extension. 1081 Macintosh file type code(s): TEXT 1083 Person & email address to contact for further information: Erik 1084 Wilde 1086 Intended usage: COMMON 1088 Restrictions on usage: none 1090 Author: Erik Wilde 1092 Change controller: IETF 1094 8.3. Media Type: application/linkset+json 1096 The Internet media type application/linkset+json for a linkset 1097 encoded as described in Section 4.2 should be registered by IANA in 1098 the Media Type Registry as per [RFC6838]. 1100 Type name: application 1102 Subtype name: linkset+json 1104 Required parameters: N/A 1105 Optional parameters: profile 1107 Encoding considerations: The encoding considerations of [RFC8259] 1108 apply 1110 Security considerations: The security considerations of [[ This 1111 document ]] apply. 1113 Interoperability considerations: The interoperability 1114 considerations of [RFC8259] apply. 1116 Published specification: [[ This document ]] 1118 Applications that use this media type: This media type is not 1119 specific to any application, as it can be used by any application 1120 that wants to interchange web links. 1122 Additional information: 1124 Magic number(s): N/A 1126 File extension(s): JSON documents often use ".json" as the file 1127 extension, and this media type does not propose a specific 1128 extension other than this generic one. 1130 Macintosh file type code(s): TEXT 1132 Person & email address to contact for further information: Erik 1133 Wilde 1135 Intended usage: COMMON 1137 Restrictions on usage: none 1139 Author: Erik Wilde 1141 Change controller: IETF 1143 9. Security Considerations 1145 The security considerations of Section 7 of [RFC3986] apply, as well 1146 as those of Web Linking [RFC8288] as long as the latter are not 1147 specifically discussing the risks of exposing information in HTTP 1148 header fields. 1150 In general, links may cause information leakage when they expose 1151 information (such as URIs) that can be sensitive or private. Links 1152 may expose "hidden URIs" that are not supposed to be openly shared, 1153 and may not be sufficiently protected. Ideally, none of the URIs 1154 exposed in links should be supposed to be "hidden"; instead, if these 1155 URIs are supposed to be limited to certain users, then technical 1156 measures should be put in place so that accidentally exposing them 1157 does not cause any harm. 1159 For the specific mechanisms defined in this specification, two 1160 security considerations should be taken into account: 1162 * The Web Linking model always has an "implicit context", which is 1163 the resource of the HTTP interaction. This original context can 1164 be lost or can change when self-contained link representations are 1165 moved. Changing the context can change the interpretation of 1166 links when they have no explicit anchor, or when they use relative 1167 URIs. Applications may choose to ignore links that have no 1168 explicit anchor or that use relative URIs when these are exchanged 1169 in stand-alone resources. 1171 * The model introduced in this specification supports "3rd party 1172 links", where one party can provide links that have another 1173 party's resource as an anchor. Depending on the link semantics 1174 and the application context, it is important to verify that there 1175 is sufficient trust in that 3rd party to allow it to provide these 1176 links. Applications may choose to treat 3rd party links 1177 differently than cases where a resource and the links for that 1178 resource are provided by the same party. 1180 10. Normative References 1182 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1183 Requirement Levels", BCP 14, RFC 2119, 1184 DOI 10.17487/RFC2119, March 1997, 1185 . 1187 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1188 Resource Identifier (URI): Generic Syntax", STD 66, 1189 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1190 . 1192 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1193 Specifications: ABNF", STD 68, RFC 5234, 1194 DOI 10.17487/RFC5234, January 2008, 1195 . 1197 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1198 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1199 September 2009, . 1201 [W3C.REC-json-ld-20140116] 1202 Sporny, M., Kellogg, G., and M. Lanthaler, "JSON-LD 1.0", 1203 World Wide Web Consortium Recommendation REC-json-ld- 1204 20140116, 16 January 2014, 1205 . 1207 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1208 Specifications and Registration Procedures", BCP 13, 1209 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1210 . 1212 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1213 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1214 May 2017, . 1216 [RFC8187] Reschke, J., "Indicating Character Encoding and Language 1217 for HTTP Header Field Parameters", RFC 8187, 1218 DOI 10.17487/RFC8187, September 2017, 1219 . 1221 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1222 Interchange Format", STD 90, RFC 8259, 1223 DOI 10.17487/RFC8259, December 2017, 1224 . 1226 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1227 DOI 10.17487/RFC8288, October 2017, 1228 . 1230 [I-D.ietf-httpbis-semantics] 1231 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 1232 Semantics", Work in Progress, Internet-Draft, draft-ietf- 1233 httpbis-semantics-19, 12 September 2021, 1234 . 1237 11. Informative References 1239 [W3C.REC-rdf11-concepts-20140225] 1240 Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 1241 Concepts and Abstract Syntax", World Wide Web Consortium 1242 Recommendation REC-rdf11-concepts-20140225, 25 February 1243 2014, 1244 . 1246 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 1247 DOI 10.17487/RFC5988, October 2010, 1248 . 1250 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1251 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1252 . 1254 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, 1255 DOI 10.17487/RFC6906, March 2013, 1256 . 1258 [RFC7284] Lanthaler, M., "The Profile URI Registry", RFC 7284, 1259 DOI 10.17487/RFC7284, June 2014, 1260 . 1262 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1263 Code: The Implementation Status Section", BCP 205, 1264 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1265 . 1267 [DCMI-TERMS] 1268 Initiative, D. C. M., "DCMI Metadata Terms", 2020, 1269 . 1272 Appendix A. JSON-LD Context 1274 A set of links rendered according to the JSON serialization defined 1275 in Section 4.2 can be interpreted as RDF triples by adding a JSON-LD 1276 context [W3C.REC-json-ld-20140116] that maps the JSON keys to 1277 corresponding Linked Data terms. And, as per 1278 [W3C.REC-json-ld-20140116] section 6.8 (https://www.w3.org/TR/2014/ 1279 REC-json-ld-20140116/#interpreting-json-as-json-ld), when delivering 1280 a link set that is rendered according to the "application/ 1281 linkset+json" media type to a user agent, a server can convey the 1282 availability of such a JSON-LD context by using a link with the 1283 relation type "http://www.w3.org/ns/json-ld#context" in the HTTP 1284 "Link" header. 1286 Figure 19 shows the response to an HTTP GET against the URI of a link 1287 set resource and illustrates this approach to support discovery of a 1288 JSON-LD Context. The example is inspired by the GS1 implementation 1289 and shows a link set that uses relation types from the GS1 vocabulary 1290 at that are expressed as HTTP URIs. 1292 HTTP/1.1 200 OK 1293 Date: Mon, 11 Oct 2021 10:48:22 GMT 1294 Server: Apache-Coyote/1.1 1295 Content-Type: application/linkset+json 1296 Link: 1297 ; rel="http://www.w3.org/ns/json-ld#context" 1298 ; type="application/ld+json" 1299 Content-Length: 1532 1301 { 1302 "linkset": [ 1303 { 1304 "anchor": "https://id.gs1.org/01/09506000149301", 1305 "https://gs1.org/voc/pip": [ 1306 { 1307 "href": "https://example.com/en/defaultPage", 1308 "hreflang": [ 1309 "en" 1310 ], 1311 "type": "text/html", 1312 "title": "Product information" 1313 }, 1314 { 1315 "href": "https://example.com/fr/defaultPage", 1316 "hreflang": [ 1317 "fr" 1318 ], 1319 "title": "Information produit" 1320 } 1321 ], 1322 "https://gs1.org/voc/whatsInTheBox": [ 1323 { 1324 "href": "https://example.com/en/packContents/GB", 1325 "hreflang": [ 1326 "en" 1327 ], 1328 "title": "What's in the box?" 1329 }, 1330 { 1331 "href": "https://example.com/fr/packContents/FR", 1332 "hreflang": [ 1333 "fr" 1334 ], 1335 "title": "Qu'y a-t-il dans la boite?" 1336 }, 1337 { 1338 "href": "https://example.com/fr/packContents/CH", 1339 "hreflang": [ 1340 "fr" 1341 ], 1342 "title": "Qu'y a-t-il dans la boite?" 1343 } 1344 ], 1345 "https://gs1.org/voc/relatedVideo": [ 1346 { 1347 "href": "https://video.example", 1348 "hreflang": [ 1349 "en", 1350 "fr" 1351 ], 1352 "title*": [ 1353 { 1354 "value": "See it in action!", 1355 "language": "en" 1356 }, 1357 { 1358 "value": "Voyez-le en action!", 1359 "language": "fr" 1360 } 1361 ] 1362 } 1363 ] 1364 } 1365 ] 1366 } 1368 Figure 19: Using a typed link to support discovery of a JSON-LD 1369 Context for a Set of Links 1371 In order to obtain the JSON-LD Context conveyed by the server, the 1372 user agent issues an HTTP GET against the link target of the link 1373 with the "http://www.w3.org/ns/json-ld#context" relation type. The 1374 response to this GET is shown in Figure 20. This particular JSON-LD 1375 context maps "application/linkset+json" representations of link sets 1376 to Dublin Core Terms [DCMI-TERMS]. Note that the "linkset" entry in 1377 the JSON-LD context is introduced to support links with the "linkset" 1378 relation type in link sets. 1380 HTTP/1.1 200 OK 1381 Content-Type: application/ld+json 1382 Content-Length: 658 1384 { 1385 "@context": [ 1386 { 1387 "@version": 1.1, 1388 "@vocab": "https://gs1.org/voc/", 1389 "anchor": "@id", 1390 "href": "@id", 1391 "linkset": { 1392 "@id": "@graph", 1393 "@context": { 1394 "linkset": "linkset" 1395 } 1396 }, 1397 "title": { 1398 "@id": "http://purl.org/dc/terms/title" 1399 }, 1400 "title*": { 1401 "@id": "http://purl.org/dc/terms/title" 1402 }, 1403 "type": { 1404 "@id": "http://purl.org/dc/terms/format" 1405 } 1406 }, 1407 { 1408 "language": "@language", 1409 "value": "@value", 1410 "hreflang": { 1411 "@id": "http://purl.org/dc/terms/language", 1412 "@container": "@set" 1413 } 1414 } 1415 ] 1416 } 1418 Figure 20: JSON-LD Context mapping to Dublin Core Terms 1420 Applying the JSON-LD context of Figure 20 to the link set of 1421 Figure 19 allows transforming the "application/linkset+json" link set 1422 to an RDF link set. Figure 21 shows the latter represented by means 1423 of the "text/turtle" RDF serialization. 1425 1426 1427 "text/html" . 1428 1429 1430 "en" . 1431 1432 1433 "Product information" . 1434 1435 1436 "en" . 1437 1438 1439 "What's in the box?" . 1440 1441 1442 "fr" . 1443 1444 1445 "Information produit" . 1446 1447 1448 "fr" . 1449 1450 1451 "Qu'y a-t-il dans la boite?" . 1452 1453 1454 "fr" . 1455 1456 1457 "Qu'y a-t-il dans la boite?" . 1458 1459 1460 . 1461 1462 1463 . 1464 1465 1466 . 1467 1468 1469 . 1470 1471 1472 . 1474 1475 1476 . 1477 1478 1479 "en" . 1480 1481 1482 "fr" . 1483 1484 1485 "See it in action!"@en . 1486 1487 1488 "Voyez-le en action!"@fr . 1490 Figure 21: RDF serialization of the link set resulting from 1491 applying the JSON-LD context 1493 Appendix B. Implementation Status 1495 This section is to be removed before publishing as an RFC. 1497 This section records the status of known implementations of the 1498 protocol defined by this specification at the time of posting of this 1499 Internet-Draft, and is based on a proposal described in RFC 7942 1500 [RFC7942]. The description of implementations in this section is 1501 intended to assist the IETF in its decision processes in progressing 1502 drafts to RFCs. Please note that the listing of any individual 1503 implementation here does not imply endorsement by the IETF. 1504 Furthermore, no effort has been spent to verify the information 1505 presented here that was supplied by IETF contributors. This is not 1506 intended as, and must not be construed to be, a catalog of available 1507 implementations or their features. Readers are advised to note that 1508 other implementations may exist. 1510 According to RFC 7942, "this will allow reviewers and working groups 1511 to assign due consideration to documents that have the benefit of 1512 running code, which may serve as evidence of valuable experimentation 1513 and feedback that have made the implemented protocols more mature. 1514 It is up to the individual working groups to use this information as 1515 they see fit". 1517 B.1. GS1 1519 GS1 is a provider of identifiers, most famously seen in EAN/UPC 1520 barcodes for retail and healthcare products, and manages an ecology 1521 of services and standards to leverage them at a global scale. GS1 1522 has indicated that it will fully implement this "linkset" 1523 specification as a means to allow requesting and representing links 1524 pertaining to products, shipments, assets and locations. The current 1525 GS1 Digital Link specification makes an informative reference to 1526 version 03 of the "linkset" I-D, mentions the formal adoption of that 1527 I-D by the IETF HTTPAPI Working Group, and indicates it being on 1528 track to achieve RFC status. The GS1 Digital Link specification 1529 adopts the JSON format specified by the I-D and mentions future plans 1530 to also support the Link header format as well as their respective 1531 media types, neither of which have changed since version 03. 1533 B.2. FAIR Signposting Profile 1535 The FAIR Signposting Profile is a community specification aimed at 1536 improving machine navigation of scholarly objects on the web through 1537 the use of typed web links pointing at e.g. web resources that are 1538 part of a specific object, persistent identifiers for the object and 1539 its authors, license information pertaining to the object. The 1540 specification encourages the use of Linksets and initial 1541 implementations are ongoing, for example, for the open source 1542 Dataverse data repository platform that was initiated by Harvard 1543 University and is meanwhile used by research institutions, worldwide. 1545 B.3. Open Journal Systems (OJS) 1547 Open Journal Systems (OJS) is an open-source software for the 1548 management of peer-reviewed academic journals, and is created by the 1549 Public Knowledge Project (PKP), released under the GNU General Public 1550 License. Open Journal Systems (OJS) is a journal management and 1551 publishing system that has been developed by PKP through its 1552 federally funded efforts to expand and improve access to research. 1554 The OJS platform has implemented "linkset" support as an alternative 1555 way to provide links when there are more than a configured limit 1556 (they consider using about 10 as a good default, for testing purpose 1557 it is currently set to 8). 1559 Acknowledgements 1561 Thanks for comments and suggestions provided by Phil Archer, 1562 Dominique Guinard, Mark Nottingham, Julian Reschke, Rob Sanderson, 1563 Stian Soiland-Reyes, Sarven Capadisli, and Addison Phillips. 1565 Authors' Addresses 1567 Erik Wilde 1568 Axway 1569 Email: erik.wilde@dret.net 1570 URI: http://dret.net/netdret/ 1572 Herbert Van de Sompel 1573 Data Archiving and Networked Services 1574 Email: herbert.van.de.sompel@dans.knaw.nl 1575 URI: https://orcid.org/0000-0002-0715-6126