draft-ietf-httpapi-linkset-04.txt   draft-ietf-httpapi-linkset-05.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: 9 April 2022 Data Archiving and Networked Services Expires: 24 April 2022 Data Archiving and Networked Services
6 October 2021 21 October 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-04 draft-ietf-httpapi-linkset-05
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 9 April 2022. This Internet-Draft will expire on 24 April 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
skipping to change at page 2, line 30 skipping to change at page 2, line 30
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
4.1. HTTP Link Document Format: application/linkset . . . . . 6 4.1. HTTP Link Document Format: application/linkset . . . . . 6
4.2. JSON Document Format: application/linkset+json . . . . . 7 4.2. JSON Document Format: application/linkset+json . . . . . 7
4.2.1. Set of Links . . . . . . . . . . . . . . . . . . . . 7 4.2.1. Set of Links . . . . . . . . . . . . . . . . . . . . 7
4.2.2. Link Context Object . . . . . . . . . . . . . . . . . 8 4.2.2. Link Context Object . . . . . . . . . . . . . . . . . 8
4.2.3. Link Target Object . . . . . . . . . . . . . . . . . 8 4.2.3. Link Target Object . . . . . . . . . . . . . . . . . 8
4.2.4. Link Target Attributes . . . . . . . . . . . . . . . 10 4.2.4. Link Target Attributes . . . . . . . . . . . . . . . 10
4.2.5. JSON Extensibility . . . . . . . . . . . . . . . . . 14 4.2.5. JSON Extensibility . . . . . . . . . . . . . . . . . 14
5. The "profile" paramter for media types to Represent Sets of 5. The "profile" parameter for media types to Represent Sets of
Links . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Links . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6. The "linkset" Relation Type for Linking to a Set of Links . . 15 6. The "linkset" Relation Type for Linking to a Set of Links . . 15
7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 16 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 16
7.1. Set of Links Provided as application/linkset . . . . . . 16 7.1. Set of Links Provided as application/linkset . . . . . . 16
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
skipping to change at page 6, line 20 skipping to change at page 6, line 20
construct and by switching the position of the resources involved in construct and by switching the position of the resources involved in
the link. the link.
4.1. HTTP Link Document Format: application/linkset 4.1. HTTP Link Document Format: application/linkset
This document format is near identical to the field value of the HTTP This document format is near identical to the field value of the HTTP
"Link" header field as defined in Section 3 of [RFC8288], more "Link" header field as defined in Section 3 of [RFC8288], more
specifically by its ABNF production rule for "Link" and subsequent specifically by its ABNF production rule for "Link" and subsequent
ones. It differs only from the format for field values of the HTTP ones. It differs only from the format for field values of the HTTP
"Link" header in that not only spaces and horizontal tabs are allowed "Link" header in that not only spaces and horizontal tabs are allowed
as seperators but also new line characters as a means to improve as separators but also newline characters as a means to improve
usability. The use of non-ASCII characters in the field value of the usability. The use of non-ASCII characters in the field value of the
HTTP "Link" Header field is not interoperable. HTTP "Link" Header field is not interoperable.
The assigned media type for this format is "application/linkset". The assigned media type for this format is "application/linkset".
When converting an "application/linkset" document to a field value When converting an "application/linkset" document to a field value
for the HTTP "Link" header, new line characters SHOULD be removed in for the HTTP "Link" header, newline characters SHOULD be removed in
order to comply with Section 5.5 of [I-D.ietf-httpbis-semantics]. order to comply with Section 5.5 of [I-D.ietf-httpbis-semantics].
In order to support use cases where "application/linkset" documents In order to support use cases where "application/linkset" documents
are re-used outside the context of an HTTP interaction, it is are re-used outside the context of an HTTP interaction, it is
RECOMMENDED to make them self-contained by adhering to the following RECOMMENDED to make them self-contained by adhering to the following
guidelines: guidelines:
* For every link provided in the set of links, explicitly provide * For every link provided in the set of links, explicitly provide
the link context using the "anchor" attribute. the link context using the "anchor" attribute.
* For link context ("anchor" attribute) and link target ("href" * For link context ("anchor" attribute) and link target ("href"
attribute), use URI References that are not relative references attribute), use URI references that are not relative references
(as defined in Section 4.1 of [RFC3986]). (as defined in Section 4.1 of [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 field value of the in [RFC6690] in that the former fully matches the field value of the
HTTP "Link" header field as defined in Section 3 of [RFC8288], HTTP "Link" header field as defined in Section 3 of [RFC8288],
skipping to change at page 7, line 23 skipping to change at page 7, line 23
In order to support use cases where "application/linkset+json" In order to support use cases where "application/linkset+json"
documents are re-used outside the context of an HTTP interaction, it documents are re-used outside the context of an HTTP interaction, it
is RECOMMENDED to make them self-contained by adhering to the is RECOMMENDED to make them self-contained by adhering to the
following guidelines: following guidelines:
* For every link provided in the set of links, explicitly provide * For every link provided in the set of links, explicitly provide
the link context using the "anchor" member. the link context using the "anchor" member.
* For link context ("anchor" member) and link target ("href" * For link context ("anchor" member) and link target ("href"
member), use URI References that are not relative references (as member), use URI references that are not relative references (as
defined in Section 4.1 of [RFC3986]). defined in Section 4.1 of [RFC3986]).
If these recommendations are not followed, interpretation of If these recommendations are not followed, interpretation of
"application/linkset+json" will depend on which URI is used as "application/linkset+json" will depend on which URI is used as
context URI. context URI.
The "application/linkset+json" serialization is designed such that it The "application/linkset+json" serialization is designed such that it
can directly be used as the content of a JSON-LD serialization by can directly be used as the content of a JSON-LD serialization by
adding an appropriate context. Appendix A shows an example of a adding an appropriate context. Appendix A shows an example of a
possible context that, when added to a JSON serialization, allows it possible context that, when added to a JSON serialization, allows it
skipping to change at page 8, line 13 skipping to change at page 8, line 13
in an array. in an array.
4.2.2. Link Context Object 4.2.2. Link Context Object
In the JSON representation one or more links that have the same link In the JSON representation one or more links that have the same link
context are represented by a JSON object, the link context object. A context are represented by a JSON object, the link context object. A
link context object adheres to the following rules: link context object adheres to the following rules:
* Each link context object MAY have an "anchor" member with a value * Each link context object MAY have an "anchor" member with a value
that represents the link context. If present, this value MUST be that represents the link context. If present, this value MUST be
a URI Reference and SHOULD NOT be a relative reference as per a URI reference and SHOULD NOT be a relative reference as per
Section 4.1 of [RFC3986]. Section 4.1 of [RFC3986].
* For each distinct relation type that the link context has with * 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:
skipping to change at page 8, line 43 skipping to change at page 8, line 43
an array. an array.
4.2.3. Link Target Object 4.2.3. Link Target Object
In the JSON representation a link target is represented by a JSON In the JSON representation a link target is represented by a JSON
object, the link target object. A link target object adheres to the object, the link target object. A link target object adheres to the
following rules: following rules:
* Each link target object MUST have an "href" member with a value * Each link target object MUST have an "href" member with a value
that represents the link target. This value MUST be a URI that represents the link target. This value MUST be a URI
Reference and SHOULD NOT be a relative reference as per reference and SHOULD NOT be a relative reference as per
Section 4.1 of [RFC3986]. Cases where the href member is present, Section 4.1 of [RFC3986]. Cases where the href member is present,
but no value is provided for it (i.e. the resource providing the but no value is provided for it (i.e. the resource providing the
set of links is the target of the link in the link target object) set of links is the target of the link in the link target object)
MUST be handled by providing an "href" member with an empty string MUST be handled by providing an "href" member with an empty string
("href": ""). ("href": "").
* 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.
skipping to change at page 13, line 49 skipping to change at page 13, line 49
lacking standardization, there is no interoperable understanding of lacking standardization, there is no interoperable understanding of
these extension attributes. One important consequence is that their these extension attributes. One important consequence is that their
cardinality is unknown to generic applications. Therefore, in the cardinality is unknown to generic applications. Therefore, in the
JSON serialization, all extension target attributes are treated as JSON serialization, all extension target attributes are treated as
repeatable. repeatable.
The JSON serialization for these target attributes MUST be as The JSON serialization for these target attributes MUST be as
follows: follows:
* An extension target attribute is represented as a member of the * An extension target attribute is represented as a member of the
link context object with the same name of the attribute, including link target object with the same name of the attribute, including
the * if applicable. the * if applicable.
* The value of an extension attribute MUST be represented by an * The value of an extension attribute MUST be represented by an
array, even if there only is one value to be represented. array, even if there only is one value to be represented.
* If the extension target attribute does not have a name with a * If the extension target attribute does not have a name with a
trailing asterisk, then each value in that array MUST be a string trailing asterisk, then each value in that array MUST be a string
that represents one value of the attribute. that represents one value of the attribute.
* If the extension attribute has a name with a trailing asterisk (it * If the extension attribute has a name with a trailing asterisk (it
skipping to change at page 14, line 47 skipping to change at page 14, line 47
] ]
} }
] ]
} }
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. Extensions based target attributes as discussed in Section 4.2.4.3. No other form of
on the JSON syntax (such as additional members of the linkset member extensions SHOULD be used. In case they are used nevertheless, they
that are not defined in this specification) SHOULD NOT be used. In MUST NOT change the semantics of the JSON members defined in this
case they are used nevertheless, they MUST NOT change the semantics specification. Agents that consume JSON linkset documents MUST
of the JSON members defined in this specification. Agents that ignore such extensions.
consume JSON linkset documents MUST ignore such extensions.
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 field, 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" paramter for media types to Represent Sets of Links 5. The "profile" parameter 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" [RFC6906]) that apply to a link set document, the "profile" parameter
parrameter MAY be used in conjunction with the media types MAY be used in conjunction with the media types "application/linkset"
"application/linkset" and "application/linkset+json" detailed in and "application/linkset+json" detailed in Section 4.1 and
Section 4.1 and Section 4.2, respectively. For example, the Section 4.2, respectively. For example, the parameter could be used
parrameter could be used to indicate that a link set uses a specific, to indicate that a link set uses a specific, limited set of link
limited set of link relation types. relation types.
The value of the "profile" parrameter MUST be a non-empty list of The value of the "profile" parameter MUST be a non-empty list of
space-separated URIs, each of which identifies specific constraints space-separated URIs, each of which identifies specific constraints
or conventions that apply to the link set document. Profile URIs MAY or conventions that apply to the link set document. Profile URIs MAY
be registered in the IANA Profile URI Registry in the manner be registered in the IANA Profile URI Registry in the manner
specified by [RFC7284]. specified by [RFC7284].
The presence of a "profile" parameter in conjunction with the The presence of a "profile" parameter in conjunction with the
"application/linkset" and "application/linkset+json" media types does "application/linkset" and "application/linkset+json" media types does
not change the semantics of a link set. As such, clients with and not change the semantics of a link set. As such, clients with and
without knowledge of profile URIs can use the same representation. without knowledge of profile URIs can use the same representation.
skipping to change at page 23, line 24 skipping to change at page 23, line 24
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], with the addition of allowing newline
the general encoding rules of [I-D.ietf-httpbis-semantics], with characters as whitespace characters. The encoding of [RFC8288] is
the addition of allowing indicating character encoding and based on the general encoding rules of
language for specific parameters as defined by [RFC8187]. [I-D.ietf-httpbis-semantics], with the addition of allowing
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 33, line 7 skipping to change at page 33, line 7
According to RFC 6982, "this will allow reviewers and working groups According to RFC 6982, "this will allow reviewers and working groups
to assign due consideration to documents that have the benefit of to assign due consideration to documents that have the benefit of
running code, which may serve as evidence of valuable experimentation running code, which may serve as evidence of valuable experimentation
and feedback that have made the implemented protocols more mature. and feedback that have made the implemented protocols more mature.
It is up to the individual working groups to use this information as It is up to the individual working groups to use this information as
they see fit". they see fit".
B.1. GS1 B.1. GS1
GS1 is a provider of barcodes (GS1 GTINs and EAN/UPC) for retail GS1 is a provider of identifiers, most famously seen in EAN/UPC
products and manages an ecology of services and standards to leverage barcodes for retail and healthcare products, and manages an ecology
them at a global scale. GS1 has indicated that it will implement of services and standards to leverage them at a global scale. GS1
this "linkset" specification as a means to allow requesting and has indicated that it will fully implement this "linkset"
representing links pertaining to products from various retailers. specification as a means to allow requesting and representing links
Currently, the GS1 Digital Link specification makes an informative pertaining to products, shipments, assets and locations. Currently,
reference to version 03 of the "linkset" I-D. GS1 expresses the GS1 Digital Link specification makes an informative reference to
confidence that this will become a normative reference in the next version 03 of the "linkset" I-D. GS1 expresses confidence that this
iteration of that specification, likely to be ratified as a GS1 will become a normative reference in the next iteration of that
standard around February 2021. specification.
B.2. FAIR Signposting Profile B.2. FAIR Signposting Profile
The FAIR Signposting Profile is a community specification aimed at The FAIR Signposting Profile is a community specification aimed at
improving machine navigation of scholarly objects on the web through improving machine navigation of scholarly objects on the web through
the use of typed web links pointing at e.g. web resources that are the use of typed web links pointing at e.g. web resources that are
part of a specific object, persistent identifiers for the object and part of a specific object, persistent identifiers for the object and
its authors, license information pertaining to the object. The its authors, license information pertaining to the object. The
specification encourages the use of Linksets and initial specification encourages the use of Linksets and initial
implementations are ongoing, for example, for the open source implementations are ongoing, for example, for the open source
 End of changes. 17 change blocks. 
40 lines changed or deleted 41 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/