Problem Details for HTTP APIs
draft-ietf-httpapi-rfc7807bis-07

# Internet AD comments for draft-ietf-httpapi-rfc7807bis-05
CC @ekline

## Comments

### Appendix A

* I don't know enough about JSON Schema mechanics, but I assume it's probably
  non-trivial (or even impossible) to express that "*[string]" are reserved.

* Don't forget to change the "7807bis" string here once this document has
  an allocated number.

The document is fine. Just one comment.

I am wondering if the document should say something about internationalization, even if it is considered not required as this is more or less a programmatic interface without an enduser at the higher level HTML. But right now, I wonder if there is supposed to be internationalization support, but it just hasn't been pointed out in the document.

Thank you to Deb Cooley for the SECDIR review.

Thanks for working on this specification. I must say the problem details would be equally helpful for human and non-human consumers :-).

I have following comments, where I think it will improve the document if addressed -

  # I was expecting the examples to show one usage of the "status" member.

  # Is there a constrains that the intermediary or caches cannot be consumer of the problem details and must not change the contents of the problem details from origin server? The security considerations and the description of "status" member seems to expect that no one changes the problem details on path and consumer receives that original problem details from the origin server. However, I have not seen such requirement in this specification.

  # This specification needs to refer to RFC7807

  # Section 4.2, says - "When evaluating requests, the Expert(s) should consider community feedback, how well-defined the problem type is, and this specification's requirements." 

    Here, the boundary of the community need to be defined specially when the idea is to have designated experts to do the allocation. 

    Also it says - "Specification documents should be published in a stable, freely available manner (ideally located with a URL), but need not be standards".

    Here, this "need not be standards" part seems to be unnecessary as Specification required does not need a standard as per RFC8126, Section 4.6. May be just better to remove the whole sentence.

# Éric Vyncke, INT AD, comments for draft-ietf-httpapi-rfc7807bis-05
CC @evyncke

Thank you for the work put into this document. It is easy to read for a simple and useful mechanism.

Please find below some non-blocking COMMENT points (but replies would be appreciated even if only for my own education).

Special thanks to Darrel Miller for the shepherd's detailed write-up including the WG consensus **and** the justification of the intended status. 

I hope that this review helps to improve the document,

Regards,

-éric

## COMMENTS

### Non 4xx response status code

Can this mechanism also be use in non-error response status codes ? I.e., redirect 3xx, or server error 5xx ? AFAICT, the text is a little unclear.

### Content-Language

The examples use the Content-Language header, but is it mandatory for this mechanism ? I.e., a SHOULD or a MUST would be more explicit.

### No author affiliation

I think that this is the first I-D in my 4 years of IESG that has not a single author affiliation. Just curious about the reasoning.

## 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. 

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

# GEN AD review of draft-ietf-httpapi-rfc7807bis-05

CC @larseggert

Thanks to Pete Resnick for the General Area Review Team (Gen-ART) review
(https://mailarchive.ietf.org/arch/msg/gen-art/rwof5ZAvK9MM0IPKUX2lrIFJP8c).

## Comments

### Section 4.2, paragraph 3
```
     When evaluating requests, the Expert(s) should consider community
     feedback, how well-defined the problem type is, and this
     specification's requirements. 
```
It's called "expert review" and not "community review" for a reason, because
it's the expert's call. If you want community review, the registration policy
should be "RFC Required" or "IETF Review"...

### Missing references

No reference entries found for: `[RFC3986]`, `[rfc7807]`, and `[RFC7231]`.

### Uncited references

Document obsoletes `RFC7807`, but does not cite it as a reference.

## 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 4.2, paragraph 3
```
-    and deployment-specific values are not registrable.  Specification
+    and deployment-specific values are not registerable.  Specification
+                                                 +
```

### Uncited references

Uncited references: `[UTF8]`.

## 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