draft-ietf-httpapi-linkset-05.txt   draft-ietf-httpapi-linkset-06.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: 24 April 2022 Data Archiving and Networked Services Expires: 16 May 2022 Data Archiving and Networked Services
21 October 2021 12 November 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-05 draft-ietf-httpapi-linkset-06
Abstract Abstract
This specification defines two formats and respective media types for This specification defines two formats and respective media types for
representing sets of links as stand-alone documents. One format is representing sets of links as stand-alone documents. One format is
JSON-based, the other aligned with the format for representing links JSON-based, the other aligned with the format for representing links
in the HTTP "Link" header field. This specification also introduces in the HTTP "Link" header field. This specification also introduces
a link relation type to support discovery of sets of links. a link relation type to support discovery of sets of links.
Note to Readers Note to Readers
skipping to change at page 1, line 43 skipping to change at page 1, line 43
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 24 April 2022. This Internet-Draft will expire on 16 May 2022.
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 (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components and restrictions with respect to this document. Code Components
extracted from this document must include Simplified BSD License text extracted from this document must include Revised BSD License text as
as described in Section 4.e of the Trust Legal Provisions and are described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Simplified BSD License. provided without warranty as described in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Use Cases and Motivation . . . . . . . . . . . . . . . . . . 3 3. Use Cases and Motivation . . . . . . . . . . . . . . . . . . 3
3.1. Third-Party Links . . . . . . . . . . . . . . . . . . . . 4 3.1. Third-Party Links . . . . . . . . . . . . . . . . . . . . 4
3.2. Challenges Writing to HTTP Link Header Field . . . . . . 5 3.2. Challenges Writing to HTTP Link Header Field . . . . . . 5
3.3. Large Number of Links . . . . . . . . . . . . . . . . . . 5 3.3. Large Number of Links . . . . . . . . . . . . . . . . . . 5
4. Document Formats for Sets of Links . . . . . . . . . . . . . 5 4. Document Formats for Sets of Links . . . . . . . . . . . . . 5
skipping to change at page 2, line 45 skipping to change at page 2, line 45
7.2. Set of Links Provided as application/linkset+json . . . . 17 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 19
7.4. Link Set Profiles . . . . . . . . . . . . . . . . . . . . 20 7.4. Link Set Profiles . . . . . . . . . . . . . . . . . . . . 20
7.4.1. Using a "profile" Attribute with a "linkset" Link . . 20 7.4.1. Using a "profile" Attribute with a "linkset" Link . . 20
7.4.2. Using a "profile" Parameter with a Link Set Media 7.4.2. Using a "profile" Parameter with a Link Set Media
Type . . . . . . . . . . . . . . . . . . . . . . . . 21 Type . . . . . . . . . . . . . . . . . . . . . . . . 21
7.4.3. Using a Link with a "profile" Link Relation Type . . 21 7.4.3. Using a Link with a "profile" Link Relation Type . . 21
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22
8.1. Link Relation Type: linkset . . . . . . . . . . . . . . . 22 8.1. Link Relation Type: linkset . . . . . . . . . . . . . . . 22
8.2. Media Type: application/linkset . . . . . . . . . . . . . 23 8.2. Media Type: application/linkset . . . . . . . . . . . . . 22
8.3. Media Type: application/linkset+json . . . . . . . . . . 24 8.3. Media Type: application/linkset+json . . . . . . . . . . 23
9. Security Considerations . . . . . . . . . . . . . . . . . . . 25 9. Security Considerations . . . . . . . . . . . . . . . . . . . 24
10. Normative References . . . . . . . . . . . . . . . . . . . . 25 10. Normative References . . . . . . . . . . . . . . . . . . . . 25
11. Informative References . . . . . . . . . . . . . . . . . . . 27 11. Informative References . . . . . . . . . . . . . . . . . . . 26
Appendix A. JSON-LD Context . . . . . . . . . . . . . . . . . . 27 Appendix A. JSON-LD Context . . . . . . . . . . . . . . . . . . 27
Appendix B. Implementation Status . . . . . . . . . . . . . . . 32 Appendix B. Implementation Status . . . . . . . . . . . . . . . 32
B.1. GS1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 B.1. GS1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
B.2. FAIR Signposting Profile . . . . . . . . . . . . . . . . 33 B.2. FAIR Signposting Profile . . . . . . . . . . . . . . . . 33
B.3. Open Journal Systems (OJS) . . . . . . . . . . . . . . . 33 B.3. Open Journal Systems (OJS) . . . . . . . . . . . . . . . 33
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 33 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 33
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33
1. Introduction 1. Introduction
skipping to change at page 9, line 14 skipping to change at page 9, line 14
* In many cases, a link target is further qualified by target * In many cases, a link target is further qualified by target
attributes. Various types of attributes exist and they are attributes. Various types of attributes exist and they are
conveyed as additional members of the link target object as conveyed as additional members of the link target object as
detailed in Section 4.2.4. detailed in Section 4.2.4.
The following example of a JSON-serialized set of links represents The following example of a JSON-serialized set of links represents
one link with its core components: link context, link relation type, one link with its core components: link context, link relation type,
and link target. and link target.
{ { "linkset":
"linkset": [
[ { "anchor": "http://example.net/bar",
{ "anchor": "http://example.net/bar", "next": [
"next": [ {"href": "http://example.com/foo"}
{"href": "http://example.com/foo"} ]
] }
} ]
]
} }
Figure 1 Figure 1
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 link context and relation type but have two links that share link context and relation type but have
different link targets. different link targets.
{ { "linkset":
"linkset": [
[ { "anchor": "http://example.net/bar",
{ "anchor": "http://example.net/bar", "item": [
"item": [ {"href": "http://example.com/foo1"},
{"href": "http://example.com/foo1"}, {"href": "http://example.com/foo2"}
{"href": "http://example.com/foo2"} ]
] }
} ]
]
} }
Figure 2 Figure 2
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, the other is an extension relation One relation type is registered, the other is an extension relation
type. type.
{ { "linkset":
"linkset": [
[ { "anchor": "http://example.net/bar",
{ "anchor": "http://example.net/bar", "next": [
"next": [ {"href": "http://example.com/foo1"}
{"href": "http://example.com/foo1"} ]
] },
}, { "anchor": "http://example.net/boo",
{ "anchor": "http://example.net/boo", "http://example.com/relations/baz" : [
"http://example.com/relations/baz" : [ {"href": "http://example.com/foo2"}
{"href": "http://example.com/foo2"} ]
] }
} ]
]
} }
Figure 3 Figure 3
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 Web Linking [RFC8288]. Three types of attributes exist: Section 2 of Web Linking [RFC8288]. Three types of attributes exist:
* Serialisation-defined attributes described in Section 3.4.1 of Web * Serialisation-defined attributes described in Section 3.4.1 of Web
skipping to change at page 11, line 33 skipping to change at page 11, line 37
* "title*": The optional and not repeatable "title*" target * "title*": The optional and not repeatable "title*" target
attribute is motivated by character encoding and language issues attribute is motivated by character encoding and language issues
and follows the model defined in [RFC8187]. The details of the and follows the model defined in [RFC8187]. The details of the
JSON representation that applies to title* are described in JSON representation that applies to title* are described in
Section 4.2.4.2. Section 4.2.4.2.
The following example illustrates how the repeatable "hreflang" and The following example illustrates how the repeatable "hreflang" and
the not repeatable "type" target attributes are represented in a link the not repeatable "type" target attributes are represented in a link
target object. target object.
{ { "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" ] }
} ]
] }
} ]
]
} }
Figure 4 Figure 4
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
skipping to change at page 13, line 5 skipping to change at page 13, line 5
attribute, i.e. the value of the attribute from which the encoding attribute, i.e. the value of the attribute from which the encoding
and language information are removed. The name of another, and language information are removed. The name of another,
optional, member of such JSON object is "language" and its value optional, member of such JSON object is "language" and its value
is the language tag [RFC5646] for the language in which the is the language tag [RFC5646] for the language in which the
attribute content is conveyed. attribute content is conveyed.
The following example illustrates how the "title*" target attribute The following example illustrates how the "title*" target attribute
defined by Section 3.4.1 of [RFC8288] is represented in a link target defined by Section 3.4.1 of [RFC8288] is represented in a link target
object. object.
{ { "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": "nächstes Kapitel" ,
"title*": [ { "value": "nächstes Kapitel" , "language" : "de" } ]
"language" : "de" } ] }
} ]
] }
} ]
]
} }
Figure 5 Figure 5
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. 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"
skipping to change at page 14, line 25 skipping to change at page 14, line 22
MUST be structured as described in Section 4.2.4.2. MUST be structured as described in Section 4.2.4.2.
The example shows a link target object with three extension target The example shows a link target object with three extension target
attributes. The value for each extension target attribute is an attributes. The value for each extension target attribute is an
array. The two first are regular extension target attributes, with array. The two first are regular extension target attributes, with
the first one ("foo") having only one value and the second one the first one ("foo") having only one value and the second one
("bar") having two. The last extension target attribute ("baz*") ("bar") having two. The last extension target attribute ("baz*")
follows the naming rule of [RFC8187] and therefore is encoded follows the naming rule of [RFC8187] and therefore is encoded
according to the serialization described in Section 4.2.4.2. according to the serialization described in Section 4.2.4.2.
{ { "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", "foo": [ "foovalue" ],
"foo": [ "foovalue" ], "bar": [ "barone", "bartwo" ],
"bar": [ "barone", "bartwo" ], "baz*": [ { "value": "bazvalue" ,
"baz*": [ { "value": "bazvalue" , "language" : "en" } ]
"language" : "en" } ] }
} ]
] }
} ]
]
} }
Figure 6 Figure 6
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. No other form of target attributes as discussed in Section 4.2.4.3. No other form of
extensions SHOULD be used. In case they are used nevertheless, they extensions SHOULD be used. In case they are used nevertheless, they
MUST NOT change the semantics of the JSON members defined in this MUST NOT change the semantics of the JSON members defined in this
skipping to change at page 18, line 25 skipping to change at page 18, line 25
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>
; rel="alternate" ; rel="alternate"
; type="application/linkset" ; type="application/linkset"
Content-Length: 1349 Content-Length: 1349
{ { "linkset":
"linkset": [ [
{ { "anchor": "https://example.org/resource1",
"anchor": "https://example.org/resource1",
"author": [ "author": [
{ { "href": "https://authors.example.net/johndoe",
"href": "https://authors.example.net/johndoe",
"type": "application/rdf+xml" "type": "application/rdf+xml"
} }
], ],
"memento": [ "memento": [
{ { "href": "https://example.org/resource1?version=1",
"href": "https://example.org/resource1?version=1",
"type": "text/html", "type": "text/html",
"datetime": "Thu, 13 Jun 2019 09:34:33 GMT" "datetime": "Thu, 13 Jun 2019 09:34:33 GMT"
}, },
{ { "href": "https://example.org/resource1?version=2",
"href": "https://example.org/resource1?version=2",
"type": "text/html", "type": "text/html",
"datetime": "Sun, 21 Jul 2019 12:22:04 GMT" "datetime": "Sun, 21 Jul 2019 12:22:04 GMT"
} }
], ],
"latest-version": [ "latest-version": [
{ { "href": "https://example.org/resource1?version=3",
"href": "https://example.org/resource1?version=3",
"type": "text/html" "type": "text/html"
} }
] ]
}, },
{ { "anchor": "https://example.org/resource1?version=3",
"anchor": "https://example.org/resource1?version=3",
"predecessor-version": [ "predecessor-version": [
{ { "href": "https://example.org/resource1?version=2",
"href": "https://example.org/resource1?version=2",
"type": "text/html" "type": "text/html"
} }
] ]
}, },
{ { "anchor": "https://example.org/resource1?version=2",
"anchor": "https://example.org/resource1?version=2",
"predecessor-version": [ "predecessor-version": [
{ { "href": "https://example.org/resource1?version=1",
"href": "https://example.org/resource1?version=1",
"type": "text/html" "type": "text/html"
} }
] ]
}, },
{ { "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 set of links Figure 10: 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 11 shows a client issuing an HTTP HEAD request against Figure 11 shows a client issuing an HTTP HEAD request against
skipping to change at page 22, line 23 skipping to change at page 22, line 5
"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 anchor and the Profile URI link has the URI of the link set itself as anchor and the Profile URI
as target. Multiple Profile URIs are handled by using multiple as target. Multiple Profile URIs are handled by using multiple
"href" members. "href" members.
{ { "linkset":
"linkset": [
[ { "anchor": "https://id.gs1.org/01/9506000134352?linkType=all",
{ "anchor": "https://id.gs1.org/01/9506000134352?linkType=all", "profile": [
"profile": [ {"href": "https://www.gs1.org/voc/?show=linktypes"}
{"href": "https://www.gs1.org/voc/?show=linktypes"} ]
] },
}, { "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 Link Set that declares the profile it complies with Figure 18: A Link Set 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 should be registered by IANA per The link relation type below should be registered by IANA per
skipping to change at page 23, line 22 skipping to change at page 23, line 4
The Internet media type [RFC6838] for a natively encoded linkset is The Internet media type [RFC6838] for a natively encoded linkset is
application/linkset. application/linkset.
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], with the addition of allowing newline definition of [RFC8288]. The encoding of [RFC8288] is based on
characters as whitespace characters. The encoding of [RFC8288] is the general encoding rules of [I-D.ietf-httpbis-semantics], with
based on the general encoding rules of the addition of allowing indicating character encoding and
[I-D.ietf-httpbis-semantics], with the addition of allowing language for specific parameters as defined by [RFC8187].
indicating character encoding and 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: N/A Interoperability considerations: N/A
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
skipping to change at page 27, line 28 skipping to change at page 27, line 11
semantics-19>. semantics-19>.
11. Informative References 11. Informative References
[W3C.REC-json-ld-20140116] [W3C.REC-json-ld-20140116]
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, 16 January 2014, 20140116, 16 January 2014,
<https://www.w3.org/TR/2014/REC-json-ld-20140116>. <https://www.w3.org/TR/2014/REC-json-ld-20140116>.
[RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom
Syndication Format", RFC 4287, DOI 10.17487/RFC4287,
December 2005, <https://www.rfc-editor.org/info/rfc4287>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, [RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010, DOI 10.17487/RFC5988, October 2010,
<https://www.rfc-editor.org/info/rfc5988>. <https://www.rfc-editor.org/info/rfc5988>.
Appendix A. JSON-LD Context Appendix A. 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
context [W3C.REC-json-ld-20140116] that maps the JSON keys to context [W3C.REC-json-ld-20140116] that maps the JSON keys to
corresponding Linked Data terms. And, as per corresponding Linked Data terms. And, as per
 End of changes. 29 change blocks. 
137 lines changed or deleted 111 lines changed or added

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