Subject: [httpapi] Genart last call review of draft-ietf-httpapi-linkset-06

From: Christer Holmberg via Datatracker <[email-masked]>
Date: Mon, 10 Jan 2022 15:26:40 -0800

Reviewer: Christer Holmberg
Review result: Ready with Issues

I am the assigned Gen-ART reviewer for this draft. The General Area
Review Team (Gen-ART) reviews all IETF documents being processed
by the IESG for the IETF Chair.  Please treat these comments just
like any other last call comments.

For more information, please see the FAQ at

<https://trac.ietf.org/trac/gen/wiki/GenArtfaq>.

Document: draft-ietf-httpapi-linkset-06
Reviewer: Christer Holmberg
Review Date: 2022-01-10
IETF LC End Date: 2022-01-19
IESG Telechat date: Not scheduled for a telechat

Summary: Technically I don't have any major issue.  However, I do have a minor
technical, one administrative, and some editorial, comments.

Major issues:

Q1: The draft is intended to be published as Informational RFC. That sounds a
little strange to me. Could you please explain what the reason is?

Minor issues:

Q2: The document defines the "application/linkset+json" format, and indicates
that it can also be used for JSON-LD. What is the reason for not defining a
separate format for JSON-LD? Separate formats ("application/json" and
"application/ld+json") have previously been defined.

Nits/editorial comments:

Q3: The document has long sentences like "One serializes links in the same
format as used in HTTP the Link header field". Couldn't one just say "based on
the syntax of the HTTP Link header field", or something like that?

Q4: The document talks about "document format". People familiar with HTTP are
probably familiar with that terminology, but I think it would be good to add a
reference on first occurrence.

Q5: In Section 1, you talk about serializing links as JSON objects. Should it
be JSON strings, or something? JSON object is not a serialization.

---

From: Herbert Van de Sompel <[email-masked]>
Date: Wed, 19 Jan 2022 16:11:24 +0100

Dear Christer

Thanks for your feedback.

The response from my co-author Erik Wilde and myself is included below and
posted at https://github.com/ietf-wg-httpapi/linkset/issues/63

I plan to make updates as suggested for Q4 and Q5 soon, and as such would
appreciate it if you could let us know whether OK.

Greetings

Herbert Van de Sompel

======

Q1: The I-D went through the HTTPAPI WG tagged as intended to be published
as an Informational RFC. It do not remember suggestions to go down a
different path. Maybe @richsalz <https://github.com/richsalz> @darrelmiller
<https://github.com/darrelmiller> have an opinion on whether or not
Informational is inappropriate?

Q2: The I-D defines the application/linkset+json media type and leverages
an established technique (provision of context as per as per Section 6.8 of
the W3C JSON-LD
Recommendation(https://www.w3.org/TR/2014/REC-json-ld-20140116/#interpreting-json-as-json-ld)
to allow that JSON to be interpreted as JSON-LD. This approach allows
communities of use to specify a context that best serves their needs and
does not require imposing specific vocabularies.

Q3: Yes, the sentence you suggest would work, although the "based on the
syntax" bit might be interpreted as "that syntax with a few twists". I feel
that the existing sentence does not leave such room for interpretation. A
matter of preferred style, I guess.

Q4: The term document format doesn't sound quite appropriate, indeed. I
suggest replacing the sentence:

Therefore, this specification defines two document formats that serialize
Web Links and their attributes.

by the following sentence that matches the terminology used in the Abstract:

Therefore, this specification defines two document formats for representing
sets of Web Links and their attributes as stand-alone documents.

Q5: I suggest replacing the sentence:

One serializes links in the same format as used in HTTP the Link header
field, and the other as a JSON object.

by:

One serializes links in the same format as used in HTTP the Link header
field, and the other serializes links in JSON.

On Tue, Jan 11, 2022 at 12:27 AM Christer Holmberg via Datatracker <
[email-masked]> wrote:

> --
> httpapi mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/httpapi
>

-- 
==================
Herbert Van de Sompel
https://hvdsomp.info
https://orcid.org/0000-0002-0715-6126

---

From: Christer Holmberg <[email-masked]>
Date: Wed, 19 Jan 2022 19:49:25 +0000

Hi Herbert,

Thanks for the reply! Please see inline

(I wasn’t sure whether you wanted by reply by e-mail, or in GitHub, so I send it by e-mail).

---

>Q1: The I-D went through the HTTPAPI WG tagged as intended to be published as an Informational RFC. It do not remember suggestions to
>go down a different path. Maybe @richsalz<https://github.com/richsalz> @darrelmiller<https://github.com/darrelmiller> have an opinion on whether or not Informational is inappropriate?

The reason I ask is because the definition of Information says:
   “An "Informational" specification is published for the general
   information of the Internet community, and does not represent an
   Internet community consensus or recommendation.”

To me the draft is a little more than a “specification published for the general information of the Internet community”.

I guess IESG will decide whether Informational is appropriate. To me it sounds strange, and that’s the reason I asked :)

---

>Q2: The I-D defines the application/linkset+json media type and leverages an established technique (provision of context as per as per Section 6.8 of the W3C JSON-LD
>Recommendation(https://www.w3.org/TR/2014/REC-json-ld-20140116/#interpreting-json-as-json-ld) to allow that JSON to be interpreted as JSON-LD. This approach allows
>communities of use to specify a context that best serves their needs and does not require imposing specific vocabularies.

Perhaps it would be useful to have some text explaining that.

Also, I assume that an entity that supports the media type is not required to support JSON-LD, so maybe explicitly clarifying that too?

---

>Q3: Yes, the sentence you suggest would work, although the "based on the syntax" bit might be interpreted as "that syntax with a few twists". I feel that the
>existing sentence does not leave such room for interpretation. A matter of preferred style, I guess.

If the syntax is identical, you could say something like ”using the syntax of the Link header field”.

In any case, it is just editorial, so whatever you prefer :) However, please verify that you use the same terminology throughout the document.

---

>Q4: The term document format doesn't sound quite appropriate, indeed. I suggest replacing the sentence:
>
>Therefore, this specification defines two document formats that serialize Web Links and their attributes.
>
>Therefore, this specification defines two document formats for representing sets of Web Links and their attributes as stand-alone documents.

Your new text looks better :)

However, my comment was regarding having a reference for “document”. For example, is it different than “payload format”, which is often used?

---

>One serializes links in the same format as used in HTTP the Link header field, and the other as a JSON object.
>
>by:
>
>One serializes links in the same format as used in HTTP the Link header field, and the other serializes links in JSON.

Looks good.

Regards,

Christer

On Tue, Jan 11, 2022 at 12:27 AM Christer Holmberg via Datatracker <[email-masked]<mailto:[email-masked]>> wrote:
Reviewer: Christer Holmberg
Review result: Ready with Issues

Major issues:

Minor issues:

Nits/editorial comments:

--
httpapi mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/httpapi

--
==================
Herbert Van de Sompel
https://hvdsomp.info<https://protect2.fireeye.com/v1/url?k=31323334-501d5122-313273af-454445555731-93338a574d37ade1&q=1&e=7bbc3367-01c3-4e68-b56e-f9a718d98e12&u=https%3A%2F%2Fhvdsomp.info%2F>
https://orcid.org/0000-0002-0715-6126