Subject: [httpapi] draft-ietf-httpapi-digest-fields-problem-types-03 ietf last call Genart review
From: Lars Eggert via Datatracker <[email-masked]>
To: <[email-masked]>
Cc: [email-masked], [email-masked], [email-masked]
Date: Wed, 04 Feb 2026 02:08:18 -0800
List-Id: Building Blocks for HTTP APIs <httpapi.ietf.org>

Document: draft-ietf-httpapi-digest-fields-problem-types
Title: HTTP Problem Types for Digest Fields
Reviewer: Lars Eggert
Review result: Ready with Nits

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://wiki.ietf.org/en/group/gen/GenArtFAQ>.

Document: draft-ietf-httpapi-digest-fields-problem-types-??
Reviewer: Lars Eggert
Review Date: 2026-02-04
IETF LC End Date: 2026-02-05
IESG Telechat date: Not scheduled for a telechat

# genart review of draft-ietf-httpapi-digest-fields-problem-types-03

CC @larseggert

## Comments

### Section 2, paragraph 1
```
     The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
     "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
     "OPTIONAL" in this document are to be interpreted as described in
     BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
     capitals, as shown here.
```
I think there is only one use of such a key word ("MUST NOT" in Section 3.2) in
this doc. It might be worthwhile checking whether clarity might be improved by
relying on BCP14 terms more. I'm making some easy suggestions in the nits
below, FWIW. Or, given that the doc is Informational, maybe remove all BCP14
terms instead?

### Section 3.1, paragraph 1
```
     This section defines the "https://iana.org/assignments/http-problem-
     types#digest-unsupported-algorithms" problem type.  A server can use
```
Do we really need to name this problem type with a URL? Or is that a Markdown
issue?

## Nits

All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

### Typos

#### Section 1, paragraph 1
```
-    defines a set of problem types ([PROBLEM]) that can be used by server
-                                   -         -
```

#### Section 3.1, paragraph 1
```
-    types#digest-unsupported-algorithms" problem type.  A server can use
-                                                                 ^^^
+    types#digest-unsupported-algorithms" problem type.  A server MAY use
+                                                                 ^^^
```

#### Section 3.1, paragraph 5
```
-    The response can include the corresponding integrity preference field
-                 ^^^
+    The response MAY include the corresponding integrity preference field
+                 ^^^
```

#### Section 3.1, paragraph 6
```
-    which the client could use to retry the request with different,
-                     ^^^^^
+    which the client MAY use to retry the request with different,
+                     ^^^
```

#### Section 3.1, paragraph 15
```
-    This problem type can also be used when a request contains an
-                      ^^^
+    This problem type MAY also be used when a request contains an
+                      ^^^
```

#### Section 3.2, paragraph 1
```
-    types#digest-invalid-values" problem type.  A server can use this
-                                                         ^^^
+    types#digest-invalid-values" problem type.  A server MAY use this
+                                                         ^^^
```

#### Section 3.3, paragraph 1
```
-    types#digest-mismatching-values" problem type.  A server can use this
-                                                             ^^^
+    types#digest-mismatching-values" problem type.  A server MAY use this
+                                                             ^^^
```

#### Section 3.3, paragraph 7
```
-    modified unintentionally by an intermediary.  The sender could use
-                                                             ^^^^^
+    modified unintentionally by an intermediary.  The sender MAY use
+                                                             ^^^
```

#### Section 4, paragraph 3
```
-    should not expose the calculated digest to avoid exposing information
-    ^^^^^^ ^^^
+    SHOULD NOT expose the calculated digest to avoid exposing information
+    ^^^^^^ ^^^
```

### JSON

Illegal character '.' at index 632
```
   {
     "type": "https://iana.org/assignments/http-problem-types#\
       digest-unsupported-algorithms",
     "title": "Unsupported hashing algorithms",
     "unsupported-algorithms": [
       {
         "algorithm": "foo",
         "header": "Want-Content-Digest"
       }
     ]
   }

2.  Conventions and Definitions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.
```

## Notes

This review is in the ["IETF Comments" Markdown format][ICMF]. You can use the
[`ietf-comments` tool][ICT] to automatically convert this review into
individual GitHub issues. Review generated by the [`ietf-reviewtool`][IRT].

[ICMF]: https://github.com/mnot/ietf-comments/blob/main/format.md
[ICT]: https://github.com/mnot/ietf-comments
[IRT]: https://github.com/larseggert/ietf-reviewtool