Subject: [secdir] SECDIR review of draft-ietf-httpapi-linkset

From: Donald Eastlake <[email-masked]>
Date: Mon, 24 Jan 2022 16:50:16 -0500

I have reviewed this document as part of the security directorate's
ongoing effort to review all IETF documents being processed by the
IESG.  These comments were written primarily for the benefit of the
security area directors.  Document editors and WG chairs should treat
these comments just like any other last call comments.

The summary of the review is READY with nits.

This document defines two formats and media types for sets of web
hyperlinks. One is JSON based and the other aligns with the format for
links in the HTTP Link field. It also specifies a link relation type
for sets of links. It is a reasonably straightforward draft. The
Security Considerations section looks good to me.

Figure 16 exceeds the line length limit (and, presumably to minimize
that, is outdented by 3 characters). You need some way to fold the
long line. For example, you could adopt a convention that a backslash
at the end of a line is just a representational artifact in this
document and it and any leading white space on the following line
should be ignored when interpreting the document content. This might
also sort of help on folding Link header lines.

The wording in parts of the document is pretty redundant. For example,
the entirety of Section 5 appears as the large last paragraph of
Section 6 with minor substitutions caused by the change from media
types to linkset link relation type. I would have personally tried
harder to factor out common provisions but, as far as I can tell, the
various pieces of redundant text here and elsewhere in the document do
not conflict.

I did not review the Implementation Status section.

Trivia:

Figures 1-6 do not have captions.

The content of Figures 7-20 (except 16) is flush left to the body text
margin which is a little confusing, especially when the figure content
is short as in Figure 7. Suggest indenting it 2 or 3 spaces.

Section 4.2.5: "... allows to unambiguously round trip between ..."
should be "... allows unambiguously round tripping between ..." or
"... allows unambiguously making a round trip between ...".

I would think that Sections 8.1 through 8.3 should start with "IANA is
requested to register ..." or the like.

Thanks,
Donald
===============================
 Donald E. Eastlake 3rd   +1-508-333-2270 (cell)
 2386 Panoramic Circle, Apopka, FL 32703 USA
 [email-masked]