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