draft-ietf-httpapi-linkset-02.unpg.txt   draft-ietf-httpapi-linkset-latest.txt 
Network Working Group E. Wilde Network Working Group E. Wilde
Internet-Draft Axway Internet-Draft Axway
Intended status: Informational H. Van de Sompel Intended status: Informational H. Van de Sompel
Expires: December 6, 2021 Data Archiving and Networked Services Expires: December 16, 2021 Data Archiving and Networked Services
June 4, 2021 June 14, 2021
Linkset: Media Types and a Link Relation Type for Link Sets Linkset: Media Types and a Link Relation Type for Link Sets
draft-ietf-httpapi-linkset-02 draft-ietf-httpapi-linkset-03
Abstract Abstract
This specification defines two document formats and respective media This specification defines two document formats and respective media
types for representing sets of links as stand-alone resources. One types for representing sets of links as stand-alone resources. One
format is JSON-based, the other aligned with the format for format is JSON-based, the other aligned with the format for
representing links in the HTTP "Link" header field. This representing links in the HTTP "Link" header field. This
specification also introduces a link relation type to support specification also introduces a link relation type to support
discovery of sets of links. discovery of sets of links.
skipping to change at line 43 skipping to change at page 1, line 44
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 6, 2021. This Internet-Draft will expire on December 16, 2021.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Scenarios 3. Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Third-Party Links 3.1. Third-Party Links . . . . . . . . . . . . . . . . . . . . 4
3.2. Challenges Writing to HTTP Link Header Field 3.2. Challenges Writing to HTTP Link Header Field . . . . . . 5
3.3. Large Number of Links 3.3. Large Number of Links . . . . . . . . . . . . . . . . . . 5
4. Document Formats for Sets of Links 4. Document Formats for Sets of Links . . . . . . . . . . . . . 5
4.1. HTTP Link Document Format: application/linkset 4.1. HTTP Link Document Format: application/linkset . . . . . 6
4.2. JSON Document Format: application/linkset+json 4.2. JSON Document Format: application/linkset+json . . . . . 6
4.2.1. Set of Links 4.2.1. Set of Links . . . . . . . . . . . . . . . . . . . . 7
4.2.2. Link Context Object 4.2.2. Link Context Object . . . . . . . . . . . . . . . . . 8
4.2.3. Link Target Object 4.2.3. Link Target Object . . . . . . . . . . . . . . . . . 8
4.2.4. Link Target Attributes 4.2.4. Link Target Attributes . . . . . . . . . . . . . . . 10
4.2.5. JSON Extensibility 4.2.5. JSON Extensibility . . . . . . . . . . . . . . . . . 14
5. The "profile" attribute for media types to Represent Sets of 5. The "profile" attribute for media types to Represent Sets of
Links Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
6. The "linkset" Relation Type for Linking to a Set of Links 6. The "linkset" Relation Type for Linking to a Set of Links . . 15
7. Examples 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 15
7.1. Set of Links Provided as application/linkset 7.1. Set of Links Provided as application/linkset . . . . . . 15
7.2. Set of Links Provided as application/linkset+json 7.2. Set of Links Provided as application/linkset+json . . . . 17
7.3. Discovering a Link Set via the "linkset" Link Relation 7.3. Discovering a Link Set via the "linkset" Link Relation
Type Type . . . . . . . . . . . . . . . . . . . . . . . . . . 19
8. Implementation Status 8. Implementation Status . . . . . . . . . . . . . . . . . . . . 20
8.1. GS1 8.1. GS1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
8.2. FAIR Signposting Profile 8.2. FAIR Signposting Profile . . . . . . . . . . . . . . . . 21
8.3. Open Journal Systems (OJS) 8.3. Open Journal Systems (OJS) . . . . . . . . . . . . . . . 21
9. IANA Considerations 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
9.1. Link Relation Type: linkset 9.1. Link Relation Type: linkset . . . . . . . . . . . . . . . 21
9.2. Media Type: application/linkset 9.2. Media Type: application/linkset . . . . . . . . . . . . . 22
9.3. Media Type: application/linkset+json 9.3. Media Type: application/linkset+json . . . . . . . . . . 23
10. Security Considerations 10. Security Considerations . . . . . . . . . . . . . . . . . . . 24
11. References 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 25
11.1. Normative References 11.1. Normative References . . . . . . . . . . . . . . . . . . 25
11.2. Informative References 11.2. Informative References . . . . . . . . . . . . . . . . . 26
Appendix A. Acknowledgements Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 26
Appendix B. JSON-LD Context Appendix B. JSON-LD Context . . . . . . . . . . . . . . . . . . 27
Authors' Addresses Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31
1. Introduction 1. Introduction
Resources on the Web often use typed Web Links [RFC8288], either Resources on the Web often use typed Web Links [RFC8288], either
embedded in resource representations, for example using the <link> embedded in resource representations, for example using the <link>
element for HTML documents, or conveyed in the HTTP "Link" header for element for HTML documents, or conveyed in the HTTP "Link" header
documents of any media type. In some cases, however, providing links field for documents of any media type. In some cases, however,
in this manner is impractical or impossible and delivering a set of providing links in this manner is impractical or impossible and
links as a stand-alone document is preferable. delivering a set of links as a stand-alone document is preferable.
Therefore, this specification defines two document formats and Therefore, this specification defines two document formats and
associated media types to represent sets of links. It also defines associated media types to represent sets of links. It also defines
the "linkset" relation type that supports discovery of any resource the "linkset" relation type that supports discovery of any resource
that conveys a set of links as a stand-alone document. that conveys a set of links as a stand-alone document.
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
This specification uses the terms "link context" and "link target" as This specification uses the terms "link context" and "link target" as
defined in [RFC8288]. These terms respectively correspond with defined in [RFC8288]. These terms respectively correspond with
"Context IRI" and "Target IRI" as used in [RFC5988]. Although "Context IRI" and "Target IRI" as used in [RFC5988]. Although
defined as IRIs, in common scenarios they are also URIs. defined as IRIs, in common scenarios they are also URIs.
In the examples provided in this document, links in the HTTP "Link" In the examples provided in this document, links in the HTTP "Link"
header are shown on separate lines in order to improve readability. header field are shown on separate lines in order to improve
Note, however, that as per Section 3.2 of [RFC7230], line breaks are readability. Note, however, that as per Section 5.5 of
not allowed in values for HTTP headers; only whitespaces and tabs are [I-D.ietf-httpbis-semantics], line breaks are not allowed in values
supported as seperators. for HTTP fields; only whitespaces and tabs are supported as
separators.
3. Scenarios 3. Scenarios
The following sections outline scenarios in which providing links by The following sections outline scenarios in which providing links by
means of a standalone document instead of in an HTTP "Link" header means of a standalone document instead of in an HTTP "Link" header
field or as links embedded in the resource representation is field or as links embedded in the resource representation is
advantageous or necessary. advantageous or necessary.
For all scenarios, links could be provided by means of a stand-alone For all scenarios, links could be provided by means of a stand-alone
document that is formatted according to the JSON-based serialization, document that is formatted according to the JSON-based serialization,
the serialization aligned with the HTTP "Link" header format, or the serialization aligned with the HTTP "Link" field format, or both.
both. The former serialization is motivated by the widespread use of The former serialization is motivated by the widespread use of JSON
JSON and related tools, which suggests that handling sets of links and related tools, which suggests that handling sets of links
expressed as JSON documents should be attractive to developers. The expressed as JSON documents should be attractive to developers. The
latter serialization is provided for compatibility with the existing latter serialization is provided for compatibility with the existing
serialization used in the HTTP "Link" header and to allow reuse of serialization used in the HTTP "Link" field and to allow reuse of
tools created to handle it. tools created to handle it.
It is important to keep in mind that when providing links by means of It is important to keep in mind that when providing links by means of
a standalone representation, other links can still be provided using a standalone representation, other links can still be provided using
other approaches, i.e. it is possible combine various mechanisms to other approaches, i.e. it is possible combine various mechanisms to
convey links. convey links.
3.1. Third-Party Links 3.1. Third-Party Links
In some cases it is useful that links pertaining to a resource are In some cases it is useful that links pertaining to a resource are
skipping to change at line 192 skipping to change at page 5, line 11
These requirements are addressed in this specification through the These requirements are addressed in this specification through the
definition of two media types and a link relation type, respectively. definition of two media types and a link relation type, respectively.
3.2. Challenges Writing to HTTP Link Header Field 3.2. Challenges Writing to HTTP Link Header Field
In some cases, it is not straightforward to write links to the HTTP In some cases, it is not straightforward to write links to the HTTP
"Link" header field from an application. This can, for example, be "Link" header field from an application. This can, for example, be
the case because not all required link information is available to the case because not all required link information is available to
the application or because the application does not have the the application or because the application does not have the
capability to directly write HTTP headers. In such cases, providing capability to directly write HTTP fields. In such cases, providing
links by means of a standalone document can be a solution. Making links by means of a standalone document can be a solution. Making
the resource that provides these links discoverable can be achieved the resource that provides these links discoverable can be achieved
by means of a typed link. by means of a typed link.
3.3. Large Number of Links 3.3. Large Number of Links
When conveying links in an HTTP "Link" header field, it is possible When conveying links in an HTTP "Link" header field, it is possible
for the size of the HTTP response header to become unpredictable. for the size of the HTTP response fields to become unpredictable.
This can be the case when links are determined dynamically dependent This can be the case when links are determined dynamically dependent
on a range of contextual factors. It is possible to statically on a range of contextual factors. It is possible to statically
configure a web server to correctly handle large HTTP response configure a web server to correctly handle large HTTP response fields
headers by specifying an upper bound for their size. But when the by specifying an upper bound for their size. But when the number of
number of links is unpredictable, estimating a reliable upper bound links is unpredictable, estimating a reliable upper bound is
is challenging. challenging.
HTTP [RFC7231] defines error codes related to excess communication by HTTP [I-D.ietf-httpbis-semantics] defines error codes related to
the user agent ("413 Request Entity Too Large" and "414 Request-URI excess communication by the user agent ("413 Request Entity Too
Too Long"), but no specific error codes are defined to indicate that Large" and "414 Request-URI Too Long"), but no specific error codes
response header content exceeds the upper bound that can be handled are defined to indicate that response field content exceeds the upper
by the server, and thus it has been truncated. As a result, bound that can be handled by the server, and thus it has been
applications take counter measures aimed at controlling the size of truncated. As a result, applications take counter measures aimed at
the HTTP "Link" header field, for example by limiting the links they controlling the size of the HTTP "Link" header field, for example by
provide to those with select relation types, thereby limiting the limiting the links they provide to those with select relation types,
value of the HTTP "Link" header field to clients. Providing links by thereby limiting the value of the HTTP "Link" header field to
means of a standalone document overcomes challenges related to the clients. Providing links by means of a standalone document overcomes
unpredictable nature of the size of HTTP "Link" header fields. challenges related to the unpredictable nature of the size of HTTP
"Link" header fields.
4. Document Formats for Sets of Links 4. Document Formats for Sets of Links
This section specifies two document formats to convey a set of links. This section specifies two document formats to convey a set of links.
Both are based on the abstract model specified in Section 2 of Web Both are based on the abstract model specified in Web Linking
Linking [RFC8288] that defines a link as consisting of a "link [RFC8288] that defines a link as consisting of a "link context", a
context", a "link relation type", a "link target", and optional "link relation type", a "link target", and optional "target
"target attributes": attributes":
o The format defined in Section 4.1 is identical to the payload of o The format defined in Section 4.1 is identical to the payload of
the HTTP "Link" header field as specified in Web Linking the HTTP "Link" header field as specified in Web Linking
[RFC8288]. [RFC8288].
o The format defined in Section 4.2 is based on JSON [RFC8259]. o The format defined in Section 4.2 is based on JSON [RFC8259].
Note that [RFC8288] deprecates the "rev" construct that was provided Note that [RFC8288] deprecates the "rev" construct that was provided
by [RFC5988] as a means to express links with a directionality that by [RFC5988] as a means to express links with a directionality that
is the inverse of direct links that use the "rel" construct. In both is the inverse of direct links that use the "rel" construct. In both
skipping to change at line 271 skipping to change at page 6, line 42
attribute), use absolute URIs (as defined in Section 4.3 of attribute), use absolute URIs (as defined in Section 4.3 of
[RFC3986]). [RFC3986]).
If these recommendations are not followed, interpretation of links in If these recommendations are not followed, interpretation of links in
"application/linkset" documents will depend on which URI is used as "application/linkset" documents will depend on which URI is used as
context. context.
It should be noted that the "application/linkset" format specified It should be noted that the "application/linkset" format specified
here is different than the "application/link-format" format specified here is different than the "application/link-format" format specified
in [RFC6690] in that the former fully matches the payload of the HTTP in [RFC6690] in that the former fully matches the payload of the HTTP
"Link" header as defined in Section 3 of [RFC8288], whereas the "Link" header field as defined in Section 3 of [RFC8288], whereas the
latter introduces constraints on that definition to meet requirements latter introduces constraints on that definition to meet requirements
for Constrained RESTful Environments. for Constrained RESTful Environments.
4.2. JSON Document Format: application/linkset+json 4.2. JSON Document Format: application/linkset+json
This document format uses JSON [RFC8259] as the syntax to represent a This document format uses JSON [RFC8259] as the syntax to represent a
set of links. The set of links follows the abstract model defined by set of links. The set of links follows the abstract model defined by
Web Linking [RFC8288]. Web Linking [RFC8288].
The assigned media type for this format is "application/ The assigned media type for this format is "application/
skipping to change at line 348 skipping to change at page 8, line 27
by providing an "anchor" member with empty string ("anchor": ""). by providing an "anchor" member with empty string ("anchor": "").
o For each distinct relation type that the link context has with o For each distinct relation type that the link context has with
link targets, a link context object MUST have an additional link targets, a link context object MUST have an additional
member. This member is an array in which a distinct JSON object - member. This member is an array in which a distinct JSON object -
the "link target object" (see Section 4.2.3) - MUST be used for the "link target object" (see Section 4.2.3) - MUST be used for
each link target for which the relationship with the link context each link target for which the relationship with the link context
(value of the encompassing anchor member) applies. The name of (value of the encompassing anchor member) applies. The name of
this member expresses the relation type of the link as follows: this member expresses the relation type of the link as follows:
o
* For registered relation types [RFC8288], the name of this * For registered relation types [RFC8288], the name of this
member is the registered name of the relation type. member is the registered name of the relation type.
* For extension relation types [RFC8288], the name of this member * For extension relation types [RFC8288], the name of this member
is the URI that uniquely represents the relation type. is the URI that uniquely represents the relation type.
o Even if there is only one link target object it MUST be wrapped in o Even if there is only one link target object it MUST be wrapped in
an array. Members other than link target objects MUST NOT be an array. Members other than link target objects MUST NOT be
included in this array. included in this array.
skipping to change at line 546 skipping to change at page 12, line 41
{ {
"linkset": "linkset":
[ [
{ "anchor": "http://example.net/bar", { "anchor": "http://example.net/bar",
"next": [ "next": [
{"href": "http://example.com/foo", {"href": "http://example.com/foo",
"type": "text/html", "type": "text/html",
"hreflang": [ "en" , "de" ], "hreflang": [ "en" , "de" ],
"title": "Next chapter", "title": "Next chapter",
"title*": [ { "value": "nachstes Kapitel" , "title*": [ { "value": "naechstes Kapitel" ,
"language" : "de" } ] "language" : "de" } ]
} }
] ]
} }
] ]
} }
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 native syntax it would be encoded as title*=UTF- character (in the native 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. This is not shown in the above form in the JSON representation. Implementations MUST properly
example due to the limitations of RFC publication. Implementations decode/encode internationalized target attributes that follow the
MUST properly decode/encode internationalized target attributes that model of [RFC8187] when transcoding between the "application/linkset"
follow the model of [RFC8187] when transcoding between the and the "application/linkset+json" formats.
"application/linkset" and the "application/linkset+json" formats.
4.2.4.3. Extension Target Attributes 4.2.4.3. Extension Target Attributes
Extension target attributes are attributes that are not defined by Extension target attributes are attributes that are not defined by
[RFC8288] (as listed in Section 4.2.4.1), but are nevertheless used [RFC8288] (as listed in Section 4.2.4.1), but are nevertheless used
to qualify links. They can be defined by communities in any way to qualify links. They can be defined by communities in any way
deemed necessary, and it is up to them to make sure their usage is deemed necessary, and it is up to them to make sure their usage is
understood by target applications. However, lacking standardization, understood by target applications. However, lacking standardization,
there is no interoperable understanding of these extension there is no interoperable understanding of these extension
attributes. One important consequence is that their cardinality is attributes. One important consequence is that their cardinality is
skipping to change at line 630 skipping to change at page 14, line 32
4.2.5. JSON Extensibility 4.2.5. JSON Extensibility
The extensibility of the JSON document format for representing a set The extensibility of the JSON document format for representing a set
of links is restricted to the extensibility provided by [RFC8288]. of links is restricted to the extensibility provided by [RFC8288].
The Web linking model provides for the use of extension target The Web linking model provides for the use of extension target
attributes as discussed in Section 4.2.4.3. Extensions based on the attributes as discussed in Section 4.2.4.3. Extensions based on the
JSON syntax MUST NOT be used, and MUST be ignored when found in a JSON syntax MUST NOT be used, and MUST be ignored when found in a
JSON linkset document. JSON linkset document.
This limitation of the JSON format allows to unambiguously round trip This limitation of the JSON format allows to unambiguously round trip
between links provided in the HTTP "Link" header, sets of links between links provided in the HTTP "Link" header field, sets of links
serialized according to the "application/linkset" format, and sets of serialized according to the "application/linkset" format, and sets of
links serialized according to the "application/linkset+json" format. links serialized according to the "application/linkset+json" format.
5. The "profile" attribute for media types to Represent Sets of Links 5. The "profile" attribute for media types to Represent Sets of Links
As a means to convey specific constraints or conventions (as per As a means to convey specific constraints or conventions (as per
[RFC6906]) that apply to a link set document, the "profile" attribute [RFC6906]) that apply to a link set document, the "profile" attribute
MAY be used in conjunction with the media types "application/linkset" MAY be used in conjunction with the media types "application/linkset"
and "application/linkset+json" detailed in Section 4.1 and and "application/linkset+json" detailed in Section 4.1 and
Section 4.2, respectively. For example, the attribute could be used Section 4.2, respectively. For example, the attribute could be used
skipping to change at line 666 skipping to change at page 15, line 21
document that honors the profiles it recognizes, and MUST ignore the document that honors the profiles it recognizes, and MUST ignore the
profiles which it does not recognize. profiles which it does not recognize.
6. The "linkset" Relation Type for Linking to a Set of Links 6. The "linkset" Relation Type for Linking to a Set of Links
The target of a link with the "linkset" relation type provides a set The target of a link with the "linkset" relation type provides a set
of links, including links in which the resource that is the link of links, including links in which the resource that is the link
context participates. context participates.
A link with the "linkset" relation type MAY be provided in the header A link with the "linkset" relation type MAY be provided in the header
and/or the body of a resource's representation. It may also be field and/or the body of a resource's representation. It may also be
discovered by other means, such as through client-side information. discovered by other means, such as through client-side information.
A resource MAY provide more than one link with a "linkset" relation A resource MAY provide more than one link with a "linkset" relation
type. Multiple such links can refer to the same set of links type. Multiple such links can refer to the same set of links
expressed using different media types, or to different sets of links, expressed using different media types, or to different sets of links,
potentially provided by different third-party services. potentially provided by different third-party services.
A user agent that follows a "linkset" link MUST be aware that the set A user agent that follows a "linkset" link MUST be aware that the set
of links provided by the resource that is the target of the link can of links provided by the resource that is the target of the link can
contain links in which the resource that is the context of the link contain links in which the resource that is the context of the link
skipping to change at line 699 skipping to change at page 16, line 7
documents, respectively. Section 7.3 illustrates the use of the documents, respectively. Section 7.3 illustrates the use of the
"linkset" link relation type to support discovery of sets of links. "linkset" link relation type to support discovery of sets of links.
7.1. Set of Links Provided as application/linkset 7.1. Set of Links Provided as application/linkset
Figure 1 shows a client issuing an HTTP GET request against resource Figure 1 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
Connection: close
Figure 1: Client HTTP GET request Figure 1: Client HTTP GET request
Figure 2 shows the response to the GET request of Figure 1. The Figure 2 shows the response to the GET request of Figure 1. The
response contains a Content-Type header specifying that the media response contains a Content-Type header field specifying that the
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 indicates the availability of an alternate The HTTP "Link" header field indicates the availability of an
representation of the set of links using media type "application/ alternate representation of the set of links using media type
linkset+json". "application/linkset+json".
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 12 Aug 2019 10:35:51 GMT Date: Mon, 12 Aug 2019 10:35:51 GMT
Server: Apache-Coyote/1.1 Server: Apache-Coyote/1.1
Content-Length: 1023 Content-Length: 1023
Content-Type: application/linkset; charset=UTF-8 Content-Type: application/linkset
Link: <https://example.org/links/resource1> ; rel="alternate" Link: <https://example.org/links/resource1> ; rel="alternate"
; type="application/linkset+json" ; type="application/linkset+json"
Connection: close
<https://authors.example.net/johndoe> <https://authors.example.net/johndoe>
; rel="author" ; rel="author"
; type="application/rdf+xml" ; type="application/rdf+xml"
; anchor="https://example.org/resource1", ; anchor="https://example.org/resource1",
<https://example.org/resource1?version=3> <https://example.org/resource1?version=3>
; rel="latest-version" ; rel="latest-version"
; type="text/html" ; type="text/html"
; anchor="https://example.org/resource1", ; anchor="https://example.org/resource1",
<https://example.org/resource1?version=2> <https://example.org/resource1?version=2>
; rel="predecessor-version" ; rel="predecessor-version"
skipping to change at line 756 skipping to change at page 17, line 49
<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 2: Response to HTTP GET includes a set of links Figure 2: 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 3 shows the client issuing an HTTP GET request against Figure 3 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 to indicate it prefers a response in the uses an "Accept" header field to indicate it prefers a response in
"application/linkset+json" format. 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
Connection: close
Figure 3: Client HTTP GET request expressing preference for Figure 3: Client HTTP GET request expressing preference for
"application/linkset+json" response "application/linkset+json" response
Figure 4 shows the response to the HTTP GET request of Figure 3. The Figure 4 shows the response to the HTTP GET request of Figure 3. The
set of links is serialized according to the media type "application/ set of links is serialized according to the media type "application/
linkset+json". 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
skipping to change at line 845 skipping to change at page 19, line 44
Figure 4: Response to the client's request for the set of links Figure 4: Response to the client's request for the set of links
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 5 shows a client issuing an HTTP HEAD request against resource Figure 5 shows a client issuing an HTTP HEAD request against resource
<https://example.org/resource1>. <https://example.org/resource1>.
HEAD resource1 HTTP/1.1 HEAD resource1 HTTP/1.1
Host: example.org Host: example.org
Connection: close
Figure 5: Client HTTP HEAD request Figure 5: Client HTTP HEAD request
Figure 6 shows the response to the HEAD request of Figure 5. The Figure 6 shows the response to the HEAD request of Figure 5. The
response contains an HTTP "Link" header with a link that has the response contains an HTTP "Link" header field with a link that has
"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
Connection: close
Figure 6: Response to HTTP HEAD request Figure 6: Response to HTTP HEAD request
Section 7.2 shows a client obtaining a set of links by issuing an Section 7.2 shows a client obtaining a set of links by issuing an
HTTP GET on the target of the link with the "linkset" relation type, HTTP GET on the target of the link with the "linkset" relation type,
<https://example.org/links/resource1>. <https://example.org/links/resource1>.
8. Implementation Status 8. Implementation Status
Note to RFC Editor: Please remove this section before publication. Note to RFC Editor: Please remove this section before publication.
skipping to change at line 938 skipping to change at page 21, line 39
The OJS platform has implemented "linkset" support as an alternative The OJS platform has implemented "linkset" support as an alternative
way to provide links when there are more than a configured limit way to provide links when there are more than a configured limit
(they consider using about 10 as a good default, for testing purpose (they consider using about 10 as a good default, for testing purpose
it is currently set to 8). it is currently set to 8).
9. IANA Considerations 9. IANA Considerations
9.1. Link Relation Type: linkset 9.1. Link Relation Type: linkset
The link relation type below has been registered by IANA per The link relation type below has been registered by IANA per Web
Section 6.2.1 of Web Linking [RFC8288]: Linking [RFC8288]:
Relation Name: linkset Relation Name: linkset
Description: The Target IRI of a link with the "linkset" relation Description: The Target IRI of a link with the "linkset" relation
type provides a set of links, including links in which the Context type provides a set of links, including links in which the Context
IRI of the link participates. IRI of the link participates.
Reference: [[ This document ]] Reference: [[ This document ]]
9.2. Media Type: application/linkset 9.2. Media Type: application/linkset
skipping to change at line 964 skipping to change at page 22, line 20
Type name: application Type name: application
Subtype name: linkset Subtype name: linkset
Required parameters: none Required parameters: none
Optional parameters: profile Optional parameters: profile
Encoding considerations: Linksets are encoded according to the Encoding considerations: Linksets are encoded according to the
definition of [RFC8288]. The encoding of [RFC8288] is based on definition of [RFC8288]. The encoding of [RFC8288] is based on
the general encoding rules of [RFC7230], with the addition of the general encoding rules of [I-D.ietf-httpbis-semantics], with
allowing indicating character encoding and language for specific the addition of allowing indicating character encoding and
parameters as defined by [RFC8187]. language for specific parameters as defined by [RFC8187].
Security considerations: The security considerations of [[ This Security considerations: The security considerations of [[ This
document ]] apply. document ]] apply.
Interoperability considerations: The interoperability Interoperability considerations: The interoperability
considerations of [RFC7230] apply. considerations of [I-D.ietf-httpbis-semantics] apply.
Published specification: [[ This document ]] Published specification: [[ This document ]]
Applications that use this media type: This media type is not Applications that use this media type: This media type is not
specific to any application, as it can be used by any application specific to any application, as it can be used by any application
that wants to interchange web links. that wants to interchange web links.
Additional information: Additional information:
Magic number(s): N/A Magic number(s): N/A
skipping to change at line 1089 skipping to change at page 25, line 9
and the application context, it is important to verify that there and the application context, it is important to verify that there
is sufficient trust in that 3rd party to allow it to provide these is sufficient trust in that 3rd party to allow it to provide these
links. Applications may choose to treat 3rd party links links. Applications may choose to treat 3rd party links
differently than cases where a resource and the links for that differently than cases where a resource and the links for that
resource are provided by the same party. resource are provided by the same party.
11. References 11. References
11.1. Normative References 11.1. Normative References
[I-D.ietf-httpbis-semantics]
Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP
Semantics", draft-ietf-httpbis-semantics-15 (work in
progress), March 2021.
[RFC0822] Crocker, D., "STANDARD FOR THE FORMAT OF ARPA INTERNET [RFC0822] Crocker, D., "STANDARD FOR THE FORMAT OF ARPA INTERNET
TEXT MESSAGES", STD 11, RFC 822, DOI 10.17487/RFC0822, TEXT MESSAGES", STD 11, RFC 822, DOI 10.17487/RFC0822,
August 1982, <https://www.rfc-editor.org/info/rfc822>. August 1982, <https://www.rfc-editor.org/info/rfc822>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
skipping to change at line 1129 skipping to change at page 26, line 5
[RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906,
DOI 10.17487/RFC6906, March 2013, DOI 10.17487/RFC6906, March 2013,
<https://www.rfc-editor.org/info/rfc6906>. <https://www.rfc-editor.org/info/rfc6906>.
[RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running [RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running
Code: The Implementation Status Section", RFC 6982, Code: The Implementation Status Section", RFC 6982,
DOI 10.17487/RFC6982, July 2013, DOI 10.17487/RFC6982, July 2013,
<https://www.rfc-editor.org/info/rfc6982>. <https://www.rfc-editor.org/info/rfc6982>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014,
<https://www.rfc-editor.org/info/rfc7230>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014,
<https://www.rfc-editor.org/info/rfc7231>.
[RFC7284] Lanthaler, M., "The Profile URI Registry", RFC 7284, [RFC7284] Lanthaler, M., "The Profile URI Registry", RFC 7284,
DOI 10.17487/RFC7284, June 2014, DOI 10.17487/RFC7284, June 2014,
<https://www.rfc-editor.org/info/rfc7284>. <https://www.rfc-editor.org/info/rfc7284>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8187] Reschke, J., "Indicating Character Encoding and Language [RFC8187] Reschke, J., "Indicating Character Encoding and Language
for HTTP Header Field Parameters", RFC 8187, for HTTP Header Field Parameters", RFC 8187,
skipping to change at line 1182 skipping to change at page 26, line 48
Sporny, M., Kellogg, G., and M. Lanthaler, "JSON-LD 1.0", Sporny, M., Kellogg, G., and M. Lanthaler, "JSON-LD 1.0",
World Wide Web Consortium Recommendation REC-json-ld- World Wide Web Consortium Recommendation REC-json-ld-
20140116, January 2014, 20140116, January 2014,
<https://www.w3.org/TR/2014/REC-json-ld-20140116>. <https://www.w3.org/TR/2014/REC-json-ld-20140116>.
11.3. URIs 11.3. URIs
[1] https://www.w3.org/TR/2014/REC-json-ld-20140116/#interpreting- [1] https://www.w3.org/TR/2014/REC-json-ld-20140116/#interpreting-
json-as-json-ld json-as-json-ld
[2] https://tools.ietf.org/html/rfc8288#appendix-A.2
Appendix A. Acknowledgements Appendix A. Acknowledgements
Thanks for comments and suggestions provided by Phil Archer, Thanks for comments and suggestions provided by Phil Archer,
Dominique Guinard, Mark Nottingham, Stian Soiland-Reyes, and Sarven Dominique Guinard, Mark Nottingham, Stian Soiland-Reyes, and Sarven
Capadisli. Capadisli.
Appendix B. JSON-LD Context Appendix B. JSON-LD Context
A set of links rendered according to the JSON serialization defined A set of links rendered according to the JSON serialization defined
in Section 4.2 can be interpreted as RDF triples by adding a JSON-LD in Section 4.2 can be interpreted as RDF triples by adding a JSON-LD
skipping to change at line 1213 skipping to change at page 27, line 28
the response to the GET request of Figure 3 against the URI of a set the response to the GET request of Figure 3 against the URI of a set
of links would be as shown in Figure 7. of links would be as shown in Figure 7.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 12 Aug 2019 10:48:22 GMT Date: Mon, 12 Aug 2019 10:48: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/contexts/linkset.jsonld> Link: <https://example.org/contexts/linkset.jsonld>
; rel="http://www.w3.org/ns/json-ld#context" ; rel="http://www.w3.org/ns/json-ld#context"
; type="application/ld+json" ; type="application/ld+json"
Content-Length: 846 Content-Length: 1349
{ {
"linkset": [ "linkset": [
{ {
"anchor": "https://example.org/article/view/7507", "anchor": "https://example.org/resource1",
"author": [ "author": [
{ {
"href": "https://orcid.org/0000-0002-1825-0097" "href": "https://authors.example.net/johndoe",
"type": "application/rdf+xml"
} }
], ],
"item": [ "memento": [
{ {
"href": "https://example.org/article/7507/item/1", "href": "https://example.org/resource1?version=1",
"type": "application/pdf" "type": "text/html",
"datetime": "Thu, 13 Jun 2019 09:34:33 GMT"
}, },
{ {
"href": "https://example.org/article/7507/item/2", "href": "https://example.org/resource1?version=2",
"type": "text/csv" "type": "text/html",
"datetime": "Sun, 21 Jul 2019 12:22:04 GMT"
} }
], ],
"cite-as": [ "latest-version": [
{ {
"href": "https://doi.org/10.5555/12345680", "href": "https://example.org/resource1?version=3",
"title": "A Methodology for the Emulation of Architecture" "type": "text/html"
} }
] ]
}, },
{ {
"anchor": "https://example.com/links/article/7507", "anchor": "https://example.org/resource1?version=3",
"alternate": [ "predecessor-version": [
{ {
"href": "https://mirror.example.com/links/article/7507", "href": "https://example.org/resource1?version=2",
"type": "application/linkset" "type": "text/html"
}
]
},
{
"anchor": "https://example.org/resource1?version=2",
"predecessor-version": [
{
"href": "https://example.org/resource1?version=1",
"type": "text/html"
}
]
},
{
"anchor": "https://example.org/resource1#comment=1",
"author": [
{
"href": "https://authors.example.net/alice"
} }
] ]
} }
] ]
} }
Figure 7: Using a typed link to support discovery of a JSON-LD Figure 7: Using a typed link to support discovery of a JSON-LD
Context for a Set of Links Context for a Set of Links
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 8. This particular JSON-LD response to this GET is shown in Figure 8. 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. It also renders each link relation as an to Dublin Core Terms. It also renders each link relation as an
absolute URI, inspired by the same approach used for Atom [RFC4287] absolute URI, inspired by the same approach used for Atom [RFC4287]
described in [RFC8288] appendix A.2 [2]. described in Appendix A.2 of [RFC8288].
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/ld+json Content-Type: application/ld+json
Content-Length: 638 Content-Length: 708
{ {
"@context": [ "@context": [
{ {
"@vocab": "http://www.iana.org/assignments/relation/", "@vocab": "http://www.iana.org/assignments/relation/",
"anchor": "@id", "anchor": "@id",
"href": "@id", "href": "@id",
"linkset": "@graph", "linkset": "@graph",
"_linkset": "@graph", "_linkset": "@graph",
"title": { "title": {
"@id": "http://purl.org/dc/terms/title" "@id": "http://purl.org/dc/terms/title"
}, },
"title*": { "title*": {
"@id": "http://purl.org/dc/terms/title" "@id": "http://purl.org/dc/terms/title"
}, },
"type": { "type": {
"@id": "http://purl.org/dc/terms/format" "@id": "http://purl.org/dc/terms/format"
},
"datetime": {
"@id": "http://purl.org/dc/terms/date"
} }
}, },
{ {
"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 8: JSON-LD Context mapping to schema.org and IANA assignments Figure 8: JSON-LD Context mapping to Dublin Core Terms and IANA
assignments
Applying the JSON-LD context of Figure 8 to the link set of Figure 7 Applying the JSON-LD context of Figure 8 to the link set of Figure 7
allows transforming the "application/linkset+json" link set to an RDF allows transforming the "application/linkset+json" link set to an RDF
link set. Figure 9 shows the latter represented by means of the link set. Figure 9 shows the latter represented by means of the
"text/turtle" RDF serialization. "text/turtle" RDF serialization.
<https://example.org/article/view/7507> <https://authors.example.net/johndoe>
<http://www.iana.org/assignments/relation/author> <http://purl.org/dc/terms/format>
<https://orcid.org/0000-0002-1825-0097> . "application/rdf+xml" .
<https://example.org/article/view/7507> <https://example.org/resource1#comment=1>
<http://www.iana.org/assignments/relation/item> <http://www.iana.org/assignments/relation/author>
<https://example.org/article/7507/item/1> . <https://authors.example.net/alice> .
<https://example.org/article/7507/item/1> <https://example.org/resource1>
<http://purl.org/dc/terms/format> <http://www.iana.org/assignments/relation/author>
"application/pdf" . <https://authors.example.net/johndoe> .
<https://example.org/article/view/7507> <https://example.org/resource1>
<http://www.iana.org/assignments/relation/item> <http://www.iana.org/assignments/relation/latest-version>
<https://example.org/article/7507/item/2> . <https://example.org/resource1?version=3> .
<https://example.org/article/7507/item/2> <https://example.org/resource1>
<http://purl.org/dc/terms/format> <http://www.iana.org/assignments/relation/memento>
"text/csv" . <https://example.org/resource1?version=1> .
<https://example.org/article/view/7507> <https://example.org/resource1>
<http://www.iana.org/assignments/relation/cite-as> <http://www.iana.org/assignments/relation/memento>
<https://doi.org/10.5555/12345680> . <https://example.org/resource1?version=2> .
<https://doi.org/10.5555/12345680> <https://example.org/resource1?version=1>
<http://purl.org/dc/terms/title> <http://purl.org/dc/terms/date>
"A Methodology for the Emulation of Architecture" . "Thu, 13 Jun 2019 09:34:33 GMT" .
<https://example.com/links/article/7507> <https://example.org/resource1?version=1>
<http://www.iana.org/assignments/relation/alternate> <http://purl.org/dc/terms/format>
<https://mirror.example.com/links/article/7507> . "text/html" .
<https://mirror.example.com/links/article/7507> <https://example.org/resource1?version=2>
<http://purl.org/dc/terms/format> <http://purl.org/dc/terms/date>
"application/linkset" . "Sun, 21 Jul 2019 12:22:04 GMT" .
<https://example.org/resource1?version=2>
<http://purl.org/dc/terms/format>
"text/html" .
<https://example.org/resource1?version=2>
<http://www.iana.org/assignments/relation/predecessor-version>
<https://example.org/resource1?version=1> .
<https://example.org/resource1?version=3>
<http://purl.org/dc/terms/format>
"text/html" .
<https://example.org/resource1?version=3>
<http://www.iana.org/assignments/relation/predecessor-version>
<https://example.org/resource1?version=2> .
Figure 9: RDF serialization of the link set resulting from applying Figure 9: RDF serialization of the link set resulting from applying
the JSON-LD context the JSON-LD context
Note that the JSON-LD context of Figure 8 does not handle (meta)link Note that the JSON-LD context of Figure 8 does not handle (meta)link
relations of type ""linkset"" as they are in conflict with the top- relations of type ""linkset"" as they are in conflict with the top-
level JSON key. A workaround is to rename the top-level key to level JSON key. A workaround is to rename the top-level key to
""_linkset"" in the "application/linkset+json" before transforming a ""_linkset"" in the "application/linkset+json" before transforming a
link set to JSON-LD. link set to JSON-LD.
 End of changes. 52 change blocks. 
161 lines changed or deleted 187 lines changed or added

This html diff was produced by rfcdiff 1.44jr. The latest version is available from http://tools.ietf.org/tools/rfcdiff/