Draft: draft-ietf-httpapi-linkset-03

Commentary: This is a mostly mechanical edit that makes the document valid v3 . 
 As WG chair , this should be done . The RFC Editor will appreciate it . 
 it 's done already . had it all lined up , but  beat him to the finish line . 
 Yes , this will make the editing faster and less likely to add format warts . 
 :) love to see it . 
 thanks , 
 There 's no need for this draft , but we 'll use it for future work .
Paragraph (version A):
In the examples provided in this document, links in the HTTP "Link"
header field are shown on separate lines in order to improve
readability.  Note, however, that as per Section 5.5 of I-D.ietf-
httpbis-semantics, line breaks are not allowed in values for HTTP
fields; only whitespaces and tabs are supported as seperators.
Paragraph (version B):
In the examples provided in this document, links in the HTTP "Link"
header field are shown on separate lines in order to improve
readability.  Note, however, that as per I-D.ietf-httpbis-semantics,
line breaks are not allowed in values for HTTP fields; only
whitespaces and tabs are supported as seperators.
Paragraph (version A):
Providing links in which the resource is involved not just as link
context but also as link target.
Paragraph (version A):
Providing links pertaining to the resource that the server hosting
that resource is not aware of.
Paragraph (version A):
External management of links pertaining to the resource in a
special-purpose link management service.
Paragraph (version A):
Links are provided in a document that uses a well-defined media
type.
Paragraph (version A):
The resource to which the provided links pertain is able to link
to the resource that provides these links using a well-known link
relation type.
Paragraph (version A):
Section 15 of HTTP I-D.ietf-httpbis-semantics defines error codes
related to excess communication by the user agent ("413 Request
Entity Too Large" and "414 Request-URI Too Long"), but no specific
error codes are defined to indicate that response field content
exceeds the upper bound that can be handled by the server, and thus
it has been truncated.  As a result, applications take counter
measures aimed at controlling the size of the HTTP "Link" header
field, for example by limiting the links they provide to those with
select relation types, thereby limiting the value of the HTTP "Link"
header field to clients.  Providing links by means of a standalone
document overcomes challenges related to the unpredictable nature of
the size of HTTP "Link" header fields.
Paragraph (version A):
The format defined in linkset-native is identical to the payload
of the HTTP "Link" header field as specified in Web Linking
RFC8288.
Paragraph (version A):
The format defined in linkset-json is based on RFC8259.
Paragraph (version B):
I-D.ietf-httpbis-semantics defines error codes related to excess
communication by the user agent ("413 Request Entity Too Large" and
"414 Request-URI Too Long"), but no specific error codes are defined
to indicate that response field content exceeds the upper bound that
can be handled by the server, and thus it has been truncated.  As a
result, applications take counter measures aimed at controlling the
size of the HTTP "Link" header field, for example by limiting the
links they provide to those with select relation types, thereby
limiting the value of the HTTP "Link" header field to clients.
Providing links by means of a standalone document overcomes
challenges related to the unpredictable nature of the size of HTTP
"Link" header fields.
Paragraph (version A):
This document format is identical to the payload of the HTTP "Link"
header field as defined in Section 3 of RFC8288, more specifically by
its ABNF production rule for "Link" and subsequent ones.  Whereas the
HTTP "Link" Header field depends on HTTP and hence on RFC0822 for its
encoding, the format specified here is encoded as UTF-8 RFC3629.
Paragraph (version B):
This document format is identical to the payload of the HTTP "Link"
header field as defined in RFC8288, more specifically by its ABNF
production rule for "Link" and subsequent ones.  Whereas the HTTP
"Link" Header field depends on HTTP and hence on RFC0822 for its
encoding, the format specified here is encoded as UTF-8 RFC3629.
Paragraph (version A):
For every link provided in the set of links, explicitly provide
the link context using the "anchor" attribute.
Paragraph (version A):
For link context ("anchor" attribute) and link target ("href"
attribute), use absolute URIs (as defined in Section 4.3 of
RFC3986).
Paragraph (version A):
It should be noted that the "application/linkset" 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
"Link" header field as defined in Section 3 of RFC8288, whereas the
latter introduces constraints on that definition to meet requirements
for Constrained RESTful Environments.
Paragraph (version B):
It should be noted that the "application/linkset" 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
"Link" header field as defined in RFC8288, whereas the latter
introduces constraints on that definition to meet requirements for
Constrained RESTful Environments.
Paragraph (version A):
For every link provided in the set of links, explicitly provide
the link context using the "anchor" member.
Paragraph (version A):
For link context ("anchor" member) and link target ("href"
member), use absolute URIs (as defined in Section 4.3 of RFC3986).
Paragraph (version A):
A set of links MUST be represented as a JSON object which MUST
have "linkset" as its sole member.
Paragraph (version A):
The "linkset" member is an array in which a distinct JSON object -
the "link context object" (see linkset-json-link-context-object) -
MUST be used to represent links that have the same link context.
Paragraph (version A):
If necessary, the "linkset" member MAY contain information in
addition to link context objects, in which case that information
MUST NOT change the semantics of the links provided by those link
context objects.
Paragraph (version A):
Even if there is only one link context object, it MUST be wrapped
in an array.  Members other than link context objects MUST NOT be
included in this array.
Paragraph (version A):
Each link context object MAY have an "anchor" member with a value
that represents the link context.  If present, this value SHOULD
be an absolute URI as defined in Section 4.3 of RFC3986.  Cases
where the anchor member is present, but no value is provided for
it (i.e. the resource providing the set of links is the link
context for each link in the link context object) MUST be handled
by providing an "anchor" member with empty string ("anchor": "").
Paragraph (version A):
For registered relation types RFC8288, the name of this member
is the registered name of the relation type.
Paragraph (version A):
For extension relation types RFC8288, the name of this member
is the URI that uniquely represents the relation type.
Paragraph (version A):
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
included in this array.
Paragraph (version A):
Each link target object MUST have an "href" member with a value
that represents the link target.  This value SHOULD be an absolute
URI as defined in Section 4.3 of RFC3986.  Cases where the href
member is present, 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) MUST be handled by providing an "href"
member with an empty string ("href": "").
Paragraph (version A):
In many cases, a link target is further qualified by target
attributes.  Various types of attributes exist and they are
conveyed as additional members of the link target object as
detailed in json-target-attributes.
Paragraph (version A):
Attributes defined by the serialization of RFC8288.
Paragraph (version A):
Extension attributes defined and used by communities as allowed by
RFC8288.
Paragraph (version A):
Internationalized versions of the "title" attribute defined by
RFC8288 and of extension attributes allowed by RFC8288.
Paragraph (version A):
"hreflang": The optional and repeatable "hreflang" target
attribute MUST be represented by an array (even if there only is
one value to be represented), and each value in that array MUST be
a string - representing one value of the "hreflang" target
attribute for a link - which follows the same model as in the
RFC8288 syntax.
Paragraph (version A):
"media": The optional and not repeatable "media" target attribute
MUST be represented by a "media" member in the link target object,
and its value MUST be a string that follows the same model as in
the RFC8288 syntax.
Paragraph (version A):
"type": The optional and not repeatable "type" target attribute
MUST be represented by a "type" member in the link target object,
and its value MUST be a string that follows the same model as in
the RFC8288 syntax.
Paragraph (version A):
"title": The optional and not repeatable "title" target attribute
MUST be represented by a "title" member in the link target object,
and its value MUST be a string that follows the same model as in
the RFC8288 syntax.
Paragraph (version A):
"title*": The optional and not repeatable "title*" target
attribute is motivated by character encoding and language issues
and follows the model defined in RFC8187.  The details of the JSON
representation that applies to title* are described in linkset-
json-i18n-link-parameter.
Paragraph (version A):
An internationalized target attribute is represented as a member
of the link context object with the same name (including the *) of
the attribute.
Paragraph (version A):
The character encoding information as prescribed by RFC8187 is not
preserved; instead, the content of the internationalized attribute
is represented in the character encoding used for the JSON set of
links.
Paragraph (version A):
The value of the internationalized target attribute is an array
that contains one or more JSON objects.  The name of one member of
such JSON object is "value" and its value is the actual content
(in its unescaped version) of the internationalized target
attribute, i.e. the value of the attribute from which the encoding
and language information are removed.  The name of another,
optional, member of such JSON object is "language" and its value
is the language tag RFC5646 for the language in which the
attribute content is conveyed.
Paragraph (version A):
An extension target attribute is represented as a member of the
link context object with the same name of the attribute, including
the * if applicable.
Paragraph (version A):
The value of an extension attribute MUST be represented by an
array, even if there only is one value to be represented.
Paragraph (version 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
that represents one value of the attribute.
Paragraph (version A):
If the extension attribute has a name with a trailing asterisk (it
follows the content model of RFC8187), then each value in that
array MUST be a JSON object.  The value of each such JSON object
MUST be structured as described in linkset-json-i18n-link-
parameter.
Paragraph (version A):
Description: The Target IRI of a link with the "linkset" relation
type provides a set of links, including links in which the Context
IRI of the link participates.
Paragraph (version A):
Encoding considerations: Linksets are encoded according to the
definition of RFC8288.  The encoding of RFC8288 is based on the
general encoding rules of I-D.ietf-httpbis-semantics, with the
addition of allowing indicating character encoding and language
for specific parameters as defined by RFC8187.
Paragraph (version A):
Interoperability considerations: The interoperability
considerations of I-D.ietf-httpbis-semantics apply.
Paragraph (version A):
File extension(s): This media type does not propose a specific
extension.
Paragraph (version A):
Interoperability considerations: The interoperability
considerations of RFC8259 apply.
Paragraph (version A):
File extension(s): JSON documents often use ".json" as the file
extension, and this media type does not propose a specific
extension other than this generic one.
Paragraph (version A):
The Web Linking model always has an "implicit context", which is
the resource of the HTTP interaction.  This original context can
be lost or can change when self-contained link representations are
moved.  Changing the context can change the interpretation of
links when they have no explicit anchor, or when they use relative
URIs.  Applications may choose to ignore links that have no
explicit anchor or that use relative URIs when these are exchanged
in stand-alone resources.