rfc9264v2.txt   rfc9264.txt 
skipping to change at line 416 skipping to change at line 416
{ "linkset": { "linkset":
[ [
{ "anchor": "https://example.net/bar", { "anchor": "https://example.net/bar",
"next": [ "next": [
{"href": "https://example.com/foo"} {"href": "https://example.com/foo"}
] ]
} }
] ]
} }
Figure 1: Simple Linkset Example Figure 1: Simple linkset example
The following example of a JSON-serialized set of links represents The following example of a JSON-serialized set of links represents
two links that share a link context and relation type but have two links that share a link context and relation type but have
different link targets. different link targets.
{ "linkset": { "linkset":
[ [
{ "anchor": "https://example.net/bar", { "anchor": "https://example.net/bar",
"item": [ "item": [
{"href": "https://example.com/foo1"}, {"href": "https://example.com/foo1"},
{"href": "https://example.com/foo2"} {"href": "https://example.com/foo2"}
] ]
} }
] ]
} }
Figure 2: Linkset with Two Links with the Same Context Figure 2: Linkset with two links with the same context
The following example shows a set of links that represents two links, The following example shows a set of links that represents two links,
each with a different link context, link target, and relation type. each with a different link context, link target, and relation type.
One relation type is registered, and the other is an extension One relation type is registered, and the other is an extension
relation type. relation type.
{ "linkset": { "linkset":
[ [
{ "anchor": "https://example.net/bar", { "anchor": "https://example.net/bar",
"next": [ "next": [
skipping to change at line 455 skipping to change at line 455
] ]
}, },
{ "anchor": "https://example.net/boo", { "anchor": "https://example.net/boo",
"https://example.com/relations/baz" : [ "https://example.com/relations/baz" : [
{"href": "https://example.com/foo2"} {"href": "https://example.com/foo2"}
] ]
} }
] ]
} }
Figure 3: Linkset with Two Links with Different Contexts Figure 3: Linkset with two links with different contexts
4.2.4. Link Target Attributes 4.2.4. Link Target Attributes
A link may be further qualified by target attributes as defined by A link may be further qualified by target attributes as defined by
Section 2 of [RFC8288]. Three types of attributes exist: Section 2 of [RFC8288]. Three types of attributes exist:
* Serialization-defined attributes as described in Section 3.4.1 of * Serialization-defined attributes as described in Section 3.4.1 of
[RFC8288]. [RFC8288].
* Extension attributes defined and used by communities as allowed by * Extension attributes defined and used by communities as allowed by
skipping to change at line 529 skipping to change at line 529
"next": [ "next": [
{ "href": "https://example.com/foo", { "href": "https://example.com/foo",
"type": "text/html", "type": "text/html",
"hreflang": [ "en" , "de" ] "hreflang": [ "en" , "de" ]
} }
] ]
} }
] ]
} }
Figure 4: Linkset with "hreflang" and "type" Target Attributes Figure 4: Linkset with "hreflang" and "type" target attributes
4.2.4.2. Internationalized Target Attributes 4.2.4.2. Internationalized Target Attributes
In addition to the target attributes described in Section 4.2.4.1, In addition to the target attributes described in Section 4.2.4.1,
Section 3.4 of [RFC8288] also supports attributes that follow the Section 3.4 of [RFC8288] also supports attributes that follow the
content model of [RFC8187]. In [RFC8288], these target attributes content model of [RFC8187]. In [RFC8288], these target attributes
are recognizable by the use of a trailing asterisk in the attribute are recognizable by the use of a trailing asterisk in the attribute
name, such as "title*". The content model of [RFC8187] uses a name, such as "title*". The content model of [RFC8187] uses a
string-based microsyntax that represents the character encoding, an string-based microsyntax that represents the character encoding, an
optional language tag, and the escaped attribute value encoded optional language tag, and the escaped attribute value encoded
skipping to change at line 583 skipping to change at line 583
"hreflang": [ "en" , "de" ], "hreflang": [ "en" , "de" ],
"title": "Next chapter", "title": "Next chapter",
"title*": [ { "value": "nächstes Kapitel" , "title*": [ { "value": "nächstes Kapitel" ,
"language" : "de" } ] "language" : "de" } ]
} }
] ]
} }
] ]
} }
Figure 5: Linkset with "title" and "title*" Target Attributes Figure 5: Linkset with "title" and "title*" target attributes
The above example assumes that the German title contains an umlaut The above example assumes that the German title contains an umlaut
character (in the original syntax, it would be encoded as title*=UTF- character (in the original syntax, it would be encoded as title*=UTF-
8'de'n%c3%a4chstes%20Kapitel), which gets encoded in its unescaped 8'de'n%c3%a4chstes%20Kapitel), which gets encoded in its unescaped
form in the JSON representation. Implementations MUST properly form in the JSON representation. Implementations MUST properly
decode/encode internationalized target attributes that follow the decode/encode internationalized target attributes that follow the
model of [RFC8187] when transcoding between the "application/linkset" model of [RFC8187] when transcoding between the "application/linkset"
format and the "application/linkset+json" format. format and the "application/linkset+json" format.
4.2.4.3. Extension Target Attributes 4.2.4.3. Extension Target Attributes
skipping to change at line 649 skipping to change at line 649
"foo": [ "foovalue" ], "foo": [ "foovalue" ],
"bar": [ "barone", "bartwo" ], "bar": [ "barone", "bartwo" ],
"baz*": [ { "value": "bazvalue" , "baz*": [ { "value": "bazvalue" ,
"language" : "en" } ] "language" : "en" } ]
} }
] ]
} }
] ]
} }
Figure 6: Linkset with Extension Target Attributes Figure 6: Linkset with extension target attributes
4.2.5. JSON Extensibility 4.2.5. JSON Extensibility
The Web Linking model [RFC8288] provides for the use of extension The Web Linking model [RFC8288] provides for the use of extension
target attributes as discussed in Section 4.2.4.3. The use of other target attributes as discussed in Section 4.2.4.3. The use of other
forms of extensions is NOT RECOMMENDED. Limiting the JSON format in forms of extensions is NOT RECOMMENDED. Limiting the JSON format in
this way allows unambiguous round trips between links provided in the this way allows unambiguous round trips between links provided in the
HTTP "Link" header field, sets of links serialized according to the HTTP "Link" header field, sets of links serialized according to the
"application/linkset" format, and sets of links serialized according "application/linkset" format, and sets of links serialized according
to the "application/linkset+json" format. to the "application/linkset+json" format.
skipping to change at line 752 skipping to change at line 752
link set. link set.
7.1. Set of Links Provided as "application/linkset" 7.1. Set of Links Provided as "application/linkset"
Figure 7 shows a client issuing an HTTP GET request against resource Figure 7 shows a client issuing an HTTP GET request against resource
<https://example.org/links/resource1>. <https://example.org/links/resource1>.
GET /links/resource1 HTTP/1.1 GET /links/resource1 HTTP/1.1
Host: example.org Host: example.org
Figure 7: Client HTTP GET Request Figure 7: Client HTTP GET request
Figure 8 shows the response to the GET request of Figure 7. The Figure 8 shows the response to the GET request of Figure 7. The
response contains a "Content-Type" header field specifying that the response contains a "Content-Type" header field specifying that the
media type of the response is "application/linkset". A set of links, media type of the response is "application/linkset". A set of links,
revealing authorship and versioning related to resource revealing authorship and versioning related to resource
<https://example.org/resource1>, is provided in the response body. <https://example.org/resource1>, is provided in the response body.
The HTTP "Link" header field indicates the availability of an The HTTP "Link" header field indicates the availability of an
alternate representation of the set of links using media type alternate representation of the set of links using media type
"application/linkset+json". "application/linkset+json".
skipping to change at line 802 skipping to change at line 802
; anchor="https://example.org/resource1", ; anchor="https://example.org/resource1",
<https://example.org/resource1?version=2> <https://example.org/resource1?version=2>
; rel="memento" ; rel="memento"
; type="text/html" ; type="text/html"
; datetime="Sun, 21 Jul 2019 12:22:04 GMT" ; datetime="Sun, 21 Jul 2019 12:22:04 GMT"
; anchor="https://example.org/resource1", ; anchor="https://example.org/resource1",
<https://authors.example.net/alice> <https://authors.example.net/alice>
; rel="author" ; rel="author"
; anchor="https://example.org/resource1#comment=1" ; anchor="https://example.org/resource1#comment=1"
Figure 8: Response to HTTP GET Includes a Set of Links Figure 8: Response to HTTP GET includes a set of links
7.2. Set of Links Provided as "application/linkset+json" 7.2. Set of Links Provided as "application/linkset+json"
Figure 9 shows the client issuing an HTTP GET request against Figure 9 shows the client issuing an HTTP GET request against
<https://example.org/links/resource1>. In the request, the client <https://example.org/links/resource1>. In the request, the client
uses an "Accept" header field to indicate that it prefers a response uses an "Accept" header field to indicate that it prefers a response
in the "application/linkset+json" format. in the "application/linkset+json" format.
GET links/resource1 HTTP/1.1 GET links/resource1 HTTP/1.1
Host: example.org Host: example.org
Accept: application/linkset+json Accept: application/linkset+json
Figure 9: Client HTTP GET Request Expressing Preference for an Figure 9: Client HTTP GET request expressing preference for an
"application/linkset+json" Response "application/linkset+json" response
Figure 10 shows the response to the HTTP GET request of Figure 9. Figure 10 shows the response to the HTTP GET request of Figure 9.
The set of links is serialized according to the media type The set of links is serialized according to the media type
"application/linkset+json". "application/linkset+json".
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 12 Aug 2019 10:46:22 GMT Date: Mon, 12 Aug 2019 10:46:22 GMT
Server: Apache-Coyote/1.1 Server: Apache-Coyote/1.1
Content-Type: application/linkset+json Content-Type: application/linkset+json
Link: <https://example.org/links/resource1> Link: <https://example.org/links/resource1>
skipping to change at line 877 skipping to change at line 877
] ]
}, },
{ "anchor": "https://example.org/resource1#comment=1", { "anchor": "https://example.org/resource1#comment=1",
"author": [ "author": [
{ "href": "https://authors.example.net/alice"} { "href": "https://authors.example.net/alice"}
] ]
} }
] ]
} }
Figure 10: Response to the Client's Request for the Linkset Figure 10: Response to the client's request for the linkset
7.3. Discovering a Link Set via the "linkset" Link Relation Type 7.3. Discovering a Link Set via the "linkset" Link Relation Type
Figure 11 shows a client issuing an HTTP HEAD request against Figure 11 shows a client issuing an HTTP HEAD request against
resource <https://example.org/resource1>. resource <https://example.org/resource1>.
HEAD resource1 HTTP/1.1 HEAD resource1 HTTP/1.1
Host: example.org Host: example.org
Figure 11: Client HTTP HEAD Request Figure 11: Client HTTP HEAD request
Figure 12 shows the response to the HEAD request of Figure 11. The Figure 12 shows the response to the HEAD request of Figure 11. The
response contains an HTTP "Link" header field with a link that has response contains an HTTP "Link" header field with a link that has
the "linkset" relation type. It indicates that a set of links is the "linkset" relation type. It indicates that a set of links is
provided by resource <https://example.org/links/resource1>, which provided by resource <https://example.org/links/resource1>, which
provides a representation with media type "application/linkset+json". provides a representation with media type "application/linkset+json".
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 12 Aug 2019 10:45:54 GMT Date: Mon, 12 Aug 2019 10:45:54 GMT
Server: Apache-Coyote/1.1 Server: Apache-Coyote/1.1
Link: <https://example.org/links/resource1> Link: <https://example.org/links/resource1>
; rel="linkset" ; rel="linkset"
; type="application/linkset+json" ; type="application/linkset+json"
Content-Length: 236 Content-Length: 236
Content-Type: text/html;charset=utf-8 Content-Type: text/html;charset=utf-8
Figure 12: Response to HTTP HEAD Request Figure 12: Response to HTTP HEAD request
7.4. Link Set Profiles 7.4. Link Set Profiles
The examples in this section illustrate the use of the "profile" The examples in this section illustrate the use of the "profile"
attribute for a link with the "linkset" link relation type and the attribute for a link with the "linkset" link relation type and the
"profile" attribute for a link set media type. The examples are "profile" attribute for a link set media type. The examples are
inspired by the implementation of link sets by GS1 (the standards inspired by the implementation of link sets by GS1 (the standards
body behind many of the world's barcodes). body behind many of the world's barcodes).
7.4.1. Using a "profile" Attribute with a "linkset" Link 7.4.1. Using a "profile" Attribute with a "linkset" Link
Figure 13 shows a client issuing an HTTP HEAD request against trade Figure 13 shows a client issuing an HTTP HEAD request against trade
item 09506000134352 at <https://id.gs1.org/01/9506000134352>. item 09506000134352 at <https://id.gs1.org/01/9506000134352>.
HEAD /01/9506000134352 HTTP/1.1 HEAD /01/9506000134352 HTTP/1.1
Host: id.gs1.org Host: id.gs1.org
Figure 13: Client HTTP HEAD Request Figure 13: Client HTTP HEAD request
Figure 14 shows the server's response to the request of Figure 13, Figure 14 shows the server's response to the request of Figure 13,
including a "linkset" link with a "profile" attribute that has the including a "linkset" link with a "profile" attribute that has the
profile URI <https://www.gs1.org/voc/?show=linktypes> as its value. profile URI <https://www.gs1.org/voc/?show=linktypes> as its value.
Dereferencing that URI yields a profile document that lists all the Dereferencing that URI yields a profile document that lists all the
link relation types that a client can expect when requesting the link link relation types that a client can expect when requesting the link
set made discoverable by the "linkset" link. The link relation types set made discoverable by the "linkset" link. The link relation types
are presented in abbreviated form, e.g., <gs1:activityIdeas>, whereas are presented in abbreviated form, e.g., <gs1:activityIdeas>, whereas
the actual link relation type URIs are available as hyperlinks on the the actual link relation type URIs are available as hyperlinks on the
abbreviations, e.g., <https://www.gs1.org/voc/activityIdeas>. For abbreviations, e.g., <https://www.gs1.org/voc/activityIdeas>. For
skipping to change at line 946 skipping to change at line 946
HTTP/1.1 307 Temporary Redirect HTTP/1.1 307 Temporary Redirect
Date: Mon, 27 Sep 2021 16:03:07 GMT Date: Mon, 27 Sep 2021 16:03:07 GMT
Server: nginx Server: nginx
Link: <https://id.gs1.org/01/9506000134352?linkType=all> Link: <https://id.gs1.org/01/9506000134352?linkType=all>
; rel="linkset" ; rel="linkset"
; type="application/linkset+json" ; type="application/linkset+json"
; profile="https://www.gs1.org/voc/?show=linktypes" ; profile="https://www.gs1.org/voc/?show=linktypes"
Location: https://example.com/risotto-rice-with-mushrooms/ Location: https://example.com/risotto-rice-with-mushrooms/
Figure 14: Response to the Client's HEAD Request, including a Figure 14: Response to the client's HEAD request, including a
"profile" Attribute for the "linkset" Link "profile" attribute for the "linkset" link
7.4.2. Using a "profile" Parameter with a Link Set Media Type 7.4.2. Using a "profile" Parameter with a Link Set Media Type
Figure 15 shows a client issuing an HTTP HEAD request against the Figure 15 shows a client issuing an HTTP HEAD request against the
link set <https://id.gs1.org/01/9506000134352?linkType=all> that was link set <https://id.gs1.org/01/9506000134352?linkType=all> that was
discovered through the HTTP interactions shown in Section 7.4.1. discovered through the HTTP interactions shown in Section 7.4.1.
HEAD /01/9506000134352?linkType=all HTTP/1.1 HEAD /01/9506000134352?linkType=all HTTP/1.1
Host: id.gs1.org Host: id.gs1.org
Figure 15: Client HTTP HEAD Request Figure 15: Client HTTP HEAD request
Figure 16 shows the server's response to the request of Figure 15. Figure 16 shows the server's response to the request of Figure 15.
Note the "profile" parameter for the "application/linkset+json" media Note the "profile" parameter for the "application/linkset+json" media
type, which has as its value the same profile URI type, which has as its value the same profile URI
<https://www.gs1.org/voc/?show=linktypes> as was used in Figure 14. <https://www.gs1.org/voc/?show=linktypes> as was used in Figure 14.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 27 Sep 2021 16:03:33 GMT Date: Mon, 27 Sep 2021 16:03:33 GMT
Server: nginx Server: nginx
Content-Type: application/linkset+json; Content-Type: application/linkset+json;
profile="https://www.gs1.org/voc/?show=linktypes" profile="https://www.gs1.org/voc/?show=linktypes"
Content-Length: 396 Content-Length: 396
Figure 16: Response to the Client's HEAD Request, including a Figure 16: Response to the client's HEAD request, including a
"profile" Parameter for the "application/linkset+json" Media Type "profile" parameter for the "application/linkset+json" media type
7.4.3. Using a Link with a "profile" Link Relation Type 7.4.3. Using a Link with a "profile" Link Relation Type
Note that the response shown in Figure 16 from the link set resource Note that the response shown in Figure 16 from the link set resource
is equivalent to the response shown in Figure 17, which leverages the is equivalent to the response shown in Figure 17, which leverages the
"profile" link relation type defined in [RFC6906]. "profile" link relation type defined in [RFC6906].
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 27 Sep 2021 16:03:33 GMT Date: Mon, 27 Sep 2021 16:03:33 GMT
Server: nginx Server: nginx
Content-Type: application/linkset+json Content-Type: application/linkset+json
Link: <https://www.gs1.org/voc/?show=linktypes>; rel="profile" Link: <https://www.gs1.org/voc/?show=linktypes>; rel="profile"
Content-Length: 396 Content-Length: 396
Figure 17: Response to the Client's HEAD Request, including a Figure 17: Response to the client's HEAD request, including a
"profile" Link "profile" link
A link with a "profile" link relation type as shown in Figure 17 can A link with a "profile" link relation type as shown in Figure 17 can
also be conveyed in the link set document itself. This is also be conveyed in the link set document itself. This is
illustrated by Figure 18. Following the recommendation that all illustrated by Figure 18. Following the recommendation that all
links in a link set document should have an explicit anchor, such a links in a link set document should have an explicit anchor, such a
link has the URI of the link set itself as the anchor and the profile link has the URI of the link set itself as the anchor and the profile
URI as the target. Multiple profile URIs are handled by using URI as the target. Multiple profile URIs are handled by using
multiple "href" members. multiple "href" members.
{ "linkset": { "linkset":
skipping to change at line 1014 skipping to change at line 1014
] ]
}, },
{ "anchor": "https://id.gs1.org/01/9506000134352", { "anchor": "https://id.gs1.org/01/9506000134352",
"https://gs1.org/voc/whatsInTheBox": [ "https://gs1.org/voc/whatsInTheBox": [
{"href": "https://example.com/en/packContents/GB"} {"href": "https://example.com/en/packContents/GB"}
] ]
} }
] ]
} }
Figure 18: A Linkset That Declares the Profile It Complies with, Figure 18: A linkset that declares the profile it complies with,
Using a "profile" Link using a "profile" link
8. IANA Considerations 8. IANA Considerations
8.1. Link Relation Type: linkset 8.1. Link Relation Type: linkset
The link relation type below has been registered by IANA in the "Link The link relation type below has been registered by IANA in the "Link
Relation Types" registry as per Section 4.2 of [RFC8288]: Relation Types" registry as per Section 4.2 of [RFC8288]:
Relation Name: linkset Relation Name: linkset
skipping to change at line 1346 skipping to change at line 1346
"value": "Voyez-le en action!", "value": "Voyez-le en action!",
"language": "fr" "language": "fr"
} }
] ]
} }
] ]
} }
] ]
} }
Figure 19: Using a Typed Link to Support the Discovery of a JSON- Figure 19: Using a typed link to support the discovery of a JSON-
LD Context for a Linkset LD context for a linkset
In order to obtain the JSON-LD context conveyed by the server, the In order to obtain the JSON-LD context conveyed by the server, the
user agent issues an HTTP GET against the link target of the link user agent issues an HTTP GET against the link target of the link
with the "http://www.w3.org/ns/json-ld#context" relation type. The with the "http://www.w3.org/ns/json-ld#context" relation type. The
response to this GET is shown in Figure 20. This particular JSON-LD response to this GET is shown in Figure 20. This particular JSON-LD
context maps "application/linkset+json" representations of link sets context maps "application/linkset+json" representations of link sets
to Dublin Core Terms [DCMI-TERMS]. Note that the "linkset" entry in to Dublin Core terms [DCMI-TERMS]. Note that the "linkset" entry in
the JSON-LD context is introduced to support links with the "linkset" the JSON-LD context is introduced to support links with the "linkset"
relation type in link sets. relation type in link sets.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/ld+json Content-Type: application/ld+json
Content-Length: 658 Content-Length: 658
{ {
"@context": [ "@context": [
{ {
skipping to change at line 1396 skipping to change at line 1396
"language": "@language", "language": "@language",
"value": "@value", "value": "@value",
"hreflang": { "hreflang": {
"@id": "http://purl.org/dc/terms/language", "@id": "http://purl.org/dc/terms/language",
"@container": "@set" "@container": "@set"
} }
} }
] ]
} }
Figure 20: JSON-LD Context Mapping to Dublin Core Terms Figure 20: JSON-LD context mapping to Dublin Core terms
Applying the JSON-LD context of Figure 20 to the link set of Applying the JSON-LD context of Figure 20 to the link set of
Figure 19 allows transforming the "application/linkset+json" link set Figure 19 allows transforming the "application/linkset+json" link set
to an RDF link set. Figure 21 shows the latter represented by means to an RDF link set. Figure 21 shows the latter represented by means
of the "text/turtle" RDF serialization. of the "text/turtle" RDF serialization.
<https://example.com/en/defaultPage> <https://example.com/en/defaultPage>
<http://purl.org/dc/terms/format> <http://purl.org/dc/terms/format>
"text/html" . "text/html" .
<https://example.com/en/defaultPage> <https://example.com/en/defaultPage>
skipping to change at line 1467 skipping to change at line 1467
<https://video.example> <https://video.example>
<http://purl.org/dc/terms/language> <http://purl.org/dc/terms/language>
"fr" . "fr" .
<https://video.example> <https://video.example>
<http://purl.org/dc/terms/title> <http://purl.org/dc/terms/title>
"See it in action!"@en . "See it in action!"@en .
<https://video.example> <https://video.example>
<http://purl.org/dc/terms/title> <http://purl.org/dc/terms/title>
"Voyez-le en action!"@fr . "Voyez-le en action!"@fr .
Figure 21: RDF Serialization of the Linkset Resulting from Figure 21: RDF serialization of the linkset resulting from
Applying the JSON-LD Context applying the JSON-LD context
Acknowledgements Acknowledgements
Thanks for comments and suggestions provided by Phil Archer, Thanks for comments and suggestions provided by Phil Archer,
Dominique Guinard, Mark Nottingham, Julian Reschke, Rob Sanderson, Dominique Guinard, Mark Nottingham, Julian Reschke, Rob Sanderson,
Stian Soiland-Reyes, Sarven Capadisli, and Addison Phillips. Stian Soiland-Reyes, Sarven Capadisli, and Addison Phillips.
Authors' Addresses Authors' Addresses
Erik Wilde Erik Wilde
 End of changes. 22 change blocks. 
29 lines changed or deleted 29 lines changed or added

This html diff was produced by rfcdiff 1.48.